Skip to content

For Design Engineers

Who this is for. The person whose primary responsibility is refining the design harness itself — tokens, components, lint rules, contrast checks, DESIGN.md, the agent context that tells Claude Code how to consume all of it. You also ship features end-to-end (no engineer handoff). "Design engineer" describes the shape of the job, not a handoff line: product engineers and product owners are also builders shipping production code; this page is just the entry point for the person whose center of gravity is the harness.

Sister pages: for product engineers (consuming tokens in product code) · for product owners (voice, tone, density). Read this, then read HARNESS.md.

The job, in one screen

You do You don't
Write DESIGN.md rules + rationales Make Figma mockups as the final artifact
Write code that ships to production Hand pixel specs to an engineer
Build tokens, components, lint rules Approve work in design review as a gate
Spot-audit agent-produced surfaces Review every screen before merge
Run Claude Design for ideation Maintain a Figma library as canonical
Refine the harness so agents stop making the same mistake Hand-fix every drift on every PR

The work is the harness. One polished screen is worth less than the lint rule that produces ten thousand acceptable screens. (DESIGN.md §0 Rule 4.)

Where to start

  1. Read DESIGN.md §0 — five rules every other choice is downstream of. Twice.
  2. Read HARNESS.md — the practice. Toolchain, two loops, 30-day onboarding, open questions.
  3. Browse the /catalog/ — every surface's live components, by chrome and theme. This is where you'll spot drift.
  4. Browse proposals/ — dated stress-tests. The studio for things not yet codified.

The toolchain

Tool What for
Claude Code Shipping features end-to-end. Reads DESIGN.md + CLAUDE.md before producing UI.
Claude Design (Anthropic Labs) Ideation. Reads the codebase, applies the system, produces visuals. Throwaway unless promoted to proposals/.
DESIGN.md + tokens/ The canonical guidance. Best-effort; the lint/CI/eval around it makes it stick.
proposals/ studio Dated mockups that stress-test ideas before codification.
Specialist subagents @ui-designer, @perceptual-ux, @accessibility-expert, @agent-ux — invoke for review before landing.

What's not in the toolchain: Figma as the canonical reference, a hand-maintained Storybook, a JSON token export pipeline. Figma still has a niche for early ideation; nothing here ships from it.

The two loops

Loop A — Tighten the harness (most of your time). Sample agent-produced surfaces. Find drift. Hypothesize a rule. Stress-test in proposals/. Codify in DESIGN.md. Automate where possible. Ship. Verify the next week's surfaces.

Loop B — Ship a feature end-to-end (a fraction of your time). Claude Design for direction, Claude Code for implementation, your hands on the code review. No engineer handoff. If a gap surfaced, run Loop A on it before moving on.

Full versions in HARNESS.md Part 3.

Quick references

  • Tokens — colors · typography · spacing. Reach for --sage-500 over #7a8f78, var(--space-3) over 12px. If a token doesn't exist for what you need, name the gap and add it.
  • Theme matrix — light + dark + calm are mandatory. The catalog's theme switcher is how you verify.
  • Brand contracts — see logos and guardrails. These are the pixel-exact assets agents shouldn't regenerate.
  • Voice & tone — see the writing reference for product owners. The voice rules apply to anyone writing copy, including you.

Anti-patterns to resist

  • "Let me Figma this first." Ask whether you're avoiding the precise-language work. The seed is intent in prose, not a wireframe.
  • "I'll fix this one screen." Ask whether the fix belongs in DESIGN.md, in a token, in a lint rule, in a worked example in proposals/. The harness fix compounds; the screen fix doesn't.
  • "Engineering will pick this up." They won't. You are engineering. If you can't write the production code, the design doesn't ship.