| name | faithful-prototype |
| description | Build a high-fidelity prototype of an EXISTING Automattic product surface using the real components, tokens, and stylesheets, so it is indistinguishable from production and survives design-system scrutiny. Use when the user wants to prototype, rebuild, or recreate an existing surface with real components — "faithful prototype", "high fidelity prototype of [surface]", "rebuild X with the real design system", "recreate the real [panel/page/flow]", or "prototype a new experience inside [existing surface]". NOT for greenfield/new-surface designs, quick throwaway mockups, or visual concept explorations — use the lighter mockup skills for those; this method's rigor (live ground-truth capture, three-agent research, acceptance testing) is for when production fidelity is the point. |
Faithful Prototype
Recreate an existing product surface from its real parts, then layer new experiences onto it. Never build a lookalike. The output must survive a design-system team's inspection: real imports, real tokens, verbatim bespoke styles, disclosed gaps.
Cardinal rule: this skill contains no facts about any surface. No color values, no component names, no package versions live here — they rot, sometimes same-day. Every run extracts fresh facts and writes them to a dated project knowledge base. The skill is the method; the KB is the truth.
Why this order
Agents reading code produce confident lookalikes — they fabricate tokens and hand-build components they believe are real, and they genuinely cannot tell the difference. Code inventories also go stale and get details wrong:
- colors that resolve through variable fallback chains to something other than the named token
- shadows and elevations that render as separate layers, not on the element the code suggests
- values that only exist at runtime (viewport-relative sizes, host-injected theme variables)
- behavior the code implies but the product doesn't ship (flags off, overrides downstream)
The live DOM is the only source that cannot be wrong about what ships today. So: capture ground truth from the live product FIRST, treat it as the acceptance test, and let it overrule code reading whenever they disagree. They will disagree — a code inventory can be contradicted by the live DOM the same day it was written.
Phase 0 — Scope and collision check
Before any research:
- Name the target. Which live surface, which states, and which new experiences (if any) will be prototyped on top of it. Confirm the user's naming matches the product's — internal platform names and user-facing surface names often differ; use the user-facing one.
- Collision check — is this surface being rebuilt right now?
- Search the product code for feature flags that swap out or replace the surface.
- Check for live experiments running on it.
- Sweep P2/Slack (context-a8c MCP) for in-flight redesigns or replatforming by other teams.
- If found: record it in the KB, position the prototype as the experience layer for wherever the surface is going (not a parallel rebuild), and flag which owning team to check in with before any structural pitch.
- Skill check — does the house already have this? Look for existing prototype skills in the a8c-design plugin, design-system MCP guidance, and any newer community skills for this kind of surface. Extend what exists; don't fork it.
- Create the project KB. A project folder with numbered docs, starting with
00-resume-here.md: date every fact, keep status to one line, list next actions. All facts extracted below land in these docs, never in this skill. Suggested spine: 00 resume-here, then one doc per research track, then a build plan.
Phase 1 — Three-agent research fan-out
Launch three parallel agents with distinct mandates. Each writes its own dated KB doc.
Agent A — Ground truth (the acceptance test)
Drive a logged-in browser over the LIVE production surface (chrome-devtools MCP).
- Capture every reachable state: entry point, default, each navigation level, loading, error, empty, minimized/expanded, menus open. Screenshot + accessibility snapshot per state, with a table of how each state was reached.
- Extract computed styles from the real DOM for every distinctive element: dimensions, spacing, radii, colors as resolved values, typography, shadows, z-index, positioning.
- Dump resolved CSS custom properties on the key containers — the full set, not just the ones you expect. Note which token systems are present and which are absent.
- Record component provenance from class names: which prefixes map to which library. This is evidence of what production actually uses, independent of what the repo suggests.
- Record behavioral facts styles can't show: what auto-forwards, what persists across navigation, what the a11y tree names each view.
- Write a deviations section: everywhere the live DOM contradicts the code inventory or prior assumptions. This section is the point.
Conduct rules (read-only): never submit forms that create tickets or contact real staff, never change account settings, never escalate to humans, never send messages a person will read. Navigate, open, type into search fields, screenshot — nothing with side effects on other people.
The output doc is the acceptance test: match these values or it's wrong. Ground truth outranks every other source.
Agent B — Build spec (the parts list)
Map every visual piece of the surface to a real part. Every row of the spec is one of two verdicts:
- IMPORT: a published component. Search in this order:
- the design-system MCP (
get_components, get_component_details, get_design_tokens)
- the product repo's own packages
- published npm packages
Verify the export actually exists in the installed version — docs and MCP listings include components that aren't shipped yet.
- COPY: bespoke stylesheets from the product repo, copied verbatim with file paths recorded. Bespoke SCSS is legitimate provenance — it IS the production look. Copying it is fidelity; rewriting it is drift.
Also:
- Check what the repo's packages export beyond what the surface uses today — new experiences may have real parts available that production hasn't adopted yet.
- Map the token systems actually in play (there are usually several, and they conflict). Note clashes as design-system findings to report upstream, not problems to silently fix.
- Produce a coverage estimate (roughly what % importable / % copyable / % true invention).
- Produce a PROMINENT GAPS section: every piece with no off-the-shelf part, ordered by how much invention it needs. Gaps get flagged, never papered over.
- End with a stack verdict: what build setup the states demand (see Phase 2).
Agent C — House practice (the social layer)
Sweep P2 and Slack (context-a8c MCP) for:
- How designers here prototype this kind of surface now — named precedents with links, their stacks, their enforcement tricks (lint rules, agent rule files, token-validation hooks).
- Current design-system guidance, including which component generation applies to THIS surface — faithful means matching what production ships, not migrating to the newest recommended stack. Knowing the difference pre-empts the likeliest critique.
- Who owns the surface, who is designing near it, and who to show early — support/frontline folks who feel the pain, then the owning team, then design-system reviewers.
- Existing skills or starters promised in recent posts — chase those before building guardrails from scratch.
Phase 2 — Build
Only after all three docs exist and the user has seen the gaps list.
Choose the stack by what the states demand:
- Interactive, animated, or stateful moments (typing, thinking/shimmer, loading, transfer, open menus) usually force a real React sandbox importing the actual packages — those states only exist as components and cannot be faithfully frozen.
- Static HTML is acceptable only when nothing stateful matters.
- A hybrid (sandbox for the stateful surface, static for the rest) is a fallback — but if the shell styles are one copied file, the full sandbox is barely more work.
Build rules:
- Real packages imported, bespoke styles copied verbatim. Pin package versions to what the product uses.
- Configure the build so the copied stylesheets' own imports resolve (usually a Sass load path into node_modules) rather than editing them.
- NEVER: Tailwind, shadcn, invented styles, invented tokens, hand-copied token values, or restyling a real component's internals. If a real component doesn't look right, the answer is the copied production stylesheet or the divergence protocol — not overrides.
- Mock state, not systems: drive the UI with local state; each visual state should be a pure function of a few switches, so every state is scriptable and demoable.
- Consider mechanical guardrails from house practice (stylelint rules that reject unknown tokens and raw colors) so drift fails the build instead of the review.
- Write the agent rules into the sandbox's own CLAUDE.md so future sessions inherit them: package responsibilities, never hardcode a color, no invented tokens, the divergence protocol.
Divergence protocol — for every gap and anything custom that comes up mid-build: STOP before building it. Tell the designer: "The closest existing part is X; I can compose A + B + C; here is my proposal for the remainder." Then wait for the call. Never invent silently, even for something small — the small silent inventions are what reviewers catch.
Phase 3 — Acceptance and share
- Side-by-side acceptance before anyone else sees it: prototype next to the ground-truth screenshots, computed values checked against the ground-truth doc. Fix until indistinguishable at a glance. Record any conscious remaining differences in the KB.
- Deploy a PIN-protected live preview URL. A live link people can step through is the house norm; static images read as "a slideshow of intentions". Put the link in the P2 alongside the design-file and issue-tracker links.
- Share with provenance stated. In the P2 or demo, say explicitly:
- which real packages, at which versions
- which styles are verbatim production copies (and from where)
- which generation of the design system it matches, and why that's the faithful choice
- the disclosed gaps and any conscious divergences, with the decision that approved each
Stating provenance up front converts the design-system critique into a design-system endorsement.
- Route through the people the house-practice doc named: frontline first, owning team before any structural pitch, design-system channel for the token findings.
Checklist
