feat: refine menu-item focus states and sidebar story layouts

.specs/dropdown-menu.md

@@ -7,9 +7,9 @@ spec_version: 1
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=3775-16746
   node_id: 3775:16746
-checksum: 5eedb67724f3eaa8c5f656a09f363f2600cd983a23cc55ed9f93a977919c066e
+checksum: 4127c081919eccd8281c4b69251be703cd99317f3c72c7b7e89eec3c3e3f2d88
 created: 2026-05-22
-last_updated: 2026-05-22
+last_updated: 2026-05-29
 ---
 # Dropdown Menu — Component Spec
 
@@ -35,6 +35,7 @@ Layered surface above the page (modal, drawer, menu). Migrated from the existing
 | `defaultOpen` | `boolean` | `undefined` | no | Initial open state when uncontrolled. |
 | `closeable` | `boolean` | `undefined` | no | When true, Escape and outside click close the menu. |
 | `closeOnSelect` | `boolean` | `undefined` | no | When true, selecting an item closes the menu. |
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right' \| 'auto'` | `'auto'` | no | Preferred panel placement. `auto` picks the side with the most viewport space; explicit sides flip to the opposite when they overflow. |
 | `sideOffset` | `number` | `undefined` | no | Gap between trigger and panel (px). |
 | `alignOffset` | `number` | `undefined` | no | Horizontal offset from trigger left edge (px). |
 

.specs/menu-item.md

@@ -7,9 +7,9 @@ spec_version: 1
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=3601-2693
   node_id: 3601:2693
-checksum: 9142b6a3366d26151037777ebb01398851c84803f92a1b4c79631c75b0265043
+checksum: d084e89a360fad2914c4137f7e020e00588d18792b843d811637ad01edb1d2b6
 created: 2026-05-22
-last_updated: 2026-05-22
+last_updated: 2026-05-27
 ---
 # Menu Item — Component Spec
 

.specs/sidebar.md

@@ -7,15 +7,48 @@ spec_version: 1
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=3735-14866
   node_id: 3735:14866
-checksum: 3e8dacf24608d93e15664ef7d188cf85d3212c3118e11979ad6439f3800949c8
+checksum: 5a95c6bb2fa2b2444eeeaa299f570536ecaf8250012366785ecfd2b5e2fba111
 created: 2026-05-22
-last_updated: 2026-05-22
+last_updated: 2026-05-28
 ---
 # Sidebar — Component Spec
 
 ## Purpose
 
-Helps users move between views or sections. Lives at `packages/webkit/src/components/webkit/layout/sidebar/`.
+Helps users move between views or sections. Composable application sidebar with optional header and footer regions; navigation content scrolls inside a built-in `ScrollArea`.
+
+## Usage
+
+```vue
+<script setup>
+import Sidebar from '@aziontech/webkit/layout/sidebar'
+import SidebarGroup from '@aziontech/webkit/layout/sidebar-group'
+import SidebarHeader from '@aziontech/webkit/layout/sidebar-header'
+import SidebarFooter from '@aziontech/webkit/layout/sidebar-footer'
+import MenuItem from '@aziontech/webkit/navigation/menu-item'
+</script>
+
+<template>
+  <Sidebar aria-label="Application" class="h-screen w-[280px]">
+    <template #header>
+      <SidebarHeader>
+        <!-- optional header content -->
+      </SidebarHeader>
+    </template>
+    <SidebarGroup>
+      <MenuItem label="Home" icon="ai ai-home" href="/" selected />
+    </SidebarGroup>
+    <SidebarGroup label="Build">
+      <MenuItem label="Applications" icon="ai ai-edge-application" href="/applications" />
+    </SidebarGroup>
+    <template #footer>
+      <SidebarFooter>
+        <!-- optional footer content -->
+      </SidebarFooter>
+    </template>
+  </Sidebar>
+</template>
+```
 
 ## Sub-components
 
@@ -25,7 +58,9 @@ Helps users move between views or sections. Lives at `packages/webkit/src/compon
 
 ## Props
 
-| _none_ | — | — | — | Public API is slots-only. |
+| Prop | Type | Default | Required | JSDoc |
+|---|---|---|---|---|
+| `ariaLabel` | `string` | `'Sidebar'` | no | Accessible name for the navigation landmark. |
 
 ## Events
 
@@ -77,6 +112,8 @@ _none_
 ## Stories (Storybook)
 
 - Default
+- WithHeaderSearch
+- WithHeaderAndProfileFooter
 
 ## Constraints — DO NOT
 

apps/storybook/src/stories/webkit/layout/ScrollArea.stories.js

@@ -27,7 +27,7 @@ const meta = {
     docs: {
       description: {
         component:
-          'Native overflow container with themed thin scrollbars and keyboard scrolling (arrow keys, Page Up/Down, Home/End). Pass height/width via `class` on the root; use inside sidebars via `SidebarGroup scroll`.'
+          'Native overflow container with themed thin scrollbars and keyboard scrolling (arrow keys, Page Up/Down, Home/End). Pass height/width via `class` on the root; `Sidebar` wraps its nav content in `ScrollArea` automatically.'
       }
     }
   },