@pudge-ui/mcp-server 0.1.0

package/spec/spec/components/overlays/toast.md

@@ -0,0 +1,93 @@
+---
+name: Toast
+id: toast
+class: .toast
+category: overlays
+index: 6
+materials: [glossy-polycarbonate]
+sizes: [default]
+interactive: false
+requires_js: true
+canvas: false
+---
+
+# Toast
+
+## Physical Analog
+**Reference devices**: Nokia SMS arrival notification, iPod song change notification, camera "image saved" confirmation.
+**Mechanism**: A transient notification bar that appears briefly and then dismisses automatically. The entry animation (`toastIn`) slides the element down from above with a slight scale-up -- simulating the way early phone notifications would "slide down" from the top of the screen. The animation uses `--snap-soft` easing for a damped settling effect.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Min width | 180px |
+| Padding | 8px 12px |
+| Border radius | `--radius-md` (8px) |
+| Element gap | 8px |
+| Text font size | 10px |
+| Time font size | 9px |
+| Animation duration | 0.3s |
+
+## CSS Recipe
+
+### Container (`.toast`)
+```css
+.toast {
+  display: flex; align-items: center; gap: 8px;
+  background: var(--bg-raised); border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-md); padding: 8px 12px; min-width: 180px;
+  box-shadow: 0 4px 12px rgba(0,0,0,0.2);
+  animation: toastIn 0.3s var(--snap-soft);
+}
+```
+
+### Entry animation
+```css
+@keyframes toastIn { from{opacity:0;transform:translateY(-8px) scale(0.96)} to{opacity:1;transform:translateY(0) scale(1)} }
+```
+
+### Text (`.toast-text`)
+```css
+.toast-text { font-family: var(--font-ui); font-size: 10px; font-weight: 500; color: var(--text-primary); letter-spacing: 0.5px; }
+```
+
+### Time (`.toast-time`)
+```css
+.toast-time { font-family: var(--font-mono); font-size: 9px; color: var(--text-muted); margin-left: auto; flex-shrink: 0; }
+```
+
+## HTML Structure
+```html
+<div class="toast">
+  <div class="led-dot green"></div>
+  <span class="toast-text">File saved successfully</span>
+  <span class="toast-time">12:45</span>
+</div>
+```
+
+## Size Variants
+No size variants defined.
+
+## Material Variants
+No material variants. Uses standard raised surface.
+
+## Theme Behavior
+- Background swaps via `--bg-raised`
+- Shadow reduces in light mode (0.2 ambient)
+- Text colors adapt via tokens
+- LED dot follows its own color rules
+
+## Constraints
+1. MUST use `toastIn` animation on appearance
+2. Animation MUST use `--snap-soft` easing (damped settle)
+3. MUST include status LED dot on the left for type indication
+4. Time MUST use monospace font and be pushed to the right via `margin-left: auto`
+5. MUST auto-dismiss after a timeout (JS responsibility, typically 3-5s)
+6. Animation MUST include both translateY and scale for natural appearance
+
+## Accessibility
+- Use `role="alert"` or `role="status"` with `aria-live="polite"`
+- If auto-dismissing, provide sufficient time to read (min 5 seconds)
+- Should not interrupt screen reader announcements in progress
+- Consider providing a way to pause auto-dismiss on hover/focus

package/spec/spec/components/overlays/tooltip.md

@@ -0,0 +1,85 @@
+---
+name: Tooltip
+id: tooltip
+class: .tooltip
+category: overlays
+index: 9
+materials: [glossy-polycarbonate]
+sizes: [default]
+interactive: false
+requires_js: true
+canvas: false
+---
+
+# Tooltip
+
+## Physical Analog
+**Reference devices**: Camera HUD floating labels, broadcast graphics lower-thirds, military HUD callout boxes.
+**Mechanism**: A small pop-up information panel that appears near a point of interest to provide context. The triangular tail (created via `::after` rotated 45 degrees) points toward the source element, derived from the callout line patterns in engineering drawings and military head-up display overlays.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Padding | 6px 12px |
+| Border radius | `--radius-sm` (4px) |
+| Font size | 10px |
+| Tail size | 8x8px rotated 45deg |
+| Tail offset | 5px below |
+| Shadow | 0 2px 8px rgba(0,0,0,0.3) |
+
+## CSS Recipe
+
+### Container (`.tooltip`)
+```css
+.tooltip {
+  position: relative; display: inline-flex; padding: 6px 12px;
+  background: var(--bg-raised); border: 1px solid var(--border-mid);
+  border-radius: var(--radius-sm); box-shadow: 0 2px 8px rgba(0,0,0,0.3);
+  font-family: var(--font-ui); font-size: 10px; font-weight: 500;
+  color: var(--text-primary); letter-spacing: 0.5px;
+}
+```
+
+### Tail (pointing down)
+```css
+.tooltip::after {
+  content: ''; position: absolute; bottom: -5px; left: 50%;
+  width: 8px; height: 8px; background: var(--bg-raised);
+  border-right: 1px solid var(--border-mid); border-bottom: 1px solid var(--border-mid);
+  transform: translateX(-50%) rotate(45deg);
+}
+```
+
+## HTML Structure
+```html
+<div class="tooltip">ISO 800 -- Auto</div>
+```
+
+## Size Variants
+No size variants defined.
+
+## Material Variants
+No material variants. Uses standard raised surface.
+
+## Theme Behavior
+- Background swaps via `--bg-raised`
+- Border adapts via `--border-mid`
+- Tail background matches container background
+- Shadow reduces in light mode
+- Text adapts via `--text-primary`
+
+## Constraints
+1. MUST include triangular tail via `::after` pseudo-element
+2. Tail MUST be an 8x8px square rotated 45 degrees
+3. Tail MUST inherit container background and border colors
+4. MUST use `--radius-sm` (small, callout-proportioned)
+5. MUST use `position: relative` for tail positioning
+6. Shadow MUST be moderate (0 2px 8px) -- tooltip is close to surface
+
+## Accessibility
+- Use `role="tooltip"` on the element
+- Trigger element should have `aria-describedby` pointing to tooltip id
+- Tooltip should appear on hover AND focus of the trigger
+- Tooltip should dismiss on Escape key
+- Tooltip must not contain interactive elements

package/spec/spec/components/readouts/camera-readout.md

@@ -0,0 +1,123 @@
+---
+name: Camera Readout
+id: readout
+class: .readout
+category: readouts
+index: 2
+materials: [phosphor-screen]
+sizes: [sm, md, lg]
+interactive: false
+requires_js: false
+canvas: false
+---
+
+# Camera Readout
+
+## Physical Analog
+**Reference devices**: Sony Alpha viewfinder overlay data, Nikon D850 top LCD panel, Canon EOS viewfinder display.
+**Mechanism**: Two display technologies: (1) Top LCD panel -- monochrome segmented LCD, reflective, LED-illuminated in dark. (2) Electronic viewfinder overlay -- data superimposed on EVF OLED microdisplay.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Default value | 24px Michroma |
+| Small value | 16px |
+| Large value | 32px |
+| Inline value | 14px |
+| Label | 8px IBM Plex Mono |
+| Recess | 0.6 opacity inset shadow |
+
+## CSS Recipe
+
+### Default
+```css
+.readout {
+  background: var(--bg-inset); border: 1px solid #1e1e1e;
+  border-radius: var(--radius-md); padding: 8px 14px 10px;
+  display: inline-flex; flex-direction: column; gap: 3px;
+  box-shadow: inset 0 1px 4px rgba(0,0,0,0.6), inset 0 0 0 1px #181818;
+}
+[data-theme="light"] .readout { border-color: var(--border-mid); box-shadow: var(--shadow-inset); }
+```
+
+### Label
+```css
+.readout-label { font-family: var(--font-mono); font-size: 8px; letter-spacing: 3px; color: var(--text-muted); text-transform: uppercase; }
+```
+
+### Value
+```css
+.readout-value {
+  font-family: var(--font-display); font-size: 24px; font-weight: 400;
+  color: var(--amber); line-height: 1; letter-spacing: 1px;
+  text-shadow: 0 0 16px var(--amber-glow);
+}
+```
+
+### Unit
+```css
+.readout-unit { font-family: var(--font-display); font-size: 12px; color: var(--amber-dim); margin-left: 3px; }
+```
+
+### Size & Layout Variants
+```css
+.readout.sm .readout-value { font-size: 16px; }
+.readout.lg .readout-value { font-size: 32px; }
+.readout.wide { min-width: 200px; }
+.readout.timecode .readout-value { font-size: 20px; letter-spacing: 2px; }
+.readout.inline { flex-direction: row; align-items: baseline; gap: 8px; padding: 5px 10px; }
+.readout.inline .readout-label { font-size: 8px; }
+.readout.inline .readout-value { font-size: 14px; }
+```
+
+## HTML Structure
+```html
+<!-- Default -->
+<div class="readout">
+  <div class="readout-label">SHUTTER</div>
+  <div class="readout-value">1/250</div>
+</div>
+
+<!-- Small -->
+<div class="readout sm">
+  <div class="readout-label">ISO</div>
+  <div class="readout-value">800</div>
+</div>
+
+<!-- Inline -->
+<div class="readout inline">
+  <div class="readout-label">F</div>
+  <div class="readout-value">2.8</div>
+</div>
+```
+
+## Size Variants
+
+| Variant | Value Font-Size | Analog |
+|---------|----------------|--------|
+| `.sm` | 16px | Secondary parameters (white balance, drive mode) |
+| default | 24px | Primary parameters (shutter speed, aperture) |
+| `.lg` | 32px | Main hero display (top LCD panel) |
+| `.inline` | 14px | Viewfinder bottom status row |
+| `.timecode` | 20px | SMPTE timecode on video cameras |
+
+## Material Variants
+Single material: Phosphor screen with recessed cavity.
+
+## Theme Behavior
+- Dark: `bg-inset` background, strong inset shadow (0.6), inner ring at `#181818`
+- Light: Lighter background, softer shadow, no inner ring
+- Amber value and glow are fixed
+
+## Constraints
+1. Inset shadow is 0.6 opacity -- standard recess depth (between shallow 0.4 and deep 0.9).
+2. Label MUST use `--font-mono` (IBM Plex Mono) with wide letter-spacing (3px).
+3. Value MUST use `--font-display` (Michroma) with `text-shadow` glow.
+4. Inner ring (`inset 0 0 0 1px #181818`) creates double-depth effect.
+5. Inline variant switches to horizontal layout (row, baseline alignment).
+
+## Accessibility
+- Read-only display
+- Use `aria-live="polite"` for dynamically updating values
+- Labels provide context for the numeric values

package/spec/spec/components/readouts/dot-matrix.md

@@ -0,0 +1,88 @@
+---
+name: Dot Matrix Display
+id: dot-matrix
+class: .dot-matrix
+category: readouts
+index: 7
+materials: [phosphor-screen]
+sizes: [md]
+interactive: false
+requires_js: false
+canvas: false
+---
+
+# Dot Matrix Display
+
+## Physical Analog
+**Reference devices**: LED ticker tape displays (stock exchanges, sports arenas), synthesizer patch name scrollers (Korg M1, Roland JV-1080), bus destination signs.
+**Mechanism**: Grid of individual LEDs (5x7 or 8x8 per character cell). Displays arbitrary text by selectively lighting pixels. Text wider than display scrolls horizontally (marquee) via shift register at fixed rate (20-50ms per column shift).
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Text font | 20px VT323 |
+| Letter-spacing | 3px |
+| Scroll animation | 8s linear infinite |
+| Padding | 8px 16px |
+
+## CSS Recipe
+
+### Container
+```css
+.dot-matrix {
+  padding: 8px 16px; background: var(--bg-inset);
+  border: 1px solid #1e1e1e; border-radius: var(--radius-md);
+  box-shadow: inset 0 1px 4px rgba(0,0,0,0.7); overflow: hidden;
+}
+```
+
+### Scrolling Text
+```css
+.dot-matrix-text {
+  font-family: var(--font-lcd); font-size: 20px; letter-spacing: 3px;
+  color: var(--green-hi); text-shadow: 0 0 8px var(--green-glow);
+  white-space: nowrap;
+  animation: marquee 8s linear infinite;
+}
+```
+
+### Marquee Animation
+```css
+@keyframes marquee {
+  0% { transform: translateX(100%); }
+  100% { transform: translateX(-100%); }
+}
+```
+
+## HTML Structure
+```html
+<div class="dot-matrix" style="width:200px">
+  <div class="dot-matrix-text">NOW PLAYING: TRACK 07 -- MIDNIGHT CITY</div>
+</div>
+```
+
+## Size Variants
+No explicit size variants. Width set by container.
+
+## Material Variants
+Single material: Phosphor screen with LED grid. Default color is green (most common dot-matrix color).
+
+## Theme Behavior
+- Container adapts via `--bg-inset`
+- Green LED color and glow are fixed
+- Inset shadow at 0.7 opacity
+
+## Constraints
+1. Animation MUST use `linear` timing function -- dot matrix scrolling is uniform speed (clock-driven), NOT eased.
+2. `white-space: nowrap` is REQUIRED to prevent text wrapping.
+3. `overflow: hidden` on container clips the scrolling text.
+4. Font MUST be `--font-lcd` (VT323) for pixel-grid appearance.
+5. `text-shadow` with green glow simulates LED light bleeding.
+6. Width MUST be set on container to define the visible "window".
+
+## Accessibility
+- Use `aria-label` on container with the full text content
+- `role="marquee"` or `role="status"` for the scrolling region
+- Consider `prefers-reduced-motion` to pause animation
+- Text content should be accessible even when partially scrolled off-screen

package/spec/spec/components/readouts/lcd-readout.md

@@ -0,0 +1,116 @@
+---
+name: LCD Readout
+id: lcd-readout
+class: .lcd-readout
+category: readouts
+index: 3
+materials: [phosphor-screen]
+sizes: [md]
+interactive: false
+requires_js: false
+canvas: false
+---
+
+# LCD Readout
+
+## Physical Analog
+**Reference devices**: iPod Classic now-playing display, Nokia phone main screen, Casio G-Shock watch display, Game Boy screen.
+**Mechanism**: STN or TN LCD with LED backlight. Characteristic color tint from backlight. Visible pixel grid at close inspection. Slow response time (40-80ms) causing ghosting.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Value font | 28px VT323 (pixel LCD font) |
+| Label font | 8px Rajdhani UI |
+| Padding | 8px 14px 10px |
+
+## CSS Recipe
+
+### Default
+```css
+.lcd-readout {
+  display: inline-flex; flex-direction: column; gap: 3px;
+  padding: 8px 14px 10px; background: var(--bg-inset);
+  border: 1px solid var(--border-subtle); border-radius: var(--radius-md);
+  box-shadow: var(--shadow-inset);
+}
+```
+
+### Label
+```css
+.lcd-label { font-family: var(--font-ui); font-size: 8px; font-weight: 500; letter-spacing: 2px; color: var(--text-muted); text-transform: uppercase; }
+```
+
+### Value (Default: Blue)
+```css
+.lcd-value { font-family: var(--font-lcd); font-size: 28px; color: var(--blue-info); line-height: 1; letter-spacing: 1px; }
+```
+
+### Unit
+```css
+.lcd-unit { font-family: var(--font-ui); font-size: 10px; font-weight: 500; color: var(--text-muted); margin-left: 2px; }
+```
+
+### Color Variants (Backlight Colors)
+```css
+.lcd-readout.green .lcd-value { color: var(--green-on); }
+.lcd-readout.amber .lcd-value { color: var(--amber); }
+.lcd-readout.pink .lcd-value { color: var(--pink-action); }
+.lcd-readout.red .lcd-value { color: var(--red-alert); }
+```
+
+## HTML Structure
+```html
+<!-- Default (blue) -->
+<div class="lcd-readout">
+  <div class="lcd-label">TRACKS</div>
+  <div class="lcd-value">42</div>
+</div>
+
+<!-- Green variant -->
+<div class="lcd-readout green">
+  <div class="lcd-label">SIGNAL</div>
+  <div class="lcd-value">OK</div>
+</div>
+
+<!-- Amber with unit -->
+<div class="lcd-readout amber">
+  <div class="lcd-label">TEMP</div>
+  <div class="lcd-value">72<span class="lcd-unit">&deg;F</span></div>
+</div>
+
+<!-- Pink variant -->
+<div class="lcd-readout pink">
+  <div class="lcd-label">BPM</div>
+  <div class="lcd-value">128</div>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+
+| Color Variant | Backlight Era/Device |
+|---------------|---------------------|
+| default (blue) | iPod Classic, Nokia 6600 |
+| `.green` | Game Boy, early Nokia |
+| `.amber` | Car stereo displays, clock radios |
+| `.pink` | Sony Ericsson, RAZR accent |
+| `.red` | Alert/error states |
+
+## Theme Behavior
+- Background and shadow adapt via tokens (`--bg-inset`, `--shadow-inset`)
+- Color variants are fixed accent colors
+
+## Constraints
+1. Value font MUST be `--font-lcd` (VT323) -- simulates pixel grid of low-res LCDs.
+2. Color variants represent different backlight colors, NOT states.
+3. Unit text uses `--font-ui` (not LCD font) as it's supplementary info.
+4. No text-shadow glow (unlike signal-display) -- LCDs don't emit like OLEDs.
+
+## Accessibility
+- Read-only display
+- Use `aria-live="polite"` for dynamic values
+- Color alone should not convey meaning; pair with labels

package/spec/spec/components/readouts/resource-monitor.md

@@ -0,0 +1,98 @@
+---
+name: Resource Monitor
+id: resource
+class: .resource
+category: readouts
+index: 5
+materials: [panel]
+sizes: [md]
+interactive: false
+requires_js: false
+canvas: false
+---
+
+# Resource Monitor
+
+## Physical Analog
+**Reference devices**: Mac OS X Activity Monitor (circa 2003-2005), Windows Task Manager resource graphs, server rack front-panel status displays.
+**Mechanism**: Derived from analog panel meters on rack-mounted server equipment displaying CPU load, memory usage, or network activity as bar graphs.
+
+## Geometry
+
+| Property | Value |
+|----------|-------|
+| Grid | 2 columns |
+| Gap | 14px |
+| Bar height | 6px |
+| Value font | 24px Michroma |
+| Name font | 9px Rajdhani |
+
+## CSS Recipe
+
+### Grid Container
+```css
+.resource-grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 14px; }
+```
+
+### Individual Resource Card
+```css
+.resource {
+  background: linear-gradient(180deg, var(--bg-panel), var(--bg-inset));
+  border: 1px solid var(--border-subtle); border-radius: var(--radius-md); padding: 14px;
+}
+```
+
+### Name Label
+```css
+.resource-name { font-size: 9px; color: var(--text-muted); letter-spacing: 2px; font-family: var(--font-ui); font-weight: 500; }
+```
+
+### Value
+```css
+.resource-value { margin-top: 8px; color: var(--amber); font-family: var(--font-display); font-size: 24px; }
+```
+
+### Progress Bar
+```css
+.resource-bar { margin-top: 10px; height: 6px; border-radius: 99px; overflow: hidden; background: var(--bg-inset); }
+.resource-fill { height: 100%; background: linear-gradient(90deg, var(--green-hi), var(--green-on)); border-radius: 99px; }
+```
+
+## HTML Structure
+```html
+<div class="resource-grid" style="width:240px">
+  <div class="resource">
+    <div class="resource-name">CPU</div>
+    <div class="resource-value">74%</div>
+    <div class="resource-bar"><div class="resource-fill" style="width:74%"></div></div>
+  </div>
+  <div class="resource">
+    <div class="resource-name">MEM</div>
+    <div class="resource-value">52%</div>
+    <div class="resource-bar"><div class="resource-fill" style="width:52%"></div></div>
+  </div>
+</div>
+```
+
+## Size Variants
+No explicit size variants.
+
+## Material Variants
+- Card: Panel gradient (bg-panel to bg-inset)
+- Bar track: Recessed (bg-inset)
+- Bar fill: Green gradient
+
+## Theme Behavior
+- Card background and borders adapt via tokens
+- Amber value and green bar fill are fixed accent colors
+
+## Constraints
+1. Grid MUST be 2 columns for compact dashboard layout.
+2. Bar fill width is set via inline style (percentage).
+3. Bar uses full pill radius (99px) for rounded ends.
+4. Value font is Michroma display, name font is Rajdhani UI.
+
+## Accessibility
+- Read-only display
+- Each resource card should have `role="meter"` with `aria-valuenow`, `aria-valuemin="0"`, `aria-valuemax="100"`
+- `aria-label` should describe the resource (e.g., "CPU usage")