pantheon-org/web-reference-sheet-generator

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.

| BAD | GOOD | |-----|------| | Infer --space-4: 1rem because it seems reasonable | Document only values found in CSS; mark missing sections as TBD — not yet defined | | Expand one brand colour into a full 9-shade palette | Document only the hardcoded hex values found; note they are not formalised tokens |

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.

| BAD | GOOD | |-----|------| | ## Dark Mode followed by empty content | ## Dark Mode followed by TBD — not yet defined |

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