@pudge-ui/mcp-server 0.1.0

package/spec/components/navigation/context-menu.md

@@ -0,0 +1,94 @@
+---
+name: Context Menu (Radial)
+id: context-menu
+class: .radial-menu
+category: navigation
+index: 9
+materials: [glossy-polycarbonate]
+sizes: [default]
+interactive: true
+requires_js: true
+canvas: false
+---
+
+# Context Menu (Radial)
+
+## Physical Analog
+**Reference devices**: Pro camera "quick menu" (Sony Alpha quick-access dial), Wacom tablet radial menu, video game weapon wheels.
+**Mechanism**: A radial/pie menu that appears around a point of activation. Items are arranged in a circle at equal angular intervals, each accessible by moving in that direction from center. Derived from military heads-up display (HUD) target-designator patterns. Faster than linear menus for small numbers of items (4-8) because the user only needs to specify a direction, not navigate a list.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Container | 140x140px, circular |
+| Container border | 2px solid |
+| Item size | 36x36px, circular |
+| Item border | 1px solid |
+| Shadow | 0 4px 20px rgba(0,0,0,0.4) |
+
+## CSS Recipe
+
+### Container (`.radial-menu`)
+```css
+.radial-menu {
+  width: 140px; height: 140px; border-radius: 50%;
+  background: var(--bg-raised); border: 2px solid var(--border-mid);
+  box-shadow: 0 4px 20px rgba(0,0,0,0.4); position: relative;
+}
+```
+
+### Item (`.radial-menu-item`)
+```css
+.radial-menu-item {
+  position: absolute; width: 36px; height: 36px; border-radius: 50%;
+  background: var(--bg-surface); border: 1px solid var(--border-subtle);
+  display: flex; align-items: center; justify-content: center;
+  font-size: 14px; color: var(--text-secondary); cursor: pointer;
+  transition: background 0.12s, color 0.12s;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.2);
+}
+```
+
+### Hover
+```css
+.radial-menu-item:hover { background: var(--bg-panel); color: var(--amber); }
+```
+
+## HTML Structure
+```html
+<div class="radial-menu">
+  <div class="radial-menu-item" style="top:8px;left:50%;transform:translateX(-50%)">&#9733;</div>
+  <div class="radial-menu-item" style="top:50%;right:8px;transform:translateY(-50%)">&#9998;</div>
+  <div class="radial-menu-item" style="bottom:8px;left:50%;transform:translateX(-50%)">&#128465;</div>
+  <div class="radial-menu-item" style="top:50%;left:8px;transform:translateY(-50%)">&#128269;</div>
+</div>
+```
+
+## Size Variants
+No size variants defined.
+
+## Material Variants
+No material variants. Uses standard raised surface with elevated shadow.
+
+## Theme Behavior
+- Background swaps via `--bg-raised`
+- Item backgrounds swap via `--bg-surface`
+- Hover always uses amber accent
+- Shadow reduces in light mode
+
+## Constraints
+1. MUST use circular container (border-radius: 50%)
+2. Items MUST be positioned at cardinal/ordinal points using absolute positioning
+3. MUST support 4-8 items maximum (more becomes unusable)
+4. Items MUST be circular buttons (border-radius: 50%)
+5. Hover MUST highlight item in amber
+6. MUST use elevated shadow to indicate floating overlay context
+7. Container border MUST be 2px (thicker than standard 1px to define the ring)
+
+## Accessibility
+- Container should have `role="menu"`
+- Items should have `role="menuitem"` with descriptive `aria-label`
+- Support arrow key navigation between items (mapped to positions)
+- Escape key should dismiss the menu
+- Menu should trap focus while open

package/spec/components/navigation/d-pad.md

@@ -0,0 +1,121 @@
+---
+name: D-Pad
+id: d-pad
+class: .dpad
+category: navigation
+index: 4
+materials: [rubber]
+sizes: [default]
+interactive: true
+requires_js: false
+canvas: false
+---
+
+# D-Pad
+
+## Physical Analog
+**Reference devices**: Game Boy Advance, Nintendo DS, Sony PSP, Nokia N-Gage.
+**Mechanism**: A cross-shaped rocker pad (directional pad). The D-pad is a single injection-molded plastic cross that sits over four individual dome switches arranged at the cardinal points. The cross pivots on a central post -- pressing one arm tilts the cross to actuate the dome switch beneath that arm. The other arms lift slightly. Only one dome switch can be activated at a time in a pure D-pad design (some allow diagonals by pressing two adjacent arms).
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Container | 110x110px, position relative |
+| Arm width (up/down) | 26x22px |
+| Arm width (left/right) | 22x26px |
+| Center button | 24x24px, circular |
+| Travel | 1px in pressed direction |
+| Cross span | ~20mm arm-to-arm |
+| Arm material | Rubber (matte) |
+
+## CSS Recipe
+
+### Container (`.dpad`)
+```css
+.dpad { width: 110px; height: 110px; position: relative; }
+```
+
+### Arms (`.dpad-arm`)
+```css
+.dpad-arm {
+  position: absolute; border: none; cursor: pointer;
+  background: linear-gradient(180deg, var(--rubber-hi), var(--rubber-bg));
+  box-shadow: 0 2px 0 var(--border-deep), inset 0 1px 0 rgba(255,255,255,0.08);
+  display: flex; align-items: center; justify-content: center;
+  color: var(--text-muted); font-size: 12px;
+  transition: transform 0.05s, box-shadow 0.05s, color 0.1s;
+}
+```
+
+### Active (pressed)
+```css
+.dpad-arm:active { box-shadow: 0 1px 0 var(--border-deep); color: var(--blue-info); }
+```
+
+### Directional positioning
+```css
+.dpad-arm.up { top: 0; left: 50%; transform: translateX(-50%); width: 26px; height: 22px; border-radius: 4px 4px 0 0; }
+.dpad-arm.down { bottom: 0; left: 50%; transform: translateX(-50%); width: 26px; height: 22px; border-radius: 0 0 4px 4px; }
+.dpad-arm.left { left: 0; top: 50%; transform: translateY(-50%); width: 22px; height: 26px; border-radius: 4px 0 0 4px; }
+.dpad-arm.right { right: 0; top: 50%; transform: translateY(-50%); width: 22px; height: 26px; border-radius: 0 4px 4px 0; }
+```
+
+### Directional press animations
+```css
+.dpad-arm.up:active { transform: translateX(-50%) translateY(1px); }
+.dpad-arm.down:active { transform: translateX(-50%) translateY(-1px); }
+.dpad-arm.left:active { transform: translateY(-50%) translateX(1px); }
+.dpad-arm.right:active { transform: translateY(-50%) translateX(-1px); }
+```
+
+### Center button (`.dpad-center`)
+```css
+.dpad-center {
+  position: absolute; top: 50%; left: 50%; transform: translate(-50%,-50%);
+  width: 24px; height: 24px; border-radius: 50%;
+  background: linear-gradient(155deg, var(--bg-surface), var(--bg-panel));
+  box-shadow: 0 1px 3px rgba(0,0,0,0.3), inset 0 1px 0 var(--glossy-hi);
+  border: none; cursor: pointer; z-index: 2;
+  transition: transform 0.07s var(--snap-fast);
+}
+.dpad-center:active { transform: translate(-50%,-50%) scale(0.9); }
+```
+
+## HTML Structure
+```html
+<div class="dpad">
+  <button class="dpad-arm up">&#9650;</button>
+  <button class="dpad-arm down">&#9660;</button>
+  <button class="dpad-arm left">&#9664;</button>
+  <button class="dpad-arm right">&#9654;</button>
+  <button class="dpad-center"></button>
+</div>
+```
+
+## Size Variants
+No size variants defined. Single default size matching Game Boy proportions.
+
+## Material Variants
+- Arms use rubber material (matte, `--rubber-hi`/`--rubber-bg` gradient)
+- Center button uses glossy polycarbonate (brighter highlight, `--glossy-hi`)
+
+## Theme Behavior
+- Rubber tokens swap: dark `#3a3835`/`#2a2826`, light `#d8d4cc`/`#c8c4bc`
+- Center button adapts via surface/panel tokens
+- Shadow depth reduces in light mode
+
+## Constraints
+1. MUST press in the direction of the arrow (up arm moves down 1px, etc.)
+2. MUST use rubber material gradient on arms (matte, low highlight opacity 0.08)
+3. Center button MUST be circular and use glossy material
+4. Center button MUST sit at z-index 2 above the arms
+5. Arms MUST have rounded corners only on their outward-facing edges
+6. MUST NOT allow more than one arm to appear pressed simultaneously (pure D-pad)
+7. Travel MUST be exactly 1px in the pressed direction
+
+## Accessibility
+- Each arm should be a `<button>` element
+- Arms should have `aria-label` describing direction ("Up", "Down", "Left", "Right")
+- Center button should have `aria-label="Select"`
+- Support keyboard arrow keys mapped to corresponding arm actions

package/spec/components/navigation/drawer.md

@@ -0,0 +1,103 @@
+---
+name: Drawer
+id: drawer
+class: .drawer-demo
+category: navigation
+index: 11
+materials: [glossy-polycarbonate]
+sizes: [default]
+interactive: true
+requires_js: true
+canvas: false
+---
+
+# Drawer
+
+## Physical Analog
+**Reference devices**: Sliding tray mechanisms on CD players, cassette deck tape compartment doors, rack-mount equipment sliding rails.
+**Mechanism**: A panel that slides linearly from a hidden position to a visible one, typically from the right edge. Derived from the sliding tray mechanism in optical disc players -- a motorized tray extends from the device chassis on linear bearings. The transition uses `--snap-soft` easing to simulate the damped slide-and-settle motion of a tray reaching its stop position.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Demo container | 280x160px |
+| Panel width | 180px |
+| Panel padding | 12px |
+| Title font size | 9px |
+| Slide duration | 0.3s |
+| Easing | `--snap-soft` |
+
+## CSS Recipe
+
+### Container (`.drawer-demo`)
+```css
+.drawer-demo {
+  position: relative; width: 280px; height: 160px;
+  background: var(--bg-inset); border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-md); overflow: hidden;
+}
+```
+
+### Panel (`.drawer-panel`)
+```css
+.drawer-panel {
+  position: absolute; top: 0; right: -180px; width: 180px; height: 100%;
+  background: var(--bg-raised); border-left: 1px solid var(--border-mid);
+  box-shadow: -4px 0 12px rgba(0,0,0,0.3);
+  transition: right 0.3s var(--snap-soft); padding: 12px; z-index: 2;
+}
+```
+
+### Open state
+```css
+.drawer-demo.open .drawer-panel { right: 0; }
+```
+
+### Title (`.drawer-panel-title`)
+```css
+.drawer-panel-title { font-family: var(--font-ui); font-size: 9px; font-weight: 600; letter-spacing: 2px; color: var(--text-muted); margin-bottom: 10px; }
+```
+
+## HTML Structure
+```html
+<div class="drawer-demo" id="drawerDemo">
+  <div style="padding:12px">
+    <button class="push-btn xs" onclick="document.getElementById('drawerDemo').classList.toggle('open')">OPEN</button>
+  </div>
+  <div class="drawer-panel">
+    <div class="drawer-panel-title">SETTINGS</div>
+    <div class="flex-col" style="gap:8px">
+      <!-- drawer content here -->
+    </div>
+  </div>
+</div>
+```
+
+## Size Variants
+No size variants defined.
+
+## Material Variants
+No material variants. Panel uses raised surface, container uses recessed inset.
+
+## Theme Behavior
+- Container background uses `--bg-inset` (recessed cavity)
+- Panel background uses `--bg-raised` (sliding tray surface)
+- Shadow on panel left edge provides depth separation
+- Shadow reduces in light mode
+
+## Constraints
+1. MUST slide from right edge using `right` property animation
+2. MUST use `--snap-soft` easing (damped slide, not linear or bouncy)
+3. Transition duration MUST be 0.3s (250-350ms range for larger movements)
+4. Panel MUST have left border and left shadow for edge definition
+5. MUST use `overflow: hidden` on container to clip the hidden panel
+6. Panel MUST be at z-index 2 to overlay container content
+7. MUST toggle via `.open` class on the container element
+
+## Accessibility
+- Drawer trigger should indicate expanded state: `aria-expanded="true/false"`
+- Drawer panel should have `role="dialog"` or `role="complementary"`
+- Focus should move to drawer content when opened
+- Escape key should close the drawer
+- Focus should return to trigger when drawer closes

package/spec/components/navigation/menu-grid.md

@@ -0,0 +1,113 @@
+---
+name: Menu Grid
+id: menu-grid
+class: .menu-grid
+category: navigation
+index: 1
+materials: [glossy-polycarbonate]
+sizes: [default]
+interactive: true
+requires_js: false
+canvas: false
+---
+
+# Menu Grid
+
+## Physical Analog
+**Reference devices**: Nokia Series 40 app menu, Sony Ericsson main menu, Samsung SGH series phone menus.
+**Mechanism**: A matrix navigation pattern originating from feature phone operating systems. The 3x3 grid (or 3x4) maps to the phone's numeric keypad -- press 1 for the top-left app, 2 for top-center, etc. Each cell contains an icon and a short label. The grid is navigated via the D-pad with a visual highlight showing the currently selected cell.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Grid | 3-column via `repeat(3, 1fr)` |
+| Gap | 6px |
+| Wrapper max-width | 200px |
+| Wrapper padding | 12px |
+| Item padding | 10px 6px |
+| Icon size | 24x24px |
+
+## CSS Recipe
+
+### Wrapper (`.menu-grid-wrap`)
+```css
+.menu-grid-wrap {
+  display: flex; flex-direction: column;
+  background: var(--bg-raised); border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-lg); padding: 12px;
+  box-shadow: var(--shadow-deep); max-width: 200px;
+}
+```
+
+### Grid (`.menu-grid`)
+```css
+.menu-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 6px; }
+```
+
+### Item (`.menu-grid-item`)
+```css
+.menu-grid-item {
+  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  gap: 4px; padding: 10px 6px; border-radius: var(--radius-md);
+  cursor: pointer; transition: background 0.12s;
+  font-family: var(--font-ui); font-size: 8px; font-weight: 500;
+  color: var(--text-muted); letter-spacing: 1px;
+}
+```
+
+### Hover
+```css
+.menu-grid-item:hover { background: var(--glow-color); }
+```
+
+### Active
+```css
+.menu-grid-item.active { background: var(--glow-color); color: var(--blue-info); }
+```
+
+### Icon (`.mgi-icon`)
+```css
+.menu-grid-item .mgi-icon {
+  width: 24px; height: 24px; border-radius: var(--radius-sm);
+  display: flex; align-items: center; justify-content: center; font-size: 14px;
+}
+```
+
+## HTML Structure
+```html
+<div class="menu-grid-wrap">
+  <div class="menu-grid">
+    <div class="menu-grid-item active"><div class="mgi-icon">&#9742;</div>PHONE</div>
+    <div class="menu-grid-item"><div class="mgi-icon">&#9993;</div>MSG</div>
+    <div class="menu-grid-item"><div class="mgi-icon">&#9881;</div>SET</div>
+    <div class="menu-grid-item"><div class="mgi-icon">&#9835;</div>MUSIC</div>
+    <div class="menu-grid-item"><div class="mgi-icon">&#128247;</div>CAM</div>
+    <div class="menu-grid-item"><div class="mgi-icon">&#127760;</div>WEB</div>
+  </div>
+</div>
+```
+
+## Size Variants
+No size variants defined. Single default size.
+
+## Material Variants
+No material variants. Uses standard raised panel surface (`--bg-raised`).
+
+## Theme Behavior
+- Wrapper background swaps via `--bg-raised` token (dark: `#1c1a18`, light: `#ffffff`)
+- Shadow depth reduces in light mode via `--shadow-deep` token
+- Text and border colors swap via theme tokens
+
+## Constraints
+1. MUST use 3-column grid layout to match phone keypad mapping
+2. MUST NOT exceed 200px max-width (phone screen proportion)
+3. MUST use `--radius-lg` on wrapper to match device bezel curvature
+4. MUST show hover background highlight using `--glow-color`
+5. Active item MUST use `--blue-info` color (iPod-era selection blue)
+
+## Accessibility
+- Each grid item should be a `<button>` or have `role="menuitem"`
+- Container should have `role="menu"` or `role="grid"`
+- Support arrow key navigation between grid items
+- Active item should have `aria-current="true"`

package/spec/components/navigation/menu-list.md

@@ -0,0 +1,134 @@
+---
+name: Menu List
+id: menu-list
+class: .menu-list-wrap
+category: navigation
+index: 2
+materials: [glossy-polycarbonate, glass]
+sizes: [default]
+interactive: true
+requires_js: false
+canvas: false
+---
+
+# Menu List
+
+## Physical Analog
+**Reference devices**: iPod Classic menu system, iPod Nano list navigation.
+**Mechanism**: A scrolling list with arrow indicators -- the core navigation pattern of the iPod. Items are listed vertically with right-pointing chevrons indicating that selecting the item will navigate to a sub-menu. The currently selected item is highlighted with a blue/translucent bar. The Click Wheel scrolls the selection highlight up and down; the center button selects.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Min width | 200px |
+| Title padding | 8px 14px |
+| Item padding | 8px 14px |
+| Border radius | `--radius-lg` (14px) |
+| Title font size | 9px |
+| Item font size | 11px |
+
+## CSS Recipe
+
+### Wrapper (`.menu-list-wrap`)
+```css
+.menu-list-wrap {
+  background: linear-gradient(180deg, rgba(255,255,255,0.04), rgba(255,255,255,0.02));
+  border: 1px solid var(--border-subtle); border-radius: var(--radius-lg);
+  overflow: hidden; box-shadow: var(--shadow-deep); min-width: 200px;
+}
+```
+
+### Light theme override
+```css
+[data-theme="light"] .menu-list-wrap { background: var(--bg-raised); }
+```
+
+### Title (`.menu-list-title`)
+```css
+.menu-list-title {
+  padding: 8px 14px;
+  background: linear-gradient(180deg, var(--bg-surface), var(--bg-panel));
+  border-bottom: 1px solid var(--border-subtle);
+  font-family: var(--font-ui); font-size: 9px; font-weight: 600;
+  letter-spacing: 2px; color: var(--text-muted); text-transform: uppercase;
+}
+```
+
+### Item (`.menu-list-item`)
+```css
+.menu-list-item {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 8px 14px; cursor: pointer;
+  border-bottom: 1px solid rgba(128,128,128,0.06); transition: background 0.1s;
+}
+.menu-list-item:last-child { border-bottom: none; }
+```
+
+### Hover
+```css
+.menu-list-item:hover { background: var(--glow-color); }
+```
+
+### Active
+```css
+.menu-list-item.active {
+  background: linear-gradient(90deg, rgba(68,119,204,0.12), transparent);
+  color: var(--blue-info);
+}
+```
+
+### Sub-elements
+```css
+.mli-label { font-family: var(--font-ui); font-size: 11px; font-weight: 500; color: var(--text-primary); letter-spacing: 0.5px; }
+.mli-arrow { color: var(--text-muted); font-size: 10px; }
+```
+
+## HTML Structure
+```html
+<div class="menu-list-wrap">
+  <div class="menu-list-title">MUSIC</div>
+  <div class="menu-list-item active">
+    <span class="mli-label">Now Playing</span>
+    <span class="mli-arrow">&#9654;</span>
+  </div>
+  <div class="menu-list-item">
+    <span class="mli-label">Artists</span>
+    <span class="mli-arrow">&#9654;</span>
+  </div>
+  <div class="menu-list-item">
+    <span class="mli-label">Albums</span>
+    <span class="mli-arrow">&#9654;</span>
+  </div>
+  <div class="menu-list-item">
+    <span class="mli-label">Playlists</span>
+    <span class="mli-arrow">&#9654;</span>
+  </div>
+</div>
+```
+
+## Size Variants
+No size variants defined. Single default size.
+
+## Material Variants
+No material variants. Uses subtle translucent gradient in dark mode, solid raised surface in light mode.
+
+## Theme Behavior
+- Dark mode: translucent gradient background (`rgba(255,255,255,0.04)` to `0.02`)
+- Light mode: solid `--bg-raised` background
+- Active item uses blue-tinted left gradient in both themes
+- Shadow depth reduces in light mode
+
+## Constraints
+1. MUST include right-pointing chevron arrow on each navigable item
+2. MUST use horizontal blue gradient for active/selected item (iPod selection style)
+3. MUST NOT use opaque backgrounds in dark mode -- the subtle translucency is key
+4. MUST include a title bar with raised gradient background
+5. Item separators MUST be very subtle (`rgba(128,128,128,0.06)`)
+
+## Accessibility
+- Container should have `role="menu"` or `role="listbox"`
+- Items should have `role="menuitem"` or `role="option"`
+- Active item should have `aria-selected="true"`
+- Support Up/Down arrow key navigation
+- Support Enter to select

package/spec/components/navigation/pagination.md

@@ -0,0 +1,100 @@
+---
+name: Pagination
+id: pagination
+class: .pagination
+category: navigation
+index: 8
+materials: [glossy-polycarbonate]
+sizes: [default]
+interactive: true
+requires_js: false
+canvas: false
+---
+
+# Pagination
+
+## Physical Analog
+**Reference devices**: Track/channel number selectors on tape machines, CD changers.
+**Mechanism**: Numbered buttons resembling track select buttons on multi-track tape machines or CD changers. Each button represents a page/track, with the active one highlighted.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Button size | 28x28px |
+| Gap | 4px |
+| Border radius | `--radius-sm` (4px) |
+| Font size | 11px |
+| Bottom shadow | 1px |
+
+## CSS Recipe
+
+### Container (`.pagination`)
+```css
+.pagination { display: flex; gap: 4px; }
+```
+
+### Page Button (`.page-btn`)
+```css
+.page-btn {
+  width: 28px; height: 28px; border-radius: var(--radius-sm);
+  background: var(--bg-surface); border: 1px solid var(--border-subtle);
+  display: flex; align-items: center; justify-content: center;
+  font-family: var(--font-mono); font-size: 11px; color: var(--text-secondary);
+  cursor: pointer; transition: all 0.12s;
+  box-shadow: 0 1px 0 var(--border-deep);
+}
+```
+
+### Hover
+```css
+.page-btn:hover { color: var(--text-primary); border-color: var(--border-mid); }
+```
+
+### Active (pressed)
+```css
+.page-btn:active { transform: translateY(1px); box-shadow: none; }
+```
+
+### Active (selected page)
+```css
+.page-btn.active { color: var(--amber); border-color: var(--amber-dim); background: rgba(245,166,35,0.08); }
+```
+
+## HTML Structure
+```html
+<div class="pagination">
+  <button class="page-btn">&#9664;</button>
+  <button class="page-btn">1</button>
+  <button class="page-btn active">2</button>
+  <button class="page-btn">3</button>
+  <button class="page-btn">4</button>
+  <button class="page-btn">&#9654;</button>
+</div>
+```
+
+## Size Variants
+No size variants defined.
+
+## Material Variants
+No material variants. Uses Tier 1 (flush) raised depth model.
+
+## Theme Behavior
+- Button backgrounds swap via `--bg-surface`
+- Border colors swap via `--border-subtle`
+- Active page uses amber tint in both themes
+- Shadow depth adapts via `--border-deep`
+
+## Constraints
+1. MUST use monospace font for page numbers (data readout convention)
+2. Active page MUST use amber color with amber-dim border and amber-tinted background
+3. Buttons MUST be square (28x28px)
+4. Press travel MUST be 1px with shadow collapse (Tier 1 depth model)
+5. MUST include prev/next arrow buttons (&#9664; / &#9654;)
+6. MUST use `--radius-sm` (not pill or round) to match small hardware buttons
+
+## Accessibility
+- Container should have `role="navigation"` and `aria-label="Pagination"`
+- Active page: `aria-current="page"`
+- Previous/Next buttons: `aria-label="Previous page"` / `aria-label="Next page"`
+- Disabled nav buttons should have `aria-disabled="true"`