Using Wafel with impeccable

impeccable is a design-quality tool for coding agents. To use it with Wafel, copy this site's /DESIGN.md to the root of the project, and refresh the copy whenever the product's styles are re-pinned.

Set it up

1. Fetch /DESIGN.md from this site and save it as DESIGN.md at the project root. impeccable walks up from the working directory and reads the first DESIGN.md it finds, so a copy in a subdirectory shadows it.
2. Commit the copy. Do not fetch it during a build. The product must not depend on this site to build.
3. Let the agent fetch this site. Each section of the file ends with links to the pages here that carry the full reference. If the agent's fetch tool uses an allowlist, add this site's host to it.

Keep it current

Refresh the copy each time the product's stylesheets are re-pinned on this site. The file states the commit it was generated from in its Overview, so a copy can be compared with the one served here.

impeccable's doctor command reports how many commits have touched the project's visual source since DESIGN.md last changed. In an active repository the count grows within days, whether or not the design system moved. The count on its own does not mean the values are wrong. Compare the commit named in the file with the one this site reports, and refresh the copy if they differ.

Do not edit the copy

Every colour, radius and size in the file is read from the product's tokens, and the prose is authored in this repository. A change made to the copy is lost at the next refresh, and it makes the project disagree with the product.

• A value is wrong. Fix it in the product's stylesheets. The file picks it up at the next re-pin.
• The prose is wrong or missing something. Change it here, in content/site/design-md.md, which is the template the file is built from.

The same applies to a copy impeccable offers to regenerate. See the next section.

Do not let impeccable change the stylesheets

Do not accept a change from an impeccable command to the product's stylesheets, and do not let it regenerate DESIGN.md from the code. impeccable may change how a view uses the tokens. It may not change which tokens exist. A change to the tokens is a change to the design system. Make it on purpose, in its own pull request to the product, not as a side effect of a polish pass.

The reason is where the rules come from. This site reads the product's stylesheets and treats them as the source of truth, and DESIGN.md is generated from them. Nothing checks the stylesheets against anything else. So a change impeccable makes to a stylesheet becomes, at the next re-pin, the rule impeccable checks the product against. The tool would be grading its own edits, and no check in the pipeline would notice.

Several commands propose this kind of change. Their own instructions say so:

• distill tells the agent to remove dead CSS, merge similar styles, cut the palette to one or two colours plus neutrals, and cap typography at three or four sizes. DESIGN.md lists every colour token the product defines, so a palette cut is the first thing it will propose.
• polish removes obsolete styles and promotes repeated values to new tokens.
• optimize removes unused CSS.
• extract creates tokens from repeated values and deletes the old implementations.
• document regenerates DESIGN.md from the project's code. It asks before replacing an existing file, and offers to overwrite or merge. Decline both. A regenerated file describes the product as impeccable found it, including any change it made, and it loses the prose authored here.

When a command proposes one of these, decline the part that touches the stylesheets or DESIGN.md and take it to design as a proposal. Whether a token is unused is a question for the inventory, which counts uses across the whole product. impeccable sees only the area it was pointed at. Scope commands to a view or a component rather than running them over the project.

What the file switches on

impeccable's detector reads the frontmatter and checks code against it:

Only literal values are checked. A value written through a custom property, such as var(--color-content-default), passes.

The prose is read by impeccable's model-driven commands, such as polish, typeset and colorize. A class named in backticks counts as part of the system. The same class named under "Don't", or beside words such as "legacy" or "avoid", is treated as condemned wherever else in the file it appears.

Reading findings

Most findings are literals the product writes outside its tokens. Fix them by using a semantic token. Do not add the literal to DESIGN.md. The file describes the system as it is, and it is not changed to make a finding go away.

A finding can be the rule misfiring on something the system intends. Syntax-highlighting themes and vendored stylesheets are the common cases. Exceptions belong in the project's .impeccable/config.json, which engineering owns and maintains. Ask design when it is unclear whether a finding is a misfire or a real defect.

The detector skips ERB and HAML views unless they are listed under detector.extensions in the config. A clean run over a Rails project has not checked its views.

Where impeccable's own rules and Wafel disagree

impeccable's commands also follow written rules of their own. Where the product departs from one on purpose, DESIGN.md says so, and the brief takes precedence over impeccable's defaults:

• The system UI font is deliberate. impeccable treats a system face used for display text as a defect. Wafel uses the operating system's font for every role. Do not add a display face to satisfy the tool.
• Caps headings are section labels. .c-heading--caps names a group of content. impeccable bans decorative labels above headings; this is not one.

If a command proposes one of these changes, the agent has missed that part of DESIGN.md. Point it at the relevant section rather than accepting the change.

What the file does not cover

• Writing and tone. DESIGN.md is visual only. Writing guidance is under Writing.
• impeccable's live panel. The panel reads a separate .impeccable/design.json, with motion, breakpoints and component snippets. This site does not publish one.
• Component values. The frontmatter has no components group yet. Components are described in prose, and their full reference is the inventory.