@pudge-ui/mcp-server 0.1.0

package/spec/components/meters/level-indicator.md

@@ -0,0 +1,95 @@
+---
+name: Level Indicator
+id: level-bar
+class: .level-bar
+category: meters
+index: 10
+materials: [panel]
+sizes: [md]
+interactive: false
+requires_js: false
+canvas: false
+---
+
+# Level Indicator
+
+## Physical Analog
+**Reference devices**: Camera electronic level/horizon indicator (Sony Alpha, Nikon Z series).
+**Mechanism**: Derived from spirit level / bubble level. Accelerometer data drives bar indicator where center mark = level (0 degrees). Fill represents current tilt angle and direction.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Bar | 160px wide x 8px height |
+| Center mark | 1px at 50% |
+| Fill | Amber, positioned relative to center |
+| Border-radius | pill (100px) |
+
+## CSS Recipe
+
+### Wrapper
+```css
+.level-wrap { display: flex; flex-direction: column; align-items: center; gap: 6px; }
+```
+
+### Bar
+```css
+.level-bar {
+  width: 160px; height: 8px; background: var(--bg-inset);
+  border: 1px solid var(--border-subtle); border-radius: var(--radius-pill);
+  position: relative; overflow: hidden; box-shadow: inset 0 1px 3px rgba(0,0,0,0.4);
+}
+```
+
+### Fill
+```css
+.level-fill {
+  position: absolute; top: 1px; bottom: 1px;
+  background: var(--amber); border-radius: var(--radius-pill);
+  transition: left 0.1s, width 0.1s;
+}
+```
+
+### Center Mark
+```css
+.level-center-mark { position: absolute; top: 0; bottom: 0; left: 50%; width: 1px; background: #444; z-index: 2; }
+```
+
+### Text Label
+```css
+.level-text { font-size: 8px; color: var(--text-muted); letter-spacing: 2px; font-family: var(--font-ui); }
+```
+
+## HTML Structure
+```html
+<div class="level-wrap">
+  <div class="level-bar">
+    <div class="level-center-mark"></div>
+    <div class="level-fill" style="left:45%;width:10%"></div>
+  </div>
+  <span class="level-text">HORIZON &mdash; +2&deg;</span>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+- Bar: Recessed panel with pill shape
+- Fill: Solid amber
+
+## Theme Behavior
+- Bar adapts via tokens
+- Amber fill is fixed
+- Center mark is fixed at `#444`
+
+## Constraints
+1. Center mark MUST be at exact 50% horizontal position.
+2. Fill uses `left` and `width` to show position and magnitude of tilt.
+3. Pill border-radius (100px) for level-instrument aesthetic.
+4. Fill transitions use 0.1s for responsive feedback.
+
+## Accessibility
+- Use `role="meter"` with `aria-valuenow` for tilt angle
+- `aria-label="Horizon level"`

package/spec/components/meters/oscilloscope.md

@@ -0,0 +1,83 @@
+---
+name: Oscilloscope
+id: oscilloscope
+class: .oscilloscope
+category: meters
+index: 14
+materials: [phosphor-screen]
+sizes: [md]
+interactive: false
+requires_js: true
+canvas: true
+---
+
+# Oscilloscope
+
+## Physical Analog
+**Reference devices**: Tektronix analog oscilloscopes, audio test equipment, synthesizer waveform monitors.
+**Mechanism**: Cathode ray tube (CRT) display. Electron beam deflected by input signal (vertical) while swept horizontally at constant rate. Beam strikes P31 phosphor screen which glows briefly, creating trailing afterglow effect.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Container | 200x80px |
+| Center line | 1px at 50% height (zero-voltage reference) |
+| Canvas | Full container size |
+
+## CSS Recipe
+
+### Container
+```css
+.oscilloscope {
+  width: 200px; height: 80px; background: var(--bg-inset);
+  border: 1px solid var(--border-subtle); border-radius: var(--radius-sm);
+  box-shadow: inset 0 1px 4px rgba(0,0,0,0.5); position: relative; overflow: hidden;
+}
+```
+
+### Zero Reference Line
+```css
+.oscilloscope-line {
+  position: absolute; top: 50%; left: 0; right: 0; height: 1px;
+  background: rgba(102,255,102,0.15);
+}
+```
+
+### Canvas
+```css
+.oscilloscope canvas { display: block; width: 100%; height: 100%; }
+```
+
+## HTML Structure
+```html
+<div class="oscilloscope">
+  <div class="oscilloscope-line"></div>
+  <canvas width="200" height="80" id="oscCanvas"></canvas>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+Single material: Phosphor screen (CRT display).
+
+## Theme Behavior
+- Container adapts via tokens
+- Phosphor green color is fixed
+- Center line green tint is fixed
+
+## Constraints
+1. Background fade (`rgba(14,12,10,0.3)` fill each frame) simulates phosphor decay -- previous trace fades gradually.
+2. Trace color MUST be green (`rgba(102,255,102,0.8)`) matching P31 phosphor.
+3. Canvas `shadowBlur` of 4px green simulates phosphor glow/bloom.
+4. Center reference line is ALWAYS faintly visible (zero-voltage reference), even with no signal.
+5. Animation uses `requestAnimationFrame` loop.
+6. Waveform: `sin(x*0.06 + t)` + harmonics with time offset.
+
+## Accessibility
+- Use `role="img"` with `aria-label` on the canvas
+- Provide text description of the waveform if informational
+- Consider `prefers-reduced-motion` to pause animation
+- Requires JS for canvas animation

package/spec/components/meters/progress-bar.md

@@ -0,0 +1,84 @@
+---
+name: Progress Bar
+id: progress-track
+class: .progress-track
+category: meters
+index: 7
+materials: [panel]
+sizes: [md]
+interactive: false
+requires_js: false
+canvas: false
+---
+
+# Progress Bar
+
+## Physical Analog
+**Reference devices**: iPod file transfer progress, Windows XP file copy dialog, CD burning progress.
+**Mechanism**: Linear indicator showing completion percentage of time-bound process. Track = total work, fill = completed work.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Track | 100% width x 8px height |
+| Fill gradient | Blue-to-green |
+| Container width | 180px |
+
+## CSS Recipe
+
+### Wrapper
+```css
+.progress-wrap { display: flex; flex-direction: column; gap: 4px; width: 180px; }
+```
+
+### Track
+```css
+.progress-track {
+  width: 100%; height: 8px; border-radius: 4px;
+  background: var(--bg-inset); border: 1px solid var(--border-subtle);
+  overflow: hidden; box-shadow: var(--shadow-inset);
+}
+```
+
+### Fill
+```css
+.progress-fill { height: 100%; border-radius: 3px; background: linear-gradient(90deg, var(--blue-info), var(--green-on)); transition: width 0.3s var(--ease-out); }
+```
+
+### Label
+```css
+.progress-label {
+  display: flex; justify-content: space-between;
+  font-family: var(--font-ui); font-size: 9px; font-weight: 500;
+  color: var(--text-muted); letter-spacing: 1px;
+}
+```
+
+## HTML Structure
+```html
+<div class="progress-wrap">
+  <div class="progress-track"><div class="progress-fill" style="width:65%"></div></div>
+  <div class="progress-label"><span>TRANSFER</span><span>65%</span></div>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+- Track: Recessed panel
+- Fill: Blue-to-green gradient
+
+## Theme Behavior
+- Track adapts via tokens
+- Fill gradient colors are fixed
+
+## Constraints
+1. Fill transition MUST use `--ease-out` with 0.3s duration for smooth progress animation.
+2. Track has `overflow: hidden` to clip the fill at edges.
+3. Label row shows description on left, percentage on right.
+
+## Accessibility
+- Use `role="progressbar"` with `aria-valuenow`, `aria-valuemin="0"`, `aria-valuemax="100"`
+- `aria-label` should describe the process

package/spec/components/meters/signal-bars.md

@@ -0,0 +1,80 @@
+---
+name: Signal Bars
+id: signal-bars
+class: .signal-bars
+category: meters
+index: 8
+materials: [panel]
+sizes: [md]
+interactive: false
+requires_js: false
+canvas: false
+---
+
+# Signal Bars
+
+## Physical Analog
+**Reference devices**: Nokia phone signal indicator (universally adopted since ~1998).
+**Mechanism**: Received signal strength indication (RSSI) from cellular radio. 5-bar ascending staircase standardized by Nokia. Each bar = one step of signal quality. Bars light left-to-right as signal improves. Unlit bars shown as dim outlines.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Container height | 24px |
+| Bar width | 4px |
+| Bar gap | 3px |
+| Bar heights | 6px, 10px, 14px, 18px, 22px (ascending) |
+
+## CSS Recipe
+
+### Container
+```css
+.signal-bars { display: flex; align-items: flex-end; gap: 3px; height: 24px; }
+```
+
+### Bars
+```css
+.signal-strength-bar { width: 4px; border-radius: 1px; background: var(--green-on); transition: opacity 0.2s; }
+.signal-strength-bar:nth-child(1) { height: 6px; }
+.signal-strength-bar:nth-child(2) { height: 10px; }
+.signal-strength-bar:nth-child(3) { height: 14px; }
+.signal-strength-bar:nth-child(4) { height: 18px; }
+.signal-strength-bar:nth-child(5) { height: 22px; }
+```
+
+### Off State (Dim)
+```css
+.signal-strength-bar.off { opacity: 0.15; background: var(--text-muted); }
+```
+
+## HTML Structure
+```html
+<div class="signal-bars">
+  <div class="signal-strength-bar"></div>
+  <div class="signal-strength-bar"></div>
+  <div class="signal-strength-bar"></div>
+  <div class="signal-strength-bar off"></div>
+  <div class="signal-strength-bar off"></div>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+- Active: Solid green
+- Off: Muted at 15% opacity
+
+## Theme Behavior
+- Green bar color is fixed
+- Off state uses `--text-muted` (adapts per theme)
+
+## Constraints
+1. Bars MUST ascend left-to-right (6, 10, 14, 18, 22px).
+2. Off bars MUST use `.off` class with `opacity: 0.15` and muted color.
+3. Always 5 bars total (Nokia convention).
+4. Bar border-radius is 1px (minimal rounding).
+
+## Accessibility
+- Use `role="img"` with `aria-label` (e.g., "Signal strength: 3 of 5 bars")

package/spec/components/meters/signal-meter.md

@@ -0,0 +1,84 @@
+---
+name: Signal Meter
+id: signal-meter
+class: .signal-meter
+category: meters
+index: 1
+materials: [phosphor-screen]
+sizes: [md]
+interactive: false
+requires_js: false
+canvas: false
+---
+
+# Signal Meter
+
+## Physical Analog
+**Reference devices**: Graphic equalizer displays (Pioneer, Kenwood car stereos), Winamp visualization, broadcast spectrum analyzers.
+**Mechanism**: LED bar graph array. Each bar is a vertical column of LEDs (8-16 per column, 4-16 columns). Column height represents amplitude of a frequency band. LEDs light bottom-to-top. Green-to-red gradient via different colored LEDs at different heights.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Container height | 100px |
+| Bar width | 16px |
+| Bar gap | 6px |
+| Bar radius | 3px top corners |
+
+## CSS Recipe
+
+### Container
+```css
+.signal-meter { display: flex; align-items: flex-end; gap: 6px; height: 100px; }
+```
+
+### Individual Bar
+```css
+.signal-bar {
+  width: 16px; border-radius: 3px 3px 0 0;
+  background: linear-gradient(180deg, var(--green-hi), var(--green-on));
+  box-shadow: 0 0 8px rgba(102,255,102,0.15);
+  animation: fluctuate 2s infinite ease-in-out;
+}
+```
+
+### Fluctuation Animation
+```css
+@keyframes fluctuate { 0%,100%{filter:brightness(1)} 50%{filter:brightness(1.25)} }
+```
+
+## HTML Structure
+```html
+<div class="signal-meter">
+  <div class="signal-bar" style="height:28%"></div>
+  <div class="signal-bar" style="height:55%"></div>
+  <div class="signal-bar" style="height:80%"></div>
+  <div class="signal-bar" style="height:42%"></div>
+  <div class="signal-bar" style="height:64%"></div>
+  <div class="signal-bar" style="height:35%"></div>
+  <div class="signal-bar" style="height:72%"></div>
+  <div class="signal-bar" style="height:50%"></div>
+</div>
+```
+
+## Size Variants
+No explicit size variants. Heights set per bar via inline style.
+
+## Material Variants
+Single material: LED bars with green gradient and glow.
+
+## Theme Behavior
+- LED colors and glow are fixed (LEDs emit their own light)
+- Container has no background (transparent)
+
+## Constraints
+1. Bars MUST align to bottom (`align-items: flex-end`).
+2. Bar heights are set individually per bar via inline `style`.
+3. `fluctuate` animation simulates continuous signal variation.
+4. Border-radius only on top corners (bars grow from bottom).
+5. Subtle glow (`0 0 8px rgba(102,255,102,0.15)`) simulates LED light spill.
+
+## Accessibility
+- Decorative visualization; use `aria-hidden="true"` if purely decorative
+- If informational, use `role="img"` with `aria-label` describing the signal levels

package/spec/components/meters/vu-meter.md

@@ -0,0 +1,88 @@
+---
+name: VU Meter
+id: vu-meter
+class: .vu-meter
+category: meters
+index: 3
+materials: [phosphor-screen]
+sizes: [md]
+interactive: false
+requires_js: false
+canvas: false
+---
+
+# VU Meter
+
+## Physical Analog
+**Reference devices**: Tascam 424 cassette portastudio, Mackie mixer channel meters, Yamaha mixer LED meters.
+**Mechanism**: Volume Unit meter displaying audio signal level. Standardized ballistic response (300ms integration time) representing perceived loudness. Green-to-amber-to-red gradient: green = safe, amber = approaching 0dBVU, red = clipping.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Container height | 80px |
+| Bar width | 12px |
+| Bar gap | 4px |
+| Bar gradient | Red top, amber middle, green bottom |
+
+## CSS Recipe
+
+### Wrapper
+```css
+.vu-wrap { display: flex; flex-direction: column; align-items: center; gap: 6px; }
+```
+
+### Container
+```css
+.vu-meter { display: flex; align-items: flex-end; gap: 4px; height: 80px; }
+```
+
+### Bar
+```css
+.vu-bar {
+  width: 12px; border-radius: 2px 2px 0 0;
+  background: linear-gradient(180deg, #ff4444, #ffaa00 50%, #44cc66);
+  min-height: 4px;
+}
+```
+
+### Label
+```css
+.vu-label { font-family: var(--font-ui); font-size: 8px; font-weight: 500; letter-spacing: 2px; color: var(--text-muted); }
+```
+
+## HTML Structure
+```html
+<div class="vu-wrap">
+  <div class="vu-meter">
+    <div class="vu-bar" style="height:55%"></div>
+    <div class="vu-bar" style="height:75%"></div>
+    <div class="vu-bar" style="height:90%"></div>
+    <div class="vu-bar" style="height:60%"></div>
+    <div class="vu-bar" style="height:40%"></div>
+    <div class="vu-bar" style="height:70%"></div>
+  </div>
+  <span class="vu-label">L CHANNEL</span>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+Single gradient bar style. The tri-color gradient automatically shows correct color at any height.
+
+## Theme Behavior
+- Bar gradient colors are fixed (LED colors)
+- Label adapts via `--text-muted`
+
+## Constraints
+1. Bar gradient MUST be `linear-gradient(180deg, #ff4444, #ffaa00 50%, #44cc66)` -- single gradient per bar automatically creates correct color at any height.
+2. Bars align to bottom (`flex-end`).
+3. Minimum height of 4px ensures bars are always visible.
+4. Border-radius only on top corners.
+
+## Accessibility
+- Use `role="img"` with `aria-label` describing the levels
+- Or `aria-hidden="true"` if paired with numeric readout

package/spec/components/meters/waveform.md

@@ -0,0 +1,70 @@
+---
+name: Waveform
+id: waveform-wrap
+class: .waveform-wrap
+category: meters
+index: 6
+materials: [phosphor-screen]
+sizes: [md]
+interactive: false
+requires_js: true
+canvas: true
+---
+
+# Waveform
+
+## Physical Analog
+**Reference devices**: Final Cut Pro waveform monitor, DaVinci Resolve parade scope, broadcast waveform monitors.
+**Mechanism**: Shows brightness value for each horizontal position in image. Y-axis = luma level (0-100 IRE). Used in broadcast to ensure legal signal levels.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Canvas | 200x80px |
+| Container padding | 2px |
+| Border-radius | var(--radius-sm) |
+
+## CSS Recipe
+
+### Container
+```css
+.waveform-wrap {
+  background: #0a0a0a; border: 1px solid #1e1e1e;
+  border-radius: var(--radius-sm); padding: 2px;
+  box-shadow: inset 0 1px 4px rgba(0,0,0,0.6);
+}
+```
+
+### Canvas
+```css
+.waveform-canvas { display: block; border-radius: 2px; }
+```
+
+## HTML Structure
+```html
+<div class="waveform-wrap">
+  <canvas class="waveform-canvas" width="200" height="80" id="waveCanvas"></canvas>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+Single material: Phosphor screen.
+
+## Theme Behavior
+- Container uses hardcoded dark colors
+- Canvas content rendered by JS
+
+## Constraints
+1. Canvas renders 200x80px audio waveform.
+2. Single stroke path using compound sine waves (`sin(x*0.08)` + `sin(x*0.03)`) with random jitter.
+3. Stroke color: `rgba(102,255,102,0.6)`, 1px line width.
+4. Container MUST match histogram container styling.
+5. Requires JS for canvas rendering.
+
+## Accessibility
+- Use `role="img"` on canvas with `aria-label`
+- Provide text fallback for screen readers

package/spec/components/navigation/breadcrumbs.md

@@ -0,0 +1,94 @@
+---
+name: Breadcrumbs
+id: breadcrumbs
+class: .breadcrumbs
+category: navigation
+index: 7
+materials: []
+sizes: [default]
+interactive: true
+requires_js: false
+canvas: false
+---
+
+# Breadcrumbs
+
+## Physical Analog
+**Reference devices**: Channel strip label chains on mixing desks.
+**Mechanism**: Represents a navigation path -- derived from the channel routing labels on mixing console signal chains (INPUT -> PREAMP -> EQ -> COMP -> BUS). Each segment represents a level in the navigation hierarchy, with separators indicating signal flow direction.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Gap | 6px |
+| Font size | 10px |
+| Separator font size | 8px |
+| Letter spacing | 1px |
+
+## CSS Recipe
+
+### Container (`.breadcrumbs`)
+```css
+.breadcrumbs {
+  display: flex; align-items: center; gap: 6px;
+  font-family: var(--font-ui); font-size: 10px; font-weight: 500;
+  color: var(--text-muted); letter-spacing: 1px;
+}
+```
+
+### Item (`.breadcrumb-item`)
+```css
+.breadcrumb-item { cursor: pointer; transition: color 0.12s; }
+```
+
+### Hover
+```css
+.breadcrumb-item:hover { color: var(--text-primary); }
+```
+
+### Active (current location)
+```css
+.breadcrumb-item.active { color: var(--amber); }
+```
+
+### Separator (`.breadcrumb-sep`)
+```css
+.breadcrumb-sep { color: var(--text-muted); opacity: 0.5; font-size: 8px; }
+```
+
+## HTML Structure
+```html
+<div class="breadcrumbs">
+  <span class="breadcrumb-item">HOME</span>
+  <span class="breadcrumb-sep">&#9654;</span>
+  <span class="breadcrumb-item">SETTINGS</span>
+  <span class="breadcrumb-sep">&#9654;</span>
+  <span class="breadcrumb-item active">DISPLAY</span>
+</div>
+```
+
+## Size Variants
+No size variants defined.
+
+## Material Variants
+No material variants. Text-only component.
+
+## Theme Behavior
+- Text colors swap via `--text-muted`, `--text-primary` tokens
+- Active item always uses `--amber`
+- Separator opacity remains constant
+
+## Constraints
+1. MUST use right-pointing triangle (&#9654;) as separator to indicate signal flow direction
+2. Separator MUST be at 50% opacity to maintain visual hierarchy
+3. Current/active item MUST be amber colored
+4. Previous items MUST be clickable (navigable)
+5. MUST use uppercase text (mixing desk convention)
+
+## Accessibility
+- Container should have `role="navigation"` and `aria-label="Breadcrumb"`
+- Use `<nav>` element as wrapper
+- Use `<ol>` with `<li>` for semantic list structure
+- Current item should have `aria-current="page"`
+- Separators should be decorative (`aria-hidden="true"`)