@pudge-ui/mcp-server 0.1.0 → 0.2.0

package/spec/spec/guides/for-llms.md

@@ -1,129 +0,0 @@
-# Using pudge-ui with Coding Agents
-
-This guide explains how to feed pudge-ui design specs to any LLM or coding agent to generate 2000s-inspired UI components in any framework.
-
-## Core Principle
-
-pudge-ui is not code — it is **context**. You feed the spec to your coding agent, describe what you want, and the agent generates components in your framework (React Native, SwiftUI, Jetpack Compose, Flutter, web CSS, etc.).
-
-## What to provide
-
-Every request to your agent needs two layers of context:
-
-### 1. Foundation (always include)
-
-The foundation establishes the design system's rules. Without it, the agent will make incorrect visual decisions. Include these files:
-
-| File | What it provides | Size |
-|------|-----------------|------|
-| `philosophy.md` | Core design principles (physical analog, warm neutrals, 3-plane depth) | ~1.5KB |
-| `tokens.md` | All color, spacing, typography, radius, motion, shadow values | ~6KB |
-| `materials.md` | 6 material recipes with full CSS | ~4KB |
-| `depth-model.md` | Shadow stack rules, press interaction, glow effects | ~4KB |
-| `naming.md` | Class naming conventions | ~1KB |
-
-**Total foundation**: ~17KB. This fits easily within any LLM's context window.
-
-### 2. Component specs (include only what you need)
-
-Each component has its own spec file (~2-5KB each). Include only the components you're building. Each file contains:
-- The physical analog (what real hardware it mimics)
-- Exact CSS recipe (copy-paste ready)
-- HTML structure
-- Size/material/state variants
-- Constraints (rules that prevent "close but wrong" implementations)
-
-## How to prompt
-
-### Pattern 1: Generate a single component
-
-```
-Here is the pudge-ui design system foundation:
-[paste foundation files]
-
-Here is the component spec:
-[paste component spec file]
-
-Generate this component in [React Native / SwiftUI / Jetpack Compose / Flutter].
-Follow the CSS recipe exactly — translate each CSS property to the framework equivalent.
-Follow the Constraints section strictly.
-```
-
-### Pattern 2: Build a screen with multiple components
-
-```
-Here is the pudge-ui design system foundation:
-[paste foundation files]
-
-Here are the component specs I need:
-[paste 3-5 component spec files]
-
-Build a [music player / camera viewfinder / settings screen] using these components.
-Arrange them according to the composition rules in the foundation.
-```
-
-### Pattern 3: Create a new component (not in the spec)
-
-```
-Here is the pudge-ui design system foundation:
-[paste foundation files]
-
-Here is an example component spec for reference:
-[paste one component spec as an example]
-
-Here is the extension guide:
-[paste extension.md]
-
-Create a new component: [describe what you need].
-Follow the extension guide's checklist. Choose a physical 2000s-era analog.
-Use the foundation's material recipes and depth model.
-```
-
-## Using the MCP server
-
-If your agent supports MCP (Claude Code, Cursor, etc.), install the pudge-ui MCP server for automatic context delivery:
-
-```json
-{
-  "mcpServers": {
-    "pudge-ui": {
-      "command": "npx",
-      "args": ["@pudge-ui/mcp-server"]
-    }
-  }
-}
-```
-
-The agent can then call:
-- `get_component("push-button")` — returns foundation + component spec
-- `get_components(["push-button", "toggle-switch"])` — returns foundation + multiple specs
-- `list_components()` — browse the catalog
-- `search_components("dial")` — fuzzy search
-
-## Framework translation guide
-
-When translating CSS to native frameworks, map these properties:
-
-| CSS Property | React Native | SwiftUI | Jetpack Compose |
-|-------------|-------------|---------|-----------------|
-| `background: linear-gradient(...)` | `LinearGradient` component | `LinearGradient` | `Brush.linearGradient(...)` |
-| `box-shadow: 0 2px 0 #color` | `elevation` + `shadowColor/Offset/Radius` | `.shadow(color:radius:x:y:)` | `Modifier.shadow(elevation, color)` |
-| `box-shadow: inset ...` | Inner `View` with gradient overlay | `overlay` with gradient | `drawBehind` with gradient |
-| `border-radius` | `borderRadius` | `.cornerRadius()` | `shape = RoundedCornerShape()` |
-| `transform: translateY(1px)` | `Animated.Value` | `.offset(y:)` with animation | `Modifier.offset(y = 1.dp)` |
-| `transition: 70ms ease` | `Animated.timing({ duration: 70 })` | `.animation(.easeOut(duration: 0.07))` | `animateFloatAsState(animationSpec = tween(70))` |
-| `backdrop-filter: blur(4px)` | `BlurView` library | `.ultraThinMaterial` | Not natively supported — use `RenderEffect.createBlurEffect` |
-
-## Critical rules for agents
-
-1. **Always include foundation context.** A component spec without the foundation will produce incorrect shadows, wrong colors, and missing materials.
-
-2. **Follow the Constraints section literally.** The constraints exist for physical accuracy. "Travel MUST be 1-2px" means exactly that — not 3px, not 5px.
-
-3. **Use warm grays, not pure grays.** The token `#1c1a18` is NOT `#1c1c1c`. The warmth is the difference between "generic dark UI" and "physical hardware under tungsten lighting."
-
-4. **The 3-plane shadow model is non-negotiable.** Every raised element needs: bottom edge shadow + inner top highlight + inner bottom shadow. Omitting any layer breaks the physical illusion.
-
-5. **Glow effects simulate light emission.** LEDs glow, phosphor screens glow, active indicators glow. Use `box-shadow` with the accent glow color, not just a color change.
-
-6. **Materials are recipes, not suggestions.** Each material (rubber, glossy, metal, etc.) has a specific gradient, border, and shadow recipe. Don't mix properties between materials.

package/spec/spec/guides/prompt-templates.md

@@ -1,143 +0,0 @@
-# Prompt Templates
-
-Pre-built prompts for common pudge-ui tasks. Copy these, fill in the blanks, and paste into your LLM along with the relevant spec files.
-
----
-
-## Generate a single component
-
-```
-I'm using the pudge-ui design system. Here is the foundation context and
-component specification.
-
-[paste foundation files: philosophy.md, tokens.md, materials.md, depth-model.md, naming.md]
-
-[paste the component spec file]
-
-Generate this component in [React Native / SwiftUI / Jetpack Compose / Flutter / Vue / Svelte].
-
-Requirements:
-- Translate every CSS property to the framework's equivalent
-- Follow the Constraints section strictly — these prevent "close but wrong" implementations
-- Include all size variants listed in the spec
-- Include all state transitions (default, hover, active, disabled)
-- Use the exact color tokens from the foundation
-- The 3-plane shadow model (bottom edge + top highlight + bottom chamfer) is mandatory
-```
-
----
-
-## Build a multi-component screen
-
-```
-I'm using the pudge-ui design system. Here is the foundation context and
-the component specifications I need for this screen.
-
-[paste foundation files]
-
-[paste 3-8 component spec files]
-
-Build a [describe the screen: "music player with EQ controls", "camera settings panel",
-"device diagnostic dashboard", etc.] using these components.
-
-Layout requirements:
-- [describe layout: "two columns", "top status bar + main content + bottom controls", etc.]
-- Use the foundation's spacing scale for gaps between components
-- All components should share the same light direction (top-left)
-- Use at most 2 material types in the same panel
-
-The screen should be a complete, functional view — not just individual components
-placed side by side.
-```
-
----
-
-## Create a new component not in the spec
-
-```
-I'm using the pudge-ui design system. Here is the foundation context
-and an example component spec to show the pattern.
-
-[paste foundation files]
-
-[paste one component spec as a reference example — choose one similar to what you need]
-
-[paste extension.md guide]
-
-I need a new component: [describe it — e.g., "a circular progress ring like
-a countdown timer on a microwave oven display"].
-
-Create this component following the pudge-ui design system:
-1. Identify a real 2000s-era device that had this control
-2. Describe how the physical mechanism worked
-3. Apply the appropriate material recipe from the foundation
-4. Use the depth model for shadows
-5. Write the full CSS recipe
-6. Write 3-5 constraints with physical reasoning
-7. Output as a complete spec file following the template format
-```
-
----
-
-## Translate an existing UI to pudge-ui style
-
-```
-I'm using the pudge-ui design system. Here is the foundation context.
-
-[paste foundation files]
-
-I have an existing [React Native / SwiftUI / etc.] screen with standard
-flat UI components. I want to restyle it using the pudge-ui aesthetic.
-
-Here is my current code:
-[paste your existing component/screen code]
-
-Restyle this using pudge-ui's design system:
-- Replace flat backgrounds with the appropriate material recipes (gradient + shadow)
-- Add the 3-plane shadow model to all raised elements
-- Add inset shadows to all recessed elements (inputs, displays)
-- Replace solid colors with the warm token palette
-- Add physical-accurate press interactions (translateY + shadow collapse)
-- Use the pudge-ui typography tokens
-```
-
----
-
-## Build a composition (assembled multi-component panel)
-
-```
-I'm using the pudge-ui design system.
-
-[paste foundation files]
-
-[paste the composition spec file — e.g., camera-viewfinder.md or audio-mixer-strip.md]
-
-[paste all component spec files referenced in the composition]
-
-Build this composition in [framework]. Follow the composition's Layout section
-for positioning, and the Assembly Rules for component configuration. Each
-component must follow its individual spec exactly — the composition just
-arranges them.
-```
-
----
-
-## Quick restyling (minimal context)
-
-For simple restyling tasks where you don't need full spec files, use this minimal prompt:
-
-```
-Restyle this [button/input/card/etc.] using a 2000s consumer electronics aesthetic:
-
-- Warm gray palette (NOT pure gray — use slight amber/brown warmth: #1c1a18 not #1c1c1c)
-- 3-plane shadow model for raised elements:
-  1. Bottom edge: 0 2px 0 #0a0908
-  2. Inner top highlight: inset 0 1px 0 rgba(255,255,255,0.14)
-  3. Inner bottom shadow: inset 0 -1px 0 #111
-- On press: translateY(1px) + bottom shadow collapses to 0 1px 0
-- Inset shadow for recessed elements: inset 0 1px 4px rgba(0,0,0,0.6)
-- Active indicators glow amber: box-shadow 0 0 8px rgba(245,166,35,0.35)
-- Fonts: geometric sans-serif for labels, monospace for data values
-
-[paste your existing component code]
-```