# [Product name] — design rules

Replace every bracketed placeholder before using this file. Keep the document
in your repository (for example, docs/design-system.md). The filename itself
does not automatically load these rules into an assistant.

## Product and reference views

- Audience and primary task: [who uses this product, to do what]
- Visual character: [three concrete qualities already present in the product]
- Reference pages: [two or three routes and their component files]
- Authoritative tokens: [stylesheet, theme, or token file]
- Reusable components: [actual header, button, field, list, and panel components]

## Color and surfaces

Use existing semantic tokens. Record their roles here; keep actual values in
code. If you include a value table, update it when the tokens change.

- Main surface: [token and intended use]
- Raised surface: [token and intended use]
- Main/supporting text: [tokens; verify contrast on the actual background]
- Accent/selection/focus: [tokens and intended use]
- Success/warning/error: [tokens plus a textual or shape-based signal]
- Borders, radii, shadows: [existing conventions and justified exceptions]

Do not create a page-local palette unless the design explicitly calls for one.

## Typography and hierarchy

- Reading family: [existing font stack]
- Metadata family: [existing font stack, if different]
- Ordinary page header: [component or selector]
- Heading/body/metadata scale: [existing sizes and line heights]
- Uppercase/letter spacing: [where already used]
- Heading structure: one descriptive h1 and meaningful section levels.

## Layout and spacing

- Shared container and navigation: [files/components]
- Page/panel/row spacing: [existing scale or tokens]
- Use a panel for: [a distinct task or object]
- Use rows for: [repeated or sequential content]
- Column collapse: [based on content and available width, including navigation]
- Long content: [wrapping and truncation rules, with access to full values]

## Interactions and states

Reuse existing components. Keep links for navigation and buttons for actions.
Preserve visible labels, native input behavior, keyboard focus, and form status
announcements. Do not make a static panel look clickable.

Define loading, empty, success, validation, and error states where applicable.
Document the product's target-size convention and test actual controls.
Respect reduced-motion preferences; information must not depend on animation.

## Content and visuals

- Interface language and tone: [actual product conventions]
- Example content: clearly label previews and illustrative data.
- Claims: do not invent user counts, performance gains, or conversion results.
- Images: explain the specific content, with appropriate alternatives/captions.

## Verification

- Compare with the named reference pages.
- Inspect wide and narrow layouts, including 320 px where supported.
- Check long content and text zoom; record horizontal overflow if present.
- Operate relevant controls using the keyboard; inspect focus and labels.
- Inspect relevant loading, validation, success, and failure states.
- Measure contrast against the actual background; do not infer compliance
  from a token name or a screenshot.
- Check other consumers when shared CSS/components change.
- Run [verified existing test/build commands].
- Report what was checked and what remains unverified.

## Maintenance

Update this document when a reviewed shared design decision changes. Resolve
conflicts with implementation explicitly; do not silently follow the last-read
file. Avoid turning every local exception into a permanent global rule.

---

# Suggested instruction-file pointer

Put a short rule in the instruction mechanism your assistant actually reads:

> For UI work, read docs/design-system.md and the named reference components
> before editing. Reuse existing tokens and patterns. Preserve behavior unless
> the task explicitly changes it. Verify the rendered result on wide and narrow
> screens. Update the design document when intentionally changing a shared rule.

# Per-change review checklist

- [ ] The page follows the product's existing hierarchy and spacing.
- [ ] New styles reuse tokens and are scoped appropriately.
- [ ] The diff is limited to the requested change and its necessary cleanup.
- [ ] Form behavior, accessibility semantics, and analytics remain intact.
- [ ] Keyboard navigation, focus, labels, and relevant states were inspected.
- [ ] No unexplained overflow, clipped content, or overlapping controls.
- [ ] Other consumers of changed shared styles were inspected.
- [ ] Relevant tests/build passed, or failures are explicitly reported.
- [ ] Screenshots record the route and viewport dimensions.
- [ ] Any claimed improvement has evidence; visual consistency is not proof
      of higher conversion or full accessibility compliance.