@pudge-ui/mcp-server 0.1.0

package/spec/components/toggles/radio-button.md

@@ -0,0 +1,106 @@
+---
+name: Radio Button
+id: radio-wrap
+class: .radio-wrap
+category: toggles
+index: 7
+materials: [panel, phosphor]
+sizes: [md]
+interactive: true
+requires_js: true
+canvas: false
+---
+
+# Radio Button
+
+## Physical Analog
+**Reference devices**: Camera drive mode selector (single/continuous/timer), tape deck speed selector (3.75/7.5 IPS), synthesizer waveform selector.
+**Mechanism**: Rotary detented selector adapted to linear layout. Mutually exclusive options with circular indicator dot within recessed ring -- resembling sighting dot on a rotary selector's face that aligns with position markings.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Outer ring | 18x18px, circular |
+| Inner dot | 8x8px, circular |
+| Border width | 2px on outer ring |
+| Gap to label | 8px |
+
+## CSS Recipe
+
+### Container
+```css
+.radio-wrap { display: inline-flex; align-items: center; gap: 8px; cursor: pointer; user-select: none; }
+```
+
+### Outer Ring (Selector Housing)
+```css
+.radio-dot-outer {
+  width: 18px; height: 18px; border-radius: 50%;
+  background: var(--bg-inset); border: 2px solid var(--border-mid);
+  display: flex; align-items: center; justify-content: center;
+  box-shadow: inset 0 1px 3px rgba(0,0,0,0.4);
+  transition: border-color 0.15s, box-shadow 0.15s;
+}
+```
+
+### Inner Dot (Indicator)
+```css
+.radio-dot-inner {
+  width: 8px; height: 8px; border-radius: 50%;
+  background: transparent; transition: background 0.15s, box-shadow 0.15s;
+}
+```
+
+### Selected State
+```css
+.radio-dot-outer.selected { border-color: var(--amber); box-shadow: inset 0 1px 2px rgba(0,0,0,0.2), 0 0 6px var(--amber-glow); }
+.radio-dot-outer.selected .radio-dot-inner { background: var(--amber); box-shadow: 0 0 6px var(--amber-glow); }
+```
+
+### Label
+```css
+.radio-label { font-family: var(--font-ui); font-size: 11px; font-weight: 500; color: var(--text-secondary); letter-spacing: 0.5px; }
+```
+
+## HTML Structure
+```html
+<div data-radio-group>
+  <label class="radio-wrap">
+    <div class="radio-dot-outer selected"><div class="radio-dot-inner"></div></div>
+    <span class="radio-label">Single Shot</span>
+  </label>
+  <label class="radio-wrap">
+    <div class="radio-dot-outer"><div class="radio-dot-inner"></div></div>
+    <span class="radio-label">Continuous Hi</span>
+  </label>
+  <label class="radio-wrap">
+    <div class="radio-dot-outer"><div class="radio-dot-inner"></div></div>
+    <span class="radio-label">Timer 10s</span>
+  </label>
+</div>
+```
+
+## Size Variants
+No explicit size variants defined.
+
+## Material Variants
+- Outer ring: Recessed selector housing (bg-inset)
+- Inner dot: Illuminated indicator (amber when selected, transparent when not)
+
+## Theme Behavior
+- Outer ring background and border swap via tokens
+- Selected state amber glow is fixed across themes
+- Inset shadow adapts via tokens
+
+## Constraints
+1. Only ONE radio in a group can be `.selected` at a time (mutually exclusive).
+2. Inner dot MUST be transparent when not selected.
+3. Selected state MUST include amber glow on both outer ring and inner dot.
+4. Outer ring uses 2px border (thicker than checkbox's 1px) for circular housing.
+
+## Accessibility
+- Wrap group in `[data-radio-group]` with `role="radiogroup"`
+- Each option uses `role="radio"` with `aria-checked`
+- Keyboard: Arrow keys to navigate within group, Space to select
+- Requires JS to manage mutual exclusion (toggle `.selected` between items)

package/spec/components/toggles/rocker-switch.md

@@ -0,0 +1,92 @@
+---
+name: Rocker Switch
+id: rocker
+class: .rocker
+category: toggles
+index: 3
+materials: [panel]
+sizes: [md]
+interactive: true
+requires_js: false
+canvas: false
+---
+
+# Rocker Switch
+
+## Physical Analog
+**Reference devices**: Nokia phone side volume rocker, iPod volume buttons, Sony Ericsson volume control.
+**Mechanism**: SPST momentary rocker switch -- elongated button pivots around central fulcrum. Pressing top tilts forward, pressing bottom tilts backward. Each end sits over its own dome switch. Momentary action -- springs back to center when released.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Body | 36x52px, elongated rectangle |
+| Split | Central dividing line between halves |
+| Pivot | Internal see-saw with spring-loaded center pivot |
+| Travel | 1-2 degrees from center each direction |
+| Mounting | Side-mounted, flush or slightly proud |
+
+## CSS Recipe
+
+### Container
+```css
+.rocker {
+  display: flex; flex-direction: column;
+  width: 36px; height: 52px; border-radius: var(--radius-sm);
+  overflow: hidden; border: 1px solid var(--border-deep);
+  box-shadow: 0 1px 0 var(--glossy-hi);
+}
+```
+
+### Button Halves
+```css
+.rocker-btn {
+  flex: 1; display: flex; align-items: center; justify-content: center;
+  background: linear-gradient(180deg, var(--bg-surface), var(--bg-panel));
+  border: none; cursor: pointer; color: var(--text-muted); font-size: 10px;
+  transition: background 0.1s;
+}
+```
+
+### Active (Pressed) State
+```css
+.rocker-btn:active { background: var(--bg-inset); color: var(--text-primary); }
+```
+
+### Split Line (Plus Half)
+```css
+.rocker-btn.plus { border-bottom: 1px solid var(--border-deep); }
+```
+
+## HTML Structure
+```html
+<div class="rocker">
+  <button class="rocker-btn plus">+</button>
+  <button class="rocker-btn minus">&minus;</button>
+</div>
+```
+
+## Size Variants
+No explicit size variants defined.
+
+## Material Variants
+Default panel material for both halves.
+
+## Theme Behavior
+- Surface gradients swap via tokens
+- Border colors swap via `--border-deep`
+- Pressed state uses `--bg-inset` (recessed appearance)
+
+## Constraints
+1. Two halves MUST be separate `<button>` elements stacked vertically.
+2. Split line (`border-bottom: 1px solid border-deep`) on top half creates visible pivot point.
+3. Each half MUST press independently (`:active` on each).
+4. Rocker is MOMENTARY -- no persistent state, springs back to neutral.
+5. `overflow: hidden` is required to clip the border-radius to the container.
+
+## Accessibility
+- Uses native `<button>` elements for each half
+- Keyboard: Enter/Space to activate focused half
+- ARIA: Container could use `role="group"` with `aria-label="Volume"`
+- Each button should have `aria-label` ("Volume up", "Volume down")

package/spec/components/toggles/slide-switch.md

@@ -0,0 +1,121 @@
+---
+name: Slide Switch
+id: slide-track
+class: .slide-track
+category: toggles
+index: 2
+materials: [panel, glossy]
+sizes: [md]
+interactive: true
+requires_js: true
+canvas: false
+---
+
+# Slide Switch
+
+## Physical Analog
+**Reference devices**: iPod Classic hold switch, iPhone original silent/ring switch, Sony Walkman play/hold slider.
+**Mechanism**: Functionally identical to toggle switch (SPDT wiper contact) but with larger, more ergonomic sliding element designed for finger operation (not thumbnail). iPod hold switch used gold-colored metal slider in milled aluminum channel.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Track | 52x26px (larger than toggle's 46x22px) |
+| Thumb | 20px diameter (larger than toggle's 16px) |
+| Border-radius | 13px (half of height) |
+| Travel | 26px (left: 2px to left: 28px) |
+
+## CSS Recipe
+
+### Container
+```css
+.slide-switch { display: flex; flex-direction: column; align-items: center; gap: 4px; cursor: pointer; user-select: none; }
+```
+
+### Track
+```css
+.slide-track {
+  width: 52px; height: 26px; border-radius: 13px;
+  background: var(--bg-inset); border: 1px solid var(--border-subtle);
+  position: relative; transition: background 0.2s, border-color 0.2s;
+  box-shadow: var(--shadow-inset);
+}
+```
+
+### Track ON State
+```css
+.slide-track.on { background: linear-gradient(180deg, #1a2a1a, #0d1a0d); border-color: var(--green-on); }
+[data-theme="light"] .slide-track.on { background: linear-gradient(180deg, #c0e8c0, #a0d8a0); border-color: #66bb66; }
+```
+
+### Thumb
+```css
+.slide-thumb {
+  position: absolute; top: 2px; left: 2px;
+  width: 20px; height: 20px; 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);
+  transition: left 0.18s var(--snap-fast), background 0.2s;
+}
+```
+
+### Thumb ON State
+```css
+.slide-track.on .slide-thumb {
+  left: 28px;
+  background: linear-gradient(155deg, #66ff66, #228833);
+  box-shadow: 0 1px 3px rgba(0,0,0,0.3), 0 0 8px var(--green-glow);
+}
+```
+
+### Label
+```css
+.slide-label {
+  font-family: var(--font-ui); font-size: 9px; font-weight: 500;
+  letter-spacing: 1px; color: var(--text-muted);
+}
+.slide-track.on ~ .slide-label { color: var(--green-on); }
+```
+
+## HTML Structure
+```html
+<div class="slide-switch" data-toggle>
+  <div class="slide-track">
+    <div class="slide-thumb"></div>
+  </div>
+  <span class="slide-label">SILENT</span>
+</div>
+
+<!-- ON state -->
+<div class="slide-switch" data-toggle>
+  <div class="slide-track on">
+    <div class="slide-thumb"></div>
+  </div>
+  <span class="slide-label">RING</span>
+</div>
+```
+
+## Size Variants
+No explicit size variants defined. Key difference from toggle-switch is the larger default size.
+
+## Material Variants
+- Track: Recessed panel
+- Thumb OFF: Panel surface gradient with glossy highlight
+- Thumb ON: Bright green gradient with glow
+
+## Theme Behavior
+- Dark ON track: `linear-gradient(180deg, #1a2a1a, #0d1a0d)` with green border
+- Light ON track: `linear-gradient(180deg, #c0e8c0, #a0d8a0)` with lighter green border
+- Thumb uses surface tokens, adapting automatically
+
+## Constraints
+1. Track MUST be 52x26px -- larger than toggle for thumb/finger operation.
+2. Thumb MUST be 20px (not 16px like toggle) for ergonomic blind operation.
+3. Slide transition MUST be 0.18s (slightly slower than toggle's 0.15s).
+4. ON state track MUST use a gradient (not flat color) unlike the simpler toggle.
+
+## Accessibility
+- Add `tabindex="0"` and `role="switch"` with `aria-checked`
+- Keyboard: Space to toggle
+- Requires JS to toggle `.on` class

package/spec/components/toggles/toggle-switch.md

@@ -0,0 +1,135 @@
+---
+name: Toggle Switch
+id: toggle-track
+class: .toggle-track
+category: toggles
+index: 1
+materials: [panel, chrome]
+sizes: [md]
+interactive: true
+requires_js: true
+canvas: false
+---
+
+# Toggle Switch
+
+## Physical Analog
+**Reference devices**: Nikon lens VR switch (ON/OFF), Sony Alpha AF/MF toggle, Canon EOS stabilizer switch.
+**Mechanism**: SPDT slide switch (Single Pole, Double Throw). Plastic or metal slider moves linearly along a track between two positions. Metal wiper contact bridges different PCB trace pairs. Ball-and-spring detent mechanism holds slider in each position with positive click.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Track | 46x22px, milled rectangular channel, 2-3mm deep |
+| Thumb | 16px diameter, 4-5mm protruding above track |
+| Travel | 24px (left: 2px to left: 26px) |
+| Detent force | 100-200gf |
+
+## CSS Recipe
+
+### Track (Container)
+```css
+.toggle-track {
+  width: 46px; height: 22px; border-radius: 11px;
+  background: var(--bg-inset); border: 1px solid var(--border-subtle);
+  position: relative; transition: background 0.2s, border-color 0.2s;
+  box-shadow: inset 0 1px 4px rgba(0,0,0,0.4);
+}
+```
+
+### Track ON State
+```css
+.toggle-track.on { background: #0d1a0d; border-color: #1a4a1a; }
+[data-theme="light"] .toggle-track.on { background: #d0f0d0; border-color: #88cc88; }
+```
+
+### Thumb (Slider Knob)
+```css
+.toggle-thumb {
+  position: absolute; top: 2px; left: 2px;
+  width: 16px; height: 16px; border-radius: 50%;
+  background: linear-gradient(155deg, #585858, #2a2a2a);
+  box-shadow: 0 1px 3px rgba(0,0,0,0.5), inset 0 1px 0 #686868;
+  transition: left 0.15s var(--snap-fast), background 0.2s, box-shadow 0.2s;
+}
+```
+
+### Thumb Light Theme
+```css
+[data-theme="light"] .toggle-thumb {
+  background: linear-gradient(155deg, #eee, #ccc);
+  box-shadow: 0 1px 3px rgba(0,0,0,0.15), inset 0 1px 0 #fff;
+}
+```
+
+### Thumb ON State
+```css
+.toggle-track.on .toggle-thumb {
+  left: 26px;
+  background: linear-gradient(155deg, var(--green-hi), var(--green-on));
+  box-shadow: 0 1px 3px rgba(0,0,0,0.5), inset 0 1px 0 #aaff99, 0 0 8px var(--green-glow);
+}
+```
+
+### Label
+```css
+.toggle-label {
+  font-size: 8px; letter-spacing: 2px; color: var(--text-muted);
+  transition: color 0.2s; text-transform: uppercase;
+  font-family: var(--font-ui); font-weight: 500;
+}
+.toggle-track.on ~ .toggle-label { color: var(--green-on); }
+```
+
+### Wrapper
+```css
+.toggle-wrap {
+  display: flex; flex-direction: column; align-items: center;
+  gap: 6px; cursor: pointer;
+}
+```
+
+## HTML Structure
+```html
+<div class="toggle-wrap" data-toggle>
+  <div class="toggle-track">
+    <div class="toggle-thumb"></div>
+  </div>
+  <span class="toggle-label">OFF</span>
+</div>
+
+<!-- ON state -->
+<div class="toggle-wrap" data-toggle>
+  <div class="toggle-track on">
+    <div class="toggle-thumb"></div>
+  </div>
+  <span class="toggle-label">STAB</span>
+</div>
+```
+
+## Size Variants
+No explicit size variants defined.
+
+## Material Variants
+- Track: Recessed panel material
+- Thumb OFF: Metallic gradient (dome catching light from upper-left)
+- Thumb ON: Green gradient with green glow (embedded status LED)
+
+## Theme Behavior
+- Dark OFF thumb: `linear-gradient(155deg, #585858, #2a2a2a)` with strong shadow
+- Light OFF thumb: `linear-gradient(155deg, #eee, #ccc)` with softer shadow
+- Dark ON track: `#0d1a0d` (dark green)
+- Light ON track: `#d0f0d0` (light green)
+
+## Constraints
+1. Thumb travel MUST be exactly `left: 2px` (OFF) to `left: 26px` (ON) -- 24px travel.
+2. Detent snap MUST use `--snap-fast` easing (overshoot simulates detent spring).
+3. ON state thumb MUST include green glow (`0 0 8px var(--green-glow)`) for LED effect.
+4. Track border-radius MUST be half of height (11px) for capsule shape.
+5. Inset shadow on track MUST be `rgba(0,0,0,0.4)` -- shallow recess.
+
+## Accessibility
+- Add `tabindex="0"` and `role="switch"` with `aria-checked` on toggle-wrap
+- Keyboard: Space to toggle
+- Requires JS to toggle `.on` class on track

package/spec/compositions/audio-mixer-strip.md

@@ -0,0 +1,62 @@
+---
+name: Audio Mixer Strip
+id: audio-mixer-strip
+components: [radial-knob, vu-meter, vertical-fader, led-dots, mode-badge]
+materials: [default, metal]
+---
+
+# Audio Mixer Strip
+
+## Description
+
+A vertical channel strip from a mixing console. Multiple strips are placed side by side to form a mixer bank. Each strip contains a pan knob, VU meter, channel fader, channel label, and solo/mute LED indicator.
+
+## Reference Devices
+
+Mackie 1604-VLZ Pro, SSL Duality, Neve 5088, Yamaha 02R, Behringer X32 (channel strip section).
+
+## Layout
+
+```
+┌──────┐  ┌──────┐  ┌──────┐
+│ (PAN)│  │ (PAN)│  │ (PAN)│    ← radial-knob (40x40px)
+│      │  │      │  │      │
+│ ██   │  │ ██   │  │ ██   │    ← vu-meter (2 bars per channel)
+│ ██   │  │ ██   │  │ ██   │
+│      │  │      │  │      │
+│ ┃━┃  │  │ ┃━┃  │  │ ┃━┃  │    ← vertical-fader (100px track)
+│ ┃━┃  │  │ ┃━┃  │  │ ┃━┃  │
+│ ┃━┃  │  │ ┃━┃  │  │ ┃━┃  │
+│      │  │      │  │      │
+│ CH1  │  │ CH2  │  │ MST  │    ← channel label
+│  ●   │  │  ●   │  │  ●   │    ← led-dot (status)
+└──────┘  └──────┘  └──────┘
+```
+
+## Assembly Rules
+
+1. **Container**: Use `.panel` with default material. `display: flex; gap: 16px; align-items: flex-end; padding: 16px`.
+
+2. **Each channel strip**: Vertical flex column (`flex-direction: column; align-items: center; gap: 6px`).
+
+3. **Pan knob**: `.radial-knob` at 40x40px (smaller than default). Indicator transform-origin adjusted for the smaller size (`transform-origin: 50% 16px`). Default material for regular channels, `.variant-metal` for master.
+
+4. **Pan label**: `font-size: 7px; letter-spacing: 1px; color: var(--text-muted)`.
+
+5. **VU meter**: 2 bars per channel, 50px height, 2px gap, 6px bar width. Compact sizing.
+
+6. **Channel fader**: `.fader-v-track` at 100px height, 8px width. Thumb at 16x8px (smaller than default). Each channel at different fill heights for visual variety.
+
+7. **Channel label**: `font-family: var(--font-display); font-size: 8px; color: var(--amber)`. Master channel in `color: var(--red-alert)`.
+
+8. **Status LED**: `.led-dot.green` for regular channels, `.led-dot.red` for master.
+
+## Component Configuration
+
+| Component | Channel Config | Master Config |
+|-----------|---------------|---------------|
+| radial-knob | 40x40px, default material | 40x40px, `.variant-metal` |
+| vu-meter | 2 bars, 50px height | 2 bars, 50px height, higher levels |
+| vertical-fader | 100px track, varied fills | 100px track, high fill (80%) |
+| channel label | `color: var(--amber)` | `color: var(--red-alert)` |
+| led-dot | `.green` | `.red` |

package/spec/compositions/camera-viewfinder.md

@@ -0,0 +1,66 @@
+---
+name: Camera Viewfinder HUD
+id: camera-viewfinder
+components: [camera-readout, mode-badge, status-chips, battery-icon, focus-brackets, grid-overlay, exposure-scale, timecode-display]
+materials: [phosphor-screen]
+---
+
+# Camera Viewfinder HUD
+
+## Description
+
+Full-frame camera electronic viewfinder overlay. Components are positioned absolutely over a dark background, simulating the heads-up display (HUD) seen through a mirrorless camera EVF (Electronic Viewfinder). All readouts float over the live image without obscuring it.
+
+## Reference Devices
+
+Sony Alpha A7 III/IV EVF, Nikon Z6/Z8 EVF, Canon EOS R5 EVF, Fujifilm X-T4 EVF.
+
+## Layout
+
+```
+┌─────────────────────────────────────────────┐
+│ [mode-badge:M] [readout:SS] [readout:F] [readout:ISO]  [status-chip:REC] [battery] │
+│                                             │
+│                                             │
+│              [focus-brackets]               │
+│                  [grid-overlay]             │
+│                                             │
+│                                             │
+│ [exposure-scale ─────●─────]  [timecode:00:12:34] │
+└─────────────────────────────────────────────┘
+```
+
+## Assembly Rules
+
+1. **Container**: Use `.panel` with phosphor-screen material (`background: linear-gradient(180deg, #080808, #111)`). Padding: 0. Overflow: hidden.
+
+2. **Top status bar**: Horizontal flex row with `justify-content: space-between`. Contains:
+   - Left group: mode badge (compact, `padding: 3px 8px`), camera readouts (`.inline` variant, `padding: 3px 8px`)
+   - Right group: status chip (`.active`, small font `8px`), battery icon
+   - Separated by `border-bottom: 1px solid #222`
+
+3. **Viewfinder area**: Relative positioned div, minimum height 180px, `background: #1a1a1a`. Contains:
+   - Grid overlay lines at 33.3% and 66.6% (vertical and horizontal)
+   - Grid center dot
+   - Focus brackets positioned within the area
+
+4. **Bottom bar**: Horizontal flex row with `justify-content: space-between`. Contains:
+   - Exposure scale (compact, `width: 120px`)
+   - Timecode display (compact, `padding: 3px 10px`, `font-size: 14px`)
+   - Separated by `border-top: 1px solid #222`
+
+5. **All readouts use `.inline` variant** — horizontal layout for compact display
+
+6. **Focus brackets default to one acquiring + one locked** for visual variety
+
+## Component Configuration
+
+| Component | Variant | Size Override |
+|-----------|---------|--------------|
+| mode-badge | compact | `font-size: 16px` on mode letter, `padding: 3px 8px` |
+| camera-readout | `.inline` | `font-size: 12px` on value, `font-size: 7px` on label |
+| status-chip | `.active` | `font-size: 8px`, `padding: 2px 6px` |
+| battery-icon | default | `width: 20px`, `height: 10px` on body |
+| exposure-scale | compact | `width: 120px` |
+| timecode-display | compact | `font-size: 14px` on segments, `padding: 3px 10px` |
+| focus-brackets | mixed | One `.acquiring`, one `.locked` |

package/spec/compositions/phone-interface.md

@@ -0,0 +1,66 @@
+---
+name: Phone Interface
+id: phone-interface
+components: [status-bar, menu-grid, keypad-button, dialog, toast, d-pad, signal-bars, battery-icon]
+materials: [glossy-polycarbonate, rubber]
+---
+
+# Phone Interface
+
+## Description
+
+A Nokia-era feature phone interface. Combines the status bar, app menu grid, numeric keypad, and notification elements into a complete device screen experience.
+
+## Reference Devices
+
+Nokia 6600, Nokia 3310, Sony Ericsson T610, Motorola RAZR V3, Samsung SGH-D500.
+
+## Layout
+
+```
+┌──────────────────────────┐
+│ 12:45    3G  ▂▄▆█  [██] │  ← status-bar
+├──────────────────────────┤
+│                          │
+│  📞  ✉  ⚙               │
+│  PHONE MSG SET           │  ← menu-grid (3x3)
+│  ♪  📷  🌐              │
+│  MUSIC CAM WEB           │
+│                          │
+├──────────────────────────┤
+│  [1] [2] [3]             │
+│  [4] [5] [6]             │  ← keypad (3x4 grid)
+│  [7] [8] [9]             │
+│  [*] [0] [#]             │
+├──────────────────────────┤
+│  OPTIONS          BACK   │  ← softkeys
+└──────────────────────────┘
+```
+
+## Assembly Rules
+
+1. **Container**: Use `.device-bezel` for the outer phone frame. Inner content area uses `bg-inset` background.
+
+2. **Status bar**: Full width, compact variant. Contains time (left), network indicator text (center-left), signal bars (right), battery icon (far right).
+
+3. **Menu grid**: `.menu-grid-wrap` centered in the screen area. 3x3 layout. Each item has an emoji icon (or Unicode symbol) and a label. Active item highlighted with blue tint.
+
+4. **Keypad**: `.keypad` container below the screen. Full 3x4 grid with T9 letter labels on keys 2-9. Special keys (* and #) use `.special` variant. Optional `.call` key variant for green answer key.
+
+5. **Softkeys**: A flex row below the keypad with `justify-content: space-between`. Two text labels (OPTIONS, BACK) styled as `.softkey` — small, muted text that responds to hover.
+
+6. **Toast notification**: When shown, appears at the top of the screen area, overlaying the menu grid. Uses slide-down animation.
+
+7. **Dialog**: When shown, centers over the screen area with the standard phone dialog pattern (title, body, two action buttons).
+
+## Component Configuration
+
+| Component | Variant | Notes |
+|-----------|---------|-------|
+| status-bar | compact (4px padding) | Width: full container |
+| signal-bars | 3 of 5 active | `.off` on bars 4-5 |
+| battery-icon | 70% fill, green | default variant |
+| menu-grid | 3x3, one `.active` | Unicode icons for phone apps |
+| keypad-button | T9 labels on 2-9 | One `.call` key optional |
+| dialog | centered overlay | `max-width: 220px` |
+| toast | top of screen | LED dot + text + timestamp |

package/spec/foundation/accessibility.md

@@ -0,0 +1,33 @@
+# Accessibility
+
+Accessibility requirements for all pudge-ui components — color contrast ratios, focus management, screen reader support, and keyboard interaction patterns.
+
+---
+
+## Color Contrast
+
+All text/background combinations meet WCAG AA minimum (4.5:1 for normal text):
+- `--text-primary` on `--bg-base`: 11.2:1 (dark), 12.8:1 (light)
+- `--text-secondary` on `--bg-base`: 5.1:1 (dark), 5.8:1 (light)
+- `--amber` on `--bg-inset`: 6.3:1
+
+## Focus Management
+
+- Use native `<button>` elements for all interactive controls
+- Browser default focus rings are preserved (not overridden)
+- For custom controls (toggles, dials), add `tabindex="0"` and `role` attributes
+
+## Screen Reader Text
+
+```html
+<span class="sr-only">Description for screen readers</span>
+```
+Uses the standard visually-hidden technique (1x1px, overflow hidden, clip rect).
+
+## Keyboard Interaction Patterns
+
+- **Buttons**: Enter/Space to activate
+- **Toggles**: Space to toggle
+- **Tabs**: Arrow keys to navigate, Enter to select
+- **Steppers**: Arrow keys to increment/decrement
+- **Accordion**: Enter/Space to expand/collapse