Ui Design Craft

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.

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 ): 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

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 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: F-e-u-e-r
• Source: F-e-u-e-r/opus-pack
• License: MIT

Install and usage instructions live in the source repository linked above.