Frontend Design Deslop

frontend design deslop

AI-generated UI looks generic for two reasons. First, with no constraints the model samples the statistical median of 2019-2024 web code, which is Tailwind UI's bg-indigo-500, Inter, rounded cards, and soft shadows. You cannot out-prompt a vacuum. Second, and deeper: designing before you know what you are designing. A corporate landing page, a creative portfolio, a developer-tool landing page, an analytics dashboard, and an ecommerce product page share almost no design DNA. A beautiful aesthetic that fights the artifact's job is its own slop.

The fix is a discipline borrowed from brand design: strategy drives design. Commit to words first (what this is, who it serves, the adjectives it must feel like), then translate those words into a typography and color system, then build from tokens, then apply the craft layer (layout, components, motion, iconography, imagery, dark mode, accessibility), then audit. Never pick aesthetics first. Target the convergence mechanism, not a frozen blocklist; the slop fingerprint shifts over time (purple gradients in 2022, cream backgrounds and italic-serif heroes in 2026).

This skill does two jobs at once: it de-slops the default AI look, and it designs applications well. A distinctive theme on top of careless components, weak layout, or thoughtless motion still reads as amateur. The mechanisms behind every choice live in references/design-theory.md (hierarchy, Gestalt, CRAP, signal-vs-noise, affordances, the interaction laws); read it once so the rest is reasoning rather than rule-following.

Asking questions (CRITICAL)

ALWAYS use the AskUserQuestion tool for ANY question to the user. Never ask questions as plain text output. The tool gives a guided, interactive experience with structured options that the user can answer in one tap. Every single user question must go through this tool. (On claude.ai the equivalent tool is ask_user_input_v0; use whichever structured question tool the environment provides.)

Discipline on top of that rule: batch related questions, offer 2 to 4 concrete options each, and ask only the high-signal subset that changes the design system. Infer from context first and confirm inferences rather than re-asking. The bank is generous; the asking is selective. Do not interrogate.

Phase 0: Discover and commit to words (do this FIRST, before any code)

First, check for an existing DESIGN.md at the project root (and common locations like docs/). If one exists, read it, honor its tokens, skip the questions it already answers, and extend it rather than starting over. If none exists, resolve three things before any pixel. Read references/discovery.md for the full protocol, question bank, and the personality-to-token translation table, and references/artifact-types.md for per-type priorities.

1. WHAT is the artifact? Classify it: marketing/landing page, pricing page, SaaS application, dashboard/data tool, ecommerce, marketplace, mobile app, AI/conversational interface, email/newsletter, blog/editorial publication, onboarding/auth flow, settings/admin/CMS, presentation/deck, docs/API reference, portfolio/brand site, or one of the long-tail types in references/artifact-types.md. Each optimizes for a different thing and has its own layout grammar and density. A composite artifact (a marketing site with an embedded app, an AI chat inside a SaaS app) is designed region by region. 2. WHO and WHY? Audience, positioning (corporate vs creative vs technical vs luxury vs playful), and the single primary action or outcome. 3. Commit to words. Lock 3 to 5 brand adjectives and a 3-word aesthetic essence before any visual exploration. This is the highest-leverage input; it drives type, color, density, radius, and motion. Strategy drives design, never the reverse.

Run discovery adaptively: infer, state inferences, ask the high-signal subset through the question tool, and ground the direction in 1 to 3 references (web-search strong current examples of the exact artifact type and positioning if none are given, then transpose rather than originate). Do not proceed until artifact type, positioning, and the adjectives are locked.

Phase 1: Translate strategy into a design system (the gate)

State these commitments in prose, briefly. Each must follow from Phase 0, not from reflex.

1. Aesthetic commitment. Pick ONE opinionated direction that fits the artifact and the adjectives; generic is the failure mode. See references/aesthetics-library.md. If the user gave a brand or reference, transpose it.

2. Typography (brand-first). Choose type from personality, not aesthetic preference. Match classification to the adjectives, pick a modular-scale ratio that fits the content, and pair for contrast (display + body) without typographic mud. Never Inter/Roboto/Arial/system as the primary face. See references/typography.md.

3. Color (appropriateness + differentiation). Choose colors for fit with the brand and audience, then find uncontested territory (the indigo/violet band is the red ocean of AI UI; avoid it unless the brief demands it). Build one dominant plus a sharp accent plus neutrals plus semantic states, distributed roughly 60-30-10. Author in OKLCH. See references/color-oklch.md.

4. Token table (emit BEFORE components). Display + body font; type scale (state the ratio and base, 6 steps); spacing base unit; max two radius values; ONE shadow approach (defined edge OR soft elevation, never both on one element); palette with roles (bg, fg, muted, border, accent, accent-fg, success, warning, error). Everything references tokens; no scattered hex/px. Pull a starting set from references/token-sets.md.

5. Signature move. Name the single thing that makes this UI memorable and unmistakably not-default. One per project.

6. Adapter. Pick the stack syntax: plain CSS custom properties, Tailwind v4 @theme, or shadcn semantic tokens. See references/adapters.md. references/token-core.css is the portable source of truth.

Phase 2: Apply the system to the interface (the craft layer)

Tokens make a UI consistent; the craft layer makes it good. This is the "design an application" half of the skill and the half most AI output skips. Apply each of the following to the artifact, pulling the matching reference on demand. Density and emphasis vary by artifact type (see references/artifact-types.md); a dashboard applies these very differently from a landing page.

1. Layout and composition. Compose space with intent: a base spacing unit, spacing that is tight within groups and generous between sections, an intentional grid (12-column, modular, or bento where content genuinely varies), at least one brief-specific layout move, and whitespace as a signal of confidence. Break the centered-max-width-column reflex. See references/layout.md.

2. Components and states. Specify every interactive component across its full state matrix (default, hover, active, focus, disabled, loading, error, selected), not just at rest. Get buttons (ranked by importance, not colored by meaning), forms (real labels, correct types, inline validation that keeps input), tables (left-align text, right-align tabular-nums numerals, light separators), navigation, overlays, and the empty/loading/error states right. See references/components.md.

3. Motion. Treat motion as communication, under a duration and easing token scale. Default to ease-out under 300ms, animate only transform and opacity, scale popovers from their trigger, and never animate high-frequency actions. See references/motion.md.

4. Iconography. One grid, one stroke, one radius across the set; do not let the unmodified default starter-kit set define the look. See references/iconography.md.

5. Imagery and illustration. Art-direct imagery as a system. Prefer real product visuals over stock and abstract; avoid the AI/stock fingerprint (people pointing at laptops, gradient blobs, corporate-Memphis, default Midjourney). Use texture and a graphic device to escape flat-slop. See references/imagery.md.

6. Dark mode and theming. If dark mode is in scope, design it (do not invert): near-black not pure black, off-white not pure white, elevation via lightness, desaturated accents, all driven by semantic tokens. See references/dark-mode.md.

7. Accessibility as you build. WCAG 2.2 AA: visible managed focus, keyboard operability, labels, 24px-plus targets, color independence, reduced-motion. Build it in; do not bolt it on. See references/accessibility.md.

At the end of conception, once the direction and craft decisions are locked, suggest to the user a relevant subset of design and component catalogs to mine for concrete ideas and ready implementations, framed as inspiration to transpose through the committed system (never to clone) and with a reminder to verify component licenses. Pick by artifact type and stage rather than dumping the whole list. See references/catalogs.md.

Phase 3: Write DESIGN.md (the durable output)

Everything this skill produces lives in a single DESIGN.md at the project root: the discovery context, the committed aesthetic and signature move, the typography and color systems, the tokens, the spacing/radius/shadow rules, the craft-layer decisions (layout, components, motion, iconography, imagery, dark mode, accessibility), and the slop-audit result. Write or update it before or alongside building components, using the schema in references/design-md.md. DESIGN.md is the single source of truth; the CSS, the adapter, and the components are projections of it. If they ever drift, DESIGN.md wins. On later sessions, Phase 0 reads this file instead of re-running discovery.

Token-first generation rules

• Colors in OKLCH, dominant + sharp accent, not a timid even spread. Design hierarchy in grayscale first, add the accent last and sparingly, roughly 60-30-10 (neutral / brand / accent). On colored backgrounds, darken/desaturate the same hue rather than going gray. Define semantic state colors (success, warning, error) and never use color as the only signal.
• Typography: a distinctive display face paired with a refined body face, modular scale with a stated ratio. Source from Fontshare/Google. Limit to 2 to 3 families.
• Spacing rhythm: vary spacing by relationship (tight within a group, generous between sections). One uniform value everywhere is a tell.
• Density fits the artifact. Dashboards and pro tools tolerate high density; marketing and portfolio pages want air.
• Match implementation complexity to the aesthetic: maximalism gets elaborate detail; minimalism gets restraint and precision, not laziness.

NEVER (negative prompt)

NEVER use generic AI-generated aesthetics: overused fonts (Inter, Roboto, Arial, system-ui as the primary face); cliched color schemes (especially purple/indigo/violet gradients on white or dark); the hero + 3-feature-cards + testimonials + CTA boilerplate as the only structure; the icon-tile-above-heading feature-card template; side-tab accent borders on cards; hairline border and diffuse drop shadow stacked on the same element; gradient text on headings or metrics; decorative glassmorphism; blob-rounding (radius > 16px on small cards); cream/beige backgrounds by reflex; bounce/elastic easing and animate-everything micro-interactions. Use distinctive fonts, a cohesive committed palette, and motion only where it serves the interaction.

Craft-layer NEVERs: do not ship components with only a resting state; do not use placeholder text as the label; do not color buttons by meaning instead of ranking them by importance; do not center-align numeric table columns or use non-tabular numerals for figures; do not let the unmodified shadcn/Tailwind default icon set define the look; do not use stock people-pointing-at-laptops, gradient blobs, floating orbs, glossy isometric tech illustrations, corporate-Memphis figures, or raw default-Midjourney imagery where a real product visual belongs; do not invert a light palette to make dark mode, use pure black backgrounds, pure white text, or glowing colored box-shadows by reflex; do not animate layout properties (width/height/top/left) or ignore prefers-reduced-motion; do not remove focus outlines without replacing them, convey meaning by color alone, or ship sub-24px targets.

Self-audit before finishing

Run the generated UI against references/slop-checklist.md and score it. Verify it serves the artifact type's priorities from references/artifact-types.md (a dashboard that reads as a portfolio piece, or a landing page with no clear primary action, has failed even if it is beautiful), and that the type and color choices match the committed adjectives. Verify the craft layer: components have full state matrices, layout has rhythm and an intentional move, motion is communicative and respects reduced-motion, icons are one coherent system, imagery is not stock/AI slop, and dark mode (if present) is designed not inverted. Run the accessibility gate in references/accessibility.md (focus, keyboard, contrast, targets, color independence); accessibility is a pass/fail gate, not a nicety. If any tell fires or the fit is wrong, regenerate that section before presenting. Record the result in the DESIGN.md slop-audit section and bump its changelog. State the artifact type, positioning, adjectives, aesthetic, type system, palette, and signature move used. All checklist items are detectable within a single generation; do not invent cross-generation rules the model cannot verify.

Reference files

Load on demand.

Foundation and intake:

• references/design-theory.md - the mechanisms behind every choice: hierarchy, Gestalt, CRAP, signal-vs-noise, affordances, interaction laws. Read once early.
• references/discovery.md - design intake: AskUserQuestion protocol, commit-to-words, question bank, personality-to-token translation table. Read at the start of Phase 0.
• references/design-md.md - the DESIGN.md schema and persistence conventions. The durable output of the whole skill. Read in Phase 0 (to consume an existing file) and Phase 3 (to write one).
• references/artifact-types.md - artifact taxonomy with per-type priorities, layout grammar, density, positioning variants, anti-patterns. Read at the start of Phase 0.

System (Phase 1):

• references/typography.md - full type strategy: brand-first selection, classification matrix, modular scale ratios, pairing, variable fonts, accessibility, anti-slop sourcing and ban-list.
• references/color-oklch.md - full color strategy: appropriateness, Blue Ocean differentiation, harmony systems, 60-30-10, archetype map, OKLCH primer, Radix roles, accessibility.
• references/aesthetics-library.md - encoded style families with defining traits, plus the method for originating a bespoke theme from discovery.
• references/token-sets.md - ready-to-use distinctive palettes, each with a signature move, plus shared motion tokens.
• references/token-core.css - the framework-agnostic OKLCH token core, including motion tokens.
• references/adapters.md - Tailwind v4 / shadcn / plain-CSS token syntax.

Craft (Phase 2):

• references/layout.md - spacing rhythm, grids (12-col, bento), asymmetry, whitespace, scanning, density, responsive, layout inspiration.
• references/components.md - the state matrix and patterns for buttons, forms, tables, navigation, overlays, feedback, empty/loading/error states, plus component inspiration.
• references/motion.md - duration and easing scales, springs, transform-origin, performance, reduced motion, motion tokens and inspiration.
• references/iconography.md - grid, stroke, radius, optical balance, when defaults become slop, how to differentiate, icon inspiration.
• references/imagery.md - art direction, photography direction, the AI/stock fingerprint, illustration systems, graphic devices and texture, imagery inspiration.
• references/dark-mode.md - dark mode as a designed mode (not inversion), elevation via lightness, desaturation, semantic-token theming, dark/theme tokens.
• references/accessibility.md - unified WCAG 2.2 AA: contrast, focus, keyboard, target size, forms, ARIA basics, motion, testing.
• references/catalogs.md - component catalogs (shadcn/ui, 21st.dev, Magic UI, Aceternity, Origin, Cult, Kibo, shadcnblocks) and inspiration galleries (Awwwards, Behance, Dribbble, Mobbin, Land-book, Page Collective, Godly, SaaS Landing Page, Lapa Ninja, Refero, Screenlane), with transposition and licensing cautions. Suggest a relevant subset at the end of conception.

Audit:

• references/slop-checklist.md - the self-audit (tell catalog + quality gates). Read before finishing any UI.

Accessibility

Accessibility is a build-time discipline, not an audit you bolt on at the end. It also overlaps almost entirely with good design: clear hierarchy, sufficient contrast, visible focus, sane keyboard order, and meaningful feedback help everyone. This file consolidates the practical, implementation-level requirements that are otherwise scattered across the type and color references. The bar is WCAG 2.2 AA. Automated tools catch only a fraction of real issues, so manual keyboard and screen-reader testing is required regardless of any scan result.

Contents

1. Contrast and color independence 2. Focus: visible and managed 3. Keyboard navigation 4. Target size and pointer 5. Forms accessibility 6. Names, roles, and ARIA basics for common components 7. Motion 8. WCAG 2.2 AA: the criteria that bite UI 9. Testing 10. Accessibility slop tells

1. Contrast and color independence

Text contrast: 4.5:1 for normal text, 3:1 for large text (about 24px, or about 18.66px bold). AAA is 7:1 and 4.5:1. Non-text UI (icons, control boundaries, focus indicators, chart elements that convey meaning) needs 3:1 against adjacent colors (1.4.11). Never convey information by color alone (1.4.1): pair status color with an icon, label, or shape, and verify the whole UI still reads in grayscale (this also proves hierarchy does not depend on hue). For data, provide the underlying numbers in an accessible table alongside any color-coded chart.

2. Focus: visible and managed

Every interactive element needs a clearly visible keyboard focus state. Use box-shadow for the ring, not outline, so it follows border-radius. WCAG 2.2 adds two focus criteria: the focus indicator must not be entirely hidden by sticky headers, footers, or banners (2.4.11 Focus Not Obscured), and the indicator itself must be substantial enough, at least the area of a 2px-thick perimeter around the element and at least 3:1 contrast between the focused and unfocused states (2.4.13 Focus Appearance). Manage focus across interactions: when a modal or dialog opens, move focus into it and trap it; when it closes, return focus to the trigger; never leave focus stranded on a removed element. Do not remove focus outlines without replacing them with something at least as visible.

3. Keyboard navigation

Everything operable by mouse must be operable by keyboard, in a logical order that matches the visual order. Composite widgets follow expected key patterns: menus and listboxes navigate with arrow keys (not Tab between every item), Escape closes overlays, Enter and Space activate, and editable lists support a delete shortcut. Do not put non-interactive elements in the tab order, and do not skip interactive ones. Custom controls (a div acting as a button) must add the role, tabindex, and key handlers a native element would have given for free; prefer native elements (button, a, input) precisely because they bring keyboard support and semantics already.

4. Target size and pointer

Interactive targets must be at least 24 by 24 CSS pixels, or have enough spacing that a 24px-diameter circle centered on each does not overlap its neighbors (2.5.8 Target Size Minimum). Padding counts toward the size. The AAA target is 44 by 44 (2.5.5), which is also the comfortable touch standard, so meeting 44px satisfies both. Any interaction driven by a dragging movement must have a single-pointer, non-drag alternative (2.5.7 Dragging Movements): drag-to-reorder needs move-up/move-down controls, a pannable map needs buttons, a draggable carousel needs arrows.

5. Forms accessibility

Every input has a programmatically associated visible label (not placeholder-as-label); clicking the label focuses the input. Group related fields (fieldset and legend, or an accessible grouping). Errors are conveyed in text, associated with the field, and announced; do not rely on red border alone. Keep the user's input on error and explain how to fix it. Use correct input types and autocomplete tokens so assistive tech and password managers work. WCAG 2.2 adds 3.3.8 Accessible Authentication: do not require a cognitive test (transcribing, solving a puzzle, retyping) to log in; allow paste and password managers. Also 3.3.7 Redundant Entry: do not make users re-enter information they already provided in the same flow.

6. Names, roles, and ARIA basics for common components

The first rule of ARIA is to prefer native HTML, which carries role and behavior for free. When you must add ARIA: icon-only buttons need an accessible name (aria-label); an HTML illustration or icon that conveys meaning needs a label, and a purely decorative one is hidden with aria-hidden. Common patterns: a modal uses role="dialog", aria-modal="true", and a labelled title; a toggle uses a native checkbox or role="switch" with aria-checked; a tab set uses role="tablist"/tab/tabpanel with aria-selected and arrow-key navigation; a disclosure uses aria-expanded. Live regions (aria-live="polite") announce async feedback like toasts and validation summaries. Do not put interactive content inside a hover-triggered tooltip, and do not give disabled buttons tooltips (they are out of the tab order and never announced; surface the reason elsewhere).

7. Motion

Honor prefers-reduced-motion (see motion.md). Large movement, parallax, and scaling can cause vestibular discomfort; opacity fades are generally safe. The robust approach enables motion only under (prefers-reduced-motion: no-preference) or swaps motion for a fade when reduction is requested, rather than a blunt global zeroing. Avoid content that flashes more than three times per second (2.3.1). Do not auto-play motion or carousels without a pause control.

8. WCAG 2.2 AA: the criteria that bite UI

WCAG 2.2 (2023, also published as ISO/IEC 40500:2025) adds criteria over 2.1 and removed 4.1.1 Parsing. The ones that most often catch interface work: 2.4.11 Focus Not Obscured (Minimum), 2.4.13 Focus Appearance, 2.5.7 Dragging Movements, 2.5.8 Target Size (Minimum), 3.2.6 Consistent Help (help in the same relative place across pages), 3.3.7 Redundant Entry, and 3.3.8 Accessible Authentication. Treat these as a build checklist, not a post-hoc audit. The long-standing essentials still apply: contrast, keyboard operability, labels, headings in order (no skipped levels), alt text, and a logical reading and focus order.

9. Testing

Automated scanners (axe, Lighthouse, and similar) reliably catch only a portion of issues; published estimates of automated coverage vary widely (from roughly a tenth of success criteria fully detectable up to around half of issues by some vendor measures), so a clean automated pass is necessary but far from sufficient. Always also: tab through the entire interface with the keyboard only, operate every control without a mouse, run a screen reader over the key flows, test at 200 percent zoom and at the reflow width (320px), and verify in grayscale and with a color-blindness simulation (protanopia, deuteranopia, tritanopia). Verify both light and dark modes against the same bar.

10. Accessibility slop tells

• No visible keyboard focus state, or outlines removed and not replaced.
• Placeholder text used as the only label.
• Status or meaning conveyed by color alone.
• Icon-only buttons with no accessible name.
• Body text below 4.5:1 contrast, or off-white-on-near-white low-contrast fashions that fail.
• Custom controls (divs as buttons) with no keyboard support or role.
• Tiny targets below 24px with no spacing compensation.
• Drag-only interactions with no button alternative.
• Modals that do not trap or return focus; tooltips with interactive content.
• Motion that ignores prefers-reduced-motion.

Adapters

The token core in token-core.css is the portable source of truth. Pick the adapter for the stack. The semantic token names stay constant across stacks so components are portable.

Plain CSS (any framework, no build step)

Import the core, then reference variables directly.

@import "./token-core.css";

.button {
  font-family: var(--font-body);
  background: var(--color-accent);
  color: var(--color-accent-fg);
  padding: var(--space-2) var(--space-4);
  border-radius: var(--radius);
  border: none;
}
.card {
  background: var(--color-bg);
  border: var(--border); /* edge, not shadow */
  border-radius: var(--radius);
  padding: var(--space-4);
}

Tailwind v4 (@theme)

@theme generates utilities AND exposes tokens as runtime CSS variables. Declare tokens once; get bg-accent, text-accent, font-display, rounded-card automatically.

@import "tailwindcss";
@import "./token-core.css";

@theme {
  --font-display: "Fraunces", serif;
  --font-body: "Newsreader", serif;
  --color-accent: oklch(0.53 0.15 30);
  --color-bg: oklch(0.97 0.008 95);
  --color-fg: oklch(0.22 0.004 250);
  --radius-card: 2px;
  --spacing: 0.25rem; /* base unit; p-4 = 1rem */
}

Usage: <button class="bg-accent text-white font-body rounded-card px-4 py-2">. Tailwind v4 ships its own palette in OKLCH, so custom OKLCH tokens sit naturally alongside it.

shadcn/ui (semantic tokens)

shadcn components read semantic variables, so overriding them reskins every component at once. Override the default primary (which is otherwise the slop accent). On Tailwind v4, shadcn uses OKLCH and @theme inline.

:root {
  --background: oklch(0.97 0.008 95);
  --foreground: oklch(0.22 0.004 250);
  --primary: oklch(0.53 0.15 30); /* replace the default */
  --primary-foreground: oklch(0.99 0 0);
  --muted-foreground: oklch(0.55 0.01 250);
  --border: oklch(0.85 0.01 250);
  --radius: 0.125rem; /* 2px, not the rounded-2xl reflex */
}
.dark {
  --background: oklch(0.18 0.01 250);
  --foreground: oklch(0.95 0.008 95);
  --border: oklch(0.32 0.01 250);
}
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

Optional: Open Props

For ready-made sizes, easings, and gradients in any stack: @import "https://unpkg.com/open-props"; then reference var(--size-3), var(--ease-3), etc. Pure CSS variables, framework-agnostic.

Three-layer token discipline (all stacks)

1. Primitives (raw): --blue-9, --space-3, --font-mono. 2. Semantic (purpose): --color-bg, --color-fg, --color-accent, --color-border. 3. Component (variant): --button-bg, --card-radius. Components reference semantic tokens, never raw primitives. Dark mode redefines the same semantic variables under .dark or the media query.

Aesthetics library

Pick ONE and execute its defining trait precisely. Each is anti-default by construction: none can be reached by sampling the SaaS-page median. Match implementation complexity to the aesthetic.

Editorial / magazine

High-contrast serif display (Fraunces, Playfair Display, Boska, Bodoni Moda) paired with a clean body. Real columns, drop caps, pull quotes, rules and dividers instead of cards, generous measure (65-75ch). Reference: broadsheet newspapers, The Verge. Defining trait: typographic contrast and editorial scaffolding (rules, columns) replacing the card grid entirely.

Terminal / monospace

Monospace family for everything (JetBrains Mono, IBM Plex Mono, Fira Code). Dark base, ANSI-derived accents (Nord, Solarized, Gogh schemes). Grid-of-text layout, blinking-cursor or CRT touches. Reference: developer tooling, TUIs. Defining trait: monospace UI (not just code blocks) with ANSI palette discipline.

Neo-brutalism

The single most recognizable trait: hard offset drop shadow, solid, no blur, often colored. Plus thick black borders (2-3px), flat saturated color fills, sharp edges (zero radius), bold sans headlines at huge size. Buttons: thick border + flat fill + hard offset shadow. Reference: Gumroad, Figma brand refresh. Defining trait: box-shadow: 6px 6px 0 #000 with no blur, thick borders, zero radius.

Brutalism / raw

Raw unstyled-HTML feel, monochrome or one harsh accent, oversized sans or system/monospace type, exposed structure, visible grid, near-zero decoration, hard edges. High contrast (black on concrete-gray + one loud accent like acid green or red). Reference: brutalistwebsites.com, Drudge Report. Defining trait: deliberate absence of polish; structure exposed rather than hidden.

Swiss / international typographic

Strict grid, sans-serif (Helvetica-class), restrained palette, generous negative space, typography as structure, left-aligned, asymmetric balance, no decoration. Reference: Josef Mueller-Brockmann. Defining trait: rigorous grid and one accent used with extreme restraint.

Retro / skeuomorphic

Y2K chrome, brushed-metal panels, beveled buttons, period-correct type. Used deliberately and consistently, never as a fallback. Reference: early-2000s OS UIs, vaporwave. Defining trait: tactile depth and period commitment.

Luxury / refined

Restrained palette (near-black, off-white, one metallic or jewel accent), large type, vast whitespace, slow deliberate motion, high-quality imagery treatment. Reference: fashion houses, premium hardware. Defining trait: restraint and space signaling premium.

Organic / natural

Warm earthy palette, soft irregular shapes, hand-drawn or textured elements, humanist type. Reference: wellness and food brands. Defining trait: irregularity and warmth, the opposite of geometric precision.

Industrial / utilitarian

Dense information, functional grid, monospace numerics, muted palette with one safety-orange or hazard-yellow accent, minimal ornamentation. Reference: aviation/control panels, data tools. Defining trait: density and function-first layout.

Maximalist

Layered color, overlapping elements, multiple typefaces in tension, dense visual rhythm, intentional chaos. Reference: zine culture, experimental portfolios. Defining trait: controlled excess; every surface does something.

Choosing

Match the aesthetic to the domain and audience, but bias toward commitment. A developer tool reads well as terminal or industrial; an essay site as editorial; a playful consumer app as neo-brutalist; a premium product as luxury or swiss. When unsure, state the chosen direction and why in one line, then proceed.

Creating a brand-new theme from discovery

The catalog above is a set of starting points, not a closed list. The strongest, least generic results come from originating a bespoke aesthetic from the discovery context (the adjectives, visual word translations, archetype, references, and artifact type), rather than picking a label off the shelf. Use the catalog as raw material to combine and diverge from.

Method:

1. Read the inputs. Take the 3 to 5 adjectives, their visual word translations, the 3-word essence, the archetype, and the admired/avoid references from discovery. 2. Find the closest one or two catalog styles, then deliberately diverge. A bespoke theme is usually a base style plus a twist that comes straight from an adjective. "Editorial but warm" pulls Editorial toward humanist serifs and a soft accent; "Swiss but playful" keeps the grid and adds one bright accent and rounder shapes; "Terminal but premium" keeps monospace and dark base but swaps ANSI accents for a single jewel tone and adds generous spacing. 3. Translate each adjective into a concrete token decision. Each visual word translation should land on at least one of: type class, scale ratio, accent hue, spacing density, radius, shadow approach, motion. If an adjective changes nothing in the tokens, it is decoration, not direction; cut it or sharpen it. 4. Name the theme. A one or two word name (for example "Ledger", "Atelier", "Console", "Almanac") forces coherence and gives the project a vocabulary. The name is not cosmetic; it is the test of whether the direction is singular. 5. Define the defining trait (the structural rule that organizes everything, like Editorial's rules-instead-of-cards or Swiss's strict grid) and the signature move (the single most memorable detail). These two must be unique to this project and must not collide with the slop tells. 6. Derive the full token set from the above (type, color in OKLCH, spacing, radius, one shadow approach), then proceed to the gate and write it all to DESIGN.md.

Worked example. Discovery yields: artifact = developer tool landing page; adjectives = precise, calm, expert, quietly confident; essence = "quiet, technical, exact"; archetype = Sage; admires Linear and a Swiss rail timetable; avoid loud startup gradients.

• Closest catalog styles: Swiss and Terminal. Diverge by softening Terminal's neon and adopting Swiss restraint.
• Token decisions: "precise" -> strict 12-column grid, monospace numerals, hairline rules, radius 2px. "calm" -> low chroma, generous line height. "expert" -> dense but ordered information, IBM Plex Sans + IBM Plex Mono. "quietly confident" -> one deep teal accent used only on focus and primary action, near-black ink on warm off-white.
• Name: "Console". Defining trait: text-and-rule structure on a strict grid, no cards. Signature move: a single hairline accent rule that marks the active section, echoing a timetable.
• Result: a coherent, original theme that no median sampling would produce, fully specified and ready to write to DESIGN.md.

Reuse vs originate: if the user already has a DESIGN.md or brand assets, do not invent a theme. Read the existing DESIGN.md, honor its tokens, and extend it. Originate only for greenfield work.

Artifact types

Each type optimizes for a different thing and has its own layout grammar, density, and aesthetic range. Identify the type in Phase 0, then design to its priorities. The positioning variants are where the same type splits into genuinely different design systems. The named products under each type are inspiration to study and transpose one move from (an interaction, a layout device, a density choice), never templates to clone, and their specific look may have changed since writing; borrow the durable design quality, not a snapshot.

Marketing / landing page

Optimizes for: one conversion action. Everything serves a single primary CTA. Layout grammar: focused single-column narrative, above-the-fold value proposition, proof, then CTA. A landing page (campaign-specific) is tighter and more singular than a homepage (brand hub with navigation). Density: airy. One idea per section. Aesthetic range: wide, set by positioning below. Anti-patterns: no clear primary action; competing CTAs; the generic hero + 3-cards + testimonials + CTA template used by reflex.

Positioning variants (these are different design systems):

• Corporate / enterprise: trust and proof first. Restrained palette (often blue/neutral), clear hierarchy, logos, case studies, data-backed claims, professional imagery. Competence personality. Conservative motion. Avoid: looking like a startup toy.
• Creative / design-forward: visual impact and expression first. Bold or unexpected color, strong typographic personality, motion and micro-interactions as features, asymmetry. Conversion is secondary to impression. Think design studios, agencies, premium products. Avoid: timid, templated layouts.
• Technical / developer tool: show the product, not adjectives. Often dark mode, dense, code snippets and live demos, workflow-mirroring structure (for example a three-column build/deploy/run), real interface screenshots over stock imagery, honest performance claims. Avoid: marketing fluff, hidden product, stock photos of people pointing at laptops.
• Ecommerce landing (single product/campaign): hero image, price, CTA above the fold; trust signals; benefit bullets; reviews. See ecommerce below.

Inspiration: Stripe and Linear (technical, product-as-hero, restrained), Vercel (developer landing, blueprint grid, build-log motion), Apple and BMW (premium, full-bleed product), Mercury and Ramp (fintech, disciplined and bold), Anthropic and OpenAI (calm, editorial-leaning AI positioning), Awwwards and Godly entries (creative, design-forward).

SaaS application

Optimizes for: repeated task completion. Productivity over impression. Layout grammar: persistent navigation (sidebar or top), content area, consistent component system, predictable patterns, empty states and loading states that teach. Density: medium to high; depends on user expertise and task. Power users tolerate density; consumer apps want clarity. Aesthetic range: usually restrained (swiss, industrial, clean neutral). A committed but quiet palette; the accent carries primary actions and focus. Anti-patterns: marketing-page flourishes inside the app; inconsistent components; decoration that slows the task; reinventing controls. Inspiration: Linear (keyboard-first, low-latency, consistent), Notion (flexible blocks, calm surfaces), Figma (dense pro tooling that stays legible), Height and Superhuman (command-driven speed), Vercel and Sentry dashboards (developer-grade density).

Dashboard / data tool

Optimizes for: a specific decision, not data display. If no one can name the decision, the dashboard will fail. Layout grammar: 12-column grid, primary elements span 6 to 8 columns and secondary 3 to 4; F or Z scan pattern, most critical data top-left; grouped sections with whitespace; bento grids work for scanning diverse metrics. Keep metric definitions one click away. Density: high, but disciplined. 5 to 9 prioritized metrics, not everything. Desktop tolerates more density than mobile (touch targets 44x44, 3 to 5 metrics on the go). Aesthetic range: restrained and functional. Color is meaning (status, thresholds), not decoration. Charts chosen by data structure, not aesthetics. Anti-patterns: information overload (the top dashboard failure); charts nobody reads; gradient text on metrics; treating it as a portfolio piece; raw-data dump with no hierarchy.

Type variants:

• Operational: live monitoring. Big status indicators, clear ownership, tiles or tables with sparklines, low latency, immediate clarity.
• Analytical: exploration. Filters, drill-downs, range pickers, reset controls, more breathing room for deep dives.
• Strategic / executive: high-level KPIs at a glance. Simplicity, only the critical metrics, trend over detail.
• Tactical: mid-level, daily/weekly, bridges operational and strategic.

Inspiration: Grafana and Datadog (operational, dense, status-forward), Vercel and Sentry (developer analytics with restraint), Stripe Dashboard (financial data presented calmly, tabular-nums everywhere), Linear insights and PostHog (analytical exploration), executive KPI views in Geckoboard-style boards (strategic simplicity).

Ecommerce

Optimizes for: confident purchase. Reduce uncertainty and friction at the decision point. Layout grammar (product page): hero with multiple high-quality images and zoom, product name, price, prominent CTA (Add to Cart) above the fold; benefit bullets; trust section (secure payment, shipping, returns); detailed specs, reviews, FAQs; related items. CTA repeats above fold, mid-page, and below reviews. Density: medium; imagery-forward. Trust and proof density: reviews and real human signals near the point of decision, not buried. Proof should be specific and traceable, not generic. State shipping, returns, guarantees clearly. Aesthetic range: set by brand (luxury = sparse and refined; consumer = bright and energetic), but conversion mechanics are constant. Anti-patterns: dark patterns (pre-ticked boxes, manufactured urgency) that erode trust; hidden fees; weak or distant product imagery; proof reduced to a star count. Inspiration: Apple (premium product pages, vast space), Gymshark and Allbirds (consumer, energetic, strong PDPs), Aesop and SSENSE (luxury restraint, editorial), Gumroad (creator commerce, raw confidence), Shopify storefront references (conversion mechanics done well).

Presentation / deck

Optimizes for: a narrative that persuades. Structure beats decoration. Layout grammar: clear arc, commonly problem -> solution -> proof -> CTA, or awareness -> consideration -> conversion. One idea per slide; strong visual hierarchy with bold headlines, charts, icons guiding attention; consistent branding throughout. Density: low per slide; the deck carries density, not the slide. Aesthetic range: consistent system, customer-centric framing over feature-dumping. Anti-patterns: walls of text; one slide doing five jobs; inconsistent template; decoration competing with the point. Inspiration: classic pitch-deck references (Airbnb, Sequoia template) for structure, conference-talk decks for one-idea-per-slide discipline, and editorial/keynote styling (Apple keynote slides) for typographic restraint.

Docs / content site

Optimizes for: reading and findability. Layout grammar: clear navigation (sidebar for depth), strong measure (65 to 75ch), generous line-height, good code styling if technical, persistent search, scannable headings. Density: text-forward; structured. Aesthetic range: editorial or clean technical; restrained so content leads. Anti-patterns: marketing-page styling that hurts readability; centered long-form; weak code blocks; poor navigation for depth. Inspiration: Stripe Docs (docs-as-product, live and copyable examples), Tailwind and React docs (clear IA, strong code styling), Mintlify and GitBook (modern docs platforms), Vercel docs (calm technical), Cloudflare and Twilio (deep API references).

Portfolio / brand site

Optimizes for: a single strong impression and showcasing the work. Layout grammar: the work is the hero; layout can break convention deliberately; strong typographic and motion personality. Density: usually airy; the work fills the space. Aesthetic range: the widest; this is where maximalism, editorial, and creative directions shine. Anti-patterns: hiding the work behind chrome; generic template that says nothing about the maker. Inspiration: Awwwards and Brutalist Websites galleries, designer portfolios indexed by Typewolf, agency sites (Pentagram, Locomotive, Active Theory) for motion and craft.

Mobile app (native and mobile web)

Optimizes for: thumb-reachable, focused task flow on a small screen. One primary action per screen. Layout grammar: platform navigation (tab bar or bottom nav on iOS/Android, not a desktop sidebar), top app bar, content scroll, bottom sheets and action sheets for secondary choices, primary actions in the thumb zone (lower half). Follow Apple Human Interface Guidelines and Material Design 3 rather than porting a desktop layout. Density: low to medium per screen; progressive disclosure carries depth. Touch targets at least 44x44. Aesthetic range: platform-native restraint to bold consumer; respect platform conventions for gestures, back behavior, and system controls. Anti-patterns: desktop layouts squashed into a phone; tiny targets; hover-dependent interactions; ignoring safe areas and the keyboard covering inputs; custom controls that fight the platform. Inspiration: Things and Linear mobile (focus and restraint), Duolingo (playful motion and character), Arc Search and Family (gesture and sheet craft), Airbnb and Revolut (consumer polish). Mobbin is the reference library for real mobile flows.

AI / conversational interface

Optimizes for: a legible exchange between user and model, with trust in the output. The message stream is the product. Layout grammar: a scrollable conversation (user vs assistant clearly differentiated), a persistent composer (input plus send, often with attachment and model controls), streaming text that renders incrementally, and treatments for rich output (code blocks with copy, tables, citations, tool-call or step indicators, artifacts/side panels). A history or thread list for returning to past conversations. Stop and regenerate controls. Density: medium; the content is variable-length, so the layout must hold both a one-line reply and a long structured answer. Aesthetic range: calm and readable usually wins; the type and code styling matter more than decoration. Streaming and tool-use motion should communicate progress, not entertain. Anti-patterns: chat bubbles so styled they hurt long-form reading; no copy button on code; citations that cannot be traced; no streaming feedback (the user stares at nothing); losing the composer off-screen; hiding model or context controls the user needs. Inspiration: ChatGPT, Claude, Perplexity (citation-forward), Raycast AI and Vercel v0 (AI inside a tool). Treat these as inspiration; the patterns are evolving fast.

Email and newsletter

Optimizes for: rendering and reading inside an email client, then one click out. The client, not the browser, is the constraint. Layout grammar: single-column, table-based layout for client compatibility; inline styles; a clear hierarchy that survives stripped CSS; a single primary CTA; preheader text; web-safe or system fonts with graceful fallback; dark-mode-aware colors. Roughly 600px content width is the durable convention. Density: low; one message, scannable in seconds. Aesthetic range: brand-consistent but constrained by client support; do not rely on modern CSS, custom fonts, or background images rendering everywhere. Anti-patterns: multi-column desktop layouts that break on mobile clients; external CSS; tiny tap targets; image-only emails that fail with images off; ignoring dark mode inversion in clients. Inspiration: well-crafted product and editorial newsletters (Stripe, Linear changelog emails, Substack issues); tools like Mailchimp and Loops for client-safe patterns. Newsletter as a web post is a different artifact (see blog/editorial).

Blog / editorial publication

Optimizes for: sustained reading and return visits. Distinct from docs (findability) and from landing (conversion). Layout grammar: a strong measure (65 to 75ch), generous line-height and paragraph spacing, a confident type system (a real display face for titles, a refined body face), article furniture (byline, date, reading time, pull quotes, figures with captions, footnotes), an index or archive, and a quiet but present subscribe or follow CTA at the end (see copywriting-cta thinking). Left-aligned long-form, never centered. Density: text-forward and airy; the words lead. Aesthetic range: editorial and typographic; this is where serif display and real columns shine (see aesthetics-library.md Editorial). Anti-patterns: centered body text; weak hierarchy between article and chrome; aggressive popups over the read; code blocks and figures that break the rhythm; a homepage that buries the writing. Inspiration: Stripe Press and editorial sites (The Verge, Pitchfork redesigns), personal sites indexed by Typewolf, Ghost and Substack web posts, paula-scher-grade typographic publications. Inspiration only.

Onboarding and auth flows

Optimizes for: getting the user to first value with the least friction. Conversion through a sequence, not a page. Layout grammar: focused, single-task screens (sign up, log in, verify, set up); a stepper or progress indicator for multi-step setup; minimal chrome; smart defaults and inference (Tesler's law); a strong empty-first-run state that teaches; passwordless and social options; server-side redirects so the user never sees the wrong screen flash. Density: very low; one decision per step. Aesthetic range: matches the product, stripped to essentials. Trust signals on auth (security, privacy) where relevant. Anti-patterns: long forms before any value; cognitive-test logins (WCAG 3.3.8); re-entering known data (3.3.7); no progress sense; dead-end empty states; autofocus opening the keyboard over a mobile screen. Inspiration: Linear and Vercel onboarding (fast to first value), Superhuman (guided setup), Stripe and Mercury (trustworthy auth), Duolingo (motivating first-run). See components.md for the underlying state work.

Pricing page

Optimizes for: a confident plan choice. A conversion artifact distinct enough from the landing page to design on its own. Layout grammar: a comparable set of tiers (typically 2 to 4), one recommended plan visually emphasized, a feature comparison that is scannable (not an undifferentiated matrix), clear price and billing cadence with a monthly/annual toggle, an FAQ addressing the real objections, and a single primary CTA per tier. Enterprise as a contact tier. Density: medium; comparison-heavy but must stay scannable. Aesthetic range: matches the product; restraint and clarity beat decoration here because the user is comparing, not browsing. Anti-patterns: too many tiers; a giant feature matrix with no hierarchy; hidden total cost; manufactured urgency; no recommended default (Hick's law); ambiguous billing. Inspiration: Linear, Vercel, and Stripe pricing (clear tiers, honest comparison), Notion and Figma (per-seat clarity). Inspiration only.

Settings, account, and admin / CMS

Optimizes for: finding and changing the right setting safely. Configuration density, not data display. Layout grammar: a clear category navigation (grouped sections), forms organized by task, sensible grouping and search for large surfaces, instant-apply toggles vs explicit save for batched changes, destructive actions guarded and clearly separated, audit and confirmation feedback. Admin and CMS add tables, bulk actions, roles and permissions, and content editing. Density: medium to high; dense but zoned with surfaces and dividers, not borders. Aesthetic range: restrained and functional; the system recedes so the task is clear. Anti-patterns: a wall of ungrouped toggles; unclear save model (does this apply now?); destructive actions next to benign ones; no search on large settings; reinventing form controls. Inspiration: Linear, GitHub, and Vercel settings (grouped, searchable, calm), Stripe Dashboard settings, Shopify admin and WordPress/Sanity/Contentful for CMS patterns. See components.md for form and table craft.

Marketplace (two-sided)

Optimizes for: matching supply and demand with trust on both sides. Search, filter, listing, and trust are the core. Layout grammar: a search and filter surface, a results grid or list with strong scannable cards (image, key facts, price, rating), a detailed listing page with rich media and trust signals (reviews, verification, policies), and a booking or purchase flow. Seller and buyer views differ. Map plus list for location-based marketplaces. Density: medium; imagery and facts balanced for fast comparison. Aesthetic range: set by brand, but trust and clarity are constant; specific, traceable proof beats generic badges. Anti-patterns: weak listing cards; filters that do not persist or reset cleanly; trust reduced to a star count; hidden fees revealed late; results with no hierarchy. Inspiration: Airbnb (listing and trust craft), Etsy and eBay (volume and filtering), Vinted and StockX (vertical marketplaces), Booking.com (filter-heavy comparison). Inspiration only.

More artifact types in brief

For the long tail, the same discipline applies: name what it optimizes for, its one hard constraint, and one reference to study. Inspiration only.

Quick selection

Decision support -> dashboard. Repeated task -> SaaS app. One conversion action -> landing page. Choose a plan -> pricing page. Buy a product -> ecommerce. Match supply and demand -> marketplace. Persuade an audience -> deck. Read and find reference -> docs. Read long-form -> blog/editorial. Look up an API while coding -> API reference. Talk to a model -> AI/conversational. Reach the user in their inbox -> email/newsletter. Get a user started -> onboarding/auth. Change a setting -> settings/admin. Manage content -> CMS. Phone-first focused task -> mobile app. Leave an impression -> portfolio. When an artifact spans two (a marketing site with an embedded app, an AI chat inside a SaaS app, a landing page with a pricing section), design each region to its own type.

Catalogs: components and inspiration

Once the direction is committed (artifact type, adjectives, aesthetic, type and color system, signature move) and before or during building, scan these catalogs for concrete ideas and ready implementations. They are accelerators, not the design. Two cautions hold throughout. First, transpose, never adopt wholesale: pull a layout idea, an interaction, or a component implementation and refit it to the committed tokens, because several of these catalogs have a recognizable house style that is itself becoming a tell (animated-gradient hero blocks, beam/spotlight borders, the same Aceternity/Magic flourishes everywhere). Run anything you borrow through references/slop-checklist.md. Second, check the license before shipping: some are MIT copy-paste, some are free plus paid tiers, some are community registries with mixed licenses, and some are paid.

Component catalogs (implementation and patterns)

Use these for built components, blocks, and interaction patterns you can adapt to the token set. Most target React plus Tailwind and the shadcn/ui registry convention.

• shadcn/ui: the baseline. Unstyled, accessible, copy-paste components you own and restyle through semantic tokens (MIT). The correct foundation precisely because it carries no opinionated look; you supply the identity via tokens (see references/adapters.md).
• 21st.dev: a large community registry of shadcn-compatible components and blocks, installable via the shadcn CLI. Mixed authorship and licenses, so verify per component. Good for breadth and discovering patterns.
• Magic UI: animated and marketing-oriented components (free plus pro). Strong for landing-page motion ideas; filter heavily, as its signature effects are widely copied.
• Aceternity UI: high-impact animated components and hero effects (free plus paid). Striking, but its look is one of the most recognizable on the current web, so transpose the technique, not the exact effect.
• Origin UI: a broad, restrained set of Tailwind plus shadcn components and inputs (free). Useful for form, input, and control variety without a heavy house style.
• Cult UI: distinctive, well-crafted shadcn components with more character (free plus some paid). Good for interaction detail.
• Kibo UI: composable shadcn-registry components, including richer pieces (tables, editors, kanban). Useful for application-grade building blocks.
• shadcnblocks: large library of prebuilt marketing and app blocks for shadcn (paid). Good for fast section scaffolding; restyle to the system.

Workflow with these: take the structure or the interaction, strip the donor styling, and reattach the committed tokens (type, color, radius, motion). A borrowed component that still carries its catalog's default look has not been deslopped.

Design inspiration galleries (direction and reference)

Use these in Phase 0 and Phase 1 to find strong current examples of the exact artifact type and positioning, then transpose one move (a type pairing, a color relationship, a layout device, a signature detail) per the recipe in references/discovery.md. Match the gallery to the job.

• Awwwards: juried, cutting-edge, often maximalist and motion-heavy. Best for creative, portfolio, and brand-forward work; over-indexes on spectacle, so adapt for product UI.
• Behance: broad design portfolios across disciplines (branding, illustration, UI). Good for visual identity and illustration direction.
• Dribbble: shots and concepts; fast for visual ideas, but much is non-shipping concept work, so weight toward real products.
• Mobbin: real product UX flows and screens (web and mobile), searchable by pattern. The best source for how shipped apps actually solve a flow (onboarding, settings, empty states).
• Land-book: curated landing pages across industries. Strong for marketing and landing direction.
• Page Collective: curated, high-quality site and page references with a tasteful bias.
• Godly: ultra-curated, tech and startup and SaaS leaning. Small, high signal.
• SaaS Landing Page: landing pages specifically for SaaS, organized for that artifact type.
• Lapa Ninja: large landing-page gallery, filterable by category and section.
• Refero: searchable real-product UI reference (screens and patterns), good for app and dashboard detail.
• Screenlane: curated web and mobile UI patterns and inspiration, useful for component-level ideas.

Workflow with these: find one to three references for the exact artifact type and positioning, name what specifically is worth borrowing from each, transpose into the token set, and state what was borrowed before building. Do not clone a layout; extract its relationships.

How to suggest these to the user

At the end of conception, recommend the relevant subset, not the whole list. Pick by artifact type and stage: galleries (Land-book, Godly, SaaS Landing Page, Lapa Ninja) for landing direction; Mobbin, Refero, Screenlane for app and dashboard flows; Awwwards, Behance, Dribbble, Page Collective for creative and brand-forward work; the component catalogs for implementation once the system is set. Frame them as inspiration to transpose through the committed system, with a reminder to verify component licenses.

Color strategy and OKLCH

Color is a strategic decision, not an aesthetic preference. Snap judgments about products form within about 90 seconds and 62 to 90 percent of that assessment is color-driven; consistent color use can raise brand recognition by up to 80 percent. Color is a first impression that shapes all later perception. So choose for fit and differentiation, specify exactly, author in a perceptual model, and verify accessibility.

Frameworks below draw on Elliot and Maier (color-in-context), Singh (the 62 to 90 percent finding), Eiseman (color harmony), Neumeier (brand as gut feeling), and Blue Ocean strategy (Kim and Mauborgne).

Contents

1. Color-in-context theory 2. The appropriateness principle 3. Blue Ocean differentiation (the strategic anti-indigo) 4. OKLCH primer and hue points 5. Color harmony systems 6. The 60-30-10 rule 7. Key mental models 8. Brand archetype color map 9. Industry conventions 10. Cultural considerations 11. Building the palette (roles) 12. Tints and shades 13. Neutrals 14. Color combinations and proportions 15. Accessibility and color blindness 16. Specification systems and output 17. Testing and validation methods 18. Common mistakes 19. Validation checklist

1. Color-in-context theory

Color effects are neither universal nor arbitrary; they depend on context. Meaning varies with the psychological context, some responses are biological and others learned, and hue, lightness, and chroma all matter. Red is danger in one context, attractiveness in another; urgency on a sale banner, warning in a health app, love on Valentine's. Always reason about the context the color will be seen in. Never treat a hue's meaning as fixed.

2. The appropriateness principle

Color effectiveness depends on perceived fit with the brand, product, and context. An appropriate color outperforms a theoretically better one that feels wrong. Blue works for finance because trust signals are expected there; it would not work for a children's candy brand. Appropriateness may be the single most important factor in color effectiveness.

3. Blue Ocean differentiation (the strategic anti-indigo)

In a crowded category everyone uses the same cues (a red ocean); find uncontested visual territory (blue ocean). For AI-generated UI, the indigo/violet band is the reddest ocean: it is the literal default. Avoid OKLCH hue ~250 to 320 for accents unless the brief demands it. Process: audit what competitors and the AI default use; find the absent or underused hue; check it still fits brand personality and audience; decide whether you can own it credibly. Precedents: Lufthansa yellow among blue airlines; T-Mobile magenta among blue/red telecoms; Apple white/silver among black/gray hardware; ING orange in blue banking; Tiffany trademarked its blue-green (PMS 1837) so the color alone triggers recognition.

4. OKLCH primer and hue points

Author in OKLCH because it is perceptually uniform: lightness matches perceived brightness, scale steps come out even without manual correction, and gradients avoid gray dead-zones. Format oklch(L C H): L 0 to 1, C 0 to about 0.37 (sRGB max, P3 about 0.4), H 0 to 360. Hue points: red ~20, orange ~40, yellow ~90, green ~140, teal ~195, blue ~220, purple ~320. Accents far from indigo: orange oklch(0.70 0.19 40), brick oklch(0.53 0.15 30), crimson oklch(0.64 0.22 0.6), grass oklch(0.65 0.14 145), teal oklch(0.70 0.12 195), amber oklch(0.835 0.146 86). Chroma is gamut-limited per hue; high C at some hues (teal ~195) clips on sRGB. Verify at oklch.com and ship a hex fallback: .accent{ background:#12A594; background:oklch(0.70 0.12 195); }.

5. Color harmony systems

Based on traditional color theory (Newton's color wheel).

In OKLCH, build categorical sets by holding L and C and rotating H by 360/n; equal C gives equal visual weight.

6. The 60-30-10 rule

60 percent dominant/neutral (backgrounds, large areas), 30 percent secondary/brand (headers, nav, key elements), 10 percent accent (CTAs, highlights). Creates hierarchy without overwhelming and ensures the accent draws attention exactly where intended.

7. Key mental models

• Recognition compounds over time; consistency makes a color iconic (Coca-Cola red was not special at first).
• Differentiation over conformity; conforming to norms is safe, strategic difference often creates more value (T-Mobile magenta).
• The 90-second rule; color is a first impression, not decoration.
• Simplicity scales; complex palettes break down in real use. The simpler the palette, the more consistently it is applied.
• Saturation and brightness matter; bright saturated reads energetic and youthful, muted desaturated reads sophisticated and mature. Hue is only part of the equation.

8. Brand archetype color map

Useful when the brand has a clear archetype.

9. Industry conventions

• Tech and finance: blue (trust, competence). Users: IBM, Chase, LinkedIn. Differentiate with purple (Twitch), green (Robinhood), magenta (T-Mobile).
• Healthcare and wellness: blue (trust), green (calm, less eye strain). Cool colors reduce anxiety.
• Food and beverage: red, yellow, orange (appetite, energy, urgency). Users: McDonald's, Coca-Cola.
• Luxury and premium: black, gold, deep navy, white. Restrained palettes, metallic accents, less is more.
• Eco and sustainability: green, earth tones, natural neutrals. Users: Whole Foods, Patagonia. Meeting a convention buys instant legibility; breaking it with fit buys recognition.

10. Cultural considerations

Meanings vary across cultures; research target markets and adapt.

11. Building the palette (roles)

Keep 3 to 5 core colors plus neutrals and semantic states. Define by role, not raw hue, so components stay portable:

• Primary/brand (1, sometimes 2): the 30 percent.
• Accent/CTA (1): the 10 percent, highest contrast, drives action.
• Neutrals: bg, surface, border, muted-fg, fg (the 60 percent).
• Semantic states: success, warning, error (never color alone; pair with icon or text). Build a 12-step scale per important hue when you need depth (Radix model): 1 to 2 app/subtle bg, 3 to 5 component bg (normal/hover/active), 6 to 8 borders (subtle/normal/strong), 9 solid (pure, the value to override with a brand color), 10 solid hover, 11 low-contrast text, 12 high-contrast text. Radix Colors ships accessible APCA-tuned scales if you do not want to hand-roll.

12. Tints and shades

For each important color, generate a 100 (lightest) to 900 (darkest) ramp with 500 as the base, used for hover/active states, surfaces, and borders. In OKLCH, step lightness evenly and ease chroma down at the extremes so light tints do not look washed and dark shades do not muddy.

13. Neutrals

Do not use pure black or pure white. Soften to a near-black ink and an off-white, often tinted slightly toward the brand hue (lower the L and C of the brand color). State why: softer on the eyes, warmer, more intentional. On colored backgrounds use the same hue darker and desaturated, never gray.

14. Color combinations and proportions

Document approved combinations (primary, secondary, background, text, context) and combinations to avoid (clash, accessibility, cultural). Apply 60-30-10: neutral canvas, brand presence, accent for action.

15. Accessibility and color blindness

WCAG AA: 4.5:1 normal text, 3:1 large. AAA: 7:1 and 4.5:1. Test protanopia (red-blind), deuteranopia (green-blind), tritanopia (blue-blind). Never encode meaning in color alone; add icon, label, or pattern. Verify the palette in grayscale, which proves hierarchy does not depend on hue.

16. Specification systems and output

• RGB: additive, screens. rgb(255,0,0). Largest gamut.
• HEX: six-digit RGB for web. #FF0000.
• CMYK: subtractive, print. C0 M100 Y100 K0. Smaller gamut; some screen colors dull in print.
• Pantone (PMS): pre-mixed spot color, exact brand matching. About 30 percent cannot be replicated in CMYK. Author and ship OKLCH for screen with a hex fallback; add HSL if helpful. Only add CMYK and Pantone when print is in scope. Document each color with its role and values.

17. Testing and validation methods

• Qualitative: focus groups (3 to 5 options, emotional reactions, fit), depth interviews (cultural and demographic nuance).
• Quantitative: A/B testing (CTR, conversion, behavior not stated preference), MaxDiff (forced ranking reveals true preference), implicit association (subconscious associations).
• Biometric: eye tracking and heatmaps (where attention lands first), facial coding (unconscious emotional reaction).

18. Common mistakes

Too many colors (cap at 3 to 5); copying competitors (you blend in); ignoring accessibility (excludes about 5 percent colorblind plus low-vision users); chasing trends (age fast); choosing by personal preference over audience psychology; cultural color blindness; inconsistent application across touchpoints.

19. Validation checklist

• Works in grayscale (hierarchy holds without color)?
• Passes WCAG AA for every text-on-bg pair?
• Accent sits outside the indigo/violet default band (unless briefed)?
• Distinct from direct competitors and from the AI default at a glance?
• 3 to 5 core colors, simple enough to apply consistently?
• Semantic states defined and never color-only?
• If global: meanings checked in target markets?
• If print: CMYK conversion and Pantone matching considered?

Component and interaction craft

This is the "expert at designing an application" layer: the part most AI output skips. A beautiful theme on top of careless components still reads as amateur. Components are judged by their states and their behavior under real conditions (loading, empty, error, dense data), not by their resting appearance. The discipline below draws on Refactoring UI (Wathan and Schoger), Rauno Freiberg's interface guidelines, Nielsen Norman Group, and the patterns codified by Apple HIG, Material Design 3, IBM Carbon, Atlassian, Shopify Polaris, and GitHub Primer. Mine those systems for any component not covered here.

Contents

1. The universal state matrix 2. Buttons 3. Forms and inputs 4. Tables and data grids 5. Navigation and command surfaces 6. Overlays: modals, dialogs, sheets, drawers, popovers 7. Feedback: toasts, inline validation, optimistic updates 8. Empty, loading, and error states 9. Interaction details that separate expert from default 10. Component slop tells 11. Inspiration library (components)

1. The universal state matrix

Every interactive component needs every state specified, not just its default. The matrix: default, hover, active/pressed, focus (keyboard-visible), disabled, loading, error, and where relevant selected and read-only. Two rules prevent the most common defects. First, font weight must not change between states (regular to bold on hover or selected) because it shifts layout; change color, background, or a border instead, or reserve space for the bold weight. Second, use box-shadow for focus rings, not outline, so the ring follows border-radius (older Safari ignored radius on outline). Specify the matrix once per component and reuse it.

2. Buttons

Hierarchy by importance, not by semantic color. One primary action per view (solid, highest contrast), secondary actions (outlined or low-contrast fill), tertiary actions (styled like text or links). Do not paint every button with its meaning (green save, blue edit, red delete); that destroys hierarchy. Destructive actions get the loud red treatment only when destruction is the primary action of that surface, such as the confirm button inside a delete dialog; elsewhere a delete is a quiet tertiary action. Always: a hover state, an active/pressed state (a subtle scale to 0.97 or a darkened fill reads as physical), a keyboard focus ring, and a disabled state. Async buttons need a loading state and should disable on submit to prevent duplicate network requests. Size by context: comfortable touch targets (at least 44px tall) on mobile and primary CTAs, tighter in dense toolbars. Label with a verb describing the outcome ("Create project", not "Submit").

3. Forms and inputs

Forms are where craft is most visible and most often missing.

• Labels: every input has a visible label, not placeholder-as-label (placeholders vanish on focus and fail accessibility). Clicking the label focuses the input (wrap the input in the label or use for/id).
• Submission: wrap fields in a real <form> so Enter submits; do not rebuild this in JS.
• Types and attributes: use the correct type (email, tel, url, number) to get the right mobile keyboard and built-in validation; add required; set inputmode where useful; disable spellcheck and autocomplete where they hurt (names, codes) and enable them where they help.
• iOS zoom: input font-size at least 16px on touch, or iOS Safari zooms the viewport on focus.
• Autofocus: autofocus the first field on desktop; do not autofocus on touch, because it opens the keyboard over the screen before the user is ready.
• Affixes: position prefix/suffix icons or units absolutely inside the input with padding, so they sit within the field and clicking them focuses the input, rather than as separate adjacent boxes.
• Validation: validate at the right moment (on blur or on submit, not on every keystroke for format errors), show the error inline next to the field, highlight the offending field, keep the user's input, and explain how to fix it. Never clear the form on error.
• Toggles and instant controls: switches, checkboxes that filter, and segmented controls take effect immediately with no separate confirm; reserve Save for forms that batch changes.

4. Tables and data grids

• Alignment: left-align text, right-align numbers so decimals and magnitudes line up for comparison, and align headers with their column's content.
• Numerals: use font-variant-numeric: tabular-nums for any column of figures, IDs, timestamps, or anything that should align vertically, so digits share a fixed width.
• Separation: prefer light horizontal row separators or generous row padding over heavy full borders; zebra striping is optional and earns its keep only at high density. Avoid a grid of heavy lines (chart junk for tables).
• Scroll: sticky header on vertical scroll; pin the identifying first column on horizontal scroll; provide a totals or summary row for numeric tables.
• Density: pick a density for the page and keep it; do not mix loose and tight rows in one view. Use surface color and dividers to create zones in dense layouts rather than more borders.
• Sorting and actions: indicate sortable columns and current sort; keep row actions discoverable (visible or on row hover with a keyboard-accessible fallback).

5. Navigation and command surfaces

Choose sidebar vs topbar by information architecture depth: sidebar for many sections and nested areas, topbar for shallow IA and marketing. Breadcrumbs for deep hierarchies. For power-user products, a command palette (the cmd-K pattern) is the fastest navigation and action surface; the cmdk library by Paco Coursey is the de facto React implementation. Make the current location obvious (one accent on the active item, never weight change). Dropdown and menu triggers can open on mousedown rather than click for perceived immediacy. For nested menus, use a prediction cone (a triangular safe zone toward the submenu) so the pointer can travel diagonally without the submenu closing.

6. Overlays: modals, dialogs, sheets, drawers, popovers

Use the lightest overlay that fits: a popover for a small contextual choice, a sheet or drawer for a focused subtask, a modal dialog only for a decision that must block the flow. Requirements: trap focus inside while open, return focus to the trigger on close, close on Escape, close on backdrop click for non-destructive dialogs, and scale or slide from a sensible origin (a popover scales from its trigger via a transform-origin variable, not from center; a sheet slides from the edge). Drawers should resist accidental dismissal (a short delay or velocity threshold before drag-to-dismiss fires). Keep modals shallow; a modal that opens another modal is a flow smell.

7. Feedback: toasts, inline validation, optimistic updates

Give feedback where the action happened. A copy-to-clipboard button shows an inline checkmark on itself, not a toast across the screen. Toasts are for background or cross-surface events (saved, synced, failed), are brief, stack sanely, and never carry the only copy of an error the user must act on. Prefer optimistic updates for local actions: apply the change immediately, then reconcile with the server and roll back visibly with an explanation if it fails. Server-side gate redirects (auth) before the client renders so the user never sees a flash of the wrong screen.

8. Empty, loading, and error states

These are first-class screens, not afterthoughts.

• Empty states: explain what the feature is and prompt the first action, ideally with a template or example to remove the blank-canvas problem. Lead with a verb. A good empty state teaches; a bad one is a sad icon and "No data".
• Loading: use skeletons that mirror the eventual layout for content, spinners only for short indeterminate waits; preserve layout so content does not jump in. Show progress for long operations.
• Error: say what went wrong, why if known, and the next step; keep the user's context and work. Distinguish recoverable (retry) from terminal. Never dead-end.

9. Interaction details that separate expert from default

• Disabled buttons should not show tooltips (they are out of the tab order and never announced); explain the disabled reason elsewhere or keep the button enabled and validate on click.
• Keyboard-navigable lists: arrow keys to move, Enter to open, a delete shortcut where relevant.
• Do not animate high-frequency or keyboard-initiated actions; speed beats delight there (see motion.md).
• Respect the platform: a web app that fights browser conventions (custom scrollbars that break, hijacked Cmd-F) frustrates.
• Make hit targets larger than their visible icon; pad the clickable area.

10. Component slop tells

• Components with only a resting state (no hover, focus, active, disabled, loading).
• Placeholder text used as the label.
• Buttons colored by meaning instead of ranked by importance.
• Tables with center-aligned numbers, proportional (non-tabular) numerals, or heavy full borders.
• Modal-on-modal; toasts carrying must-act errors; no empty/loading/error states.
• Layout shift on hover or selection (weight change), focus rings that ignore radius (outline instead of box-shadow).
• The icon-tile-above-heading feature card as the universal content shape (see iconography.md).

11. Inspiration library (components)

Transpose the named behavior, not the visuals. Inspiration only.

• Linear: instant, keyboard-first interactions; command palette; near-zero perceived latency. Transpose the keyboard-first, low-latency interaction model.
• Stripe Dashboard and Docs: dense data presented calmly; docs-as-product with live, copyable examples. Transpose tabular-nums tables and inline copy feedback.
• Raycast: deliberate restraint, almost no animation on high-frequency actions. Transpose the no-animation-on-frequent-actions discipline.
• Superhuman: command-driven speed, every action keyboard-reachable. Transpose the everything-has-a-shortcut model.
• Shopify Polaris / IBM Carbon / GitHub Primer (design systems): fully specified component state matrices, density guidance, accessible patterns. Transpose the rigor of specifying every state.
• Family (iOS) and Vaul (web): spring-based sheets that resist accidental dismissal. Transpose the drawer dismissal threshold and edge-origin motion.

Dark mode and theming

Dark mode is a design problem, not an inversion. Flipping a light palette produces a UI that looks like someone dimmed the lights rather than designed for the dark: pure-black backgrounds that vibrate, shadows that vanish, accents that glare. Theming is the broader discipline of expressing one design system in multiple modes (light, dark, brand themes) from one set of semantic tokens. Both come down to driving everything through semantic tokens and redefining those tokens per mode. The specs below are concrete starting points.

Contents

1. Theming through semantic tokens 2. Dark mode is not an inversion 3. Backgrounds: never pure black 4. Elevation via lightness, not shadow 5. Text: never pure white 6. Desaturating accents for dark 7. Borders, icons, and charts in dark 8. Mode switching mechanics 9. Dark mode and theming slop tells 10. Token set 11. References (inspiration)

1. Theming through semantic tokens

A theme is a set of values bound to semantic token names. Components reference semantic tokens (--color-bg, --color-surface, --color-fg, --color-muted, --color-border, --color-accent, --color-accent-fg, plus elevation and state tokens), never raw values. To add dark mode or a brand theme, redefine those same semantic tokens under a selector (.dark, [data-theme="..."]) or media query; nothing in the components changes. This is the three-layer discipline from adapters.md (primitive, semantic, component) applied to modes. The dark palette is a sibling of the light one, authored deliberately, not derived by inversion.

2. Dark mode is not an inversion

Light mode's job is legibility on a bright, high-reflectance surface. Dark mode's job is to manage contrast so text is readable but not harsh, and color is vivid but not aggressive, on a low-luminance surface. The same hex values behave differently on dark: light text on dark at full contrast can shimmer and fatigue, saturated accents glare, and pure black plus pure white is the harshest possible pairing. Design the dark palette for its own context.

3. Backgrounds: never pure black

Base the darkest surface on a very dark gray, not #000. A common base sits around 8 to 12 percent lightness (Material recommends roughly #121212; the 0x12 to 0x16 range is typical). Pure black causes halation (text appears to vibrate, worse for readers with astigmatism), shows OLED black-smear during scrolling, and leaves no room to express elevation by lightening surfaces. A near-black base, often tinted very slightly toward the brand hue, reads more intentional and warmer.

4. Elevation via lightness, not shadow

On dark, shadows barely register, so elevation is expressed by making higher surfaces lighter, not by drop shadows. Build an elevation ramp in lightness: base around L10, cards and raised surfaces L14 to L16, popovers and modals L18 to L20, each step roughly plus 3 to 4 L. Material models this as a translucent white overlay whose opacity grows with elevation (about 5 percent at the lowest raised level up to about 16 percent at the highest). The practical rule: the closer a surface is to the user, the lighter it is. Reserve actual shadows for genuine floating elements, and keep them subtle.

5. Text: never pure white

Body text on dark should be an off-white, not #FFF, to reduce glare and halation (around rgba(255,255,255,0.87) for primary text, lower opacities for secondary and disabled). Maintain the contrast tiers (primary, secondary, disabled) by stepping opacity or lightness, the same hierarchy logic as light mode.

6. Desaturating accents for dark

Saturated colors that work on white glare on dark. Lighten and desaturate accents for the dark theme: blues and cyans desaturated noticeably, reds and oranges slightly, greens nudged toward teal, and bright yellows usually redesigned toward amber. The principle: pick a lighter, less-saturated sibling of the light-mode accent rather than reusing the same value. Verify every text-on-surface and accent-on-surface pair still meets contrast (see accessibility.md). OKLCH makes this easy: raise L, lower C, keep H (see color-oklch.md).

7. Borders, icons, and charts in dark

Borders are lighter than the surface in dark, not darker. Icons should use currentColor so they follow the text color and do not disappear. Charts: desaturate series by roughly 15 percent, keep at least a 20 percent luminance gap between adjacent series so they remain distinguishable, and drop gridlines to white at 5 to 10 percent opacity.

8. Mode switching mechanics

Drive mode from a class or data attribute on the root plus prefers-color-scheme for the default. Do not animate a transition on the theme switch; transitioning every color at once is janky and slow, so suppress transitions during the swap (libraries like next-themes handle this). Respect the user's system preference as the default and remember an explicit override. Test both modes against the same accessibility bar; a palette that passes in light can fail in dark and vice versa.

9. Dark mode and theming slop tells

• Pure black (#000) backgrounds and pure white (#FFF) text.
• A straight inversion of the light palette.
• Drop shadows used for elevation on dark (where they do not read) instead of lightness steps.
• Glowing colored box-shadows by reflex (cyberpunk-by-default) when the brief is not neon.
• Fully saturated light-mode accents reused unchanged on dark, glaring.
• Borders darker than the surface in dark mode.
• A visible color-transition animation when toggling theme.
• Raw values scattered in components so only one mode can be themed.

10. Token set

:root {
  /* Light (semantic) */
  --color-bg: oklch(0.99 0 0);
  --color-surface: oklch(0.97 0.005 250);
  --color-fg: oklch(0.22 0.01 250);
  --color-muted: oklch(0.55 0.01 250);
  --color-border: oklch(0.9 0.005 250);
  --color-accent: oklch(0.55 0.16 250); /* example brand hue */
  --color-accent-fg: oklch(0.99 0 0);
  /* Dark elevation ramp */
  --elev-0: oklch(0.16 0.01 250);
  --elev-1: oklch(0.2 0.01 250);
  --elev-2: oklch(0.24 0.01 250);
}

.dark,
[data-theme="dark"] {
  --color-bg: var(--elev-0); /* near-black, not #000 */
  --color-surface: var(--elev-1); /* raised = lighter */
  --color-fg: oklch(0.95 0 0); /* off-white, not #FFF */
  --color-muted: oklch(0.7 0.01 250);
  --color-border: oklch(0.3 0.01 250); /* lighter than surface */
  --color-accent: oklch(0.72 0.12 250); /* lighter, desaturated sibling */
  --color-accent-fg: oklch(0.16 0.01 250);
}

/* Suppress transitions during the theme swap */
.theme-switching * {
  transition: none !important;
}

11. References (inspiration)

• Material dark theme guidance: the #121212 base, the white-overlay elevation model, and the desaturation rationale.
• Radix dark color scales: ready-made, contrast-tuned 12-step dark scales (see color-oklch.md) so you do not hand-roll elevation and state steps.
• Apple dark mode (HIG): system semantic colors, elevation through material and lightness, and the principle that dark is a designed mode, not a filter.

DESIGN.md output

Everything this skill produces lives in a single DESIGN.md at the project root. It is the durable source of truth for the design system: the discovery context, the committed aesthetic, the typography and color systems, the tokens, the spacing/radius/shadow rules, component conventions, and the slop-audit result. Code (token-core.css, the Tailwind or shadcn adapter, components) is generated from DESIGN.md, not the other way around.

Why a file

• Persistence: the design system survives across sessions and contributors. A new session reads DESIGN.md instead of re-running discovery.
• Single source of truth: tokens live in one place; the CSS/adapter is a projection of it.
• Reviewable: the rationale sits next to the values, so choices can be checked and changed deliberately.

Lifecycle

1. On any UI task, first check for DESIGN.md at the project root (and common locations like docs/). 2. If it exists: read it, honor its tokens, skip questions it already answers, and extend it. Do not re-originate a theme. 3. If it does not exist: run discovery, Phase 1, and Phase 2, then write DESIGN.md before or alongside building components. 4. After the self-audit, append the audit result and any fixes to DESIGN.md and bump the changelog. 5. Keep token-core.css and the chosen adapter in sync with the Tokens section; if they drift, DESIGN.md wins.

Template

Write DESIGN.md using this structure. Fill every section; use OKLCH with a hex fallback for color. Keep it dense and specific, no vague guidance, no em dashes.

# DESIGN.md - [Project name]

## Context (from discovery)

- Artifact type: [landing | pricing | SaaS app | dashboard | ecommerce | marketplace | mobile app | AI/chat | email | blog/editorial | onboarding/auth | settings/admin/CMS | deck | docs/API ref | portfolio | other (see artifact-types.md)]
- Positioning: [corporate | creative | technical | luxury | playful | utilitarian]
- Audience: [who] | Primary action: [the one outcome]
- Adjectives: [3 to 5]
- Visual word translations: [adjective -> concrete visual move, one line each]
- Aesthetic essence (3 words): [x, y, z]
- Single-minded proposition: [the one impression to leave]
- Archetype (optional): [Hero | Sage | ... ]
- References: admire [1 to 3, and what specifically]; avoid [1 to 2]
- Mode: [light | dark | both] | Density: [airy | balanced | dense]
- Constraints: [stack, accessibility bar, content volume, must-keep/avoid]

## Aesthetic

- Direction: [named theme, catalog style, or bespoke]
- Defining trait: [the structural rule that organizes everything]
- Signature move: [the single most memorable detail]

## Typography

- Display: [family] | source: [Fontshare/Google/foundry] | license: [OFL/...]
- Body: [family] | source | license
- Mono (if used): [family]
- Scale: ratio [e.g. 1.25 Major Third], base 16px | step | size | line-height | use | |------|------|-------------|-----| | display | [px] | [n] | hero | | h1 | [px] | [n] | page title | | h2 | [px] | [n] | section | | body | 16px | 1.6 | text | | small | 14px | 1.5 | meta |
- Weights: [e.g. 400/500/700] | Measure: 65-75ch | Tracking notes: [...]

## Color

- Strategy: [appropriateness note + how it differs from the indigo default]
- Distribution: 60 neutral / 30 brand / 10 accent
- Palette (role -> OKLCH | hex):
  - bg: oklch(...) | #...
  - surface: oklch(...) | #...
  - fg: oklch(...) | #...
  - muted: oklch(...) | #...
  - border: oklch(...) | #...
  - accent: oklch(...) | #...
  - accent-fg: oklch(...) | #...
  - success / warning / error: oklch(...) | #...
- Dark mode overrides (if both): [bg, fg, border, ...]

## Spacing, radius, shadow

- Spacing base: [4px | 8px], scale: [1,2,3,4,6,8 ...]
- Radius: [<= 2 values, e.g. 2px and pill]
- Shadow approach: [defined edge OR soft elevation, not both] -> [the rule]

## Layout and composition

- Grid: [12-col | modular | bento | editorial] | gutters/margins: [...]
- Spacing rhythm: [tight-within / loose-between rule]
- Signature layout move: [the one brief-specific composition decision]
- Density: [airy | balanced | dense] | Scanning: [F | Z]
- Responsive: [mobile-first | desktop-first] | breakpoints: [...]

## Components and states

- Button hierarchy: [primary filled / secondary outlined / tertiary text], states [hover/active/focus/disabled/loading]
- Inputs: [label style, validation timing, error pattern]
- Tables: [alignment, tabular-nums, separators, density]
- Overlays: [popover/sheet/modal usage, focus trap+return]
- Empty / loading / error: [the pattern for each]
- Focus ring: [box-shadow, accent, offset]

## Motion

- Duration scale: [instant/fast/normal/slow/sheet ms]
- Easing: [--ease-out, --ease-in-out, --ease-sheet values]
- What animates: [transform/opacity only] | reduced-motion: [fade swap]
- Signature motion (if any): [...]

## Iconography

- Set: [Phosphor | Tabler | custom | customized default] | grid: [24px] | stroke: [px] | caps/joins: [...] | radius match: [yes]

## Imagery and illustration

- Mode: [product screenshots | photography | illustration | device | mix]
- Rules: [lighting/grading | illustration spec | device technique]
- Avoid: [category stock cliches, AI fingerprint, corporate-Memphis]
- Text-over-image contrast: [the guarantee]

## Dark mode (if in scope)

- Base bg: [near-black L] | fg: [off-white] | elevation ramp: [L steps]
- Accent (dark): [lighter desaturated sibling] | border: [lighter than surface]

## Accessibility

- Contrast: [AA verified both modes] | Focus: [visible, managed]
- Keyboard: [fully operable] | Targets: [>=24px, 44 preferred]
- Color independence: [yes] | Reduced motion: [yes] | Notes: [...]

## Tokens (source of truth)

\`\`\`css :root { --font-display: ...; --font-body: ...; --font-mono: ...; /_ scale, spacing, radius, color in OKLCH _/ } @media (prefers-color-scheme: dark) { :root { /_ overrides _/ } } \`\`\`

- Adapter: [plain CSS | Tailwind v4 @theme | shadcn semantic tokens] (see adapters.md)

## Cards and surfaces

- Cards/surfaces: [border XOR shadow, radius, padding] | nesting: [avoid cards-in-cards]

## Slop audit

- Date: [date] | Result: [pass | fixed N tells]
- Notes: [tells caught and corrected; craft-layer and accessibility gate result]

## Changelog

- [date]: [what changed and why]

Notes

• Express colors in OKLCH with a hex fallback so the file is both modern and portable; add CMYK/Pantone only if print is in scope.
• Keep DESIGN.md framework-agnostic in the Tokens section; the adapter line records which stack projection is in use.
• If the project already uses a different design-system file (a Tailwind config, a tokens.json, a vibes visual-direction doc), reconcile into DESIGN.md as the human-readable source of truth and note the link.

Design theory

The mechanisms behind every later choice. Read this once so the rest of the skill is reasoning, not rule-following. None of these are aesthetics; they are the physics of perception and interaction. When a layout, component, or motion decision feels arbitrary, one of these laws usually has the answer.

Contents

1. Visual hierarchy (the master tool) 2. Gestalt principles applied to UI 3. CRAP: contrast, repetition, alignment, proximity 4. Signal vs noise and data-ink (Tufte) 5. Affordances and signifiers (Norman) 6. Interaction laws: Fitts, Hick, Jakob, Tesler, Miller 7. How these map to slop

1. Visual hierarchy (the master tool)

Hierarchy is the single most effective lever for making something feel designed (Wathan and Schoger, Refactoring UI). The reader's eye should land on things in the order of their importance. Build hierarchy from five controls, in rough order of strength: size, weight, color/contrast, spacing, and position. The common beginner mistake is making everything loud: bold the heading, color the label, box the section, shadow the card. Loud-everywhere is flat. To emphasize one thing, de-emphasize its neighbors. To make secondary text recede, lower its contrast rather than shrinking it to illegibility. Establish three tiers (primary, secondary, tertiary) and assign every element to one. Design in grayscale first so hierarchy comes from size/weight/space, then add color last and sparingly; if it reads in grayscale, color is decoration you can afford, not a crutch you depend on.

2. Gestalt principles applied to UI

The brain groups visual input automatically. Use these to imply structure without drawing boxes, borders, and arrows (which add noise). This is why a well-spaced bento grid reads as organized with no dividers at all.

• Proximity: elements placed close together are read as a group. The fastest way to relate a label to its input, or a caption to its image, is to move them closer and push everything else away. Proximity is stronger than a shared border.
• Similarity: elements that share a trait (radius, color, shadow, shape) are read as belonging to the same class. Consistent component styling is what makes a UI feel like one system. Breaking similarity deliberately (one differently-styled button) is how you signal "this is the primary action."
• Common region: a shared background or container groups items even when far apart. A subtle surface color groups a section more quietly than a 1px border.
• Enclosure: a border or background encloses and separates. Use the lightest enclosure that works; a faint surface beats a hard border beats a heavy shadow.
• Continuity: the eye follows lines and alignment. Aligned edges create invisible rails that guide scanning.
• Closure: the brain completes implied shapes. You can suggest a card or grouping with alignment and spacing alone.
• Pragnanz (simplicity): the brain prefers the simplest interpretation. Reduce the number of distinct visual ideas per screen.

3. CRAP: contrast, repetition, alignment, proximity

Robin Williams' four principles, the most portable checklist in design.

• Contrast: if two elements are not the same, make them very different. Timid contrast (16px vs 18px, gray vs slightly-grayer) reads as a mistake. Push differences hard.
• Repetition: repeat visual motifs (a radius, a spacing unit, an accent, a type treatment) to unify and to teach the user the system.
• Alignment: nothing should be placed arbitrarily. Every element aligns to something. Strong left or grid alignment beats centered-everything.
• Proximity: group related items, separate unrelated ones, using space. A layout that passes CRAP rarely looks like slop, because slop is usually weak contrast plus arbitrary placement plus uniform spacing.

4. Signal vs noise and data-ink (Tufte)

For dashboards, data tools, and any dense interface: maximize the data-ink ratio. Every pixel that is not conveying information is a candidate for removal. Tufte's targets: erase non-data ink (heavy gridlines, chart borders, backgrounds, 3D effects, redundant labels), erase redundant data-ink, and revise. Concretely: prefer light row separators to heavy table borders, drop chart junk, label directly instead of with a legend when possible, and ask "what one decision does this view support?" before adding anything. One question per visualization. Density is fine; noise is not. A dense dashboard with a high data-ink ratio reads as expert; a sparse one full of decoration reads as a toy.

5. Affordances and signifiers (Norman)

From The Design of Everyday Things. An affordance is a possible action between an object and an actor (a button can be pressed). A signifier is the perceivable cue that reveals where and how to act (the button looks pressable: it has a fill, an edge, a label, a hover state). Norman's later clarification: most of what UI designers casually call "affordances" are really signifiers. The practical rule: interactive elements must signify their interactivity (cursor, contrast, affordance of depth or underline), and the system must give immediate feedback that the action registered. Flat design that strips all signifiers (no hover, no edge, link-colored-as-body-text) creates discoverability failures: users cannot tell what is clickable. Discoverability and feedback are the two qualities to protect.

6. Interaction laws: Fitts, Hick, Jakob, Tesler, Miller

• Fitts's Law: time to acquire a target grows with distance and shrinks with target size. Make primary actions large and place them where the cursor or thumb already rests. Screen edges and corners behave as infinitely large targets (the pointer cannot overshoot them), which is why macOS menu bars and full-bleed mobile tab bars work. Tiny far-away targets are a usability tax.
• Hick's Law: decision time grows logarithmically with the number and complexity of choices. Chunk long menus, use progressive disclosure, and default to a recommended option. A wall of equally-weighted options is slow; a clear primary plus a few secondaries is fast.
• Jakob's Law: users spend most of their time on other products, so they expect yours to work like those. Favor convention (logo top-left returns home, cart icon top-right, underlined links, search where search lives) unless novelty buys a real advantage. Deslop is not the same as breaking conventions; break the visual median, keep the interaction conventions.
• Tesler's Law (conservation of complexity): every system has an irreducible amount of complexity. The question is who absorbs it. Push it onto the product (smart defaults, inference) rather than the user (more fields, more decisions).
• Miller's Law (7 plus or minus 2): working memory is small. Chunk information; do not present long undifferentiated lists or forms. This underwrites grouping, stepped flows, and summary rows.

7. How these map to slop

Slop is usually a theory failure, not a taste failure. The AI-default look is flat (no signifiers), uniformly spaced (no proximity grouping), centered (no alignment intent), low-contrast (timid hierarchy), and decoration-heavy (low data-ink). Naming the violated principle is faster than naming the visual tell: "this section has no hierarchy" or "these cards have no proximity grouping" is more actionable than "make it less generic." When auditing, ask which principle each weak area violates, then fix the principle.

Discovery

The intake that produces the design system. Strategy drives design: resolve what, who, and the adjectives before any visual. The question bank is generous on purpose; the asking is selective.

Contents

1. Asking questions (CRITICAL) 2. Protocol 3. The five discovery phases 4. Commit to words 5. Core question bank 6. Personality sliders 7. Personality-to-token translation 8. Which questions matter, by artifact type 9. System governance (constant vs variable) 10. Human-sounding writing protocol 11. Reference transposition recipe

1. Asking questions (CRITICAL)

ALWAYS use the AskUserQuestion tool for ANY question to the user. Never ask questions as plain text output. The tool gives a guided, interactive experience with structured options the user can answer in one tap. Every single user question must go through this tool. (On claude.ai use ask_user_input_v0.) Use it to gather preferences before deciding, present options with clear tradeoffs, validate direction before building, and confirm outputs before finishing. Never make a significant design decision without user input; the result belongs to them. Discipline on top: batch related questions, give 2 to 4 concrete options each, infer from context first and confirm inferences, ask only the high-signal subset. Do not interrogate.

2. Protocol

1. Classify the artifact type (see artifact-types.md); type decides which questions matter. 2. Infer from context (prompt, domain, repo, existing brand) and state inferences so they are cheap to correct. 3. Ask the high-signal subset through the question tool. Offer to go deeper rather than front-loading. 4. Commit to words before designing. 5. Gather references: 1 to 3 sites admired (and what specifically), 1 to 2 to avoid, key competitors. If none and direction is unclear, web-search current strong examples of the type plus positioning and transpose.

3. The five discovery phases

Adapted from brand visual-direction practice. Run lightly for small jobs, fully for client work.

1. Synthesize strategy: extract purpose, values, positioning, audience, and the competitive (and AI-default) landscape to differentiate from. 2. Commit to words: 3 to 5 adjectives, a visual word translation for each, a single-minded proposition, and the 3-word aesthetic essence (see below). 3. Translate strategy to visual language: for each adjective and any archetype quality, define the concrete visual expression (type, color, space, motion, imagery). 4. Comprehensive direction: decide overall aesthetic and references, then type system, color strategy, spatial composition, motion, and supporting details. 5. System governance: define what stays constant and what may vary, the hierarchy of elements, and application priorities.

4. Commit to words (do before any visual)

The highest-leverage step.

• Lock 3 to 5 brand adjectives. These translate directly into type, color, density, and motion.
• Write a one-line visual word translation per adjective: adjective -> concrete visual move. Example: "precise" -> tight grid, monospace numerals, hairline rules; "warm" -> humanist sans, soft saturated accent, generous spacing; "bold" -> oversized display, high contrast, one loud accent.
• Distil a 3-word aesthetic essence capturing the overall feel (for example "quiet, technical, exact" or "bold, editorial, loud").
• State a single-minded proposition: the one impression the UI must leave. Only after the words are locked, move to Phase 1 of the skill.

5. Core question bank (ask the relevant subset, via the tool)

• Artifact and primary action: what is this, and what single outcome matters most (sign up, buy, explore data, read, book a demo, present)?
• Audience: who uses it; B2B/B2C/developer/internal; technical sophistication; decision-maker or end-user; demographics if relevant?
• Positioning: corporate/enterprise, creative/design-forward, technical/developer, luxury/premium, playful/consumer, or utilitarian/internal? (See per-type variants in artifact-types.md.)
• Personality: 3 to 5 adjectives, or place on the sliders below.
• Archetype (optional): Hero, Sage, Outlaw, Innocent, Explorer, Caregiver, Creator, Ruler, Magician, Lover, Jester, Everyman. Drives both color and type mood.
• References: sites admired and why; aspirational brands; sites to avoid; direct competitors.
• Brand assets: existing logo, colors, fonts, or greenfield? Must-keep and must-avoid constraints?
• Mode and constraints: dark, light, or both? Accessibility bar? Content volume (sparse vs dense)? Stack? Fidelity (prototype vs production)? Timeline/budget?

6. Personality sliders (fast structured intake)

Each end pulls concrete token moves. warm <-> cool; playful <-> serious; traditional <-> innovative; minimalist <-> expressive; formal <-> conversational; bold <-> restrained; dense <-> airy.

7. Personality-to-token translation

Built on Aaker's five brand-personality dimensions plus the sliders. Turn adjectives into a token set.

Slider deltas (stack on top): more expressive -> add a second typeface, more color, more motion. More minimal -> fewer colors, more whitespace, one family across weights. More playful -> rounder shapes, brighter accent, micro-interactions. More serious -> tighter grid, restrained palette, sharper shapes. Denser -> smaller spacing and type steps. Airier -> larger spacing, fewer elements per view.

8. Which questions matter, by artifact type

• Landing page: primary conversion action; positioning (corporate/creative/technical); the single most important proof or differentiator; references.
• SaaS app: core daily task and frequency; user expertise; data/control density; light/dark; existing design system.
• Dashboard: the specific decision it supports; type (operational/analytical/strategic); top 5 to 9 metrics; cadence and device.
• Ecommerce: product type and price point; trust posture; primary objection to overcome; brand maturity.
• Presentation: audience and setting (pitch, sales, internal, conference); narrative arc; live or read.
• Docs/content site: reading length; navigation depth; code-heavy or prose; brand tie-in.
• Portfolio/brand site: the one impression to leave; how design-forward; work to foreground.

9. System governance (constant vs variable)

Before building, decide what is fixed and what can flex, so the system scales without drifting:

• Constant: the type families, the core palette and accent, the spacing base unit, the radius and shadow approach, the signature move.
• Variable: layout per page/section, imagery, accent intensity within range, density per context.
• Hierarchy of elements: which tokens dominate (usually type and the accent), which support.
• Application priorities: where the system must be strongest first (hero, primary CTA, key screen).

10. Human-sounding writing protocol

If the skill also generates copy, avoid AI-writing tells. Avoid vocabulary like delve, tapestry, multifaceted, leverage, crucial, comprehensive, foster, harness, navigate, landscape, realm, beacon, pivotal. Avoid openers like "It's important to note", "In today's fast-paced world", "At its core", "Let me explain". Avoid uniform sentence lengths, excessive tricolons (rule of three), and em-dash-as-rhythm. Vary sentence structure instead. For French copy or deep cleanup, defer to the user's humanizer and humaniseur-fr skills.

11. Reference transposition recipe

When the user names a site to emulate, or you find one by search: extract its color relationships, type contrast and pairing, density, and one signature move. Borrow those into the token set; do not copy its layout. State what you are borrowing before coding.