# Impeccable integration

Impeccable is the execution companion to this transversal UI/UX system. It provides a design vocabulary, focused workflows, production checks, and implementation discipline. It does not replace the house method.

Installed for Codex: `~/.codex/skills/impeccable`  
Installed version: `4.3.1`, updated 11-09-2026 from the release published 09-09-2026 (the 4.0.2 folder is kept at `9 - System/tmp/impeccable-4.0.2-backup-11-09-2026`)  
Source: [pbakaus/impeccable](https://github.com/pbakaus/impeccable), Apache-2.0

**What the 4.3 line changed, checked on the release rather than taken from the announcement.** The rule engine is a self-contained binary, version `0.1.5`, downloaded once on first use into `~/.impeccable/bin/`, so the skill needs no Node and no key; the deterministic checks run without a model. The design checks fire from a **project-local** `.codex/hooks.json` whose commands point at `.codex/skills/impeccable/scripts/impeccable`, which is why Impeccable is run from the project root and why nothing was written into Frank's global Codex configuration. The published notes also claim roughly ten millisecond hooks, four times faster hooks, twice as fast file scans, GPT Image 2.5 with transparent assets, per-application rules in monorepos and a VS Code Marketplace install; **none of those numbers has been measured here**, and the picture work needs a key before it can be.

Installed for Claude Code as well on 11-09-2026: the skill at `~/.claude/skills/impeccable` and its four agents in `~/.claude/agents/`. His own `settings.json` was left untouched, and the reason matters: the vendor's after-edit hooks point at `${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/impeccable`, so they do nothing unless the project being worked on carries the skill in its own `.claude/skills/`. Both seats therefore have the skill on call, and neither fires a check by itself.

## Where it applies, and where it does not (11-09-2026)

| The work | Impeccable | Why |
|---|---|---|
| A screen, a component, a form, an app shell, a product page | **Yes, fully** | This is what its rules were written against, and its commands and craft floor speak this language |
| An HTML page Frank reads: a board, a plan, a teaching page, a leaflet | **Yes, as the last mechanical pass** | Contrast, spacing, alignment and anti-patterns are the same craft. It never decides what the page says, and layers 1 to 5 above still outrank it |
| A drawing: an SVG concept, a Mermaid diagram, an isometric board | **No** | Its rules read interfaces, not drawings. The diagram rules and the drawing's own doctrine govern, and Impeccable has nothing to check unless the drawing sits inside a page |
| A speaker, a clip, a voice, a film | **No** | Another craft entirely; the studio's own pages and bars own it |

## Authority and precedence

For work in this workspace, apply the sources in this order:

1. The user's brief and the real product or service constraints.
2. The Teletubbies principle: the page speaks to the eye before it is read, creates appetite, and stays easy and pleasant.
3. The Kennedy method: one job, hierarchy by de-emphasis, grayscale first, colour last, generous whitespace, locality, and ABD for interactive screens.
4. `documentation-design.md` for didactic pages in Read mode.
5. The incumbent project's tokens, components, content, and interaction conventions.
6. Impeccable's command playbook and craft floor.
7. Token and composition auditors as regression nets.

When Impeccable advice conflicts with layers 1 to 5, the earlier authority wins. In particular, "bolder" never means louder without purpose, and "delight" never outranks comprehension or task completion.

## Where context belongs

Run Impeccable from the root of the specific project being designed, never from `/Users/unctad/Claude`.

- `PRODUCT.md` records that project's users, purpose, positioning, voice, and durable constraints.
- `DESIGN.md` records that project's visual implementation: colours, typography, components, and tokens.
- This folder remains the transversal method shared by all projects.

Do not copy the whole transversal system into every `DESIGN.md`. Link to this folder and record only the project-specific decisions that apply it.

## Working sequence

### 1. Classify the surface

Choose the visitor-success mode before choosing a command:

| Surface | Impeccable mode | House material to load |
|---|---|---|
| App, form, dashboard, internal tool | Operate | `README.md` and the Kennedy shelf |
| Teaching page, guide, explainer, one-pager | Read | `README.md`, Kennedy, and `documentation-design.md` |
| Landing page, campaign, public proposition | Persuade | `README.md`, Kennedy, and the real brand brief |
| Portfolio, gallery, showcase | Experience | `README.md`, Kennedy, and the shown material |

### 2. State the one job

Write one sentence describing what should happen on roughly 95 of 100 visits. Use it to de-emphasize everything that does not directly support the job.

For Read mode, state what the reader should understand or be able to explain after reading.

### 3. Choose one Impeccable intervention

Use the narrowest command that owns the need:

| Need | Command |
|---|---|
| Plan the UX before code | `shape` |
| Establish project context | `init`, then `document` |
| Review hierarchy and comprehension | `critique` |
| Final design-system and craft pass | `polish` |
| Typography, spacing, or layout correction | `typeset` or `layout` |
| Remove clutter or unclear copy | `distill` or `clarify` |
| Accessibility, responsive, performance, and production checks | `audit` |
| Errors, overflow, i18n, and edge cases | `harden` |
| Device adaptation | `adapt` |

Use `bolder`, `colorize`, `delight`, `animate`, or `overdrive` only after the one job and hierarchy are sound. They are enhancements, not substitutes for structure.

### 4. Verify in the house order

1. One-job and squint test.
2. Grayscale hierarchy check.
3. Locality and ABD check for interactive surfaces.
4. Impeccable `critique` or `polish`, as appropriate.
5. Impeccable `audit` for production quality.
6. `composition-audit.js`.
7. `python3 token-audit.py <file>`.
8. Pleasure gate: every part must remain easy and pleasant to read or use.

Passing Impeccable's detector does not prove that the page is good. Passing the house audits does not prove it either. The final judgment is whether the surface communicates before it is read and helps the visitor succeed without friction.

## Invocation examples

Use natural requests; the skill routes them to its internal command playbooks:

```text
Use Impeccable to shape this form. Apply the transversal UI/UX system and state the screen's one job before proposing UI.

Use Impeccable to critique this teaching page in Read mode. Apply documentation-design.md and report hierarchy, orientation, and reading-rhythm issues.

Use Impeccable to polish this dashboard. Preserve the incumbent tokens and run the house verification order before delivery.
```