Ui Design Craft

---
name: ui-design-craft
description: Static visual judgment for generated or restyled UI. Load when you are about to produce or modify any user-facing surface - a landing/marketing page, product screen, mockup, or component styling - when a brief says "make it look good/premium/modern" with no design system attached, or when you notice generated UI converging on default AI aesthetics. NOT for motion decisions (motion-craft), for running a measured design review (design-review-gate), for charts (the environment's dataviz tooling), or for native mobile idiom questions (Apple HIG / Material directly).
---

# UI Design Craft

AI-generated UI fails in a recognizable direction: it optimizes for the safe
average. The counter is not taste words - it is bans with exact signatures,
budgets with numbers, and a mechanical gate. One meta-rule governs the whole
file, learned from production tests upstream: **"use sparingly" does not
transfer to a generating model; binary phrasing and countable caps do.**

## Corpus-derived semantic references (authoritative)

This skill is bridged to the Phase-B design corpus — the pack's canonical design
semantics. The machine-checked rules for the domains this skill produces are
skill-local supporting files under `references/generated/`. **Where a rule below
overlaps one of these shards, the generated shard is the authoritative semantic
source**; this file's prose is task framing, review orchestration, and
explicitly-labelled pack-local extensions, never a competing rule authority.

Load a supporting file only when the task needs it — they stay out of context
until then; do not load them all at once:

- layout / structure / hero / sections → [struct rules](references/generated/struct.md)
- type scale / hierarchy → [typography rules](references/generated/typo.md)
- color / contrast / palette → [color rules](references/generated/color.md)
- spacing / density → [space rules](references/generated/space.md)
- AI-slop bans → [anti-slop rules](references/generated/antislop.md)
- interaction / states / touch targets → [interaction rules](references/generated/interact.md)
- accessibility → [accessibility rules](references/generated/a11y.md)
- flows / UX routing → [ux rules](references/generated/ux.md)
- when a rule is selector- or dial-gated → also load [controls](references/generated/controls.md)

Authority order: **canonical corpus (these shards) > pack-local extensions (this
file's numeric budgets, ban signatures, and preservation rules) > orchestration
prose.** A pack-local extension may add or tighten, never weaken / reverse /
broaden a corpus rule. The extension registry and per-statement classification are
`design-pack/generated/local-extensions.json` and
`design-pack/normative-classification.json`. Generated shards are never
hand-edited — edit the canonical corpus and regenerate with
`design-pack/tools/project_corpus.py`.

## 0. Classify the surface before generating anything

First action, before any code or mockup:

- **MARKETING** (landing, portfolio, about, pricing): all sections below
  apply, §2 layout budgets included.
- **APP UI** (dashboard, admin, dense product screens - including the
  chrome AROUND embedded tables and editors): route the visual system to
  an established design system (Material, Fluent, Carbon, Polaris, or the
  project's own); from this file everything EXCEPT §2 applies - the §1
  bans, §3 discipline, §4 states, §5 floors, §6 preservation on restyles,
  and §7's gate minus its MARKETING group. The §2 marketing budgets do
  NOT apply - a dashboard is allowed to be dense and repetitive.
- **HYBRID** (product site with embedded app screens): classify each section.
- Out of scope entirely - say so and route: the INTERNALS of data-grid
  and code-editor widgets (TanStack/AG Grid, Monaco/CodeMirror - theme
  them through their official APIs; the app chrome around them stays in
  scope above), native mobile idiom (HIG/Material), realtime collaboration
  surfaces.
- If the project has a governing design contract (DESIGN.md, tokens file,
  brand guide), it outranks every default in this file - verify and consume
  it per `design-review-gate` ("the design contract"); the bans below still
  apply to whatever the contract leaves open.

## 1. The ban list (AI tells, with signatures)

Hard bans by default; a ban yields only to an explicit brand fact or brief
requirement, stated in writing ("the brand IS purple" unlocks purple - the
override is the recorded reason, never silent).

**Color tells**
- Default indigo/violet accent: `#6366f1 #4f46e5 #8b5cf6 #7c3aed` and their
  Tailwind neighbors. The single most reliable AI fingerprint.
- The "premium consumer" beige+brass+espresso family applied to every
  luxury/artisan/wellness brief; same for olive/clay/terracotta earth tones
  as an unresearched default.
- Evenly distributed color with no accent hierarchy; semantic colors
  (error/success) reused decoratively.

**Typography tells**
- Fraunces or Instrument Serif as unjustified display defaults (the two
  LLM-favorite serifs); any serif repeated from your previous project.
- The decorative one-word swap: one headline word italicized, serif-ed, or
  color-shifted purely to feel "designed". Distinction comes from layout,
  scale, weight, or media - not a costume on one word.
- Em-dash in generated page copy: **zero**, everywhere on the page -
  headlines, body, captions, buttons, alt text. Upstream production tests
  found models ignore "limit em-dashes"; only the binary form holds. Use a
  hyphen or restructure. (Scope: copy on generated surfaces - not code, not
  prose documents.)
- ALL-CAPS or small labels without letter-spacing; italic descenders clipped
  by tight line-height (leading below ~1.1 with no padding).

**Container tells**
- Cards as the default grouping: if removing border+shadow+background+radius
  hurts nothing, it was never a card - use sections, columns, dividers.
- Decorative left accent stripe (`border-left: 4px solid <accent>`): stripes
  carry meaning (status, priority, selection) or they go.
- The 3-column icon-in-colored-circle feature grid, repeated symmetrically -
  the single most recognizable signature of generated marketing pages.
- "Split header" (huge left headline + small floating right paragraph) as a
  section-header default; stack vertically instead, max-width ~65ch.
- Hairline borders above AND below every row of a list or spec table.
- Standard emoji standing in for icons: use an icon set or a plain
  Unicode glyph (an arrow, a bullet, a diamond) - emoji as UI iconography
  reads as unfinished work.

**Label and meta tells**
- Eyebrow labels (small caps tracking-wide strings above headlines) above
  every section. Cap: **at most 1 eyebrow per 3 sections, hero included** -
  the check is a count, see §7.
- Section numbering (`001 · Capabilities`), version stamps in heroes or
  footers (`v0.6`, `BETA`, `Build 0048`), pagination on tiles (`01 / 4`).
- Locale/weather/time strips ("LIS 14:23 · 18°C"), scroll cues ("Scroll to
  explore"), decorative status dots, poetic section labels ("From the
  field", "Quietly trusted by"), generic step labels ("Step 1 / Step 2" -
  the verb is the label: "Install", "Configure", "Ship").
- Middle-dot separator chains ("foo · bar · baz · qux") - max one `·` per
  metadata line.

**Fake-content tells**
- Div-built fake product UI in the hero (fake terminal, fake dashboard of
  styled divs) - use a real screenshot, a real component, or nothing.
- Placeholder people ("Jane Doe", "John Smith"), invented testimonials,
  fake logos, fake metrics. Absent real content, design the empty state.
- Image-led direction collapsed to text-only because no image was handy:
  preserve the media slot with honest dimensions and an art-direction note
  instead of faking imagery with CSS blobs.

**Mode tells**
- Dark mode as an unrequested default: light is the baseline unless the
  brief says otherwise (dark is a brand decision, not a vibe).
- "Calm editorial" autopilot (cream canvas + oversized serif + airy spacing)
  on products that need utility or proof. Before using it, write down why
  THIS product earns an editorial voice; no written reason, no serif system.

## 2. Layout budgets (MARKETING surfaces)

- **Hero:** headline max 2 lines desktop; subtext max 20 words; at most 4
  text elements total (one eyebrow-or-brand-strip, headline, subtext, CTA
  row of 1 primary + max 1 secondary); CTAs visible without scrolling; top
  padding capped ~6rem. Trust logos, pricing teasers, and feature bullets
  live in sections BELOW the hero, never inside it. If the value
  proposition does not fit in 20 words, the proposition is unclear - fix
  that, not the rule.
- **Headline scale is planned with the asset:** 3-5 word headlines may take
  the largest scale; 6+ words step down one or two sizes. A hero headline
  wrapping to 4 lines is a font-size error, not a copy problem.
- **Navigation:** single line at desktop, height max 80px (default 64-72px).
  A two-line desktop nav is broken, not cozy.
- **Section rhythm:** a layout family (3-col cards, full-width quote,
  text+image split...) appears at most once per page - which itself
  forces variety, no separate diversity quota needed; max 2 consecutive
  alternating image/text "zigzag" sections - the third consecutive is a
  gate failure.
- **Bento grids:** exactly as many cells as there is content (3 items = a
  1+2 or 2+1 composition, never a blank filler tile), and at least 2-3
  cells carry real visual variation (image, tinted background, pattern) -
  not six white-on-white text tiles.
- **Mobile collapse is declared per section** in the same component; "the
  framework will handle it" is not a declaration.

## 3. Type and color discipline

- Hierarchy has 3-4 distinct levels, differentiated by weight and spacing,
  not size alone.
- **Accent budget: at most 2 visible accent uses per screen.** Spend them
  deliberately - a highlighted label plus the primary action is the usual
  allocation. Links draw from the same budget; once it is spent, style
  them as underlined foreground text instead.
- One lock each per page: ONE theme (no section flipping to inverted
  mid-page), ONE accent applied identically, ONE corner-radius system.
- Contrast floors (WCAG AA): text needs 4.5:1 at normal size and 3:1 only
  at large size (large = at least 24px, or 18.66px bold) - placeholder
  text and text over images or scrims
  included, with no exemption for either; non-text UI needs 3:1 where
  the visual carries identification or state (WCAG 1.4.11's scope -
  inactive controls and unmodified browser defaults are exempt, and a
  decorative boundary not needed to identify the control is too; this
  pack treats focus and state indicators as always in scope, a
  deliberately stricter pack floor); secondary BODY-size text needs
  4.5:1 in both color modes - dark-mode secondary text is where this
  fails silently.
- Micro text is whitelisted, not vibes-based: the smallest size (11px and
  below) appears only in an enumerated role list you can state (timestamps,
  badge pills, axis labels...) - any other use upgrades a size.

## 4. State coverage - the most reliable generated-UI failure

_Change notice (Apache-2.0 section 4(b)): the five-state table in this section
is adapted from `nexu-io/open-design` (`craft/state-coverage.md`, Apache-2.0)
and was modified for Design Pack. License text: `LICENSE-APACHE-2.0`; notices:
`THIRD_PARTY_NOTICES.md` (both at the plugin root, `design-pack/`)._

Shipping only the populated state IS the failure mode. Every surface that
fetches, accepts, or transforms data renders five states before it is done:

| State | Must contain |
|---|---|
| Loading | skeleton/spinner plus a "taking longer than expected" fallback after ~10-15s |
| Empty | headline, plain explanation, primary CTA - designed, not blank |
| Error | plain-language cause, recovery action, user input preserved |
| Populated | the case you actually designed |
| Edge | extreme volume, long unbroken strings, missing optional fields |

Edge matrix to actually try: 10,000-row table with sort+filter; 200-char
title with no spaces; missing avatar/optional field; 0 results after a
filter; offline mid-submit. Render each and look - reading the code is not
rendering.

## 5. Platform floors (APP and touch surfaces)

- Touch targets: 44x44pt (iOS) / 48x48dp (Android) minimum - the vendors'
  published guidance (Apple phrases it as a rule, Android as a
  recommendation), adopted here as hard pack floors. Audits measure CSS px
  (~= pt/dp at 1x) and apply to touch-capable surfaces; a
  desktop-pointer-only UI may go smaller with the reason recorded.
- Modal scrims visibly isolate the foreground: content behind reads as
  inert, and any text sitting over the scrim still meets the §3 floors.
  Vendor anchor: Material defines scrim as a color ROLE, commonly
  rendered at a 32%-black component default (Compose drawers, container
  transform) - start there; heavier is a legitimate brand choice, while
  a missing or near-invisible scrim is a defect.
- Press/hover states never shift layout (no border-width or size jumps -
  swap colors/elevation instead).
- Every SUPPORTED color mode rendered and looked at before done, with
  every applicable §4 state checked in each. A single-mode product passes
  as single-mode - supporting dark is a product decision, and §1's tell
  is about DEFAULTING to dark unasked, not about supporting it. Dark-mode
  regressions hide in secondary text and disabled states.

## 6. Restyling an existing surface: preservation rules

A redesign is a visual change, not a silent content or interface change.
Never modify without explicit approval: URL slugs and anchor IDs, primary
nav labels, form field names and order (autofill + analytics depend on
them), the logo/wordmark, legal and consent copy. Extract existing brand
colors FIRST - a purple brand stays purple, overriding §1's indigo ban.
Never regress accessibility already present (focus states, alt text,
keyboard paths, contrast). These names are interfaces with hidden consumers
- operational-rigor's call-site sweep applies to them, verbatim: "Interfaces
include observable output text and names." (canonical copy in
operational-rigor §3; on disagreement that file wins).

## 7. The pre-flight gate (mechanical)

Run before delivering the surface. Every box, honestly; **if a single box
cannot be honestly ticked, the surface is not done.** Counts are counted,
not estimated. Boxes group by §0's surface class - an APP UI surface skips
the MARKETING group because §0 scoped those budgets out, not as an escape
hatch.

All surfaces:

- [ ] Surface classified (§0) and, for APP UI, a design system named?
- [ ] Zero em-dashes in page copy (search the output for the character)?
- [ ] Accent count per screen <= 2, and accent is none of the §1 hexes -
      or the §1 brand override is quoted in writing? Check the COMPUTED
      color (getComputedStyle), not only a hex grep - rgb()/hsl()
      spellings evade a literal search.
- [ ] One theme lock, one accent lock, one radius system?
- [ ] WCAG AA floors pass for text, CTAs, forms, placeholders, focus rings?
- [ ] §4 states: all five rendered and looked at on every surface that
      fetches, accepts, or transforms data; purely static surfaces get an
      explicit N/A (say so, don't skip silently)?
- [ ] No banned tell present without a written brand/brief override?
- [ ] Restyle only: §6 preservation list untouched or approval quoted?

MARKETING surfaces (and the marketing sections of a HYBRID):

- [ ] Eyebrow count <= ceil(sections / 3) (count uppercase-tracking labels)?
- [ ] Layout-family repetition within budget; zigzag run <= 2?
- [ ] Hero: <= 2-line headline, <= 20-word subtext, <= 4 text elements,
      CTA above the fold?

APP UI surfaces:

- [ ] Touch targets and scrim floors met (§5)?

Litmus checks when a box feels arguable:
- **Card test:** remove border/shadow/background - if nothing breaks, it
  was not a card.
- **Identity test:** hide the logo - if the first viewport could belong to
  any company, the design is not done.
- **Editorial test:** swap the logo for a boutique hotel's - if the hero
  still reads plausible, you built generic calm-editorial, not this brand.

## When NOT to use this skill

- Motion decisions (durations, easing, springs) -> `motion-craft`.
- Running a measured review with a fix loop -> `design-review-gate`; its
  static pass applies this file's gate.
- Charts and data visualization -> the environment's dataviz tooling.
- Native mobile idiom -> Apple HIG / Material directly.
- Brand identity creation (naming, logo) - out of scope for this pack.

## Provenance

Composed 2026-07-19 for design-pack 0.1.0. The ban corpus and layout budgets
are curated - deliberately not imported wholesale - from three MIT sources
verified in their repos at composition time: Leonxlnx/taste-skill (layout
hard rules incl. hero/nav/zigzag/bento/eyebrow caps and their mechanical
counts, the production-test tell corpus, the em-dash binary and its
"use sparingly fails" lesson, preservation rules, the pre-flight
if-one-box-fails framing; its full §9-10 corpus remains the deeper upstream
reference), referodesign/refero_skill (indigo/cards/dark-default/calm-
editorial/emoji/stripe tells, litmus tests, media-slot preservation), and
Emil Kowalski's skills (context; his marketing directives stripped).
From Apache-2.0 nexu-io/open-design: the accent-budget number and
tiered-ban severity as ideas, and §4's five-state table as ADAPTED
EXPRESSION carried under Apache-2.0 (notice in THIRD-PARTY-NOTICES) -
not an ideas-only borrow. Ideas without text from MIT garrytan/gstack
(surface classifier, icon-circle-grid tell - independently listed by
taste-skill) and MIT creativetimofficial/ui (micro-text whitelist
technique). WCAG/HIG/Material
floors are vendor facts - re-verify on major vendor releases; hex lists and
font-fashion bans are the fastest-decaying facts here (they track model
training data - revisit each model generation). Probe status: probe-tested
2026-07-19 on a private planted-slop fixture (fresh weak-tier agent, n=1
per arm, smoke grade): the bare arm found 0 of 7 planted tells - returning
CSS-engineering nits instead - while the ruled arm found 6 of 7 with rule
citations plus budget catches beyond the plants; it missed the em-dash
tell, recorded as the arm's one gap (rule retained - one miss is not yet a
wrong rule, skill-authoring §7). A round-0 run was voided for a leaked
in-fixture answer key, caught by the expected-before-actual discrepancy
rather than the score. Trail in the design-pack PR.