# Product design contract

This file tells coding agents which design decisions govern this repository.
Replace every bracketed placeholder with verified project information. Delete
sections that do not apply.

## Product and users

- Product: [name and one-sentence purpose]
- Primary users: [specific users]
- Critical task: [the main job the interface must make easy]
- Supported surfaces: [web, iOS, Android, Shopify, or other]

## Sources of truth

- Design tokens: [path to globals.css, token JSON, or theme source]
- Components: [path to the shared component library]
- Design files: [verified Figma or other design-tool URL, or "none"]
- Product copy: [path or owner]
- Existing interface references: [routes, stories, or screenshots]

When sources disagree, use this order: [write the project-specific precedence].
Ask a person when the conflict changes product behavior or brand direction.

## Tokens and theming

- Use semantic tokens for color, type, spacing, radius, and depth.
- Do not add literal colors or one-off theme values when an approved token exists.
- Preserve [light, dark, high-contrast, or other verified themes].
- New tokens require [owner or review step].

## Components and patterns

- Reuse an existing component or variant before creating a new one.
- Approved component paths: [paths]
- Approved page and flow patterns: [paths or stories]
- Do not duplicate [known primitives or patterns].

## Accessibility floor

- Meet WCAG AA contrast for text and interface elements.
- Keep every task keyboard-operable with visible focus.
- Give controls accessible names and errors useful recovery text.
- Verify reflow at the smallest supported width and at 200 percent zoom.
- Preserve content and task completion when reduced motion is enabled.

## Change rules

- Keep each interface task bounded to [scope rule].
- Do not change [protected areas] without approval.
- Record new design decisions in this file or [decision-log path].
- Human design judgment owns unresolved product, brand, and interaction choices.

## Review evidence

Before calling UI work complete, record:

1. The interface and state reviewed.
2. The three highest-impact findings and why they were prioritized.
3. The files and design decisions changed.
4. Before and after captures of the same state and viewport.
5. Keyboard, responsive, accessibility, type, lint, and test results.
6. Open questions that still need a person.