Design review
Spillway checks its public blocks and its admin against impeccable, an open-source (Apache-2.0) catalog of design anti-patterns with a detector that needs no model or API key. Two checks use it, and the skill can be installed for agents.
The two checks
| Command | What it scans | Where it runs |
|---|---|---|
pnpm design:scan | The CSS and markup in packages/admin/src and packages/blocks/src: the rules that read source, such as side stripes, gradients and font choices | CI, step Design scan, with GitHub annotations |
pnpm design:check (after pnpm build) | A fresh instance with a kit and its sample content (KIT=higher_ed by default), rendered in Chromium: every published page at 1280 px and 390 px, and eight admin screens at 1280 px | By hand, like the smoke tests |
pnpm design:check signs in as an admin it creates, scans each screen through the browser's DevTools port and exits 1 when a finding is left. Advisory notes, such as a single word on a paragraph's last line, are listed but never fail the check. Run it with another kit to check that kit's pages: KIT=city pnpm design:check.
The rendered check covers what a source scan cannot:
- contrast against the real background;
- text size and line length as laid out;
- heading order across blocks;
- overflow at phone width;
- text covered by another element.
Exceptions
A finding that is right for Spillway stays, recorded with its reason in .impeccable/config.json. Add one with the detector's own command so the format stays valid:
npx -y impeccable@4.8.1 ignores add-value side-tab "*" --file "packages/blocks/src/styles.css" --reason "Blockquote rules"
The exceptions recorded so far:
| Rule | Where | Why it stays |
|---|---|---|
side-tab | admin and blocks stylesheets, registry capability rows | Each stripe marks a quote or a status: blockquotes, toasts, the brand lock warning, sensitive capabilities |
overused-font | /admin screens | The admin is a tool people operate all day; a neutral, very legible UI face suits it. Public sites take their fonts from Brand |
.impeccable/config.local.json holds personal exceptions and is not committed.
What the first review changed
The first review, of spillwaycms.com and the admin on 2026-11-09, led to these changes in the blocks and the admin:
- headings balance their lines and running text avoids a one-word last line (
text-wrap); - Text, Form, the article template, hero subtitles and collection summaries keep a reading measure of about 70 characters;
- the hero eyebrow is set in sentence case, not tracked capitals;
- Cards and Collection have a Title level option, so titles under the page's h1 can be h2, and a Calendar's month heading is an h2;
- muted text on a primary-color band keeps 4.5:1;
- inline code wraps, and a wide table in prose scrolls on its own on a phone;
- the admin's site and avatar tiles are a solid color, and a table inside a card no longer draws a second card.
The impeccable skill for agents
The skill gives an agent the catalog and commands such as critique, audit, polish and typeset. It is about 24 MB with a native binary, so it is installed per person rather than committed. .gitignore covers its folders.
In Claude Code:
/plugin marketplace add pbakaus/impeccable
Or into this checkout, without its hooks:
npx -y impeccable@4.8.1 install --project --providers=claude --no-hooks -y
Its hooks run a design check after every UI edit an agent makes. Turn them on for yourself with /impeccable hooks on if you want that; they are left off by default because they change how every session in the repository behaves.
Spillway 0.1.0 · Edit this page on GitHub