design-philosophy/reference.md
# Design philosophy reference
Use when doing philosophy-heavy or art-direction work.
## Philosophy examples (condensed)
**Concrete Poetry** — Communication through monumental form and bold geometry. Massive color blocks, sculptural typography (huge single words, tiny labels), Brutalist spatial divisions. Polish poster energy meets Le Corbusier. Text as rare, powerful gesture — never paragraphs, only essential words in the visual architecture.
**Chromatic Language** — Color as the primary information system. Geometric precision; color zones create meaning. Typography minimal — small sans-serif labels; chromatic fields communicate. Josef Albers' interaction meets data viz. Words only to anchor what color already shows.
**Analog Meditation** — Quiet visual contemplation through texture and breathing room. Paper grain, ink bleeds, vast negative space. Photography and illustration dominate. Typography whispered (small, restrained). Japanese photobook aesthetic. Text sparingly — short phrases, never explanatory blocks.
**Organic Systems** — Natural clustering and modular growth. Rounded forms, organic arrangements, color from nature and architecture. Information through diagrams, spatial relationships, iconography. Text only for key labels floating in space.
**Geometric Silence** — Pure order and restraint. Grid-based precision, bold photography or stark graphics, dramatic negative space. Typography precise but minimal — small essential text, large quiet zones. Swiss formalism meets Brutalist material honesty. Structure communicates, not words.
---
How to *generate* a philosophy: the canonical numbered checklist lives in [SKILL.md](SKILL.md) (name the movement → 4–6 paragraphs → craftsmanship framing → minimal text → creative space).
.claude-plugin/marketplace.json
{
"$schema": "https://www.schemastore.org/claude-code-marketplace.json",
"name": "ckw-design",
"description": "Frontend design skill: direction, design system, visual philosophy.",
"owner": {
"name": "Conner K Ward",
"url": "https://github.com/connerkward"
},
"version": "1.0.0",
"plugins": [
{
"name": "ckw-design",
"description": "Frontend design skill: direction, design system, visual philosophy.",
"source": {
"source": "github",
"repo": "connerkward/ckw-design-skill"
}
}
]
}
.claude-plugin/plugin.json
{
"name": "ckw-design",
"description": "ckw-design is Conner K. Ward's frontend design skill for Claude Code",
"version": "0.1.0",
"author": {
"name": "Conner K Ward",
"url": "https://github.com/connerkward"
},
"homepage": "https://github.com/connerkward/ckw-design-skill",
"repository": "https://github.com/connerkward/ckw-design-skill",
"license": "MIT",
"keywords": [
"claude-code",
"claude-skill",
"claude-code-skill",
"agent-skills",
"anthropic",
"design",
"frontend",
"design-system",
"web-design"
]
}
design-philosophy/SKILL.md
---
name: design-philosophy
description: Visual philosophy and art-direction for frontend. Use when creating high-concept work, campaigns, or when the user asks for a visual philosophy, manifesto, or unmistakable art-like aesthetic.
author: Conner K Ward
---
# Design philosophy
Apply with **design** for high-concept work, campaigns, or when the user asks for a visual philosophy, manifesto, or art-like aesthetic. This skill guides creating a named movement and expressing it visually.
## Visual philosophy (when creating "art" or high-concept work)
1. **Name the movement** (1–2 words): e.g. "Brutalist Joy," "Chromatic Silence," "Metabolist Dreams."
2. **Articulate in 4–6 paragraphs** how the philosophy manifests through: space and form; color and material; scale and rhythm; composition and balance; visual hierarchy. Avoid redundancy; each aspect once.
3. **Craftsmanship**: Stress that the work should look meticulously crafted, labored over with care, the product of deep expertise — "painstaking attention," "master-level execution." Repeat this framing.
4. **Minimal text**: Information lives in design, not paragraphs. Text sparse and essential; integrated as visual element.
5. **Creative space**: Be specific about direction but concise so the executor can make high-level interpretive choices with the same level of craft.
For philosophy examples, see [reference.md](reference.md). The numbered checklist above is the canonical generation procedure.
## Deducing the subtle reference
Before building: identify one subtle conceptual thread from the request. The topic is a subtle, niche reference embedded in the work — not literal, always sophisticated. Someone familiar with the subject should feel it intuitively; others experience a strong abstract composition. Weave it into form, color, and composition. "Jazz quote" principle: only those who know catch it; everyone benefits.
LICENSE
MIT License
Copyright (c) 2026 Conner K Ward
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
SKILL.md
---
name: ckw-design
description: Entry point for frontend design. Use WHENEVER building or touching the look of any web UI — components, pages, dashboards, landing pages, React/Vue/HTML-CSS — and whenever the user says "make this look better/nicer", "fix the spacing/layout", or mentions styling, color, typography, fonts, responsive design, polish, or aesthetics, even without the word "design". Load design-thinking for direction; design-system for implementation; design-spatial for layout; design-philosophy for visual philosophy or art-direction.
author: Conner K Ward
---
# Design (entry)
Use this skill when the user asks to build or style web UIs: components, pages, dashboards, landing pages, React/Vue/HTML-CSS layouts, or any frontend interface. Goal: distinctive, production-grade output that avoids generic AI aesthetics.
**Before reporting any design "done": render it and have a *separate* judge critique the image** (not the code, not self-grading) — see design-spatial §1. Blind generation can't see its own collisions; this applies to all design output, not just spatial work.
> **MANDATORY HORIZONTAL-OVERFLOW GATE — runs before ANY web UI is "done".**
> Measure `document.documentElement.scrollWidth - document.documentElement.clientWidth`
> at a **narrow width (~390px and ~1024px), this turn**, and confirm it's `0`. This
> bug is invisible at desktop width and re-appears every time a row (header, nav,
> toolbar) gains an item, so it ships repeatedly. Default to `flex-wrap:wrap` on
> header/toolbar rows + `body{overflow-x:clip}`, and **re-measure after adding any
> element to a horizontal row.** Full procedure + recurrence cases: design-spatial §4.
> If you haven't measured narrow, you are not done — don't claim it.
## Sub-skills (load when relevant)
- **design-thinking** — Load for every design task. Defines purpose, tone, domain, color world, review bar, and cross-domain lens (cinema, architecture, marketing, UX, automotive, industrial design). See [design-thinking/SKILL.md](design-thinking/SKILL.md).
- **design-system** — Load when implementing: tokens, typography, motion, color semantics, backgrounds. Use when building components, pages, or design systems. See [design-system/SKILL.md](design-system/SKILL.md).
- **design-spatial** — Load when composing layout: explicit grid + 8-point spacing constraints, visual-weight/balance/alignment, and a render-then-critique vision loop. The fix for "spatial understanding is off" — generated layout that's centered mush, misaligned, or breaks at some widths. See [design-spatial/SKILL.md](deterministic-design/design-spatial/SKILL.md).
- **design-ux** — Load when auditing USABILITY (not just looks): a UI that "feels off"/"sucks to use", is hard to learn, needs an instruction wall, or any interactive tool/editor/app before shipping. Scores the rendered UI against Nielsen's 10 + interaction heuristics via a SEPARATE fresh-eyes judge → prioritized fix list. Usability ≠ aesthetics. See [design-ux/SKILL.md](deterministic-design/design-ux/SKILL.md).
- **design-philosophy** — Load for high-concept work, campaigns, or when the user asks for a visual philosophy, manifesto, or unmistakable art-like aesthetic. See [design-philosophy/SKILL.md](design-philosophy/SKILL.md).
## Visual assets — generate or source
When design-thinking identifies a need for visual assets (logos, icons, hero images, textures, backgrounds):
1. **Generate** → use an image-generation model or API for synthetic/branded assets.
2. **Source a real/archival one** → free stock or archival image search, often cheaper and more authentic than generating.
3. Use design-thinking output (tone, domain, color world) to craft prompts / queries.
4. Evaluate against the design philosophy, refine, integrate into the build.
## LLM-assisted work — always annotate model + cost
When design work involves running an LLM (generative assets, VLM analysis, layout critique, prompt generation, etc.):
- **Before running:** state which model will be used and the estimated cost (e.g., "gpt-4o-mini · ~$0.005/image" or "FLUX v1 · ~$0.006 per gen").
- **After results:** annotate the output with the model used, actual cost if different from estimate, and any key params (seed, prompt, settings). Cost goes *visible to the user* (in the message, contact sheet header, or asset caption), not buried in logs.
- **Why:** the user is deciding whether the cost-to-quality trade-off is worth it. Unlabeled or hidden costs hide the most important lever. This rule mirrors `media-attribution-rule` for generative assets and extends it to any LLM operation in the design workflow.
**Examples:**
- "Running gpt-4o-mini layout critique on 8 designs · est. ~$0.04 total" (before).
- Contact sheet header: "FLUX v1 · $0.48 total (6 gen × $0.08)" (after).
- Asset caption: "hero_banner_flux-dev_seed3891.jpg" (seeds enable reproducibility).
- Uncertainty slider result: "VLM triage on 46,978 images · gpt-4o-mini · ~$9.40" (before); "✓ Completed: 12,447 images classified · gpt-4o-mini · $7.62" (after).
## Algorithm / model explainers — show the equation, annotate the terms
Whenever a UI surfaces an algorithm or model to the user (an "ⓘ how this works"
panel, a model breakdown, a methods note), **include the actual equation, typeset,
with its key terms annotated** — don't settle for prose. A scorer described only in
words ("ranks by how much of the picked color is present") is unfalsifiable hand-
waving; the formula `score = Σ fracᵢ · max(0, 1 − ΔEᵢ/τ)` with each term labelled
tells the user *exactly* what the knob does and builds trust that there's real math
under the hood.
**How to apply:**
- Render one clean, central equation per algorithm — the "sexy" core, not every
detail. Use proper notation: σ for sigmoid, Σ for sums, ‖·‖ for norms,
superscripts, ΔE, ∇²; a monospace/serif-math block set off from the prose.
- **Annotate every symbol** immediately below: what `e_x`, `w`, `τ`, `Q` each are,
in one line each. An unlabelled equation is decoration; a labelled one is a spec.
- Keep it dependency-light — styled HTML/Unicode math is fine and works offline; only
reach for KaTeX/MathJax if the expressions genuinely need it.
- State the **decision rule** alongside the score (e.g. "personal if P ≥ 0.55").
- This composes with the model+cost annotation above: the equation says *what* it
computes, the model/cost line says *what ran it and for how much*.
**Example (a logistic head):**
> P(personal │ x) = σ(**w**·**e**ₓ + b), σ(z) = 1 / (1 + e⁻ᶻ)
> • **e**ₓ — the image's 768-d embedding · **w**, b — weights learned from your labels
> · decision: personal if P ≥ 0.55, reference if P ≤ 0.40.
## Select-all always has a deselect — no dead-end selections
Any **"Select all"** affordance MUST be paired with a way to **clear the selection** —
preferably the *same button*, label-flipped when everything is already selected
("Select all" ⇄ "Deselect all"). A select-all with no inverse is a trap: the user
over-selects (or hits it by reflex), then has to un-click items one by one, or reload
the page, to get back. The cost is silent — it only bites *after* they've committed to
the wrong set.
**How to apply:**
- **Toggle the same button** (simplest, fewest controls): when all visible items are
selected, the button reads "Deselect all" and clears; otherwise "Select all". One
control, no dead end.
- Or a **separate Clear/Deselect** shown whenever the selection is non-empty.
- The deselect must reach the **same scope** the select-all did (all *shown*, all
*filtered*, all *on this page*) — don't let "Select all" grab 500 but "Clear" only
drop the 50 on screen.
- This generalizes: any reversible bulk toggle (select, expand-all, mute-all,
check-all) needs its inverse one tap away. Symmetry of action — see
restraint-rule (don't strand the user mid-task).
design-system/references/motion-choreography.md
# Motion choreography — a generalizable animation guideline
When to animate, which transitions earn their keep, how long, and the craft that
separates intentional motion from jitter. **Framework-agnostic** — the rules hold for
plain CSS, the Web Animations API, the browser View Transition API, a JS motion library,
or React's `<ViewTransition>`. Load from design-system's Motion section when a UI has
state changes, navigation, list changes, or reveals worth animating.
> Adapted & generalized from the Web Interface Guidelines (`vercel-labs/web-interface-guidelines` @ `4e799d4`, 2026-04-06) and the React View Transitions skill (`vercel-labs/agent-skills` @ `f8a72b9`, 2026-06-10). Their API specifics are React/Next-bound; the *choreography* below is portable.
## 1. When to animate — earn every transition
Animate only when the motion **communicates** one of: a spatial relationship, continuity
("same thing, new place"), cause→effect, that data arrived, or deliberate delight.
**If you can't articulate in one sentence what a transition communicates, cut it.** Motion
with no message is noise that costs performance and attention.
- **Input-driven, never autoplay.** Animate in response to a user action or a state change
they caused — not on a timer that plays at them.
- This is the motion-specific case of restraint-rule: the default is *no* animation; a clear
communicative purpose is what forces a yes.
## 2. Which transitions earn their keep — priority order
When several kinds of change happen, implement every one that *applies* (not "pick one"),
in roughly this order of value:
1. **Shared element** — the same object persists across views (thumbnail → hero). Says "this
is the same thing, going deeper." Highest value; most worth the effort.
2. **Reveal** — skeleton/loading → real content. Says "data loaded."
3. **List identity** — items keep identity as the set reorders/filters. Says "same items,
new arrangement" (animate position, not a wholesale fade).
4. **State change** — something enters/exits (panel, toast, row). Says "this appeared/left."
5. **Route/section change** — moving to a new place.
Skip a level only when the UI has no such change. A background refresh / silent
revalidation should animate **nothing**.
## 3. Style by the *kind* of navigation — direction must be honest
The animation style must not imply a spatial relationship that isn't there:
| Navigation kind | Animation | Why |
|---|---|---|
| **Hierarchical** (list → detail, parent → child) | directional slide (in from the side, out the other) | direction encodes depth |
| **Ordered sequence** (prev/next photo, carousel, paginated) | directional slide; "next" from the right, "prev" from the left | direction encodes position |
| **Lateral / sibling** (tab ↔ tab, unordered) | **fade / cross-fade** — NOT a slide | there's no depth; a slide lies about it |
| **Reveal** (skeleton → content) | fade or short slide-up | content arriving |
| **Background refresh / revalidation** | none | nothing happened the user must track |
The single most common motion mistake is a directional slide on lateral navigation — it
falsely implies forward/back depth between peers.
## 4. Timing & easing (starting points, not law)
| Interaction | Duration |
|---|---|
| Direct toggle (expand/collapse, switch) | 100–200 ms |
| Route / section transition (slide) | 150–250 ms |
| Reveal (skeleton → content) | 200–400 ms |
| Shared-element morph | 300–500 ms |
- **Easing matches the change:** entrances `ease-out` (decelerate in), exits `ease-in`
(accelerate away), positional moves `ease-in-out`. Choose by what's changing (size,
distance, trigger) — bigger/further → a touch longer.
- A playful/toy direction (design-thinking) may stretch these and add spring/bounce; a
restrained/professional one keeps them tight. Match the feel to the chosen direction
rather than defaulting to the numbers.
## 5. Mechanics — what to animate, and how (any stack)
- **Compositor-friendly only:** animate `transform` and `opacity`. **Never** animate layout
properties (`width`, `height`, `top`, `left`) — they trigger reflow and jank.
- **Never `transition: all`** — list the exact properties; `all` silently animates
layout-affecting props and janks.
- **Correct `transform-origin`** — anchor motion where it "physically" starts (a menu from
its trigger, not screen-center).
- **Interruptible** — a new user input cancels/redirects the in-flight animation; motion is
never a modal wait.
- **SVG transforms** — apply to a `<g>` wrapper with `transform-box: fill-box;
transform-origin: center;` (avoids Safari origin bugs).
- **Stack preference:** CSS > Web Animations API > JS library. Prefer the platform; reach for
a library only when the platform can't express it.
## 6. Craft details that separate polished from amateur
- **Motion blur on morphs.** A shared-element morph reads as fast and physical with a brief
blur at mid-transition (e.g. `filter: blur(3px)` around the 30% mark), clearing to sharp.
- **Don't raster-scale text.** A shared-element morph between different text sizes (`h3 → h1`)
scales a *bitmap* of the small text up → a blurry ghost. Instead hold/cross-fade the text
(show the new text at full resolution, hide the old snapshot) rather than scaling it.
- **Isolate persistent chrome.** Headers, navs, sidebars, sticky toolbars that stay on screen
across a transition must NOT slide with the page content — give them their own transition
identity (or exclude them) so they stay put while content moves beneath.
- **Reveal anti-flicker.** If you show a spinner/skeleton, add a short show-delay (~150–300 ms)
and a minimum visible time (~300–500 ms) so a fast response doesn't flash the loader. (See
design-ux interaction add-ons.)
## 7. Accessibility — reduced motion
Honor `prefers-reduced-motion` for **public / multi-user** builds: drop the tweens (keep the
end state / a 0s cross-fade), don't remove the information the motion conveyed. For
**personal/single-user** projects this repo deliberately overrides that flag — see
`motion-preference-rule`. Either way, avoid parallax, large viewport-spanning transforms, and
strobing regardless of the flag.
## The one-line test
Before adding a transition: *what does this communicate, and is the style honest about it?*
If you can't answer the first, cut it; if the style implies depth/position that isn't there
(a slide between peers), change the style.
README.md
# ckw-design
**ckw-design** is Conner K. Ward's frontend design skill for Claude Code — direction, design system, and visual philosophy distilled into a loadable skill: how to set tone/domain/color-world, build tokens and typography, and hold a high review bar.
> **What this is:** A personal design skill — direction and taste, packaged. (For the deterministic measurement/judgment layer, see deterministic-design.)
## Install (Claude Code plugin)
```
/plugin marketplace add connerkward/ckw-design-skill
/plugin install ckw-design@ckw-design
```
Or install the whole set: `/plugin marketplace add connerkward/connerkward-skills`. Or drop this repo's `SKILL.md` into your agent's skills directory.
## License
MIT © Conner K Ward
---
# Claude Design Skills
**Claude Code skills for frontend design** — five composable agent skills that push Claude toward distinctive, production-grade UI design and away from generic AI aesthetics (Inter, purple gradients, three equal cards, centered single-column mush).
They cover design direction, design systems (tokens, typography, color), spatial composition and layout, loading/FOUT discipline, motion timing, and high-concept art direction — for any web UI work: components, pages, dashboards, landing pages, React/Vue/plain HTML-CSS.
## What's inside
| Skill | File | When it loads |
|---|---|---|
| **design** (entry) | [`design/SKILL.md`](design/SKILL.md) | Any time Claude builds or touches the look of a web UI — styling, spacing, layout, typography, color, polish, "make this look better" — even without the word "design". Routes to the four sub-skills. |
| **design-thinking** | [`design/design-thinking/SKILL.md`](design/design-thinking/SKILL.md) | Every design task, before coding. Defines purpose, tone, domain vocabulary, color world, a review bar, and a cross-domain lens (cinema, architecture, marketing, UX, automotive, industrial design). |
| **design-system** | [`design/design-system/SKILL.md`](design/design-system/SKILL.md) | When implementing: token architecture, typography hierarchy, resource loading order, FOUT prevention (no font pop-in, ever), graceful loading states, layout-stable chrome, motion timing, color semantics. |
| **design-spatial** | [`design/design-spatial/SKILL.md`](design/design-spatial/SKILL.md) | When composing layout, or when generated UI looks off — collisions, weak hierarchy, "looks like every startup site". Render-then-critique loop with a separate judge; deliberate deviation from the statistical mean. |
| **design-philosophy** | [`design/design-philosophy/SKILL.md`](design/design-philosophy/SKILL.md) | High-concept work, campaigns, visual manifestos, unmistakable art-like aesthetics. Includes a [reference](design/design-philosophy/reference.md) of condensed philosophy examples. |
## Install
Claude Code discovers skills in `~/.claude/skills/` (user-wide) or `<project>/.claude/skills/` (per-project). Copy the `design/` directory there:
```bash
# user-wide (all projects)
git clone https://github.com/connerkward/claude-design-skills.git
mkdir -p ~/.claude/skills
cp -R claude-design-skills/design ~/.claude/skills/design
```
```bash
# or per-project
mkdir -p .claude/skills
cp -R claude-design-skills/design .claude/skills/design
```
That's it — no build step, no dependencies. The skills are plain Markdown prompt content. Restart Claude Code (or start a new session) and they're available.
## How skills trigger
Each `SKILL.md` has YAML frontmatter with a `name` and a `description`. Claude Code injects all skill descriptions into the model's context; when a task matches a description, Claude loads that skill's full body on demand. The descriptions here are written to be "pushy" — they fire on styling, spacing, fonts, color, responsiveness, and "make it look nicer", not just the literal word "design".
The entry skill (`design`) is the router: it loads first and tells Claude which sub-skills to pull in for the task at hand (direction → `design-thinking`, implementation → `design-system`, layout → `design-spatial`, art direction → `design-philosophy`). Sub-skill bodies are only read when relevant, keeping context cost low.
## Philosophy
A language model's first design idea is the average of its training data — and there is more than one average: the generic-AI mean (Inter, purple-on-white, three equal cards) and the flashier designer-trend mean (oversized condensed caps, dark mode + grain, monospace "vibes" microtext). Neither is taste. These skills insist on two disciplines instead of prescribing a style: **look at the rendered output with fresh eyes** (a model can't see the collisions in its own token stream — screenshot it and have a separate judge critique the image), and **deviate from the first instinct toward the product's specific world** — its domain vocabulary, its color world, one signature element that could only exist for this product. Process over prescription; intentionality over intensity.
## License
MIT — see [LICENSE](LICENSE).
---
🧭 **[ckw-skills](https://github.com/connerkward/ckw-skills)** — part of Conner K. Ward's collection of Claude Code skills & MCP servers.
design-thinking/SKILL.md
---
name: design-thinking
description: Direction and intent for frontend design. Use with design when defining purpose, tone, domain, color world, and review bar; includes cross-domain lens from cinema, architecture, marketing, UX, automotive, industrial design.
author: Conner K Ward
---
# Design thinking
Apply with the **design** skill on every design task. Do this before coding.
## Design thinking (before coding)
- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme and execute with intention — e.g. brutally minimal, maximalist, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian.
- **Constraints**: Framework, performance, accessibility.
- **Differentiation**: One thing that makes it unforgettable.
Commit to one bold direction. Intentionality over intensity.
## Reserve impact for punctuation (use sparingly for effect)
High-impact devices — full-bleed media, dramatic motion, oversized type, a saturated accent, parallax — lose their force the moment they become the default. If every section is a full-screen video, none of them land. Choose 1–2 moments to go big (the hero, the payoff) and make everything else quiet and contained, so the big moments read as deliberate punctuation rather than noise. Restraint is what gives the rare full-bleed beat its hit; wall-to-wall intensity reads as flat. This is the luxury of reduction — a single bold gesture in generous negative space beats maximalism. Applies equally to scale, color (one accent, not five), and motion (one signature move, not constant animation).
## Domain and color
- **Domain**: 5+ concepts, metaphors, or vocabulary from the product's world (territory, not features).
- **Color world**: 5+ colors that "belong" in that world — what you'd see if this product were a physical space. Not "warm" or "cool"; name actual colors from that domain.
- **Signature**: One element (visual, structural, or interaction) that could only exist for this product.
## Review bar
Ask: "Would I put my name on this?" Design-lead review means: not "does it work?" but "is this unmistakably intentional and crafted?"
Non-negotiable craft invariants (a single failure fails the review):
- **No font pop-in. Ever.** Title/display text must never flash a fallback face or reflow as the webfont loads. Gate it on `document.fonts.ready` and fade in. See design-system → *Never let fonts pop in*.
- **First seen, first loaded.** Whatever is in the opening viewport (hero text, hero media, brand mark) must be prioritized to paint complete and correct before anything below the fold loads. See design-system → *Loading order*.
---
## Cross-domain lens
When defining direction, choose which disciplines fit the product and apply 2–3 principles from each. Examples: dashboard → UX + automotive; brand campaign → cinema + marketing; app → UX + industrial design.
### Cinema
- **Framing and composition**: Viewport as frame; rule of thirds, leading lines, foreground/mid/background depth. What's in focus = primary hierarchy.
- **Pacing and rhythm**: Sequence of reveals (like editing). One well-orchestrated load or scroll beat beats scattered motion.
- **Color and mood**: Color grading = mood; consistent palette as "look."
- **Focus and depth**: Focal plane and depth of field → visual hierarchy and layering (blur, opacity, scale).
### Architecture
- **Scale and proportion**: Human scale, rhythm of columns/grid, proportion of elements to viewport.
- **Wayfinding**: User always knows where they are and where they can go (orientation, nav, breadcrumbs).
- **Material and light**: Texture and shadow create depth; light direction implies elevation and emphasis.
- **Negative space**: Intentional emptiness; space as structure, not leftover.
- **Thresholds**: Entrance and transition moments (landing → app, modal open) as deliberate "crossings."
### Marketing
- **One hero message**: Single value proposition or takeaway above the fold; hierarchy of message, not feature list.
- **Emotional vs rational**: Decide whether the first beat is emotional pull or rational clarity; align layout and copy.
- **CTA prominence**: Primary action unmistakable; secondary actions present but not competing.
- **Audience fit**: Tone and imagery match who it's for; avoid "generic user."
- **Brand consistency**: One coherent voice and visual system across the artifact.
### UX
- **Goals and tasks**: Design around user goals and key tasks; reduce steps to completion.
- **Information architecture**: Clear grouping and hierarchy; cognitive load minimal.
- **Feedback and state**: Every action has visible feedback; loading, success, error states considered.
- **Accessibility**: Color contrast, focus order, semantics. (Reduced motion: honor `prefers-reduced-motion` for public/multi-user projects; personal projects may ship full motion.)
- **Progressive disclosure**: Show essentials first; detail on demand (expand, modal, step).
### Automotive (exterior / interior)
- **Silhouette and character**: One strong silhouette or "character line"; recognizable at a glance.
- **Surface language**: Tension, flow, continuity of surfaces (like body panels); avoid arbitrary bumps.
- **Proportion**: Balance of "cab" (content) to "wheel" (chrome/nav); stable, not top-heavy.
- **Materials and trim**: Hard/soft, cold/warm, matte/gloss as hierarchy; primary = one material language, accent = another.
- **Driver-centric layout**: Primary controls and info where the "driver" (user) looks first; secondary in reach but not competing.
- **Control hierarchy**: One primary action surface; secondary actions grouped and identifiable.
### Industrial design
- **Form follows function**: Shape and layout reflect use; no decoration without reason.
- **Material honesty**: Materials (or visual equivalent: texture, weight) feel appropriate to the function.
- **Affordances**: Shape suggests use (clickable, draggable, input); obvious without labels where possible.
- **Tactility**: Buttons and controls feel "pressable" or "grabbable" (hover/active state, depth).
- **Product personality**: One clear character (friendly, serious, playful, premium); consistent across the UI.
- **Simplify**: Remove until it breaks; "best part is no part" for UI clutter.
design-system/SKILL.md
---
name: design-system
description: "Mechanical implementation invariants for frontend design: token architecture, typography hierarchy, loading order, FOUT prevention, chrome stability, motion timing, color semantics. Use with design when building components, pages, or design systems. (Aesthetic direction lives in design-thinking; anti-trend/anti-slop in design-spatial.)"
author: Conner K Ward
---
# Design system
Apply with **design** when implementing UI: components, pages, or design systems. Every color, type, and motion choice should trace back to these rules.
## Token architecture
All colors map to a small set of primitives. No random hex values.
- **Foreground**: Text hierarchy (primary, secondary, muted).
- **Background**: Surface elevation (base, raised, overlay).
- **Border**: Separation hierarchy (subtle, default, emphasis).
- **Brand**: Identity and primary accent.
- **Semantic**: Destructive, warning, success (and optional info).
Use tokens in code (CSS variables, theme objects); never hardcode hex for UI.
## Typography
- **Hierarchy**: Headlines — heavier weight, tighter letter-spacing for presence. Body — comfortable weight for readability. Labels/UI — medium weight, works at smaller sizes. Data — monospace, `tabular-nums` for alignment.
- Combine size, weight, and letter-spacing so hierarchy is clear at a glance. If you squint and can't tell headline from body, hierarchy is too weak.
- **Fonts**: pair a display font with a body font; keep hierarchy legible at a glance. *Which* fonts is direction, not mechanics — pick from the domain and push off your first/default instinct (the mean); see design-spatial §2.
- **Data (functional only)**: real aligned numbers, IDs, timestamps in monospace with `tabular-nums` — mono earns its place when values line up in a column. Do NOT sprinkle mono on decorative eyebrow/metadata microtext ("35MM · DEVELOP · SCAN", fake spec captions) for a "technical" look — that's the current trend-slop, not data. See design-spatial §2.
## Loading order — first seen, first loaded
The first viewport must paint complete and correct, fast. Order every resource by whether the user sees it first; the rest waits.
- **Prioritize only the above-the-fold set** (hero text, hero image/video, brand mark). Preloading everything is the same as preloading nothing — the true criticals lose the bandwidth race. Pick the few things in the first screenful and prioritize *those*.
- **Fonts: self-host WOFF2.** Convert OTF/TTF → WOFF2 (Brotli; ~half the bytes, identical glyphs) and `<link rel="preload" as="font" type="font/woff2" crossorigin>` the weights used in the first viewport. Never a render-blocking third-party font stylesheet — a Google Fonts `<link>` adds a CSS round-trip plus extra DNS/TLS before the font even starts downloading; self-host instead.
- **LCP image/video:** `fetchpriority="high"` on the hero image (or the video poster); `<link rel="preload" as="image">` it when it's CSS-referenced (the parser can't see CSS `url()`s early). The hero box must never be empty — ship a poster/low-res placeholder so there's no blank frame.
- **Below the fold:** `loading="lazy" decoding="async"` on images; `preload="none"` (or `"metadata"`) on video; `defer` non-critical JS. Always reserve space (`aspect-ratio`, or `width`+`height`) so deferred media can't shift layout (CLS).
- Keep the render-blocking head minimal: inline critical CSS, defer the rest.
## Never let fonts pop in (no FOUT) — ever
`font-display: swap` **is** the pop — it paints a fallback face, then swaps to the webfont and reflows. Do not use it for any text the user watches load (titles, wordmarks, hero copy). The rule is absolute: title/display text must never flash a fallback or reflow.
- **Gate visibility on the real font.** Synchronously in `<head>`, add a `fonts-pending` class to `<html>` that holds the display-font text at `opacity: 0`. On `document.fonts.ready` — kick it with `document.fonts.load('<weight> 1em "Family"')` for each critical face — swap to `fonts-ready` and fade the text in (~0.5s). Always include a safety timeout (~2.5s) that reveals regardless, so a font failure can never leave text permanently hidden.
- Pair this with preload + WOFF2 (above) so the hidden window is a few hundred ms, not seconds — the fade reads as intentional, not as a stall.
- For body text where a sub-perceptual swap is tolerable, at minimum kill the reflow: define a fallback `@font-face` (or `font-family` fallback) tuned with `size-adjust` / `ascent-override` / `descent-override` so the fallback occupies the same metrics as the webfont and the swap shifts nothing.
Worked example — an AR product-research page: a head script toggles `fonts-pending → fonts-ready` (titles fade in on `fonts.ready`, 2.5s fallback), preloads the four above-the-fold WOFF2 weights, and self-hosts the brand face so there's no Google round-trip.
## Slow-loading content — never show the ugly intermediate state
Anything that *could* take a noticeable moment to be ready — fonts (above), large images, video, `<canvas>` scenes, Three.js / WebGL, lazy-loaded React islands, anything that fetches over the network or runs heavy main-thread setup — must either **arrive fast** or **load gracefully**. The default browser behavior (blank box → partial paint → reflow → final state) is the ugly intermediate state. Catch it.
Two levers; use both:
- **Arrive faster.** Compress (WOFF2 for fonts, Draco for glTF, WebP/AVIF for images, h264/h265 for video with `preload="metadata"`). Preload the *few* assets the first viewport actually needs (`<link rel="preload">`). Lazy-load below-the-fold so the LCP set isn't competing. Reserve the box (`aspect-ratio`, `width`+`height`) so deferred content can't trigger CLS.
- **Load gracefully.** Hide the in-flight state behind a styled placeholder, then fade the real thing in. Skeleton boxes, low-res blurred posters, a single ASCII glyph, even just the container's bg color — anything coherent with the design beats the default partial-paint.
What "ugly" looks like, concretely, and the fix:
| Symptom | Fix |
|---|---|
| Annotation labels stack at `translate(0,0)` (top-left of container) until JS positions them | Start labels at `opacity: 0` with a `transition: opacity ~0.35s`; first projection sets inline opacity → CSS fades them up. |
| Canvas/WebGL paints empty/black for a frame on first render | Show a placeholder (CSS art, low-res poster image, or paper/skeleton fill) in the same box; remove it once the first real frame has rendered. |
| Lazy image fetches and snaps in with a layout-jump | `aspect-ratio` + `<link rel="preload">` (above-the-fold) or `loading="lazy" decoding="async"` (below); fade from `opacity:0` on the `load` event for the first paint. |
| Video poster pops to first frame on play | `poster` matches a still you control; once `playing` event fires, you've already had a clean handoff. |
| 3D model "appears" mid-screen with no transition | Keep the canvas visible but at `opacity: 0`; toggle a `.viewer-ready` class (or set inline opacity) inside the GLTFLoader success callback, after the first `tick()`. |
| Lazy React island flashes a fallback that looks worse than no UI | Replace `Suspense` fallback with a skeleton that traces the final layout, not a spinner. |
Rule of thumb: if a user could screenshot the page mid-load and you'd be embarrassed, you owe it a graceful state. The placeholder doesn't have to be fancy — it has to be *intentional*, sized correctly, and in the design language of what's coming.
## Chrome stays still — status text never resizes layout
Persistent chrome (headers, nav, toolbars, search bars, status regions) must hold a **constant height** no matter what text lands in it. Transient status / loading / explanatory copy — "loading model…", "N matching · M indexed", empty-state hints — must not wrap to a second line and shove adjacent controls down. A status region that grows and shrinks as its message changes is a layout-jank bug, not dynamic content.
- **Constrain to one line:** `white-space: nowrap; overflow: hidden; text-overflow: ellipsis` so the longest message truncates instead of wrapping.
- **Reserve the space up front:** give the container a fixed `height` (or `min-height`) sized for the message, so the shortest and longest states — and the empty state — occupy the same footprint.
Only the content area should move while chrome stays fixed; layout shift from transient text reads as broken polish. (Concrete failure this prevents: in a search app, a model-loading message wrapping to two lines and pushing the search bar downward.)
## Motion
- Keep timing consistent and purposeful; one well-orchestrated moment (staggered page load with `animation-delay`) beats scattered micro-interactions. Prefer CSS-only for HTML; Motion library for React. (Honor `prefers-reduced-motion` for public/multi-user projects.)
- **Defaults for restrained/professional UIs** (a starting point, not law): micro-interactions ~150ms, larger transitions 200–250ms, ease-out. A playful/toy-like tone (design-thinking) may want spring/bounce and longer beats — match motion feel to the chosen direction rather than defaulting to these numbers.
- **Choreography** — for anything beyond a single micro-interaction (route/page transitions, list reorder, reveals, shared elements), load [references/motion-choreography.md](references/motion-choreography.md): when a transition earns its keep (it must *communicate* something or get cut), which kinds to implement and in what order, **style by navigation type** (directional slide only for hierarchical/ordered — a slide between peers lies about depth; laterals fade), a duration table, and craft (compositor-only props, motion-blur on morphs, never raster-scale text, persistent-chrome isolation). Framework-agnostic.
### Scroll-driven narrative (scrollytelling)
For **explanatory / editorial / data-walkthrough** content, prefer **scroll-driven graphics over click-interactive widgets**. A reader scrolls by default; making them hunt for and click a toggle to advance an explanation adds friction and gets skipped. Use the NYT/Pudding pattern: pin one graphic (`position: sticky`) while short text "steps" scroll past it, and let each step drive the graphic's state.
- **Mechanics:** one `IntersectionObserver` with `rootMargin: '-48% 0px -48% 0px'` (threshold 0) so a step goes "active" exactly as it crosses the viewport mid-line; the active index re-renders the pinned graphic. ~30 lines — this *is* scrollama minus the dependency; don't add a scroll library.
- **Layout:** two columns — steps scroll in one, the graphic `sticky top-0 h-screen` in the other; stack on mobile with the graphic sticky on top. Give each step ~85vh so exactly one is centered at a time; dim the inactive step cards (`opacity:.3`) so the live one reads.
- **Graphic is a pure function of the active step** (`graphic(active)`), holding no click state of its own — so it also screenshots/exports deterministically and degrades to a static figure. Animate *between* states (color / width / opacity, 300–700ms) so scrolling feels continuous, not steppy.
- **When NOT to:** dashboards, tools, forms — anything the user *operates* rather than *reads* — stay interactive. Scrollytelling is for **narration**, where you own the order. (Public/multi-user builds: honor `prefers-reduced-motion` per the Motion note above; keep the state changes but drop the tweens.)
## Spatial composition & layout
Grid systems, the 8-point spacing scale, visual-weight balance, alignment, and the render-then-critique loop live in **design-spatial** ([../design-spatial/SKILL.md](../design-spatial/SKILL.md)) — the mechanical counterpart to this file's tokens/type/color. Load it whenever composing pages, dashboards, or components. (Direction nugget that belongs here: match composition ambition to the vision — maximalist earns elaborate/layered code; minimal/refined demands restraint and precise spacing.)
## Nested radii (only when one rounded element sits inside another)
Not a push to round things — this governs the case where a rounded element is nested in
another (a button in a card, an inset panel in a container). When nested:
- **Child radius ≤ parent radius**, never larger (a child corner rounder than its parent looks
like it's bulging out).
- **Concentric** is the ideal: `child_radius = parent_radius − gap` (the padding between them),
so the two curves run parallel and the inner corner echoes the outer. Flat/unrounded children
in a rounded parent are fine; what reads as broken is mismatched, non-concentric curves.
## Color
- **Palette from domain**: colors should feel like they came *from* the product's world, not applied on top.
- **Beyond temperature**: quiet vs loud, dense vs spacious, serious vs playful, geometric vs organic — not just warm/cool.
- **Color carries meaning**: gray builds structure; color communicates status, action, emphasis, identity. Unmotivated color is noise. (Restraint — one accent, not five — is a direction principle; see design-thinking → *reserve impact for punctuation*.)
- **Contrast — APCA for decisions, WCAG for the gate.** For *perceptual* contrast judgments (is this text comfortably readable on this surface?) prefer **APCA** ([apcacontrast.com](https://apcacontrast.com/)) — it models lightness perception far better than the WCAG 2 ratio, which mis-rates light-on-dark and mid-tones. Keep **WCAG 2 (4.5 / 3:1) as the compliance floor** — it's what `design-spatial`'s `layout-audit.js` gates on and what accessibility standards require. Use APCA to design, WCAG to certify.
- **Interactive states gain contrast.** `:hover`, `:active`, `:focus` must read as *more* prominent than rest — more contrast, not less. A hover that lowers contrast (e.g. lightens text toward the bg) reads as disabled.
Avoiding the generic/trend look (Inter, purple-on-white, the same dark-glass card) and varying across generations is **design-spatial §2** — not restated here.
## Backgrounds & detail
Atmosphere over flat fills — but matched to the chosen aesthetic, not a default. The reflexive gradient-mesh / noise / grain "premium" treatment is itself the designer-trend mean (design-spatial §2); reach for it only when the direction genuinely calls for it, never as decoration for its own sake.
deterministic-design/SKILL.md
---
name: deterministic-design
description: Deterministic, measurable design verification — render the UI and PROVE it's balanced and usable instead of trusting the model's eye. Layout audit (centroid / optical-center / pixel-oracle balance via deterministic math, annotated screenshot) + a vision-judged Nielsen usability audit by a SEPARATE fresh-eyes judge. Use to catch AI-generated UI that "looks off", is misaligned / centered-mush, or fails usability — the measurement+judgment layer that token-and-taste design skills (including the default) don't have.
author: Conner K Ward
---
# deterministic-design
Thesis: **determinism beats AI randomness.** A model can't trust its own eye on layout — so
don't. Render the UI and *measure* it.
Two sub-skills (load as needed):
- **[design-spatial](design-spatial/SKILL.md)** — deterministic layout audit: explicit grid
+ 8-pt spacing, and `layout-audit.js` computes centroid / optical-center / pixel-oracle
balance and draws an annotated screenshot. **Numbers, not vibes.** Plus a render-then-
critique vision loop.
- **[design-ux](design-ux/SKILL.md)** — usability audit: scores the rendered UI against
Nielsen's 10 + interaction heuristics via a SEPARATE fresh-eyes judge → prioritized fix list.
This **improves** existing design skills (including the default Anthropic one) by adding the
layer they lack — it doesn't just advise on taste, it renders, measures, and judges the
output. Composable with any design skill.
In central this lives as a subdir of ckw-design; it **publishes separately** as
`deterministic-design-skill` (its own distribution) via publish-skill. One of the two
flagship narratives — the *determinism* one; its sibling is human-in-the-loop (lookdev).
llms.txt
# ckw-design
> ckw-design is Conner K. Ward's frontend design skill for Claude Code: direction, design system, and visual philosophy as a loadable skill.
## Install (Claude Code)
- Add the marketplace: `/plugin marketplace add connerkward/ckw-skills`
- Install this plugin: `/plugin install ckw-design@connerkward`
## Links
- Canonical README: https://github.com/connerkward/ckw-design-skill
- Marketplace (all of Conner K. Ward's skills + MCP servers): https://github.com/connerkward/ckw-skills
## Optional
- Author: Conner K. Ward — https://github.com/connerkward
deterministic-design/design-spatial/scripts/layout-audit.js
/* ============================================================================
layout-audit.js — deterministic layout metrics that MEDIATE the eye.
Run via Playwright MCP `browser_evaluate` on a rendered page. It does TWO things:
1. returns a compact JSON of measured findings (geometry, contrast, tap, balance)
2. DRAWS those findings as an SVG overlay onto the page, so the very next
`browser_take_screenshot` is an ANNOTATED screenshot.
The annotated screenshot is the whole point. You MUST view it and reason over the
picture + the numbers together — the metric tells you WHERE to look; your eyes
decide whether each flag is a real defect or an intentional choice (an avatar on a
banner "collides"; a brutalist overlap is the design). NEVER auto-fail on a count,
and never accept a metric you haven't looked at. The number points; the eye decides.
Usage (Playwright MCP):
browser_evaluate({ function: "() => { <paste this whole file> ; return __audit({}); }" })
browser_take_screenshot() // <-- now shows the overlay; LOOK at it
Options (pass to __audit):
{ align: '.card .title, .card .price', // selector whose left edges SHOULD align
space: '.feature-list', // container whose children's vertical rhythm to check
draw: true } // set false to measure without drawing
Re-run __clearAudit() to remove the overlay.
============================================================================ */
function __audit(opts){
opts = opts || {};
const DRAW = opts.draw !== false;
const COL = {collision:'#e0245e',align:'#d98a00',spacing:'#2f7fd6',contrast:'#8a2be2',tap:'#159a4d',balance:'#111'};
const vis = el => { const s=getComputedStyle(el); return s.display!=='none'&&s.visibility!=='hidden'&&el.getClientRects().length>0; };
const R = el => { const r=el.getBoundingClientRect();
return {el,x:r.left,y:r.top,w:r.width,h:r.height,r:r.right,b:r.bottom,cx:r.left+r.width/2,cy:r.top+r.height/2}; };
// ---- content set: visible, sized, leaf-ish "ink" elements (skip layout wrappers) ----
const CONTENT = (opts.contentSelector
? [...document.querySelectorAll(opts.contentSelector)]
: [...document.querySelectorAll('h1,h2,h3,h4,p,li,img,svg,button,a,input,label,figure,blockquote,[class*="card"],[class*="tile"],[class*="btn"],[class*="hero"],[class*="banner"],[class*="panel"],[class*="badge"],[class*="chip"],[class*="thumb"],[class*="avatar"]')])
.filter(vis).map(R).filter(it=>it.w>=8&&it.h>=8&&it.w<innerWidth*1.5);
// 1. COLLISION — content rects overlapping ≥12% of the smaller (skip ancestor/descendant)
const collisions=[];
for(let i=0;i<CONTENT.length;i++)for(let j=i+1;j<CONTENT.length;j++){
const a=CONTENT[i],b=CONTENT[j];
if(a.el.contains(b.el)||b.el.contains(a.el))continue;
const ix=Math.max(0,Math.min(a.r,b.r)-Math.max(a.x,b.x)), iy=Math.max(0,Math.min(a.b,b.b)-Math.max(a.y,b.y));
if(ix*iy<=0)continue;
if(ix*iy/Math.min(a.w*a.h,b.w*b.h)>0.12) collisions.push([a,b]);
}
// 2. ALIGNMENT near-miss — only meaningful when scoped to elements that SHOULD share a line
let nearmiss=[], guides=[];
if(opts.align){
const els=[...document.querySelectorAll(opts.align)].filter(vis).map(R).sort((a,b)=>a.x-b.x);
let cur=[]; const cl=[];
els.forEach(e=>{ if(cur.length&&e.x-cur[cur.length-1].x>11){cl.push(cur);cur=[];} cur.push(e); });
if(cur.length)cl.push(cur);
cl.forEach(c=>{ if(c.length<2)return;
const xs=c.map(e=>e.x).sort((a,b)=>a-b), med=xs[(xs.length/2)|0], spread=xs[xs.length-1]-xs[0];
guides.push(med); if(spread<=0.8||spread>10)return;
c.forEach(e=>{ if(Math.abs(e.x-med)>0.8) nearmiss.push({x:e.x,med,y:e.y,b:e.b,cy:e.cy,off:Math.round(e.x-med)}); });
});
}
// 3. SPACING rhythm — vertical gaps among a container's direct children
let spacing={gaps:[],cov:0,outliers:[]};
if(opts.space){ const cont=document.querySelector(opts.space);
if(cont){ const kids=[...cont.children].filter(vis).map(R).sort((a,b)=>a.y-b.y), gaps=[];
for(let i=0;i<kids.length-1;i++){const g=kids[i+1].y-kids[i].b; if(g>-6&&g<400)gaps.push({g:Math.round(g),a:kids[i],b:kids[i+1]});}
if(gaps.length>=2){ const v=gaps.map(o=>o.g),mn=v.reduce((s,x)=>s+x,0)/v.length,
sd=Math.sqrt(v.reduce((s,x)=>s+(x-mn)**2,0)/v.length);
spacing={gaps,cov:mn?Math.abs(sd/mn):0,mean:mn,outliers:gaps.filter(o=>Math.abs(o.g-mn)>Math.max(6,Math.abs(mn)*0.5))}; }
}
}
// 4. CONTRAST — WCAG ratio of text vs effective background
const rgb=s=>{const m=(s||'').match(/rgba?\(([^)]+)\)/);if(!m)return null;const p=m[1].split(',').map(parseFloat);return{r:p[0],g:p[1],b:p[2],a:p[3]??1};};
const ebg=el=>{let n=el;while(n&&n.nodeType===1){const c=rgb(getComputedStyle(n).backgroundColor);if(c&&c.a>0.5)return c;n=n.parentElement;}return{r:255,g:255,b:255,a:1};};
const lum=({r,g,b})=>{const f=v=>{v/=255;return v<=0.03928?v/12.92:((v+0.055)/1.055)**2.4;};return .2126*f(r)+.7152*f(g)+.0722*f(b);};
const ratio=(a,b)=>{const L1=lum(a),L2=lum(b),hi=Math.max(L1,L2),lo=Math.min(L1,L2);return (hi+.05)/(lo+.05);};
const contrast=[];
[...document.querySelectorAll('h1,h2,h3,h4,h5,h6,p,a,span,li,button,label,td,th,figcaption,small,strong,em')].filter(vis).forEach(el=>{
const t=(el.childNodes.length&&[...el.childNodes].some(n=>n.nodeType===3&&n.textContent.trim()));if(!t)return;
const cs=getComputedStyle(el),fg=rgb(cs.color);if(!fg)return;
const ra=ratio(fg,ebg(el)),px=parseFloat(cs.fontSize),wt=parseInt(cs.fontWeight)||400,large=px>=24||(px>=18.66&&wt>=700);
if(ra < (large?3:4.5)){const r=R(el);contrast.push({x:r.x,y:r.y,w:r.w,h:r.h,ratio:Math.round(ra*10)/10,large});}
});
// 5. TAP — interactive targets under 44×44 (Apple HIG)
const tap=[...document.querySelectorAll('a,button,[role="button"],input:not([type="hidden"]),select,textarea,[onclick]')]
.filter(vis).map(R).filter(it=>it.w<44||it.h<44);
// 6. BALANCE — ink-density-weighted centroid (box-model ESTIMATE) vs optical center (0.50,0.46)
// NOTE: this is the cheap model. For ground truth, screenshot and run a pixel-centroid (see SKILL §6).
const DENS={H1:.82,H2:.62,H3:.5,H4:.45,P:.16,LI:.16,IMG:.5,SVG:.5,BUTTON:.7,A:.4};
const dens=el=>el.tagName in DENS?DENS[el.tagName]:0.3;
let W=0,Mx=0,My=0; const pw=document.documentElement.scrollWidth, ph=document.documentElement.scrollHeight;
CONTENT.forEach(it=>{const w=it.w*it.h*dens(it.el);W+=w;Mx+=w*(it.cx+scrollX);My+=w*(it.cy+scrollY);});
const balance = W?{cx:Mx/W/pw,cy:My/W/ph}:{cx:.5,cy:.46};
balance.off=Math.hypot(balance.cx-0.5,balance.cy-0.46);
// 7. OVERFLOW — horizontal scroll (the §4 gate)
const overflow=Math.max(0, document.documentElement.scrollWidth - document.documentElement.clientWidth);
// ---- draw overlay (this is what makes the next screenshot annotated) ----
__clearAudit();
if(DRAW){
const NS='http://www.w3.org/2000/svg', svg=document.createElementNS(NS,'svg');
svg.id='__auditOverlay';
Object.assign(svg.style,{position:'fixed',inset:'0',width:'100vw',height:'100vh',zIndex:2147483647,pointerEvents:'none'});
const add=(t,a)=>{const e=document.createElementNS(NS,t);for(const k in a)e.setAttribute(k,a[k]);if(a._t)e.textContent=a._t;svg.appendChild(e);};
collisions.forEach(([a,b])=>[a,b].forEach(it=>add('rect',{x:it.x,y:it.y,width:it.w,height:it.h,fill:COL.collision+'22',stroke:COL.collision,'stroke-width':2.5})));
guides.forEach(x=>add('line',{x1:x,y1:0,x2:x,y2:innerHeight,stroke:COL.align,'stroke-width':1,'stroke-dasharray':'6 5','opacity':.6}));
nearmiss.forEach(n=>{add('line',{x1:n.x,y1:n.y,x2:n.x,y2:n.b,stroke:COL.align,'stroke-width':3});add('text',{x:n.x+8,y:n.cy+4,fill:COL.align,'font-family':'monospace','font-size':13,_t:(n.off>=0?'+':'')+n.off+'px'});});
spacing.gaps.forEach(o=>{const bad=spacing.outliers.includes(o),x=Math.min(o.a.x,o.b.x)-16;add('line',{x1:x,y1:o.a.b,x2:x,y2:o.b.y,stroke:bad?COL.collision:COL.spacing,'stroke-width':bad?3.5:2});add('text',{x:x-7,y:(o.a.b+o.b.y)/2+4,fill:bad?COL.collision:COL.spacing,'font-family':'monospace','font-size':13,'text-anchor':'end',_t:o.g});});
contrast.forEach(c=>{add('rect',{x:c.x-2,y:c.y-2,width:c.w+4,height:c.h+4,fill:'none',stroke:COL.contrast,'stroke-width':2,'stroke-dasharray':'3 3'});add('rect',{x:c.x,y:c.y-19,width:64,height:17,fill:COL.contrast});add('text',{x:c.x+4,y:c.y-6,fill:'#fff','font-family':'monospace','font-size':12,_t:c.ratio+':1 ✗'});});
tap.forEach(it=>{add('rect',{x:it.x,y:it.y,width:it.w,height:it.h,fill:'none',stroke:COL.tap,'stroke-width':2.5});add('text',{x:it.x,y:it.b+13,fill:COL.tap,'font-family':'monospace','font-size':12,_t:Math.round(it.w)+'×'+Math.round(it.h)});});
document.body.appendChild(svg);
}
// ---- JSON summary, split by KIND. The metric is never a verdict on its own. ----
return {
// GATES — correctness (accessibility/usability facts). Safe to block on; gates_pass must hold.
gates: { overflow_px: overflow, contrast_fails: contrast.length, tap_too_small: tap.length },
gates_pass: overflow===0 && contrast.length===0 && tap.length===0,
// REVIEW — usually a real defect, but can be intentional (deliberate overlap). Eye-confirm; do NOT auto-fail.
collisions: collisions.length,
// SIGNALS — convention, NOT correctness. High score = closer to the symmetric/regular MEAN (§2).
// Deviation is often the better design. Use to catch accidents; never auto-correct toward symmetry.
signals: { balance_offset:+balance.off.toFixed(3), balance_centroid:[+balance.cx.toFixed(3),+balance.cy.toFixed(3)],
align_nearmiss: nearmiss.length, spacing_cov:+spacing.cov.toFixed(2) },
contrast_detail: contrast.map(c=>({ratio:c.ratio, large:c.large})),
note: 'These are HEURISTICS. (1) LOOK at the annotated screenshot — a flag marks WHERE to look, never a verdict. '
+ '(2) GATES (overflow/contrast/tap) are correctness — fix them. (3) SIGNALS (balance/alignment/spacing) measure '
+ 'CONVENTION = the generic mean; off-center balance, deliberate misalignment, uneven rhythm are creative tools — '
+ 'do NOT "fix" a signal toward symmetry unless the eye judges the deviation worse. Maximizing signals designs the mean. '
+ '(4) collisions: usually a bug, sometimes intentional (overlap aesthetics) — eye-confirm. '
+ 'gates_pass is necessary, not sufficient; a passing layout can still be generic.'
};
}
function __clearAudit(){ const o=document.getElementById('__auditOverlay'); if(o)o.remove(); }
deterministic-design/design-ux/SKILL.md
---
name: design-ux
description: UX / usability audit — heuristic evaluation of INTERACTIVE UIs (not just visual polish). Load with design when a UI "feels off", "sucks to use", is hard to learn, needs an instruction wall, or before shipping an interactive tool/editor/app. Scores the RENDERED UI against Nielsen's 10 + interaction heuristics via a SEPARATE fresh-eyes judge and returns a prioritized, severity-ranked fix list. Usability ≠ aesthetics — a beautiful UI can still be unusable; this audits the interaction.
author: Conner K Ward
---
# design-ux — usability audit (heuristic evaluation)
Usability ≠ aesthetics. design-system/design-spatial make it *look* right; this checks whether a first-timer can do the task **without being told how**. Use it whenever a UI "sucks to use," needs a paragraph of instructions, or before shipping anything interactive.
## Rule 0 — fresh eyes, on the rendered artifact (inherited from design-spatial §1)
**Never self-grade.** The builder rationalizes its own UI. Render the *live* UI in its **default first-load state** (not a hand-arranged screenshot), capture an **interaction trace** of the primary task, and have a **separate judge** (a subagent/VLM that did NOT build it) score it. A described list of changes is not an audit — the audit is a fresh judge hunting for what's *wrong* on the real screen.
## The procedure
1. **Name the primary task(s)** the UI exists for (e.g. "trim a clip and set its speed, then export"). The audit is relative to these, not to abstract prettiness.
2. **Render default state + trace the task.** Screenshot the first-load UI (wide AND narrow — overflow gate from design-spatial §2). Then actually perform the primary task and screenshot each step.
3. **Score every heuristic** (table below) on the artifact: pass / violation, **severity** (blocker / major / minor), a *specifically located* finding, and a concrete fix. Separate judge does this.
4. **Prioritize**: blockers → majors → minors; cluster fixes that touch the same surface.
5. **Fix, then RE-RENDER and RE-SCORE.** Do not claim fixed without re-auditing the new artifact (verify-outputs-rule).
## Heuristics — score each (Nielsen's 10, 1994) + interaction add-ons
| # | Heuristic (Nielsen) | What to check in THIS UI |
|---|---|---|
| 1 | **Visibility of system status** | Every action has visible feedback; current state/selection/mode always legible; progress for slow ops. |
| 2 | **Match the real world** | Known metaphors & conventions (e.g. NLE: clips, trim handles, playhead) — not bespoke gestures users must learn. |
| 3 | **User control & freedom** | Undo/redo, cancel, clear exits from any state; reversible by default. |
| 4 | **Consistency & standards** | Same thing looks/behaves the same; platform conventions (⌘Z, Delete, drag-to-move) honored. |
| 5 | **Error prevention** | Invalid states made impossible; destructive actions confirmed or trivially undoable. |
| 6 | **Recognition over recall** | Options/affordances **visible** — no memorizing. *An instruction wall is a failure of this heuristic: if you must explain scroll-to-zoom / drag-edge / double-click in prose, the affordance is missing.* |
| 7 | **Flexibility & efficiency** | Defaults carry novices; shortcuts/accelerators for experts; sensible first-run with nothing configured. |
| 8 | **Aesthetic & minimalist** | Signal over chrome; no irrelevant elements competing; the *primary surface* carries the most visual weight. |
| 9 | **Recognize/diagnose/recover from errors** | Plain-language errors (not raw stderr), and a path out. |
| 10 | **Help & documentation** | Rarely needed if 1–9 hold; task-oriented, in-context, not a top-of-page lecture. |
**Interaction add-ons (compose, don't restate):**
- **Don't-make-me-think (Krug):** affordances self-evident; the UI teaches itself. Instruction paragraph ⇒ affordance debt (ties to #6).
- **Fitts / transit time (design-spatial §3):** controls sit near where the task leaves the cursor. A selected object's properties belong **adjacent to the object** (dock/popover), not in a far panel — every edit shouldn't be a round-trip.
- **Discoverability of gestures:** any non-obvious gesture (wheel, edge-drag, dbl-click) needs a **visible affordance** (handle, hover cue, icon) or it doesn't exist for most users.
- **Visual-weight match (design-spatial):** the surface the user *operates* (timeline, canvas, editor) should be the visual hero — not a thin strip under a big passive preview.
- **Progressive disclosure (design-thinking UX):** essentials first; advanced on demand. But disclosure ≠ hiding the primary tool.
- **Tooltip timing:** delay the *first* tooltip in a group (~300–700ms hover-intent) so sweeping the cursor over controls doesn't flash tips; once one is open, **peers show instantly** (no per-tooltip re-delay) while the user scans the row. Fires-on-every-hover is noise; re-delays-on-each-neighbor is sluggish.
- **Scroll-position restore:** Back/Forward returns the user to where they were, not the top — losing place after a detail→back trip is a silent, repeated tax. Browsers do this by default; the bug is *breaking* it with manual scroll resets or client routing that forgets.
- **Idempotency on submit:** mutating actions carry an idempotency key so a double-click, retry, or flaky-network resend can't duplicate the effect (a second charge, a duplicate post). Pairs with "disable submit during the in-flight request + spinner" — the key is the server-side guarantee, the disable is the client-side courtesy.
*(Tooltip / scroll-restore / idempotency from the Web Interface Guidelines, `vercel-labs/web-interface-guidelines` @ `4e799d4`, 2026-04-06.)*
## Output format
A scored table — `Heuristic | Finding (located) | Severity | Fix` — then a prioritized fix list (blockers first). Severity: **blocker** = can't complete the task / actively misleading; **major** = slows or confuses; **minor** = polish.
## Relation to the rest of design
- **design-spatial** owns the render-then-critique mechanism + Fitts/transit + overflow gate; this skill applies that lens to *usability* specifically and adds the heuristic scorecard.
- **design-thinking** owns the UX *principles* (goals/tasks, IA, feedback, accessibility, progressive disclosure); this skill turns them into a *scored audit + fix loop*.
- Run a usability audit **before** declaring an interactive UI "done" — alongside the visual critique, not instead of it.
deterministic-design/design-spatial/SKILL.md
---
name: design-spatial
description: Spatial composition and layout for frontend design. Load with design when composing pages/dashboards/components, or whenever generated UI looks off — overlapping/colliding elements, weak hierarchy, or generic ("looks like every startup site"). The core idea: a model can't trust its own layout, so render it, critique it with fresh eyes, and deviate from your first instinct.
author: Conner K Ward
---
# Design — spatial composition
A model cannot trust its own UI output. Everything else follows from two failures.
## 1. It can't see what it made
UI is generated as a token stream, never as pixels — so the model cannot perceive collisions, overlap, imbalance, or broken spacing. It will write a headline that runs into the hero image and have no idea.
**Render it and judge the image, not the code.** Serve with any static server (e.g. `python3 -m http.server` or `npx serve`) and screenshot headless via Playwright. Screenshot at a few widths.
**Critique with fresh eyes — not your own.** Grading your own output rationalizes it; the builder looks at its overlapping headline and calls it fine (this is exactly how a real collision shipped in testing). Use a separate judge — a subagent that did *not* write the page — and tell it to hunt for what's *wrong*: collisions, edge tangents, ragged alignment, lopsided weight, no clear focal point, breaks at some width. Fix, re-render, re-judge.
## 2. Its first idea is the average
Whatever it produces first is the mean of its training data — and there is more than one mean:
- the **generic-AI mean**: Inter, purple-on-white gradients, centered single column, three equal cards;
- the **designer-trend mean**: oversized condensed caps, dark-mode + grain, monospace "vibes" microtext, sticker badges.
Landing on the second isn't taste — it's a more flattering average, which is why it slips past. **Treat your first instinct as the mean and deviate deliberately — toward *this product's specific world*** (use design-thinking's domain / color-world / signature as the direction), **not toward another trend.** If the result could be any startup, you shipped the mean.
## 3. So don't prescribe a style
Any fixed rule — a 12-col grid, an 8-point scale, "mono = data" — *becomes* next cycle's mean, and a blind model executes it into collisions anyway. Prescribe the **process, not the look**: see it with fresh eyes, and push off the average toward the domain. Taste supplies the direction (design-thinking / design-philosophy); this skill only insists you **look** and **don't ship the mean**.
For iterative spatial tuning, a local page with live controls (sliders, pickers, drag handles) beats one-shot critique.
## 4. NEVER ship horizontal overflow — THE mandatory gate, no exceptions
> **BLOCKING GATE. You may not call any web UI "done", "working", "fixed", or
> "looks good" until you have run the `scrollWidth` check below at a narrow width
> THIS turn and seen `0`. Not "I added overflow-x:clip so it's fine." Not "it
> looked fine at my width." MEASURE. Narrow. Every time. If you didn't measure,
> it isn't done — say "haven't checked overflow yet" instead of claiming done.**
A side-to-side scrollbar that doesn't match the content is the **single most common
and most embarrassing** layout failure, and it ships *over and over* because the dev
viewport is wide enough to hide it — the overflow only appears once the window is
narrower than some element. It is **invisible at desktop width**, so the §1
render-critique loop will NOT catch it unless you screenshot narrow. Separate,
explicit, non-negotiable gate.
**It recurs because layouts GROW after they were last checked.** Every time you add a
nav tab, a toolbar button, a header control, a chip, a wider equation/`<pre>`, or any
new item to a `flex`/`inline` row, you have invalidated the last overflow check — the
row that fit yesterday now pushes past the edge between ~720–1200px while your 1440px
dev window shows nothing wrong. (Real ship, 2026-06, TWICE: a progress-bar edge label
overflowed 23px; then a `flex-wrap:nowrap` header that grew 4 tabs scrolled the whole
page 309px across 720–1200px — both invisible at dev width, both caught only by
measuring narrow.) **So: any change that adds an element to a horizontal row re-arms
this gate. Re-measure.**
**Default defenses to apply up front (so the gate passes by construction):**
- **Header / nav / toolbar rows: `flex-wrap: wrap`, never `nowrap`.** A growing
single-row flex is the #1 source of this bug. Wrapping is a no-op when it fits and
saves you when it doesn't.
- **`body { overflow-x: clip }`** as a backstop on every app (clip, not hidden — keeps
sticky/anchored layouts working). A backstop, NOT a substitute for measuring.
**The check — run before calling ANY page done:** `document.documentElement.scrollWidth - document.documentElement.clientWidth` must equal `0`, tested at your dev width AND resized narrow (≤1024px, and a phone width ~390px). If > 0, find the offender:
```js
document.querySelectorAll('*').forEach(el=>{const r=el.getBoundingClientRect();
if(r.right>innerWidth+1||r.left<-1) console.log(Math.round(r.right), el);});
```
**Safety net:** `overflow-x: clip` on `body` (prefer `clip` over `hidden` — it clips without creating a scroll container, so it won't break `position:sticky`/anchored layouts). But a net is not a fix — **find and kill the root cause:**
- **`position:absolute` + `white-space:nowrap` anchored at an edge** (`left:100%`, `right:0`): a *centered* nowrap label on the right edge juts past the viewport. (Real ship, 2026-06: a progress bar's "300 · learned model" milestone label at `left:100%` with `translateX(-50%)` overflowed 23px → phantom horizontal scroll at sub-1180px widths.) **Anchor edge labels inward** — right end `right:0; transform:none`, left end `left:0; transform:none`.
- **`100vw`** — includes the scrollbar width (~15px), so on any vertically-scrolling page it guarantees ~15px of horizontal overflow. Use `100%`.
- **flex / grid children without `min-width:0`** — they refuse to shrink below their content and blow out the track (a long title in a flex card, a `<pre>` in a grid cell). Add `min-width:0`.
- **long unbreakable strings** (URLs, hashes, tokens): `overflow-wrap:anywhere` or `word-break:break-word`.
- fixed pixel widths wider than the viewport; large negative margins; oversized `position:absolute` elements.
The generalization: **anything pinned to an edge or sized in viewport units is a horizontal-overflow suspect — test narrow, measure `scrollWidth`, clip the body as backstop, and anchor edge-pinned content inward.**
## 5. Lay out in TASK order — minimize transition cost
Before placing elements, **walk the user's actual step sequence for completing the
page's action**, then arrange elements in that same perceptual/view order. The
layout should read like the task: orient → work → confirm. Any mouse travel or
scrolling that serves no practical purpose is a defect.
- **Orient at top:** controls/options up top are good — they tell the user what
the page is for and what it can do before they commit to reading it.
- **Confirm where the work ENDS:** if the task is "review a long list, then act"
(approve, flag, submit, save), the action buttons must ALSO exist at the
bottom — where the user's eyes and cursor are when they finish. The original
failure: a delete-review page with confirm buttons only in the top toolbar —
after scrolling through 120 images, the user had to scroll all the way back up
to click "flag the rest." Duplicate the action bar at the bottom (or make the
toolbar sticky); both are one line of code, the scroll-back is paid per page.
- **The heuristic: save the user transit time.** Every interaction has a path:
where the eyes/cursor are when a step ends vs where the next step's control
is. Sum those distances; shrink the big ones. Fitts's law for the page as a
whole, not just one button.
- **Check it in the render-and-critique loop (§1):** ask the judge "trace the
task: where is the user when they finish each step, and how far is the next
control?" — a layout can be aligned, balanced, and still force a round trip.
## 6. Balance is measurable — don't eyeball it (or trust a VLM's eye)
§1 says render and have fresh eyes critique it. That qualitative pass catches
collisions and ragged alignment, but **a model has no reliable sense of visual
balance** — ask a VLM "is this centered / balanced?" and it confabulates a verdict.
The fix is to stop asking opinions and **measure a number**, then keep that number
honest with an *independent* check. Use both: §1's fresh-eyes critique AND the hard
number below. (This pairs a live in-browser box model + auto-balancer with an
offline pixel-oracle that re-measures the rendered screenshot — see the
`layout-audit.js` companion script in this skill.)
**The principle.** Visual balance is the *center of mass of visual weight*. It's
arithmetic, not taste — so compute it.
**Optical center, not geometric.** Target `x = 0.50`, `y ≈ 0.46` — slightly high,
because a centroid at literal 50% reads as sagging.
**Visual weight = area × ink-density, not area alone.** Same-size ≠ same-weight: a
solid-black heading is heavy; a grey/ASCII/light image reads far lighter than its
area; body text is sparse. Calibrated starting multipliers (from `asym.html`, re-tune
per project — these were hand-guesses until corrected against the pixel oracle):
```js
const DENS = {portrait:0.34, h1:0.82, kicker:0.42, lead:0.22, body:0.16, meta:0.5};
```
**Centroid.** Per axis, `centroid = Σ(wᵢ·posᵢ) / Σwᵢ`; balanced ⇔ the centroid sits
on the optical center. To FIX imbalance, think see-saw: what counts is the **moment**
= weight × distance-from-axis, so a heavy element near the edge is counterweighted by
(a) an opposing weight, (b) a bigger element on the other side, (c) pulling the heavy
element inward (shorter lever arm), or (d) shrinking it. That's exactly the
auto-balancer's escalation order in `asym.html` — grow the opposing heading first
(cheapest), then add weight, then pull the heavy element in, then shrink it (last
resort).
**Two models — and why you need the independent one:**
- **Cheap box model** (live tuning): put each element's weight at its bounding-box
*center*. Instant, fine for dragging sliders. BUT it has a systematic bug —
left-aligned text's ink sits *left* of its box, so the box model misplaces the
weight. A metric that shares the layout's own assumptions is **circular**; it once
reported "balanced" at a pixel-measured 0.93 lopsided.
- **Ground-truth pixel oracle** (`analyze.py`): rasterize the *rendered* page
(Playwright screenshot or html2canvas) and take the centroid of actual non-paper
pixels, weighting each pixel by its distance from the background color. It knows
nothing about the layout's intent — it just counts ink. **When the box model and
the pixels disagree, the pixels win.** (`asym.html` closes the loop: it regresses
the box-vs-pixel discrepancy and offers a trust dial α to blend toward the oracle.)
- **Acceptance criterion (measurable):** `|centroid_x − 0.50| < 0.03` and
`|centroid_y − 0.46| < 0.04`, plus low left/right and top/bottom imbalance
(`|w_left − w_right| / total`).
**The verification gate (lighter than §4's, same spirit).** Before calling a
balance-critical layout "balanced", do NOT assert it from the code or a VLM opinion —
screenshot the *rendered* page, compute the ink-centroid offset from optical center,
and report the actual number. This is the design-skill application of
`verify-outputs-rule`: look at the real artifact, and make the validating check
(pixels) independent of the thing you tuned (the layout). It's the quantitative
complement to §1's qualitative critique.
## 7. The layout audit — metrics that MEDIATE the eye, never replace it
§6 covers balance; this generalizes it to a full deterministic sweep, and fixes the
failure mode that matters most: **the model reads a metric/JSON and never looks at the
screenshot, so it can't apply the common sense that catches the metric being wrong.**
`scripts/layout-audit.js` is a dependency-free pass you run via Playwright MCP
`browser_evaluate` on a rendered page. It measures six things deterministically — all
geometry, color, and pixels, no "does this look right?":
| check | how (deterministic) | tier |
|---|---|---|
| **collision** | content-rect intersection ≥12% | gate |
| **contrast** | WCAG luminance ratio of text vs effective bg (<4.5, large <3) | gate |
| **tap** | interactive targets <44×44 (Apple HIG) | gate |
| **overflow** | `scrollWidth − clientWidth` (the §4 gate) | gate |
| **alignment** | left-edge clusters → near-misses 1–7px off the shared line | signal |
| **spacing** | gap CoV among a container's children | signal |
| **balance** | ink-density-weighted centroid vs optical center (§6) | signal |
**What makes it mediate rather than replace:** it doesn't just return JSON — it **draws
every finding as an SVG overlay onto the page**, so the *next* `browser_take_screenshot`
is an **annotated screenshot**. The number tells you WHERE to look; you then look and
decide. This is mandatory, not optional:
```
browser_evaluate({ function: "() => { <paste scripts/layout-audit.js> ; return __audit({}); }" })
browser_take_screenshot() // ← the overlay is now on the page. VIEW IT. Reason over it.
```
Pass `{align:'.card .title,.card .price', space:'.feature-list'}` to scope the two
selector-dependent checks; pass `{contentSelector:'…'}` for non-semantic layouts where
collision needs help finding the blocks.
**These are HEURISTICS, not laws — and they split into two kinds you must not conflate:**
- **GATES = correctness** (overflow, contrast, tap). These measure accessibility/
usability *facts*, not taste. Failing one is a real defect. Safe to **block** on.
(Collision is a near-gate: usually a real bug, but can be intentional — so eye-confirm,
don't auto-fail.)
- **SIGNALS = convention** (balance, alignment, spacing rhythm). These measure how
closely the layout matches a *symmetric, regular, gridded* aesthetic — which is exactly
the **generic mean** §2 tells you to push *away* from. **Optimizing a layout to maximize
these scores makes it blander.** An off-center balance, a deliberate misalignment, an
uneven rhythm are core creative tools and frequently the best thing on the page. Treat
signals as "worth a look," **never** as defects to fix.
**The discipline (the whole point — bias hard toward this):**
- **Never accept a metric you have not looked at.** A flag is a *pointer to look*, not a
verdict. Reading `collisions: 1` and acting without viewing the annotated shot is the
exact failure this section exists to kill.
- **Use signals to catch ACCIDENTS, never to enforce convention.** A 7px alignment drift
you didn't mean, a phantom scrollbar, a 1.9:1 caption — catch those. But the *same*
balance/alignment/spacing signal fires on deliberate asymmetry, intentional overlap,
and expressive rhythm. **When the metric and the interesting choice conflict, the
interesting choice usually wins.** Do not "fix" a signal toward symmetry/evenness unless
the eye judges the deviation actually worse. A model that maximizes these scores designs
the mean.
- **Overrule flags the eye judges intentional.** Brutalist headline overlap, avatar on a
banner, asymmetric hero — the metric flags them; common sense overrules. Proven live in
the worked example: obeying the collision check on the brutalist mock removes the overlap
and the design goes *flat*.
- **Gates are necessary, not sufficient.** `gates_pass:true` (overflow/contrast/tap all 0)
clears the deterministic floor — it does **not** mean the layout is good. A bland centered
template passes every gate and is still the mean. After gates pass, the real judgment (§1
fresh-eyes critique, taste, brand fit) still has to happen.
**The proof, made concrete:** build a page that runs all six algorithms live on a few
realistic mock sites in different styles, each with a toggle between the layout **as
designed** and the version **obeying the metric**, plus on-render overlays. It shows both
halves: obeying a *gate* fixes a real bug (low-contrast CTA, sub-44 tap target, overlapping
cards), while obeying a *signal* makes it worse (an asymmetric editorial hero is the more
interesting layout; "correcting" a deliberate brutalist overlap flattens it). That explorable
is where `layout-audit.js` was distilled from.
## 8. Optical craft — perception beats geometry
The audit's alignment check (§7) measures *geometric* edges. The eye doesn't read geometry,
it reads perception — so a few cases need a manual nudge the metric can't make. These are
eye-judgments, not gates. (From the Web Interface Guidelines, `vercel-labs/web-interface-guidelines` @ `4e799d4`.)
- **Optical alignment — nudge ±1–2px when it *looks* off though it measures centered.** A
play-triangle in a round button must shift right of geometric center to look centered (its
visual mass is left-biased). Glyphs, arrows, and asymmetric icons often need the same. Text
vertically centered by box metrics frequently sits a hair low — lift it. Geometry is the
starting point; the eye is the judge.
- **Balance icon/text lockups.** When an icon sits beside text, match their *visual weight* —
adjust the icon's stroke, size, spacing, or color so neither overpowers. A thin-stroke icon
next to medium-weight text looks weak; thicken its stroke (or size it up slightly) so they
read as one lockup. Optical size, not equal pixel size, is the target.
- This is the same principle as the §6/§7 debias: the number gets you close; the eye makes the
final 1px call. Don't let a geometric alignment metric *prevent* an optical correction.