Web Design Reference Sheet Generator

Generate a project-specific design reference sheet and companion enforcement skill from any website codebase, mirroring the structure of the Figma Web Design Reference Sheet.

---

Mindset

Document what exists, not what should exist.

Every invented token is technical debt dressed as documentation — developers trust the reference sheet and will use the wrong values in production. When data is missing, write TBD — not yet defined. A reference sheet with honest gaps is more useful than one with plausible fictions.

---

Workflow

See references/workflow.md for the full 8-step generation process:

1. Discover design tokens (grep CSS for -- custom properties, @theme blocks, font imports)

   grep -r "\-\-" src/ --include="*.css" -h | grep -E "^\s+--" | sort -u
   grep -r "@theme\|@font-face\|@import" src/ --include="*.css"

2. Inspect existing components (read 3–5 representative files)

3. Check dark mode implementation

4. Check accessibility patterns

5. Fill templates/skill-output.yaml — structured scratchpad validated against schemas/design-reference.schema.json

6. Generate docs/design/design-reference.md from the template

7. Generate .agents/skills/{project-slug}/SKILL.md from the enforcement skill template

8. Confirm output with a structured report listing populated sections and TBD items

---

Design Knowledge References

CRITICAL (required for output quality)

HIGH (consult when relevant section has data)

---

When NOT to Use

• The project has no CSS source files (generated styles only, e.g. CSS-in-JS with no extractable tokens)
• A design reference sheet already exists and only needs updating — use the companion enforcement skill's update workflow instead
• The user wants a generic design system template, not a project-specific one — redirect to a design system scaffolding tool

---

Rules

Never invent design values

WHY: Invented values create false documentation. Developers trust the reference sheet and may use wrong tokens, causing inconsistencies that are hard to trace.

Mark gaps as TBD

WHY: Blank sections are invisible gaps; TBD — not yet defined is an actionable signal to the team. It appears in the confirmation block, making gaps impossible to miss.

Keep patterns copy-pasteable

WHY: A reference sheet that requires editing before use wastes developer time and introduces errors. Code examples that don't run erode trust in the document.

One token file is the master

WHY: Multiple token sources create ambiguity about which file to update. Naming the authoritative file makes the reference sheet a navigation aid, not just a snapshot.

Consequence: When developers don't know the master file, they update whichever CSS file is open — creating duplicate or conflicting tokens. Merge conflicts follow, and the reference sheet becomes unreliable. Name the single source of truth explicitly in §1 Brand Identity.

The companion SKILL.md is always project-specific

WHY: A generic description means the skill doesn't activate correctly for the project. Project-specific descriptions ensure the enforcement skill fires when working on that codebase.

Do not generate from memory

WHY: Even well-known frameworks have project-level overrides. Reading the actual source files is the only way to capture what is real, not what is typical.