The missing design vocabulary for agents.

Missing or vague context can lead to more generic design. Impeccable can read your code, but it also needs to understand your users, their goals, and the decisions you want to preserve. Save that knowledge with the project so it can guide future work.

For a practical walkthrough of keeping pages consistent, see Work with a design system. This page describes the context records and how they are resolved.

Start with your product

In your agent chat, run:

/impeccable init

Impeccable reads the project, asks about missing context, and saves the agreed details in PRODUCT.md. Review what it writes. You can edit the file yourself or ask Impeccable to correct it.

Focus on who the product serves, what they need to do, and any requirements the design must meet. A useful answer connects a user’s situation to a decision:

People check service outages on their phones while away from their desks. They need to see what’s affected and whether someone is working on it.

You don’t need to specify a palette or choose fonts during setup.

Record an existing visual system

If your project already has a visual style you want to keep, run:

/impeccable document

Impeccable records the existing colors, typography, layout rules, and components in DESIGN.md. Read it before using it to guide more work. Fix anything that captures an accident or an outdated decision.

Run document separately when you want that record; init saves product context without creating DESIGN.md. A new project can establish its visual direction through Build something new.

What goes where

File	What belongs in it	Example
`PRODUCT.md`	Audience, goals, platform, constraints, terminology, and confirmed brand commitments.	“Customers reorder supplies on a phone.”
`DESIGN.md`	The shared visual system: colors, typography, components, and design rules.	“Use the existing primary button for the main action.”
`.impeccable/surfaces/*.md`	Decisions for one page or route, such as its purpose and chosen design direction.	“The pricing page should help buyers compare plans.”
`.impeccable/design.json`	Generated design metadata used by tooling. Refresh it with `document`; don’t hand-edit it.	Component previews and additional token information.

The Markdown files are yours to review and edit. document stores design tokens in the DESIGN.md frontmatter and generates the additional metadata alongside it when recording an existing system.

Name the page you’re working on

/impeccable polish the marketing homepage
/impeccable audit the billing settings

A homepage helps someone decide whether the product fits their needs. Billing settings help them complete a task. Naming the page lets Impeccable apply the right approach without treating every part of your product the same way.

How Impeccable chooses a page’s approach

Impeccable uses four modes, based on what someone comes to that page to do:

Persuade: decide and act. Landing pages, campaigns, and pricing pages.
Operate: complete a task. Dashboards, settings, editors, and other app screens.
Read: understand something. Documentation, guides, and help pages.
Experience: explore the work itself. Portfolios, galleries, and showcases.

The page determines the mode. A developer tool’s landing page can use Persuade while its documentation uses Read. If a page’s purpose is ambiguous, explain what visitors should do there.

The resolved mode is recorded with that page’s brief under .impeccable/surfaces/.

Keep the files useful

Update context when the project changes:

What changed	What to do
Your audience, goals, platform, or product requirements	Edit `PRODUCT.md`, or run `/impeccable init` to revisit the relevant details.
Your visual system	Run `/impeccable document` to update the record from the implementation.
A page’s purpose or design direction	Update its brief under `.impeccable/surfaces/`.
You’re unsure what is out of date	Run `/impeccable doctor`. About Doctor.

If a result feels generic or misses your users’ needs, check the context first. Fill in what’s missing and correct anything outdated, then tell your agent what still needs work. Good context improves its judgment; feedback helps it refine the result.

Starting DESIGN.md before there is any code

You can ask document to establish a visual direction for a new project. It needs product context and a concrete first page to design, then works with you to choose the direction.

The resulting DESIGN.md is marked as a seed. It records the chosen direction and leaves unresolved implementation details open. It doesn’t generate the design metadata file yet. Run document again after there is code to capture the actual tokens and components.

For intentional exceptions to detector rules, use Configuration & ignores.

Reference details

Native apps: iOS, Android, and adaptive (alpha)

PRODUCT.md records the platform under ## Platform. init infers it from the project and asks when the evidence is unclear. A missing value defaults to web.

Value	Use it for	Design guidance
`web`	Websites and web apps, including mobile web.	Web interfaces.
`ios`	Native iPhone and iPad apps.	Apple Human Interface Guidelines.
`android`	Native Android apps.	Material Design 3.
`adaptive`	A shared codebase whose interface adapts to each operating system.	Both iOS and Android guidance.

Native support is alpha. audit and adapt use native guidance for screen readers, touch targets, and platform conventions. Live Mode, the browser detector, and design hooks do not inspect native interfaces.

Flutter, React Native, or Kotlin Multiplatform can support an adaptive interface, but the framework alone does not determine the value. Mobile web remains web, including a website displayed inside a native wrapper.

Where to put context files, including in a monorepo

Keep PRODUCT.md and DESIGN.md together in the project root. Impeccable also supports .agents/context/ and docs/: it uses the first of those locations that contains context, in that order, starting at the root.

In a monorepo, each app can have its own context. An app’s files take priority; a missing file falls back to the repository root. Product and design context resolve separately.

For example, this store shares the product’s audience and goals but has its own visual system:

repo/
├── PRODUCT.md          Shared audience and goals
├── DESIGN.md           Shared visual system
└── apps/
    └── store/
        ├── DESIGN.md   Store’s visual system
        └── src/

For work in `apps/store/`	Impeccable reads
Product context	`repo/PRODUCT.md`
Design context	`repo/apps/store/DESIGN.md`

If the store needs different product context too, add its own PRODUCT.md.

Project boundaries come from package-workspace declarations or projectRoots in .impeccable/config.json. Configured patterns can override package boundaries for the paths they match. See Project boundaries for examples and precedence.

Generated design metadata belongs in .impeccable/design.json. Older DESIGN.json files are still recognized as fallbacks; use document to produce the current format.

What to do when context and code disagree

Each record answers a different question:

PRODUCT.md: who the product serves, what it promises, and which requirements and brand commitments must hold.
DESIGN.md: the shared visual choices, components, and interaction rules.
A surface brief: what this page needs to achieve and the direction chosen for it.

The implementation is evidence too. Impeccable should preserve established conventions when they are more current than the documentation.

For example, if the code uses your approved new typeface but DESIGN.md still names the old one, update the record. If the code introduced an accidental font change, fix the code. Explain which decision is current when the evidence does not settle it.

Use document to refresh an existing visual system’s record, or doctor to check for stale or incompatible context.

What the detector checks against your design system

When DESIGN.md is available, the detector and design hook can check for drift from documented values:

Rule	Checks for
`design-system-font`	Fonts outside the documented type system.
`design-system-color`	Literal colors outside the palette and companion-file tonal ramps.
`design-system-radius`	Corner radii outside the documented scale.
`design-system-font-size`	Literal font sizes outside the documented type scale.

The checks need the corresponding design values. The presence of a file alone does not provide a complete system. Keep DESIGN.md and its generated companion file current with document.

Design-system checks are skipped when DESIGN.md is absent, when config disables them, or when a scan uses --no-design-system. Other detector checks can still run. See Detector CLI for scan options and Config and ignores for intentional exceptions.

Upgrading from the old brand/product register

Modes replace the old brand/product register. Brand corresponds to Persuade; product corresponds to Operate. Read and Experience cover pages whose purpose is learning or exploration.

The mode belongs to the page’s brief. An old ## Register section in PRODUCT.md is no longer used. doctor flags it and offers to remove it so future readers do not mistake it for a current setting.