@pudge-ui/mcp-server 0.1.0

package/spec/components/meters/battery-icon.md

@@ -0,0 +1,104 @@
+---
+name: Battery Icon
+id: battery-icon
+class: .battery-icon
+category: meters
+index: 9
+materials: [panel]
+sizes: [md]
+interactive: false
+requires_js: false
+canvas: false
+---
+
+# Battery Icon
+
+## Physical Analog
+**Reference devices**: Every mobile phone, camera, and portable device from the era.
+**Mechanism**: Miniaturized bar gauge shaped like physical battery (rectangular body + positive terminal nub on right). Fill level = remaining charge. Three color states: green (>40%), amber (20-40%), red (<20%).
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Body | 28x14px |
+| Border | 2px solid |
+| Terminal nub | 3x6px on right side |
+| Fill padding | 2px inside body |
+
+## CSS Recipe
+
+### Container
+```css
+.battery-icon { display: inline-flex; align-items: center; gap: 2px; }
+```
+
+### Body
+```css
+.battery-body {
+  width: 28px; height: 14px; border: 2px solid var(--border-mid);
+  border-radius: 3px; padding: 2px; position: relative;
+}
+```
+
+### Terminal Nub (Pseudo-element)
+```css
+.battery-body::after {
+  content: ''; position: absolute; right: -5px; top: 50%; transform: translateY(-50%);
+  width: 3px; height: 6px; background: var(--border-mid); border-radius: 0 1px 1px 0;
+}
+```
+
+### Fill
+```css
+.battery-fill { height: 100%; border-radius: 1px; background: var(--green-on); transition: width 0.3s, background 0.3s; }
+```
+
+### Charge Level Variants
+```css
+.battery-fill.medium { background: var(--amber); }
+.battery-fill.low { background: var(--red-alert); }
+```
+
+## HTML Structure
+```html
+<!-- Full -->
+<div class="battery-icon">
+  <div class="battery-body"><div class="battery-fill" style="width:80%"></div></div>
+</div>
+
+<!-- Medium -->
+<div class="battery-icon">
+  <div class="battery-body"><div class="battery-fill medium" style="width:40%"></div></div>
+</div>
+
+<!-- Low -->
+<div class="battery-icon">
+  <div class="battery-body"><div class="battery-fill low" style="width:15%"></div></div>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+
+| Charge Level | Class | Color |
+|-------------|-------|-------|
+| >40% | default | Green (`--green-on`) |
+| 20-40% | `.medium` | Amber (`--amber`) |
+| <20% | `.low` | Red (`--red-alert`) |
+
+## Theme Behavior
+- Border color adapts via `--border-mid`
+- Fill colors are fixed accent colors
+
+## Constraints
+1. Terminal nub on RIGHT side via `::after` pseudo-element.
+2. Fill color classes MUST match charge thresholds: green > amber > red.
+3. Fill width set via inline style as percentage.
+4. Body border is 2px (thicker than most borders) for icon visibility.
+
+## Accessibility
+- Use `role="img"` with `aria-label` (e.g., "Battery: 80%")
+- Color state should be supplemented with text for accessibility

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

@@ -0,0 +1,93 @@
+---
+name: Equalizer Bars
+id: eq-bars
+class: .eq-bars
+category: meters
+index: 4
+materials: [phosphor-screen]
+sizes: [md]
+interactive: false
+requires_js: false
+canvas: false
+---
+
+# Equalizer Bars
+
+## Physical Analog
+**Reference devices**: Winamp visualization, Windows Media Player EQ display, car stereo graphic EQ.
+**Mechanism**: Graphic equalizer showing gain/cut per frequency band. Unlike VU (signal level), EQ shows frequency response curve. Bars represent fixed bands (60Hz, 250Hz, 1kHz, 4kHz, 16kHz). Height = boost/cut applied.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Container height | 90px |
+| Band width | 14px |
+| Band gap | 3px |
+
+## CSS Recipe
+
+### Wrapper
+```css
+.eq-wrap { display: flex; flex-direction: column; align-items: center; gap: 6px; }
+```
+
+### Container
+```css
+.eq-bars { display: flex; align-items: flex-end; gap: 3px; height: 90px; }
+```
+
+### Band (Default: Blue)
+```css
+.eq-band {
+  width: 14px; border-radius: 2px 2px 0 0;
+  background: linear-gradient(180deg, var(--blue-info), #2255aa);
+  min-height: 4px;
+}
+```
+
+### Color Variants
+```css
+.eq-band.warm { background: linear-gradient(180deg, var(--pink-action), #994466); }
+.eq-band.bright { background: linear-gradient(180deg, var(--gold-warm), #997722); }
+```
+
+## HTML Structure
+```html
+<div class="eq-wrap">
+  <div class="eq-bars">
+    <div class="eq-band warm" style="height:30%"></div>
+    <div class="eq-band warm" style="height:50%"></div>
+    <div class="eq-band" style="height:70%"></div>
+    <div class="eq-band" style="height:90%"></div>
+    <div class="eq-band" style="height:75%"></div>
+    <div class="eq-band bright" style="height:55%"></div>
+    <div class="eq-band bright" style="height:35%"></div>
+    <div class="eq-band bright" style="height:20%"></div>
+  </div>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+
+| Color Variant | Frequency Range |
+|---------------|----------------|
+| `.warm` (pink) | Low/mid frequencies |
+| default (blue) | Mid frequencies |
+| `.bright` (gold) | High frequencies |
+
+## Theme Behavior
+- Band colors are fixed accent colors
+- No theme-dependent changes
+
+## Constraints
+1. Color variants MUST distinguish frequency ranges: warm=low, default=mid, bright=high.
+2. Bands are narrower than VU bars (14px vs 12px) with tighter gap (3px vs 4px).
+3. Each band gradient runs lighter at top, darker at bottom.
+
+## Accessibility
+- Decorative visualization
+- Use `aria-hidden="true"` or `role="img"` with `aria-label`

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

@@ -0,0 +1,96 @@
+---
+name: EV Meter
+id: ev-meter
+class: .ev-meter
+category: meters
+index: 2
+materials: [panel]
+sizes: [md]
+interactive: false
+requires_js: false
+canvas: false
+---
+
+# EV Meter
+
+## Physical Analog
+**Reference devices**: Camera viewfinder exposure meter (present in every DSLR/mirrorless since 1960s).
+**Mechanism**: Shows difference between metered light level and selected exposure settings. Zero (center) = correct exposure. Positive = overexposure, negative = underexposure. Originally a moving-coil galvanometer needle in film-era cameras.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Track | 18px wide x 120px tall |
+| Zero line | 1px at vertical center |
+| Fill bar | Extends from center (up or down) |
+| Readout | 10px Michroma below |
+
+## CSS Recipe
+
+### Container
+```css
+.ev-meter { display: flex; flex-direction: column; align-items: center; gap: 4px; }
+.ev-sign { font-size: 10px; color: var(--text-muted); letter-spacing: 1px; font-family: var(--font-ui); }
+```
+
+### Track
+```css
+.ev-track {
+  width: 18px; height: 120px; background: var(--bg-inset);
+  border: 1px solid var(--border-subtle); border-radius: var(--radius-sm);
+  position: relative; overflow: hidden; box-shadow: inset 1px 0 3px rgba(0,0,0,0.4);
+}
+```
+
+### Zero Line
+```css
+.ev-zero-line { position: absolute; top: 50%; left: 0; right: 0; height: 1px; background: #555; z-index: 2; }
+```
+
+### Fill Bar
+```css
+.ev-fill-bar {
+  position: absolute; left: 3px; right: 3px;
+  background: var(--amber); border-radius: 1px; z-index: 1;
+}
+```
+
+### Readout
+```css
+.ev-readout { font-family: var(--font-display); font-size: 10px; color: var(--amber); letter-spacing: 1px; }
+```
+
+## HTML Structure
+```html
+<div class="ev-meter">
+  <span class="ev-sign">+</span>
+  <div class="ev-track">
+    <div class="ev-zero-line"></div>
+    <div class="ev-fill-bar" style="top:30%;height:20%"></div>
+  </div>
+  <span class="ev-sign">&minus;</span>
+  <span class="ev-readout">+0.7</span>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+- Track: Recessed panel
+- Fill: Solid amber
+
+## Theme Behavior
+- Track adapts via tokens
+- Amber fill and readout are fixed
+
+## Constraints
+1. Zero line MUST be at exact vertical center (50%).
+2. Fill bar extends from center upward (overexposure) or downward (underexposure).
+3. Fill position uses `top` and `height` percentages.
+4. + sign at top, - sign at bottom (standard photographic convention).
+
+## Accessibility
+- Use `role="meter"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
+- `aria-label="Exposure compensation"`

package/spec/components/meters/exposure-scale.md

@@ -0,0 +1,110 @@
+---
+name: Exposure Scale
+id: exp-scale
+class: .exp-scale
+category: meters
+index: 11
+materials: [panel]
+sizes: [md]
+interactive: false
+requires_js: false
+canvas: false
+---
+
+# Exposure Scale
+
+## Physical Analog
+**Reference devices**: Bottom-of-viewfinder EV ruler in SLR/DSLR cameras (since Nikon F3, ~1980).
+**Mechanism**: Horizontal tick ruler showing exposure compensation scale (-2 to +2 EV). Tick marks at 1/3-stop increments. Floating dot indicator shows current EV compensation. Major ticks (full-stop) taller than minor ticks (1/3-stop).
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Width | 200px |
+| Track height | 12px |
+| Major tick | 8px height |
+| Minor tick | 4-5px height |
+| Indicator dot | 6px diameter |
+
+## CSS Recipe
+
+### Container
+```css
+.exp-scale { display: flex; flex-direction: column; align-items: center; gap: 2px; width: 200px; }
+```
+
+### Track
+```css
+.exp-track { width: 100%; height: 12px; position: relative; display: flex; align-items: center; }
+```
+
+### Ruler Line
+```css
+.exp-ruler { width: 100%; height: 1px; background: #333; position: absolute; }
+```
+
+### Tick Marks
+```css
+.exp-ticks { position: absolute; inset: 0; display: flex; align-items: flex-end; justify-content: space-between; padding: 0 2px; }
+.exp-tick { width: 1px; background: #333; }
+.exp-tick.major { height: 8px; background: #555; }
+.exp-tick.minor { height: 5px; }
+```
+
+### Indicator Dot
+```css
+.exp-indicator {
+  position: absolute; bottom: 0; width: 6px; height: 6px;
+  background: var(--amber); border-radius: 50%; transform: translateX(-50%);
+  box-shadow: 0 0 6px var(--amber-glow);
+}
+```
+
+### Labels
+```css
+.exp-labels { width: 100%; display: flex; justify-content: space-between; padding: 0 2px; }
+.exp-labels span { font-size: 7px; color: var(--text-muted); letter-spacing: 1px; font-family: var(--font-ui); }
+```
+
+## HTML Structure
+```html
+<div class="exp-scale">
+  <div class="exp-track">
+    <div class="exp-ruler"></div>
+    <div class="exp-ticks">
+      <div class="exp-tick major" style="height:8px"></div>
+      <div class="exp-tick minor" style="height:4px"></div>
+      <div class="exp-tick minor" style="height:4px"></div>
+      <div class="exp-tick major" style="height:8px"></div>
+      <!-- ... repeat for -2 to +2 range -->
+      <div class="exp-tick major" style="height:8px"></div>
+    </div>
+    <div class="exp-indicator" style="left:62%"></div>
+  </div>
+  <div class="exp-labels"><span>-2</span><span>-1</span><span>0</span><span>+1</span><span>+2</span></div>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+- Ruler and ticks: Subtle gray lines
+- Indicator: Amber dot with glow
+
+## Theme Behavior
+- Tick and ruler colors are fixed subtle grays
+- Amber indicator and glow are fixed
+- Labels use `--text-muted`
+
+## Constraints
+1. Major ticks MUST be taller than minor ticks (8px vs 4-5px).
+2. Tick spacing represents 1/3-stop increments between major full-stop marks.
+3. Indicator position set via `left` percentage.
+4. Labels MUST show -2, -1, 0, +1, +2 at equal spacing.
+5. Labels are 7px font (very small, viewfinder annotation style).
+
+## Accessibility
+- Use `role="img"` with `aria-label` describing current EV value
+- Or `role="meter"` if interactive

package/spec/components/meters/gauge-full.md

@@ -0,0 +1,102 @@
+---
+name: Gauge Full Circle
+id: gauge-full
+class: .gauge-full
+category: meters
+index: 13
+materials: [panel, chrome]
+sizes: [md]
+interactive: false
+requires_js: true
+canvas: false
+---
+
+# Gauge Full Circle
+
+## Physical Analog
+**Reference devices**: Compass (ship/aircraft), RPM tachometer, clock face, radio tuning dial.
+**Mechanism**: Full 360-degree rotating indicator. Magnetic compass: magnetized needle aligns with Earth's magnetic field. Tachometer: moving-coil meter with extended angular range or servo-driven indicator.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Container | 120x120px circle |
+| Needle | 2px wide x 48px tall |
+| Pivot | 8px diameter at center |
+| Cardinal labels | N/S/E/W at four positions |
+
+## CSS Recipe
+
+### Container
+```css
+.gauge-full {
+  width: 120px; height: 120px; border-radius: 50%;
+  background: var(--bg-inset); border: 2px solid var(--border-mid);
+  position: relative;
+  box-shadow: inset 0 1px 6px rgba(0,0,0,0.5), 0 2px 8px rgba(0,0,0,0.3);
+}
+```
+
+### Needle
+```css
+.gauge-full-needle {
+  position: absolute; top: 12px; left: 50%; width: 2px; height: 48px;
+  background: linear-gradient(180deg, var(--red-alert), transparent);
+  transform-origin: bottom center;
+  margin-left: -1px; z-index: 2;
+}
+```
+
+### Pivot
+```css
+.gauge-full-pivot {
+  position: absolute; top: 50%; left: 50%; transform: translate(-50%,-50%);
+  width: 8px; height: 8px; border-radius: 50%;
+  background: radial-gradient(circle, #888, #333);
+  z-index: 3;
+}
+```
+
+### Cardinal Labels
+```css
+.gauge-full-label {
+  position: absolute; font-family: var(--font-ui); font-size: 7px; font-weight: 600;
+  color: var(--text-muted); letter-spacing: 1px;
+}
+```
+
+## HTML Structure
+```html
+<div class="gauge-full">
+  <div class="gauge-full-needle" style="transform:rotate(45deg)"></div>
+  <div class="gauge-full-pivot"></div>
+  <span class="gauge-full-label" style="top:8px;left:50%;transform:translateX(-50%)">N</span>
+  <span class="gauge-full-label" style="right:8px;top:50%;transform:translateY(-50%)">E</span>
+  <span class="gauge-full-label" style="bottom:8px;left:50%;transform:translateX(-50%)">S</span>
+  <span class="gauge-full-label" style="left:8px;top:50%;transform:translateY(-50%)">W</span>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+- Container: Recessed panel with thick border
+- Needle: Red-to-transparent gradient
+- Pivot: Metallic radial gradient
+
+## Theme Behavior
+- Container adapts via tokens
+- Needle red and text colors adapt via accent tokens
+
+## Constraints
+1. Needle rotates full 360 degrees from center point.
+2. Cardinal labels (N/S/E/W) are positioned absolutely at four compass points.
+3. Needle uses `transform-origin: bottom center` -- tip points outward.
+4. Needle gradient fades from red tip to transparent tail.
+5. Pivot is centered with `translate(-50%,-50%)`.
+
+## Accessibility
+- Use `role="img"` with `aria-label` (e.g., "Compass heading: 45 degrees NE")
+- Requires JS to update needle rotation

package/spec/components/meters/gauge-semi.md

@@ -0,0 +1,113 @@
+---
+name: Gauge Semicircular
+id: gauge-semi
+class: .gauge-semi
+category: meters
+index: 12
+materials: [panel, chrome]
+sizes: [md]
+interactive: false
+requires_js: true
+canvas: false
+---
+
+# Gauge Semicircular
+
+## Physical Analog
+**Reference devices**: Analog VU meters (Dorrough, Sifam), vintage radio signal strength meters, ammeter/voltmeter panel meters.
+**Mechanism**: D'Arsonval moving-coil galvanometer. Lightweight coil in permanent magnet field. Current through coil creates rotation. Needle attached to coil moves across calibrated scale. Hairspring provides restoring force. Jeweled bearing (sapphire) at pivot.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Container | 160x90px semicircle |
+| Needle | 2px wide x 70px tall |
+| Pivot | 10px diameter at bottom center |
+| Scale arc | 90-120 degrees |
+| Needle range | -60deg to +60deg |
+
+## CSS Recipe
+
+### Container (Faceplate)
+```css
+.gauge-semi {
+  width: 160px; height: 90px; position: relative;
+  background: var(--bg-inset); border: 1px solid var(--border-subtle);
+  border-radius: 80px 80px 0 0; overflow: hidden;
+  box-shadow: inset 0 1px 4px rgba(0,0,0,0.5);
+}
+```
+
+### Scale Arc
+```css
+.gauge-semi-scale {
+  position: absolute; inset: 8px; inset-block-end: 0; border-radius: 72px 72px 0 0;
+  border: 1px solid var(--border-mid); border-bottom: none;
+}
+```
+
+### Needle
+```css
+.gauge-semi-needle {
+  position: absolute; bottom: 0; left: 50%; width: 2px; height: 70px;
+  background: linear-gradient(0deg, var(--red-alert), transparent 20%, var(--text-primary) 20%);
+  transform-origin: bottom center; transform: rotate(-60deg);
+  transition: transform 0.5s var(--spring);
+  z-index: 2;
+}
+```
+
+### Pivot Bearing
+```css
+.gauge-semi-pivot {
+  position: absolute; bottom: -4px; left: 50%; transform: translateX(-50%);
+  width: 10px; height: 10px; border-radius: 50%;
+  background: radial-gradient(circle, #666, #222);
+  z-index: 3;
+}
+```
+
+### Scale Labels
+```css
+.gauge-semi-labels {
+  position: absolute; bottom: 6px; left: 10px; right: 10px;
+  display: flex; justify-content: space-between;
+  font-family: var(--font-ui); font-size: 7px; color: var(--text-muted);
+}
+```
+
+## HTML Structure
+```html
+<div class="gauge-semi">
+  <div class="gauge-semi-scale"></div>
+  <div class="gauge-semi-needle" style="transform:rotate(-20deg)"></div>
+  <div class="gauge-semi-pivot"></div>
+  <div class="gauge-semi-labels"><span>-20</span><span>VU</span><span>+3</span></div>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+- Faceplate: Recessed panel
+- Needle: Red-tipped indicator
+- Pivot: Metallic radial gradient (jeweled bearing)
+
+## Theme Behavior
+- Faceplate adapts via tokens
+- Needle tip red and body color adapt via `--red-alert` and `--text-primary`
+- Pivot metallic gradient is fixed
+
+## Constraints
+1. Needle MUST use `transform-origin: bottom center` for pivot rotation.
+2. Needle rotation range is -60deg to +60deg (set via `transform: rotate(Ndeg)`).
+3. Transition MUST use `--spring` easing for ballistic needle movement (overshoot).
+4. Needle gradient has red tip at bottom 20% -- the visible tip of the pointer.
+5. Pivot is positioned at `bottom: -4px` to appear as center pivot point.
+
+## Accessibility
+- Use `role="meter"` with `aria-valuenow`
+- `aria-label` should describe the measured value
+- Requires JS to update needle rotation

package/spec/components/meters/histogram.md

@@ -0,0 +1,70 @@
+---
+name: Histogram
+id: histogram-wrap
+class: .histogram-wrap
+category: meters
+index: 5
+materials: [phosphor-screen]
+sizes: [md]
+interactive: false
+requires_js: true
+canvas: true
+---
+
+# Histogram
+
+## Physical Analog
+**Reference devices**: Sony camera histogram overlay, Final Cut Pro waveform monitor, DaVinci Resolve parade scope.
+**Mechanism**: Shows distribution of brightness values in an image. X-axis = brightness (black to white), Y-axis = pixel count at that brightness. Used by camera operators to judge exposure.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Canvas | 200x80px |
+| Container padding | 2px |
+| Border-radius | var(--radius-sm) |
+
+## CSS Recipe
+
+### Container
+```css
+.histogram-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
+.histogram-canvas { display: block; border-radius: 2px; }
+```
+
+## HTML Structure
+```html
+<div class="histogram-wrap">
+  <canvas class="histogram-canvas" width="200" height="80" id="histCanvas"></canvas>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+Single material: Phosphor screen with deep black background.
+
+## Theme Behavior
+- Container uses hardcoded dark colors (monitor displays are always dark)
+- Canvas content rendered by JS
+
+## Constraints
+1. Canvas renders 200x80px luminance distribution.
+2. For each x pixel, calculate height using sine-based curve with random variation.
+3. Draw 1px-wide vertical bars with amber gradient (`rgba(245,166,35,0.1)` to `rgba(245,166,35,0.6)`).
+4. Container background MUST be near-black (`#0a0a0a`).
+5. Requires JS for canvas rendering.
+
+## Accessibility
+- Use `role="img"` on canvas with `aria-label` describing the histogram
+- Provide text fallback for screen readers