Design System Clawd Agent

Problem Statement

Design systems are slow and expensive to start, and AI tools that 'generate UI' usually produce generic, incoherent output — and worse, when you ask an AI to add the design to your codebase it invents new styles and ignores your conventions. The two real problems: (1) get from a vague idea to a coherent, opinionated system fast, and (2) translate that system into a real React app without the AI hallucinating new design or trampling your repo's patterns.

Proposed Solution

Studio is a Claude Code playground with two cooperating agents. The designer agent (/design-system-agent) interviews you (8–10 questions: what, who, the moment, a reference product, a color), proposes three 'stances' from a 25-style catalog, shows three side-by-side variations of the signature components so you lock the look, then builds the entire system into projects/<name>/ as static HTML and registers it on a visual gallery. The implementer agent (/ship-design-system <slug> --to ../app) reads your existing React repo first — Tailwind config, path aliases, component layout, export style, class util — then translates the HTML system into real .tsx that matches your codebase, showing diffs before any change.

Full Solution Details

• Intake → stances → variations → build. A guided flow that ends in a complete, coherent HTML design system (not a one-shot blob), with a calibrated reference project (Medcord, "Surgical paper" stance) as the quality bar.
• Gallery. index.html renders every system as a framed plate with a signature-component thumbnail; click to enter the full system. Zero build — pure static HTML.
• One-liner mode. /design-system-agent design a fintech app for retail traders skips already-answered questions.
• Ship agent guardrails. Reads the target repo before writing; asks discovery questions; never invents design, only translates; show-the-diff before touching package.json/config; never runs pnpm install without permission.
• Persistent memory. Every session the agent reads CLAUDE.md (operating manual), notes/preferences.md (durable cross-project preferences), notes/rejected.md (things you've said no to), projects/projects.json (the shelf), and styles/STYLE-CATALOG.md (the 25 stances).

Technical Documentation

The deliverable is not code-as-app but agent design: a CLAUDE.md operating manual governing two roles, a 25-entry style catalog, a memory/preferences system (preferences + rejected lists so the agent learns your taste and doesn't repeat mistakes), and a static-HTML output format that doubles as the canonical visual spec. The implementer agent is explicitly conservative: it inspects the existing repo's conventions and confirms them before generating, treats the Studio HTML as the source of truth ("why a component looks the way it does"), and gates all destructive/install actions behind diffs and permission. The whole playground is dependency-free static HTML — no Node, no build, no server.

Tech Stack

Claude Code (custom slash-command agents), Anthropic Claude, static HTML/CSS (output + gallery), a markdown-driven memory system (CLAUDE.md, preferences, rejected, style catalog).

System Design

/design-system-agent  (designer)
   intake (8-10 Qs) → propose 3 stances (from 25-style catalog)
   → 3 side-by-side signature-component variations → lock look
   → build full system → projects/<name>/*.html → register on gallery
        │  reads each session: CLAUDE.md · preferences.md · rejected.md
        │                       projects.json · STYLE-CATALOG.md
        ▼
   Studio HTML = canonical visual spec
        │
/ship-design-system <slug> --to ../react-app  (implementer)
   read repo (tailwind, aliases, exports, class util) → confirm conventions
   → translate HTML → matching .tsx  (never invents design)
   → show diffs · ask before install/config changes

Smart Architectural Decisions

• Two specialized agents, not one. Separating design (creative, divergent) from implementation (conservative, convention-matching) lets each be tuned correctly — the designer explores, the implementer never invents. That role split is the key insight.
• "Never invent design, only translate." Constraining the implementer to read the repo and translate the locked HTML spec directly solves the core failure mode of AI-codegen (hallucinated, inconsistent UI) and respects existing conventions.
• HTML as the canonical spec. Keeping the system as static HTML means it's both the deliverable and the living documentation devs reference — design decisions don't get lost in translation.
• Memory system (preferences + rejected). Persisting taste and prior 'no's across sessions makes the agent improve over time and stop re-proposing rejected ideas — real agent UX design.
• Permission-gated mutations (diffs, no auto-install) make the implementer safe to point at a real repo.

Impacts

Compresses 'idea → coherent design system → shipped in your React app' into a guided, opinionated workflow — while structurally preventing the two things that make AI UI tools fail (incoherence and convention-trampling). A meta-tool that productizes the author's own design-engineering process.

Demonstrated Skills

Agent/LLM workflow design (multi-agent role separation, guardrails, permission gating); prompt-system + memory engineering (CLAUDE.md operating manual, preferences/rejected learning, style catalog); design-systems expertise (25 stances, signature-component thinking, calibrated reference bar); code-generation safety (read-before-write, translate-not-invent, show-the-diff); Claude Code customization (slash commands).