docs/design.md

Boundary. When a heuristic implies a visual property, reference a

docs/design.md

token by name (

{colors.primary}

,

{rounded.md}

). If

docs/design.md

doesn't have the token, flag it as a New Pattern to add via the Design System skill — never inline hex, font names, or arbitrary px. If

docs/design.md

doesn't exist at all, follow the codebase's existing convention for that property (theme config, CSS custom properties, component library) and note it.

• docs/design.md

  — the style layer (recommended, not required). When present, reference its tokens by name for every visual decision. When absent, this skill still applies: fall back to the codebase's existing design conventions (theme config, CSS custom properties, existing components) as the style source, and recommend running the Design System skill to establish a single token source of truth (part of BuilderOS: https://github.com/BuildGreatProducts/builder-os).
• The thing being built or refactored — a brief, a file, or uncommitted diff.

• docs/product-vision.md

  — optional. Its strategy and brand inform microcopy tone and help weight which heuristic categories dominate.

1. Establish the style source. If

   docs/design.md

   exists, parse its token catalogue (colors, typography, rounded, spacing, components) and the markdown rules (elevation, shape, Do's and Don'ts). If it doesn't, identify the codebase's existing design conventions — theme config (e.g. Tailwind/

   tokens

   ), CSS custom properties, the component library in use — and treat those as the style source, then recommend the Design System skill so future work has a documented source of truth.
2. Confirm scope and weight. Restate the surface (signup / dashboard / chat / settings / detail / marketing) and which heuristic categories will dominate — a signup leans on Forms + States + Accessibility + Microcopy; a data dashboard leans on Hierarchy + IA + Cognitive Load; an AI chat leans on the AI-product subset.
3. Generate or review using both layers. The style source (

   docs/design.md

   tokens, or the codebase conventions) for every visual decision; the heuristics catalogue and the Laws of UX for every craft decision. Cite heuristics by number and laws by name in reviews ("H22 — disabled instead of erroring after submit"; "Hick's Law — too many options in one step").
4. Pre-flight checklist before delivering:
   • Every interactive element has default, hover/focus-visible, active, disabled, and loading (where async) states.
   • Every async surface designs and codes all four states: empty, loading, error, success.
   • Every form input has a programmatically associated

     <label>

     , the correct

     inputmode

     /

     type

     , an

     autocomplete

     attribute, and

     onBlur

     validation.
   • Every motion is 150–400 ms, eases by direction (out entering / in exiting / in-out moving), animates

     transform

     /

     opacity

     only, and honors

     prefers-reduced-motion

     .
   • Body text contrast ≥ 4.5:1, UI components ≥ 3:1, focus rings ≥ 3:1 at ≥ 2 px.
   • Pointer targets ≥ 24×24 CSS px (≥ 44×44 on touch).
   • Layout works at 320 CSS px wide with no horizontal scroll.
   • The primary action is the single visually dominant element on the view.
   • Every visual decision references a

     docs/design.md

     token (or a codebase convention when no design system exists). Missing tokens flagged as New Patterns, not invented inline.
5. Deliver. Note which heuristic categories and Laws of UX dominated and surface any trade-off where a heuristic or law was knowingly skipped.

docs/design.md

• If

  docs/design.md

  exists — flag the gap as a New Pattern in your delivery notes (what property, what value the heuristic implies, and where it's needed), and recommend adding it to

  docs/design.md

  via the Design System skill, which owns editing the token catalogue and keeps

  docs/design.html

  in sync. Use the closest existing token in the meantime.
• If

  docs/design.md

  doesn't exist — follow the codebase's existing convention for that property (theme config, CSS custom property, the component library), note that you did, and recommend running the Design System skill so the project gains a documented source of truth.