@pudge-ui/mcp-server 0.1.0 → 0.2.0

package/spec/spec/foundation/canvas.md

@@ -1,20 +0,0 @@
-# Canvas-Based Components
-
-Rendering algorithms for components drawn directly to HTML5 Canvas — histogram, waveform, and oscilloscope visualizations that simulate phosphor-screen displays.
-
----
-
-## Histogram (F5)
-
-Renders 200x80px luminance distribution. For each x pixel, calculate a height value using a sine-based curve with random variation, then draw a 1px-wide vertical bar with an amber gradient (`rgba(245,166,35,0.1)` to `rgba(245,166,35,0.6)`).
-
-## Waveform (F6)
-
-Renders 200x80px audio waveform. Single stroke path using compound sine waves (`sin(x*0.08)` + `sin(x*0.03)`) with random jitter. Stroke color: `rgba(102,255,102,0.6)`, 1px line width.
-
-## Oscilloscope (F14)
-
-Animated 200x80px trace. Uses `requestAnimationFrame` loop. Each frame:
-1. Draw semi-transparent background (creates trail effect)
-2. Calculate sine wave with time offset: `sin(x*0.06 + t)` + harmonics
-3. Stroke with green `rgba(102,255,102,0.8)` and `shadowBlur: 4` for phosphor glow

package/spec/spec/foundation/depth-model.md

@@ -1,82 +0,0 @@
-# Depth Model
-
-How raised, recessed, glowing, and textured elements are constructed using shadow stacks, inset shadows, glow effects, and CSS texture patterns. This model ensures every element feels like part of one continuous physical object.
-
----
-
-## Raised Elements
-
-Three tiers of prominence:
-
-**Tier 1 — Flush** (chips, pagination buttons):
-- Bottom edge: `0 1px 0 border-deep`
-- Top highlight: `inset 0 1px 0 glossy-hi`
-- Press: `translateY(1px)`, shadow to `none`
-
-**Tier 2 — Standard** (buttons, tabs, controls):
-- Bottom edge: `0 2-3px 0 border-deep`
-- Top highlight: `inset 0 1px 0 border-hi`
-- Bottom chamfer: `inset 0 -1px 0 #111`
-- Press: `translateY(1-2px)`, bottom edge collapses to `0 1px 0`
-
-**Tier 3 — Elevated** (panels, cards, dialogs):
-- Bottom edge: `0 4px 0 border-deep`
-- Ambient shadow: `0 8px 24px rgba(0,0,0,0.5)`
-- Top highlight: `inset 0 1px 0 border-hi`
-- No press state (panels don't press)
-
-## Recessed Elements
-
-All recessed elements (displays, input fields, toggle tracks, slider tracks) use:
-```css
-box-shadow: inset 0 1px 4px rgba(0,0,0,0.4-0.9);
-```
-The opacity varies by depth:
-- 0.4: shallow recess (toggle tracks, slider tracks)
-- 0.6: standard recess (readouts, text inputs)
-- 0.9: deep recess (signal displays, phosphor screens)
-
-Optional inner ring for extra depth:
-```css
-box-shadow: inset 0 1px 4px rgba(0,0,0,0.6), inset 0 0 0 1px #181818;
-```
-
-## Glow Effects
-
-Glow simulates light emission from LEDs, phosphor screens, and active indicators:
-
-```css
-/* Element glow (LEDs, active indicators) */
-box-shadow: 0 0 6-12px <accent-glow>;
-
-/* Text glow (readout values, display text) */
-text-shadow: 0 0 12-16px <accent-glow>;
-```
-
-Glow radius by context:
-- 6px: small LEDs, indicator dots
-- 8px: active chips, checkbox marks
-- 12px: readout values, timecode
-- 16px: large display values
-- 18px: REC button recording glow
-
-## Knurl / Texture Patterns
-
-Knurled grip textures use CSS repeating gradients:
-
-**Vertical grooves** (cylindrical dial side grips):
-```css
-background: repeating-linear-gradient(to bottom, #252525 0px, #252525 2px, #0d0d0d 2px, #0d0d0d 5px);
-```
-
-**Diamond crosshatch** (horizontal command dials):
-```css
-background-image:
-  repeating-linear-gradient(75deg, transparent 0px, transparent 2px, rgba(0,0,0,0.06) 2px, rgba(0,0,0,0.06) 3px, transparent 3px, transparent 6px),
-  repeating-linear-gradient(-75deg, transparent 0px, transparent 2px, rgba(0,0,0,0.06) 2px, rgba(0,0,0,0.06) 3px, transparent 3px, transparent 6px);
-```
-
-**Conic knurl ring** (rotary encoder outer edge):
-```css
-background: repeating-conic-gradient(#202020 0deg 4deg, #0d0d0d 4deg 8deg);
-```

package/spec/spec/foundation/layout.md

@@ -1,33 +0,0 @@
-# Layout Patterns
-
-Page structure, grid system, and responsive breakpoints used to compose pudge-ui components into full layouts.
-
----
-
-## Page Structure
-
-```
-[Sticky Nav]           — .dir-nav, position: sticky, top: 0, z-index: 100
-[Page Header]          — .page-header, 48px padding
-[Section]              — .section, 48px left/right padding
-  [Section Header]     — .section-header, flex baseline, bottom border
-  [Component Row]      — .component-row, flex wrap, 36px gap
-    [Component Block]  — .component-block, flex column, 10px gap
-      [Label]          — .component-label, uppercase eyebrow
-      [Component]      — the actual component
-      [Spec Table]     — .spec-table, annotation
-[Divider]              — .divider, 1px line
-```
-
-## Grid System
-
-Panels use CSS Grid with `auto-fit` and `minmax`:
-```css
-display: grid;
-grid-template-columns: repeat(auto-fit, minmax(340px, 1fr));
-gap: 24px;
-```
-
-## Responsive Breakpoints
-
-- **720px and below**: Padding reduces to 16px, title shrinks, component rows reflow to column

package/spec/spec/foundation/materials.md

@@ -1,68 +0,0 @@
-# Material Recipes
-
-The six canonical physical materials used across all pudge-ui components. Each material maps to a real-world manufacturing process and defines specific CSS treatments for gradients, highlights, borders, and shadows.
-
----
-
-## Brushed Metal (Anodized Aluminum)
-**Physical analog**: iPod back plate, MacBook Pro chassis, Nikon camera body
-```css
-background: linear-gradient(145deg, #d8d6d0, #b8b6b0);
-border: 1px solid #a8a6a0;
-box-shadow: 0 4px 12px rgba(0,0,0,0.3), inset 0 1px 0 rgba(255,255,255,0.5);
-```
-**Characteristics**: Subtle diagonal gradient simulates brushed grain. High-opacity white inset highlight = polished metal catching light. Border matches mid-tone of gradient.
-**When to use**: Premium dials, device panels, chassis components.
-
-## Chrome (Polished)
-**Physical analog**: Nikon mode dial ring, car stereo trim, iPod clickwheel ring
-```css
-background: linear-gradient(180deg, #5a5855, #3a3835); /* dark theme */
-/* OR */
-background: linear-gradient(180deg, #e8e6e0, #c8c6c0, #d0cec8); /* light theme — triple-stop = reflection band */
-border: 1px solid #666;
-box-shadow: 0 2px 12px rgba(0,0,0,0.3), inset 0 1px 0 rgba(255,255,255,0.4), inset 0 -1px 0 rgba(0,0,0,0.06);
-```
-**Characteristics**: Triple-stop gradient creates a reflection band. Both top and bottom inset shadows = dual chamfer typical of chrome trim.
-**When to use**: Accent rings, dial variants, premium trim elements.
-
-## Rubber (Soft-Touch Matte)
-**Physical analog**: Gameboy buttons, camera grip, headphone ear pads
-```css
-background: linear-gradient(180deg, var(--rubber-hi), var(--rubber-bg));
-border: 1px solid var(--rubber-lo);
-box-shadow: 0 2px 0 var(--border-deep), inset 0 1px 0 rgba(255,255,255,0.06);
-```
-**Characteristics**: Very subtle gradient (nearly flat). Minimal highlight opacity (0.06 vs 0.14 for glossy) = matte surface. Pill-shaped border-radius (100px) feels more organic.
-**When to use**: Soft buttons, D-pad arms, Start/Select, grip textures.
-
-## Glossy Polycarbonate (Gel)
-**Physical analog**: iPod Nano case, PSP face, early 2000s phone buttons
-```css
-background: linear-gradient(180deg, var(--clear-glass), transparent 50%),
-            linear-gradient(180deg, var(--bg-surface), var(--bg-panel));
-border: none;
-box-shadow: 0 3px 0 var(--border-deep), inset 0 1px 0 var(--glossy-hi);
-```
-**Characteristics**: **Two-layer background** is critical — the first layer is a catch-light that fades halfway down. This creates the "gel" dome appearance. `--glossy-hi` (0.14 opacity white) = sharp specular highlight. 3px bottom edge shadow = thicker than rubber (polycarbonate has more depth).
-**When to use**: Main action buttons, media player controls, phone buttons.
-
-## Glass (Translucent / Clear Plastic)
-**Physical analog**: iMac G3 clear shell, transparent phone cases, frosted diffuser
-```css
-background: rgba(255,255,255,0.08);
-border: 1px solid var(--border-subtle);
-backdrop-filter: blur(4px);
-```
-**Characteristics**: No gradient — flat transparency. `backdrop-filter` creates the frosted glass effect. Very subtle border. No bottom-edge shadow (glass doesn't cast the same hard edge).
-**When to use**: Overlay buttons, translucent panels, secondary actions.
-
-## Phosphor Screen (LCD/OLED Display Cavity)
-**Physical analog**: Camera viewfinder display, VU meter face, alarm clock display
-```css
-background: linear-gradient(180deg, #080808, #111);
-border: 1px solid #1f1f1f;
-box-shadow: inset 0 1px 8px rgba(0,0,0,0.9), inset 0 0 0 1px #181818;
-```
-**Characteristics**: Nearly black background with slight gradient = depth in the cavity. Heavy inset shadow (0.9 opacity) = deep recess. Double inset (shadow + ring) creates the "sunken screen" look. Text on this surface always has `text-shadow` with the accent glow color = phosphor bleed.
-**When to use**: All readout displays, signal displays, histogram/waveform frames, seven-segment displays.

package/spec/spec/foundation/naming.md

@@ -1,33 +0,0 @@
-# Naming Conventions
-
-CSS class naming rules for all pudge-ui components, ensuring consistent and predictable class names across the system.
-
----
-
-## BEM-lite Pattern
-
-`component-element` (no `__` or `--`, use `-` throughout):
-- `.push-btn` (component)
-- `.readout-value` (element within readout)
-- `.dial-center-bar` (element within dial)
-
-## State Classes
-
-Added to the component root:
-- `.active` — selected / on state
-- `.on` — power-on / enabled (for toggles)
-- `.pressed` — currently being pressed
-- `.disabled` or `[disabled]` — unavailable
-- `.error` — error state
-- `.recording` — REC active
-
-## Material Variant Classes
-
-- `.variant-metal` — brushed aluminum
-- `.variant-silver` — silver anodized
-- `.variant-chrome` — polished chrome
-- `.variant-glossy` — polycarbonate gel
-
-## Size Classes
-
-`.xs`, `.sm`, (default = md), `.lg`, `.xl`

package/spec/spec/foundation/philosophy.md

@@ -1,27 +0,0 @@
-# Philosophy
-
-Core design principles that govern every visual decision in the pudge-ui design system. Every CSS property maps to a real material or manufacturing process from 2000s consumer electronics.
-
----
-
-### Physical Analog Commitment
-Every CSS property in this system has a physical-world justification. A `box-shadow` is not decoration — it is the shadow cast by a raised button onto the panel surface beneath it. A `border-radius` is the machining tolerance of a milled edge. An `inset` shadow is light being blocked by the lip of a recessed display cavity.
-
-### Warm Neutral Palette
-All grays carry a slight amber/brown warmth (`#1c1a18` not `#1c1c1c`). Pure grays read as "digital" — warm grays read as "physical material under warm tungsten workbench lighting." This is the main visual distinction from generic dark UIs.
-
-### Three-Plane Depth Model
-Every raised element (buttons, panels, cards) exists in a three-layer shadow stack:
-1. **Bottom edge** — the shadow cast onto the surface below
-2. **Inner top highlight** — light catching the top chamfer
-3. **Inner bottom shadow** — shadow on the bottom chamfer
-
-Recessed elements (displays, inputs) invert this model. This consistency is what makes the entire system feel like one physical object.
-
-### Inversion Symmetry
-Raised and recessed elements use the same shadow logic, inverted:
-- Raised: dark below, bright above
-- Recessed: dark above (lip shadow), bright below (light hitting the bottom edge of the recess)
-
-### Material Honesty
-Components declare which physical material they simulate. A rubber button behaves differently from a glossy polycarbonate button — different gradients, different highlight sharpness, different border treatment. The system defines six canonical materials.

package/spec/spec/foundation/theme.md

@@ -1,39 +0,0 @@
-# Theme System
-
-How light and dark themes work in pudge-ui — the switching mechanism, what properties change between themes, and which components need explicit overrides beyond token swaps.
-
----
-
-## Mechanism
-
-Theme is controlled by `data-theme` attribute on `<html>`:
-```html
-<html lang="en" data-theme="dark">
-```
-
-Toggle via JS:
-```javascript
-document.documentElement.dataset.theme =
-  document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';
-```
-
-## What Changes Between Themes
-
-| Property | Dark | Light |
-|----------|------|-------|
-| Surface colors | Dark warm grays | Cream/white warm tones |
-| Text colors | Light on dark | Dark on light |
-| Border colors | Subtle dark lines | Subtle light lines |
-| Shadows | High opacity (0.5+) | Low opacity (0.08) |
-| Rubber material | Dark `#2a2826` | Light `#c8c4bc` |
-| Clear glass | `rgba(255,255,255,0.08)` | `rgba(255,255,255,0.5)` |
-| Inset shadow | Strong `rgba(0,0,0,0.6)` | Subtle `rgba(0,0,0,0.08)` |
-| Toggle on-state | Dark green `#0d1a0d` | Light green `#d0f0d0` |
-
-## Components with Theme-Specific Overrides
-
-Some components need explicit `[data-theme="light"]` overrides beyond token swaps:
-- **Cylindrical dials**: Light backgrounds need reduced knurl opacity
-- **Dial vignettes**: Must match the cylinder background color
-- **Toggle thumbs**: Need brighter gradients in light mode
-- **Rubber buttons**: Active state needs light green tones

package/spec/spec/foundation/tokens.md

@@ -1,148 +0,0 @@
-# Token Reference
-
-All design tokens used across the pudge-ui system — colors, typography, spacing, radii, motion, and shadows. These tokens form the shared vocabulary for every component.
-
----
-
-## Color Tokens — Surface Hierarchy
-
-| Token | Dark Mode | Light Mode | Physical Analog |
-|-------|-----------|------------|-----------------|
-| `--bg-base` | `#141210` | `#f5f0e8` | Workbench / desk surface |
-| `--bg-raised` | `#1c1a18` | `#ffffff` | Device chassis top plate |
-| `--bg-surface` | `#2a2826` | `#f0ece4` | Panel face, module front |
-| `--bg-inset` | `#0e0c0a` | `#e8e4dc` | Display cavity, recessed area |
-| `--bg-panel` | `#22201e` | `#faf6ee` | Button face, control surface |
-
-## Color Tokens — Accents
-
-| Token | Value | Usage |
-|-------|-------|-------|
-| `--amber` | `#f5a623` | Primary active/selection indicator. The universal "this is selected" signal. |
-| `--amber-dim` | `#a06010` | Secondary amber: colon separators, inactive amber elements |
-| `--amber-glow` | `rgba(245,166,35,0.35)` | Glow halo behind active amber elements (simulates phosphor bleed) |
-| `--green-on` | `#33cc66` | Power-on, connected, success states |
-| `--green-hi` | `#66ff66` | High-brightness green: focus lock, peak meter |
-| `--green-glow` | `rgba(51,204,102,0.3)` | Green glow halo |
-| `--red-alert` | `#cc2200` | REC, error, critical battery, destructive action |
-| `--red-glow` | `rgba(204,34,0,0.3)` | Red glow halo |
-| `--blue-info` | `#4477cc` | Info states, iPod-era accent, selected items in consumer contexts |
-| `--blue-glow` | `rgba(68,119,204,0.3)` | Blue glow halo |
-| `--pink-action` | `#ee6688` | Action buttons (Gameboy A), highlights, feminine accent |
-| `--gold-warm` | `#ddaa33` | Premium accent, warm EQ bands |
-
-## Color Tokens — Text
-
-| Token | Dark Mode | Light Mode |
-|-------|-----------|------------|
-| `--text-primary` | `#d8d4cc` | `#2a2826` |
-| `--text-secondary` | `#9a9690` | `#6a6662` |
-| `--text-muted` | `#6a6662` | `#9a9690` |
-
-Note: `--text-secondary` and `--text-muted` swap values between themes.
-
-## Color Tokens — Borders
-
-| Token | Dark Mode | Light Mode | Usage |
-|-------|-----------|------------|-------|
-| `--border-deep` | `#0a0908` | `#b8b4ac` | Button bottom edge shadow line |
-| `--border-mid` | `#3a3835` | `#c8c4bc` | Panel seams, general borders |
-| `--border-subtle` | `#2a2826` | `#d8d4cc` | Dividers, section separators |
-| `--border-hi` | `#4a4845` | `#e8e4dc` | Top-edge highlight (light catch) |
-
-## Typography
-
-| Token | Font Family | Role | Usage |
-|-------|-------------|------|-------|
-| `--font-display` | `Michroma` | Display / Title | Section titles, mode labels, badge letters, dial values. Geometric sans-serif that evokes consumer electronics branding. |
-| `--font-mono` | `IBM Plex Mono` | Data / Readout | Numeric readouts, data values, technical labels, text inputs. The workhorse monospace for all data display. |
-| `--font-ui` | `Rajdhani` | UI / Body | Body text, descriptions, button labels, spec tables. Semi-rounded geometric with good readability at small sizes. |
-| `--font-lcd` | `VT323` | Retro LCD | Optional pixel-font variant for deliberately retro LCD readouts. Used in 7-segment displays and dot-matrix marquees. |
-
-**Font size scale** (commonly used):
-- 7px: micro labels (mode keys, tiny annotations)
-- 8-9px: chip text, status labels, specs
-- 10-11px: button labels, UI labels, body text
-- 12-13px: data values, readout values (small)
-- 14-16px: medium readout values, keypad numbers
-- 20-24px: large readout values
-- 28-34px: hero display values, signal display
-- 42px: 7-segment display digits
-
-**Letter-spacing conventions**:
-- 0.5-1px: body text, data values
-- 1-2px: button labels, UI text
-- 2-3px: section titles, status labels
-- 3-4px: eyebrow text, panel labels
-
-## Spacing Scale
-
-| Token | Value | Usage |
-|-------|-------|-------|
-| `--space-xs` | `4px` | Chip padding, tight gaps |
-| `--space-sm` | `8px` | Button gaps, small component padding |
-| `--space-md` | `14px` | Standard padding, component gaps |
-| `--space-lg` | `22px` | Panel padding, section gaps |
-| `--space-xl` | `36px` | Section spacing |
-| `--space-2xl` | `56px` | Page-level spacing |
-
-## Border Radius Scale
-
-| Token | Value | Usage |
-|-------|-------|-------|
-| `--radius-sm` | `4px` | Chips, small buttons, tick marks, film frames |
-| `--radius-md` | `8px` | Standard buttons, readouts, inputs, tabs |
-| `--radius-lg` | `14px` | Panels, cards, device bezels, dialogs |
-| `--radius-pill` | `100px` | Pill buttons, toggle tracks, progress bars |
-| `--radius-round` | `50%` | Circular dials, LED dots, knobs |
-
-## Motion / Easing
-
-| Token | Value | Physical Analog | Usage |
-|-------|-------|-----------------|-------|
-| `--snap-fast` | `cubic-bezier(0.34, 1.56, 0.64, 1)` | Mechanical detent click — slight overshoot then settle | Button press, toggle snap, segmented control switch |
-| `--snap-soft` | `cubic-bezier(0.16, 1, 0.3, 1)` | Drawer slide, damped return | Drawer panels, slide animations |
-| `--ease-out` | `cubic-bezier(0, 0, 0.2, 1)` | Meter fill, smooth deceleration | Progress bars, slider fills, meter animations |
-| `--spring` | `cubic-bezier(0.34, 1.3, 0.64, 1)` | Spring-loaded mechanism with overshoot | Mode dial rotation, gauge needle |
-
-**Timing conventions**:
-- 70-90ms: press/release (instantaneous mechanical feel)
-- 120-150ms: state transitions (color change, toggle snap)
-- 180-220ms: movement animations (toggle slide, dial rotation)
-- 250-350ms: larger movements (drawer open, mode dial spring)
-
-## Shadow Tokens
-
-**Raised element shadow stacks** (3 tiers by prominence):
-
-```css
-/* Small — chips, small buttons */
-box-shadow: 0 1px 0 var(--border-deep), inset 0 1px 0 var(--glossy-hi);
-
-/* Medium — standard buttons, controls */
-box-shadow: 0 2px 0 var(--border-deep), inset 0 1px 0 var(--border-hi), inset 0 -1px 0 #111;
-
-/* Large — panels, cards */
-box-shadow: 0 4px 0 var(--border-deep), 0 8px 24px rgba(0,0,0,0.5), inset 0 1px 0 var(--border-hi);
-```
-
-**Recessed element shadow**:
-```css
-box-shadow: inset 0 1px 4px rgba(0,0,0,0.6);
-```
-
-**Press interaction** (applied on `:active`):
-```css
-transform: translateY(1px); /* or 2px for large buttons */
-box-shadow: 0 1px 0 var(--border-deep); /* collapse bottom edge */
-```
-
-**Glow effects**:
-```css
-/* Amber glow (active indicators) */
-box-shadow: 0 0 8px rgba(245,166,35,0.35);
-text-shadow: 0 0 14px rgba(245,166,35,0.35);
-
-/* Green glow (on-state) */
-box-shadow: 0 0 8px rgba(51,204,102,0.3);
-```

package/spec/spec/guides/extension.md

@@ -1,189 +0,0 @@
-# Extension Guide — Adding New Components
-
-This guide explains how to create new pudge-ui components that fit the design system.
-
-## The Spec File Template
-
-Every component spec file follows this structure:
-
-```markdown
----
-name: Component Name
-id: kebab-case-id
-class: .css-class-name
-category: category-folder
-index: N
-materials: [default, metal, chrome, glossy, rubber, glass]
-sizes: [xs, sm, md, lg, xl]
-interactive: true
-requires_js: false
-canvas: false
----
-
-# Component Name
-
-## Physical Analog
-**Reference devices**: Specific 2000s products with model numbers.
-**Mechanism**: How the physical mechanism works — the material science,
-the forces involved, the geometry.
-
-## Geometry
-| Property | Value | Physical Reason |
-|----------|-------|-----------------|
-| Height | Npx | What real-world dimension this represents |
-| Width | Npx | — |
-| Border-radius | Npx | Machining tolerance or mold radius |
-
-## CSS Recipe
-### Default State
-\`\`\`css
-.component-name {
-  /* Full CSS recipe */
-}
-\`\`\`
-### Hover
-\`\`\`css
-.component-name:hover { }
-\`\`\`
-### Active / Pressed
-\`\`\`css
-.component-name:active { }
-\`\`\`
-### Disabled
-\`\`\`css
-.component-name:disabled { }
-\`\`\`
-
-## HTML Structure
-\`\`\`html
-<element class="component-name [variants]">content</element>
-\`\`\`
-
-## Size Variants
-| Class | Analog | Height | Min-Width |
-|-------|--------|--------|-----------|
-
-## Material Variants
-| Class | Material | Visual Change |
-|-------|----------|---------------|
-
-## Theme Behavior
-What changes between dark and light themes.
-
-## Constraints
-1. MUST: [rule with physical reasoning]
-2. MUST NOT: [rule with physical reasoning]
-
-## Accessibility
-- Element type and ARIA role
-- Keyboard interaction pattern
-- Focus behavior
-```
-
-## Step-by-Step Process
-
-### Step 1: Choose a Physical Analog
-
-Every pudge-ui component MUST have a real-world 2000s-era electronics counterpart. This is not optional — it's what makes the system work. Ask yourself:
-- What physical device from 2000-2010 had this control?
-- How did the mechanism actually work?
-- What material was it made from?
-- What did it feel like to operate?
-
-Good analogs: Sony Walkman play button, Nokia phone keypad, iPod click wheel, Nikon mode dial, Mackie mixer fader, Roland synthesizer knob.
-
-### Step 2: Select a Material
-
-Choose from the 6 canonical materials defined in `foundation/materials.md`:
-
-| Material | When to use |
-|----------|-------------|
-| Brushed Metal | Premium controls, device chassis, high-end knobs |
-| Chrome | Accent rings, trim, dial rings |
-| Rubber | Grip surfaces, soft-touch buttons, D-pad arms |
-| Glossy Polycarbonate | Consumer electronics buttons, cases, glossy controls |
-| Glass | Translucent overlays, frosted panels |
-| Phosphor Screen | All displays and readout cavities |
-
-If your component supports multiple materials, make the most common one the default and add `.variant-*` classes for others.
-
-### Step 3: Apply the Depth Model
-
-Consult `foundation/depth-model.md`:
-
-- **Raised element?** (proud of the surface) → Use the appropriate shadow tier:
-  - Tier 1 (flush): chips, pagination buttons — 1px bottom shadow
-  - Tier 2 (standard): buttons, controls — 2-3px bottom shadow + chamfer highlights
-  - Tier 3 (elevated): panels, cards — 4px bottom shadow + ambient shadow
-
-- **Recessed element?** (inset into the surface) → Use inset shadow:
-  - Shallow: `inset 0 1px 4px rgba(0,0,0,0.4)` (toggle tracks)
-  - Standard: `inset 0 1px 4px rgba(0,0,0,0.6)` (readouts, inputs)
-  - Deep: `inset 0 1px 8px rgba(0,0,0,0.9)` (signal displays)
-
-- **Glowing element?** → Add glow with accent color at 6-16px radius.
-
-### Step 4: Set Typography
-
-| Content type | Font token |
-|-------------|-----------|
-| Display values, titles, mode labels | `--font-display` (Michroma) |
-| Data values, readouts, code | `--font-mono` (IBM Plex Mono) |
-| Labels, body text, UI elements | `--font-ui` (Rajdhani) |
-| Retro LCD characters | `--font-lcd` (VT323) |
-
-### Step 5: Define States
-
-Every interactive component needs at minimum:
-- **Default**: base appearance
-- **Hover**: subtle highlight (text brightening or border change)
-- **Active / Pressed**: `translateY(1-2px)` + shadow collapse
-- **Disabled**: `opacity: 0.35`, `pointer-events: none`
-
-Optional states:
-- **Active (selected)**: amber accent color + glow
-- **Error**: red accent color
-- **Loading**: pulse animation
-
-### Step 6: Support Both Themes
-
-Check your component in both `[data-theme="dark"]` and `[data-theme="light"]`. Most components adapt via token values automatically. Add explicit `[data-theme="light"]` overrides only for:
-- Gradients with hardcoded dark colors
-- Knurl/texture patterns (reduce opacity in light mode)
-- Material-specific shadows
-
-### Step 7: Write the Constraints
-
-The Constraints section is the most important part of the spec. Write in imperative language (MUST, MUST NOT) and always explain WHY with physical reasoning:
-
-**Good constraint**: "Travel MUST be 1-2px maximum. More feels like a keyboard key, not a camera button — real dome switches have only 0.3-0.5mm travel."
-
-**Bad constraint**: "Keep the animation subtle." (too vague, no physical reasoning)
-
-### Step 8: Follow Naming Conventions
-
-- Component class: `kebab-case` noun (e.g., `range-slider`)
-- Element class: `component-element` (e.g., `range-slider-thumb`)
-- State class: adjective (e.g., `.active`, `.on`, `.error`)
-- Size class: `.xs`, `.sm`, `.lg`, `.xl`
-- Material class: `.variant-metal`, `.variant-chrome`, etc.
-
-## Checklist
-
-Before submitting a new component:
-
-- [ ] Physical analog documented (specific 2000s device/mechanism)
-- [ ] Mechanical principle explained (how the physical thing works)
-- [ ] Material recipe applied from `materials.md`
-- [ ] Shadow stack follows `depth-model.md` (raised or recessed)
-- [ ] CSS Recipe uses exact values (not prose approximations)
-- [ ] HTML structure is minimal and semantic
-- [ ] All states defined (default, hover, active, disabled)
-- [ ] Size variants follow the existing scale (xs/sm/md/lg/xl)
-- [ ] Typography uses system font tokens
-- [ ] Works in dark theme
-- [ ] Works in light theme
-- [ ] Constraints use MUST/MUST NOT with physical reasoning
-- [ ] Accessibility documented (element type, ARIA, keyboard)
-- [ ] Named following conventions
-- [ ] Added to `_index.yaml` catalog