io.github.pudge-studio/pudge-ui

A design system for 2000s-era consumer-electronics interfaces, written for coding agents.

Like what you see? ⭐ Star pudge-ui on GitHub — it helps coding agents and developers discover the project.

pudge-ui is a specification, not a component library. There's no package to install and no React components to import. Each component is a written spec — the physical part it imitates, how that part works, the exact CSS, and the rules that keep an implementation honest. You hand the spec to a coding agent, and it builds the component in whatever stack you're using: React Native, SwiftUI, Jetpack Compose, Flutter, or plain CSS.

Skeuomorphic detail doesn't fit in design tokens. --color-primary: blue can't describe the three-layer shadow of a raised rubber button or the lip shadow inside a recessed LCD. That needs prose — which is also what an LLM reads best.

Every component spec covers:

• Physical analog — the real 2000s hardware it mimics (Sony Walkman, Nikon dials, iPod click wheel, Nokia keypads, DJ consoles)
• Mechanism — how the part actually works (dome switches, rotary encoders, capacitive touch)
• CSS recipe — the exact CSS that reproduces the look
• Constraints — rules that rule out the "close but wrong" version

Use it

1. Browse the components at ui.pudgestudio.com.
2. Copy a component spec, or install the MCP server below.
3. Give it to your agent (Claude, GPT, Copilot, whatever) and describe what you're building.

Quick start

With MCP (Claude Code, Cursor, etc.)

Add to your MCP config:

{
  "mcpServers": {
    "pudge-ui": {
      "command": "npx",
      "args": ["-y", "@pudge-ui/mcp-server"]
    }
  }
}

Then ask your agent: "Build a music player interface using pudge-ui components"

Manual (any LLM)

1. Copy the foundation spec
2. Copy the component spec(s) you need
3. Paste into your LLM conversation
4. Describe what you want to build

What's inside

93 components across 11 categories

6 material surfaces

Every component uses one of six physically-accurate material recipes:

1. Brushed Metal — iPod back plate, anodized aluminum
2. Chrome — Nikon dial rings, polished trim
3. Rubber — Gameboy buttons, soft-touch matte
4. Glossy Polycarbonate — iPod Nano case, gel buttons
5. Glass — iMac G3 clear shell, frosted plastic
6. Phosphor Screen — Camera viewfinder, VU meter display

Project structure

spec/
  foundation/     design tokens, materials, depth model, naming
  components/     individual component specs
  compositions/   multi-component assembly specs
  guides/         extension guide, LLM usage guide, prompt templates
packages/
  mcp-server/     MCP server for agent integration
docs/             documentation site (ui.pudgestudio.com)

Philosophy

1. Physical analog commitment — every CSS property maps to a real material or manufacturing process
2. Warm neutral palette — warm grays (#1c1a18 not #1c1c1c) under tungsten workbench lighting
3. Three-plane depth model — every raised element uses a 3-layer shadow stack
4. Material honesty — rubber looks different from chrome looks different from glass

Contributing

See CONTRIBUTING.md for guidelines.

License & brand

Code and component specs are MIT. The pudge-ui name, the Pudge capybara mascot, and the logo are trademarks of Pudge Studio and are not covered by the MIT license — please don't use them to imply endorsement or for a fork's branding.

License

MIT