Design Context

Impeccable works best when it can read the same product and design decisions you would give a human designer. Without that context, it has to infer audience, tone, palette, type, and component rules from code alone. That usually produces safer, more generic answers.

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:

/impeccable init

That creates PRODUCT.md, the strategy file. At the end, say yes when Impeccable offers to run:

/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.

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:

/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.

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.