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.

---

When to Use

Apply this skill when:

1. Starting a new project and needing a living design token reference
2. Onboarding a design system from an existing codebase
3. Creating a Figma-compatible reference for designers and developers
4. Auditing existing styles to identify undocumented or orphaned tokens
5. Porting design tokens between frameworks

---

Workflow

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

1. Discover design tokens

   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 and accessibility patterns

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

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

   # Review populated scratchpad before generating final docs
   cat templates/skill-output.yaml | grep -E "TBD|null" && echo "Gaps found — fill before generating"

6. Generate the enforcement skill from the enforcement skill template

   bun run generate --template enforcement-skill --output ./{project-slug}/SKILL.md

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

   bun run validate --schema schemas/design-reference.schema.json --input templates/skill-output.yaml

---

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

---

Anti-Patterns

NEVER invent or infer design tokens that don't exist in source code

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

NEVER generate the reference sheet before reading actual CSS/config files

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

  # BAD: assuming defaults
  # GOOD: always verify
  grep -r "screens" tailwind.config.ts

NEVER leave sections empty without a TBD marker

• WHY: Blank sections appear complete; TBD — not yet defined is an actionable signal that makes gaps impossible to miss.

NEVER use non-copy-pasteable code examples in the reference sheet

• WHY: A reference sheet that requires editing before use wastes developer time and erodes trust.

  /* BAD: placeholder that doesn't exist */
  /* GOOD: actual token from source */
  --color-brand-primary: #1a2b3c;

NEVER use a generic description in the companion enforcement skill

• WHY: A generic description means the skill doesn't activate correctly for the project. A common pitfall is copying the parent skill description verbatim.
• BAD — description: Enforce design tokens for any web project
• GOOD — description: Enforce design tokens for the Acme Corp marketing site

---

References

• references/workflow.md — Full 8-step generation workflow
• references/design-reference-template.md — Output template for docs/design/design-reference.md
• references/enforcement-skill-template.md — Output template for the companion enforcement skill
• templates/skill-output.yaml — Structured scratchpad; populate before writing any markdown
• schemas/design-reference.schema.json — JSON schema for scratchpad validation
• references/accessibility-guidelines.md — WCAG 2.1 AA criteria, contrast ratios, keyboard nav, ARIA
• references/typography-principles.md — Hierarchy, readability, type pairing, modular scale
• references/psychology-of-color.md — Colour associations, brand strategy, harmony, WCAG contrast
• references/visual-hierarchy.md — The seven hierarchy variables, Z/F-patterns
• references/grid-and-layout-theory.md — Column grids, 8-point system, responsive strategies
• references/whitespace-theory.md — Macro/micro whitespace, density, hierarchy
• references/gestalt-principles.md — Proximity, similarity, figure-ground, closure, continuity