If Impeccable gives you generic advice, the design context is usually missing, too vague, or stale.
## The fast path
Run the setup once from your project root:
```text
/impeccable init
```
That creates `PRODUCT.md`, the strategy file. At the end, say yes when Impeccable offers to run:
```text
/impeccable document
```
That creates `DESIGN.md`, the visual-system file, plus a generated helper at `.impeccable/design.json`. Review the two markdown files. Edit anything that does not match the real product.
Strategy
PRODUCT.md
Audience, purpose, voice, register, anti-references.
Visual system
DESIGN.md
Colors, type, components, radii, design rules.
Generated
.impeccable/design.json
Structured metadata for automation. Do not hand-edit.
Used by
Commands, hooks, detector, Live Mode
More specific edits, better audits, fewer false assumptions.
## What goes where
| File | What it should answer | Update it when |
|---|---|---|
| `PRODUCT.md` | Who is this for? What is the product trying to do? What should the brand feel like? Is this a brand surface or a product surface? What should the work avoid? | Audience, positioning, product purpose, voice, register, or anti-references change. |
| `DESIGN.md` | What colors, type stacks, component treatments, radii, elevation, and visual rules are allowed? | Palette, typography, components, tokens, spacing/radius scales, or design rules change. |
| `.impeccable/design.json` | What structured design data should automation use? | Do not edit it directly. Refresh it by running `/impeccable document`. |
The markdown files are the files you own. The generated JSON helps the detector, hooks, and Live Mode read the design system precisely.
## The most important choice: brand or product
Impeccable calls this choice the **register**. In daily use, just decide what kind of surface you are asking it to judge.
- **Brand surface:** marketing site, landing page, campaign, portfolio, editorial page. The visitor is evaluating, trusting, remembering, comparing, or feeling the brand.
- **Product surface:** app UI, dashboard, admin screen, workflow tool, settings page. The user is configuring, monitoring, searching, submitting, comparing data, or finishing a task.
The same visual move can be right in one register and wrong in the other. A campaign page can afford a huge image, expressive type, and one dominant idea per screen. A dashboard needs density, predictable controls, readable states, stable navigation, and quieter motion.
Many codebases have both. Set the project default to the surface you work on most, then be explicit when a task differs:
```text
/impeccable polish the marketing homepage as a brand surface
/impeccable audit the billing settings as a product surface
```
## How context changes the output
With context loaded, Impeccable can:
- preserve the right identity instead of "improving" it into something generic;
- pick the right standard for the surface: expressive brand page or efficient product UI;
- replace hardcoded visual choices with documented tokens and components;
- flag drift, such as fonts, colors, or border radii outside `DESIGN.md`;
- keep Live Mode variants aligned with the system instead of inventing new palettes.
The context does not replace judgment. Existing code still matters, and an intentional exception can be documented with a detector ignore. See [Config and ignores](/docs/config).
## Keeping context fresh
Use this rule:
| Change in the project | Run |
|---|---|
| New audience, positioning, product purpose, brand voice, or register | `/impeccable init` |
| New palette, type stack, component primitives, radius scale, or design rules | `/impeccable document` |
| A hook says `DESIGN.md` is newer than `.impeccable/design.json` | `/impeccable document` |
| One-off intentional detector finding | Add a narrow ignore with `/impeccable hooks ignore-value` or `npx impeccable ignores`. |
Treat context files like any other design artifact: review them in code review when they change, and update them when the product changes.
## Details when the default path is not enough
Where Impeccable looks for context files
For normal projects, put PRODUCT.md and DESIGN.md in the project root.
Skill commands look in the root first. If root context is missing, they also check .agents/context/ and docs/.
The detector's design-system rules use the same root-first behavior for DESIGN.md. For generated design metadata, the primary path is .impeccable/design.json. Legacy DESIGN.json files are still accepted as fallbacks, but new projects should use .impeccable/design.json.
What happens when docs and code disagree
PRODUCT.md wins on strategy: audience, tone, register, anti-references, and whether a change should preserve or reject the current identity.
DESIGN.md wins on visual decisions: color, typography, radius, elevation, component behavior, and system-specific do/don't rules.
Existing code still matters. Commands read project files before editing and preserve real conventions when they are stronger or newer than the docs. A stale DESIGN.md is a signal to refresh the docs, not permission to ignore the implementation.
Which detector rules unlock when DESIGN.md exists
When DESIGN.md exists, npx impeccable detect and the design hook unlock design-system checks:
design-system-font flags primary fonts not declared in DESIGN.md typography.design-system-color flags literal colors outside the documented palette or sidecar ramps.design-system-radius flags border-radius values outside the documented rounded scale.
These rules do not run when DESIGN.md is absent, when config disables design-system checks, or when you pass --no-design-system to the detector. See Detector CLI.