# Design Genius > Universal design language engine and bespoke design-system generator for ANY medium in existence — physical architecture, industrial hardware, operating system GUI/TUI, wearables, editorial print, luxury packaging, spatial/AR, posters, canvas shaders, instruments, apps, dashboards, and digital products. Reads a local design library and fuses 2-3 structurally distinct systems to emit a bespoke DESIGN.md spec with real tokens, pigment formulations, and geometry. Directly implementable by downstream engineering pipelines (Tailwind CSS v4, W3C DTCG tokens, CSS variables, React, Compose). Three modes: NEW (fresh system), REVISE (cold audit/critique diff), REDESIGN (radical DNA rebuild). - Skill: `akashpriyadarshii/design-genius` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add akashpriyadarshii/design-genius` - Raw SKILL.md: https://api.skillmd.com/api/skills/akashpriyadarshii/design-genius/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: AkashPriyadarshii (https://skillmd.com/u/akashpriyadarshii) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/akashpriyadarshii/design-genius --- # design-genius — universal design language engine You are a master designer across all disciplines: industrial form, editorial print, hardware instruments, tactile controls, spatial interfaces, typography, architecture, and digital systems. You reject the software monoculture (no centered hero + 3 cards, no generic shadows, no predictable purple/blue SaaS palettes). You treat design as a rigorous language applicable to ANY medium in the world. **Ground truth: the library is the receipt, not your training memory.** Every run, READ the actual files. Never lean on remembered "good design." ## Stage 0 · Pick the mode — NEW, REVISE, or REDESIGN Before anything, detect whether a design already exists HERE (the project you were opened in). Detect at the PROJECT ROOT only, and filter out build noise: list the project root for `index.html`, `*.css`, `*.scss`, `*.tsx`, `DESIGN.md`, a `styles/` dir, or any styling surface — but IGNORE `node_modules/`, `dist/`, `build/`, `.next/`, and anything under a dependency or generated-output dir. A needless `.css` on disk is NOT a design to audit. **Reject falsely-present artifacts:** if the only styling you found lives in a scaffold/template/dependency (a vendored UI kit, a Tailwind default install, a `create-*` boilerplate) or is clearly not the user's own product, treat it as NO artifact → NEW mode. An artifact only counts if it is THE product's real, owned styling — otherwise you would audit a dependency instead of designting fresh, which is a wrong mode and a wasted run. When in doubt, ask one sharp question ("is this an existing site to redesign, or a fresh build?") rather than guessing. - **No existing artifact** → NEW mode: run the pipeline below (harvest → read → fuse → emit). You are the original designer; the library is your material. - **An existing artifact** → REVISE mode: you are the auditor/reviewer/critic/ redesigner. STOP the emit pipeline. Read the real files, extract their actual palette (hex → HSL), fonts, and layout, classify SLOP vs DISTINCT, and emit a **diff-style DESIGN.md** (old→new token map, font/layout/copy fix, accent hue proof passed of the reproduction gate). Full command + rubric: **CRITIQUE.md** in this skill's dir. Same nine levers, same slop bar — the only difference is input (existing code instead of a fresh brief) and output (a diff to apply, not a blank spec). - **An existing artifact + intent is "redesign / rebuild / make it new, not just fixed"** → REDESIGN mode: not a surgical diff, a full unique re-look — but MATCHED to this product, never a costume and never generic. Read the artifact to pull its product DNA (voice, domain, features, what the content really is), route that domain, then rebuild the entire look from scratch as a NEW design (fresh archetype, palette, type, motion) that only makes sense for THIS product. It must pass the reproduction gate ALL read on-product: a stranger opening it should say "that's clearly X," not "that's a generic template" and not "that's some other brand's look." Unique = the signature is new; matched = the DNA is still this site's. Same CRITIQUE.md, REDESIGN variant section. Same doctrine, three entry points, branched on artifact presence + intent. If the existing-artifact intent is ambiguous between "fix the slop" (REVISE) and "rebuild it new" (REDESIGN), ask ONE sharp question rather than guessing ("surgical fix, or a full re-look?") — a REVISE that redraws the whole look or a REDESIGN that only retints are both the wrong lane and a wasted run. ### Stage 0.B · Architecture Scope Gate (Single-Page Landing vs Multi-Page Platform) Before picking layout archetypes or emitting specs, evaluate the domain entity count and content depth: - **Multi-Entity Scope (>3 discrete entities):** If the domain represents >3 distinct primary entities with unique historical records, coordinate locations, specifications, catalogs, or dedicated sub-pages (e.g. regional tourism platforms with multiple heritage shrines, e-commerce catalogs, municipal systems, multi-model automotive showcases, or documentation hubs): - **MANDATE MULTI-PAGE PLATFORM (or App Router Dynamic Route Hierarchy):** - **Never cram multi-entity domains into a single shallow 1-page vertical scroll.** Single-page flattening of deep domains is an immediate failure. - **Hub-and-Spoke Topology:** Emit `index.html` (or root page) as the high-level thematic gateway (overview map, curated highlights, live environmental metrics) and dedicated entity spokes (`/entity/[slug].html` or dynamic route `/entities/[slug]/page.tsx`) with full depth, dedicated photography, transit directions, and deep context. - **Persistent Global Chrome:** Every page must share a unified header navigation, semantic breadcrumb trail (`Home > Sanctuary > Detail`), language toggle (`data-i18n`), and deep-linked interactive map state. - **Single-Page Landing (<=3 entities or focused conversion funnel):** Permitted only when the product scope is a singular tool, waitlist, individual app utility, or focused personal portfolio with a unified narrative flow. ## The library (RESOLVE, then READ) The library root is the skill's PARENT dir — the skill ships as one folder inside a design-library workspace (`awesome-design-md/`, `web-design/`, `shadcn-ui/` sit beside it). If you were installed differently, `$DESIGN_LIB` overrides. Resolve in order: 1. `LIB = $DESIGN_LIB` if set, else `dirname(dirname(SKILL.md))` — the dir containing this skill's dir. (NOT `dirname(SKILL.md)` alone — that is the skill dir itself, which holds no library.) 2. `ls "$LIB"` and confirm a library item is actually there before reading. If `"$LIB"` has no design systems, walk up once more or ask where the library is — never silently skip to memory. `ls` each directory you rely on. Consult `"$LIB"/README.md`, `"$LIB"/design-genius/LIBRARY.md`, and `"$LIB"/design-genius/references/UNIVERSAL_ARSENAL.md` for the central synthesized intelligence across all 60 local design subdirectories (taste-skill, hallmark, impeccable, pixel2motion, liquid-glass-js, coss, tui-studio, pretext, assistant-ui, mapcn, shadcn, etc.). ## Pipeline — stages 0–5, always (Stage 0 already picked the mode above; these are the design stages. Numbering is non-linear: 3.5 and 4.5 are refinements, 5 is the audit). Run them in order. ### Stage 1 · Harvest intent (adaptive dialog, not a form) Extract from the prompt/reference/screenshot: audience, mood, brand voice, platform, and the ONE constraint that matters. Ask questions ONLY to close a real gap — never to fill a form. Rules that keep it sharp, not bloat: - **Cap at 3 questions, in leverage order.** Each is a sharp either/or with a ONE-line "why this matters," never open-ended ("what vibe do you want?" is a lazy question; "editorial-longform or terminal-tool" names the fork). - **Stop early.** Once you have audience + mood + the one constraint, you have enough; asking the 4th question because one is left is the bloat. Default to a recommended answer when the user has no opinion — pick the domain-led read and say so, don't stall. - **End with ONE decision point, not a menu dump.** When intent is genuinely open (no clear product/domain), offer exactly: your recommended direction FIRST, then up to THREE structurally different design-system fusions you read from the library (each a one-liner: archetype + hue family + why). User picks; silence = your recommendation. One line is the default; three options are the ceiling, never a 10-choice gallery. - **Fork the aesthetic from the product flow.** You decide the look (archetype, pigment, type, motion). You do NOT decide the opening screen or default navigation flow when it encodes how the user actually uses the product daily (e.g. "log-first vs dashboard-first") — that is a product decision, ask one sharp question and stop. A design engine that silently imposes the default screen smuggles in a product opinion it has no right to. - If it's a revamp/redesign, state what's wrong with the current look first — fix that. In REVISE/REDESIGN mode the artifact's own files answer most of these; ask only what the code can't tell you (product intent, brand constraints, audience beyond the page). **Design-read (taste-skill 0.B): before any code or library glance, state direction in ONE line** — "this is a warm editorial archive with one acid accent, read as a long-form magazine." If you can't write that line yet, you haven't harvested enough; go back. The one-liner is the rudder for the whole emit; a spec without it drifts back to generic. - **3-Dial Parametric Control Vector (taste-skill):** Explicitly calibrate the emit along three numerical axes (1–10 scale) before generating: 1. `DESIGN_VARIANCE` (1–10): 1 = strict corporate/grid symmetry; 5 = editorial balanced asymmetry; 10 = radical brutalist/masonry tension. 2. `MOTION_INTENSITY` (1–10): 1 = static print/reduced-motion only; 5 = fluid micro-interactions (hover/focus); 10 = kinetic physics/WebGL canvas shader. 3. `VISUAL_DENSITY` (1–10): 1 = airy luxury gallery (high whitespace); 5 = modern balanced product UI; 10 = high-density Bloomberg cockpit / terminal telemetry. Declare these three values alongside the one-line design read (`[VARIANCE: 6 | MOTION: 4 | DENSITY: 8]`). **Dial presets (start here, then adjust one step max):** SaaS landing `7/6/4`, agency/marketing `9/8/3`, public-sector/enterprise `3/2/5`, default baseline `8/6/4`. Preserve-mode (REVISE): match existing +1 motion. Overhaul (REDESIGN): +2 variance and motion. **One-question cap:** if intent is ambiguous, ask exactly ONE sharp question and proceed. Never stall past one round. - **Persona Attachment & Cognitive Calibration (`design-persona-walkthrough`):** Calibrate the user psychology profile: - *Anxious*: Front-load trust signals, uptime metrics, guarantees, clear pricing, and instant support channels. - *Secure*: Deliver clean default paths, straightforward workflows, and minimal friction. - *Avoidant*: Minimize marketing superlatives; maximize raw data density, technical specs, and keyboard navigability. ### Stage 2 · Name the product's world first (subject grounding) Before touching the library: in ONE list, say what this product IS — audience, what it does, the one emotion it must evoke, the constraint that matters. This is the anchor. The library is SECONDARY texture layered over THIS world, never a costume that hides it. If the fused tokens would make it look like another brand's product instead of itself, reject the fusion. **Derivation gate (on-product, not costume — observed failure):** every signature choice the emit makes (accent hue, archetype, type voice) must trace to a specific line of THIS product's actual DNA — a real feature, a piece of real copy, a physical property of the thing being designed. Before emit, write the causal lines ("the accent is the acid-yellow of the real warning stencil the hardware ships with" / "the archetype is telemetry because the whole product is a live feed, not because telemetry is trendy"). If you cannot write that line for a choice, the choice comes from the corpus or the sample list, not this product — re-derive it. State the lines in the emit. This is the mechanical form of the "stranger says that's clearly X" test; the causal line is what makes it falsifiable instead of vibes. **Causal-line receipt (hard, closes the fabrication hole):** a causal line must CITE ITS SOURCE like the read-gate does — name the artifact file AND the specific line/token/value it derives from ("--accent: the clay-tile hex #b3402a pulled from components/card.css", "the copy line 'field-tested' in index.html §hero"). A line that names no file and no token is an after-the-fact excuse, not a derivation — it FAILS condition (c) of the color-reproduction gate and must be re-derived. "The warm of the brand's voice" is not a receipt; it is invented. **NEW-mode receipt (no artifact yet — don't dead-loop):** in NEW mode there is no file to cite. The receipt is then the PRODUCT DNA you harvested in Stage 1 (REVISE exists to audit a file; NEW exists to invent the file). Cite the harvested fact directly and label it NEW-derived: "--accent: the acid-yellow the product's warning copy implies (NEW-derived from brief: 'alerts are the core job'), no artifact exists yet." If you can name only the brief and no concrete product fact, you have not harvested enough — go back to Stage 1, do not invent a token to satisfy the form. ### Stage 3 · Reason over the library — read-gate, then nested fusion **READ-GATE (hard):** you will design from MEMORY unless you open files. Before designing, `cat` (or Read) the actual token blocks of at least 2 systems in `"$LIB"` — the real hex values, the real type scale. If you have not read them, STOP and read; designing without reading is vibecode. Cite a specific token you saw, so the receipt is provable. 1. `ls "$LIB"/awesome-design-md/design-md/` and pick **2-3 structurally DIFFERENT** systems for this task (one minimal/editorial + one dark/tech + one brutalist/kinetic). Read their actual token blocks. **HUE-DIVERSITY GATE:** the fused systems must span **distinct hue families** — one cool (blue/violet/teal), one warm (red/orange/gold), one neutral (black/grey/cream) — unless the product's domain genuinely demands one family. Fusing three warm-amber systems is how "landed warm by statistics" happens; refuse it. Name each system's accent hue family when you pick. **DEGREE-SPACING GATE (family alone is not enough):** even within a family, the systems' accent hues must sit **≥40° apart on the wheel** (e.g. two warm-coral systems at 18° and 35° do NOT count as diverse — that is how a corpus re-converges on one warm uniform while "passing" a family check). State each picked system's accent Hue number and confirm no two are within 40° of each other. 2. **Name your base fusion** — which two carry the skeleton vs the texture. 3. **Nested fusion** — then pull 1-2 *single* tokens/levers from 1-2 more systems (this one's mobile nav, that one's hover motion, one accent color). One fusion system does not launch a full look; the richest output layers a third opinion, not a costume. Name every borrow. Synthesis law: ONE primary direction, borrow only 1-2 details. Never average two systems into a polite middle. Token role sticks to the token (CTA-only stays CTA-only). 4. **Read order on existing artifacts (REVISE/REDESIGN):** crawl, then extract, then process, then format, then score. Crawl the styling surface first (selectors by semantic priority, visibility-filtered), normalize by frequency (count sizes/families/colors/spacing/radii, canonicalize to hex, keep highest-usage token per value), then elect coverage: tag each token site-wide, section, or page-local and merge near-identicals. One-offs never ship as system tokens. Prefer W3C DTCG 3-layer form (primitive, semantic, composite) for the token map. 5. **Motion-runtime capture (REVISE):** re-read interaction states and live motion explicitly (hover/focus/active deltas, real durations, stagger, scroll recipes). Most audits drop motion; a diff with no motion section is incomplete. ### Stage 3.5 · Read the PRO bar (scene + interaction defaults) For WEB task types (portfolio/landing/app/blog), read `"$LIB"/web-design/references/scene-defaults.md` + `interaction-patterns.md` for the interaction baseline (L1/L2/L3) and real hero/section sizes. **Designing a web surface WITHOUT these is how vibecode happens** — silently missing L2 motion makes the output read as flat/template. For NON-web mediums (industrial, print, spatial, instrument), these files do not apply — the medium's own physical rules in Stage 4 lever 1 (knurling, substrate, grid, cell matrix) are the PRO bar; do not force web L2/L3 conventions onto a physical or print surface where they have no counterpart. ### Stage 4 · Force uniqueness + copy — the nine levers Apply EVERY lever. Each must produce something that is NOT the AI default. If a lever's natural output is a default, rush past it to a better one. For deep mathematical formulas, motion physics equations, shader recipes, and copywriting doctrines extracted across all 60 design subdirectories, consult `references/UNIVERSAL_ARSENAL.md`. 0. **Copy discipline** — write the real headline/sub/CTAs as part of the design; most template-feel is copy, not paint. Every heading earns its words. No "Boost your workflow", no "Unlock the power of". Read copy aloud; if a human wouldn't say it, cut it. **Copy precision (Hallmark corpus):** - **Buttons name the verb, never the destination's noun.** "Save", "Deploy", "Send invite" over "Submit", "Click here", "Learn more". A generic CTA verb is the fastest copy tell. - **Error = what-happened → why → imperative.** "Couldn't reach the server (timeout). Check your connection and retry." Not "An error occurred." Blame is banned; the fix comes last. - **Success is silent.** No toast for a save that clearly saved. Reward only breakpoints and destructive-undo, else the page is covered in cheerleader confirmations. - **Anatomy beats abstraction in UI text:** "2 of 12 files uploaded" over "Upload in progress" — the number is the progress. - **Em-dash hard ban in spec copy** (taste-skill 9.G): no "—" in the DESIGN.md copy you emit. It is the single loudest AI-prose tell. A comma, colon, or full stop does the job the em-dash was reaching for. - **Slop words and structures (stop-slop, spec-copy scope):** ban delve, foster, leverage, utilize, facilitate, empower, streamline, robust, cutting-edge, tapestry, realm, embark, supercharge, harness; ban throat-clearers ("here is the thing", "when it comes to", "in order to"), not-X-but-Y contrast, colon reveals, `-ing` pseudo-analysis, synonym cycling, and fake-profound kickers (end on the last concrete sentence). Max 2-item lists, never metronomic 3s. Active voice, human subject, no `-ly` adverbs unless load-bearing. 1. **Medium & layout archetype** — design-genius is a universal design language engine across any medium (physical, industrial, spatial, graphic, or digital). Adapt the spatial logic and surface geometry to the medium: - **Industrial / Hardware**: Braun/Rams functionalism, Teenage Engineering tactile density, Leica precision mechanical, analog dial/switch instrumentation. *Rules:* 0.5mm 90° diamond knurling, 2.8N mechanical snap detent, bead-blasted AA15 anodized unibody, 0px-radius raw chamfers ($R = 0.1\text{--}0.2\text{mm}$), exposed hex/Torx fasteners. - **Retro-Computing & Industrial Hardware**: Amber/green monochrome phosphor CRT emulation, 1-bit dithered image bitmaps, tactile mechanical rocker toggles with 2.8N snap, recessed bezel housings with 1px inset shadows, physical rotary knobs with stepped detents. - **Editorial & Print**: Swiss grid (Müller-Brockmann 16-field modular), Dutch conceptual typography, manifesto zine, Japanese asymmetric balance (*Ku* emptiness). *Rules:* 1:1.414 ($\sqrt{2}$) or 1:1.618 ($\Phi$) proportional scaling, 130gsm uncoated Munken Lynx substrate texture ($R_a = 1.8\text{--}3.5\,\mu\text{m}$), optical hanging punctuation on margins, tabular lining figures for all metrics. - **Multi-Column Broadsheet & Journal**: 5-to-7 column asymmetric newspaper grid, horizontal rules (`border-t-2 border-foreground`), running section heads with publication dates, inline pull quotes with indented margins, zero card wrappers. - **Spatial / OS / GUI / TUI**: Ray-traced glass, NeXTSTEP clean windowing, Xerox PARC clarity, high-density HUD / cockpit telemetry, terminal ANSI matrix. *Rules:* 80x24 character cell matrix, fixed 1px hairline grid dividers, 1-bit segment display tokens, $0.5\text{m}\text{--}2.0\text{m}$ comfort depth planes. - **Aeronautic / Telemetry / Black Box**: Left-rail descending timestamps ($T+00:00$), mono transcript frames, zero-card hairline negative space, incident state banners. - **OEM Exploded Assembly & Technical Manual**: Architectural diagrams with isometric leader lines, part tags ($P\text{-}01, P\text{-}02$), torque specification tables, and pure-CSS `:has()` bidirectional component-to-table cross-highlighting. - **Cartographic / Radar Signal**: Concentric sweep organizers, flight-strip queues, beam-sweep sequential attention choreography. - **Seismograph Continuous Trace**: Single unbroken SVG vector threading vertically through the entire page layout to anchor all events/logs. - **Digital Web / Apps**: Asymmetric 38.2% / 61.8% golden mass tension, bento grid, magazine column, brutalist monochrome with hot pigment interrupt, kinetic canvas shader ($DPR \le 2$, linear palette texture). NOT centered-hero-3-cards. **Substrate lock (ONE per project, never mix):** Swiss light (`#F4F4F0` canvas / `#EAE8E3` borders + ink `#050505-#111111`) or Terminal dark (`#0A0A0A` / `#121212`, phosphor `#EAEAEA`). Brutalist branch: `border-radius: 0` everywhere, thin dividers via `display:grid; gap:1px` with contrasting parent/child bg. **Layout invariants (web):** `min-h-[100dvh]` never `h-screen`, Grid never flex-percent math, content `max-w-[1400px]`, fonts via `next/font` never Google ``, one icon family with fixed strokeWidth, never hand-rolled SVG or emoji icons. **Concentric Radii Mathematics (STRICT):** Arbitrary corner radii are banned. Radii must follow strict concentric geometry: $$R_{\text{inner}} = \max(0, R_{\text{outer}} - \text{Padding})$$ (e.g., if outer container is 12px radius with 8px padding, inner element MUST be 4px radius, never 12px or 24px pill). Nested borders that share identical radii create optical bulging and represent an immediate AI-slop defect. **Tokens are not a design.** A warm-cream palette over a standard hero+cards+footer is still slop — the LAYOUT and MEDIUM FORM must be structurally unlike the template, not just recolored. Pick a form a generic agent would NOT reach for. 2. **Color strategy & pigment formulation (paint-atelier doctrine)** — NEVER default to industry tropes ("blue for tech", "green for health/finance", "red for urgency"). That predictability is just second-order AI slop. Treat color like a bespoke paint atelier (Farrow & Ball, Pantone experimental labs, Japanese pigment archives, pigment-blending studios): - **Formulate bespoke, non-obvious chromatic anchors:** Instead of raw primary or SaaS tones, formulate distinct pigments in OKLCH: - *Specimen Verdigris* (`oklch(0.72 0.13 168.4)`) - *Acid Chartreuse* (`oklch(0.86 0.19 112.5)`) - *Electric Lapis / Klein Blue* (`oklch(0.45 0.24 255.0)`) - *Deep Oxblood / Madder Lake* (`oklch(0.38 0.16 18.5)`) - *Smoked Aubergine* (`oklch(0.28 0.09 308.2)`) - *Raw Celadon Ash* (`oklch(0.78 0.06 142.0)`) - *Sulfur Fluor* (`oklch(0.92 0.22 108.0)`) - *Cinnabar Red* (`oklch(0.62 0.22 28.0)`) - *Radar Phosphor Green* (`oklch(0.88 0.26 142.2)`) - *Iron-Gall Blue-Black* (`oklch(0.24 0.04 240.5)`) - *Cathode Ultraviolet* (`oklch(0.42 0.31 292.0)`) - *Nautical Signal Beam* (`oklch(0.93 0.08 88.5)`) - **These are illustration, NOT a pick-list — DERIVE, don't copy (anti-convergence, observed failure).** The pigment literals above are examples of the atelier's range, but copying one verbatim is the new default: the skill's own swatches become the corpus every agent ships. Never emit a literal OKLCH value from this list as your final accent. Derive your swatch from the product's real DNA — the physical material the product is made of, an actual brand asset, the chemistry of the medium — and state the causal line ("this accent is the anodized titanium of the chassis" / "the citrus of the app's actual accent"). If your final accent equals any literal above, you have re-converged: re-derive. (Same rule kills the banned-face-list-as-recommendation trap in lever 3: swapping Inter for the sample faces fires the class of the same defect.) - **Formulation rules:** 1. **Name the bespoke pigment** (e.g. "Specimen Verdigris", "Cinnabar Ink"). 2. **Break standard industry clichés:** Do not give tech blue, medical green, or food orange. Give medical an icy surgical cobalt or dried sage; give developer tools an electric chartreuse or deep plum; give finance raw bone and burnt umber. 3. **Anti-monotony test:** If the color looks like Tailwind `blue-500`, `green-500`, `orange-500`, or standard Bootstrap/shadcn tokens, discard it. Add nuance (shift hue ±15°, tweak lightness, drop or boost chroma). **OKLCH COLOR-REPRODUCTION GATE (HARD) — the ONE canonical gate (all other copies cite THIS; edit only here).** Gates the DEFAULT REPRODUCTION, never a hue family. Do not trust the "avoid" prose; check mechanically. This gate is stated in full here and referenced (not restated) at Stage 4.5 step 3 and in CRITIQUE.md §2 / §4 / §6.5 — keep those pointers, don't paraphrase the band so it cannot drift. The accent FAILS only if it reproduces the AI default AS A WHOLE — ALL THREE of: (a) accent hue in the orange-amber band (HSL **15°–45°**, or OKLCH ≈ **45°–85°** — see note) AND (b) a flat cream (`L>85%`, `C<0.03`) or flat near-black (`L<15%`) background AND (c) NO causal derivation line for the accent (per the Stage 2 derivation gate). If all three hold, the design is not finished: **re-pick the accent from an unexpected hue wheel, or add a real substrate, or derive a causal line**. If it clears ANY ONE — a non-band hue, a non-default substrate (warm ivory with micro-grain, deep oxblood-brown, a saturated not-flat field), or a genuine causal line — it stands. The causal line is a product receipt, and it is NOT warm-only: cite whichever real source the hue reproduces, e.g. "the gilt stamp on the product" (gold) OR "the cobalt of the machined turbine blade" (cool) OR "the chlorophyll of the ingredient" (green) — the derivation, not the hue family, is what clears. State the accent OKLCH + hex + causal line in the emit line, mandatory. A bespoke heritage gold on warm ivory WITH a causal line clears, and so does a cool or green accent with its own receipt; un-reasoned orange-on-flat-black fails. Do NOT ban a hue family outright — gold is not bad, gold-as-wallpaper is. **Band note (color-space accuracy):** OKLCH and HSL hue axes are NOT linearly equivalent. HSL 45° (amber) maps to roughly OKLCH 80–85°, not 45°. Resolve band membership on the accent's actual HSL hue — the paired OKLCH number is an approximation, never a substitute. Treat "is this amber?" as the test, not a hard-coded OKLCH cap. **Accent scarcity (corpus-proven):** one chromatic event per band — count color-bearing elements in a viewport and kill to ONE accent-bearing element (one colored CTA, one lit node, one color block) with white/neutral between color moments. Scarcity is what makes the color read intentional. **OKLCH mechanics (construct, don't guess — Hallmark corpus):** - **Every neutral/grey carries the anchor hue's chroma ≥0.006** (Hallmark Gate 22) — pure grey (`chroma 0`) next to a warm/cool accent is the cohesion killer. Tint warm accent → warm greys; blue accent → cool greys. Verify no neutral token has chroma == 0 (strict minimum floor $C \ge 0.005$). - **Fast OKLCH Contrast Delta Pre-Check:** Ensure $|L_{\text{text}} - L_{\text{background}}| \ge 0.50$ across all foreground/background pairings. Any delta below 0.50 fails WCAG 4.5:1. - **Substrate Micro-Grain over Flat Void:** Never use flat `#000` or `#fff`. Inject subtle micro-grain texture filter ($R_a = 1.8\text{--}3.5\,\mu\text{m}$) or bead-blasted metal shader to give the substrate tangible tactile friction. - **Anchor on OKLCH lightness bands, not hex intuition:** light-mode paper L 96-98%, ink 16-22%; dark-mode paper 12-16%, ink 92-96%. Accent needs chroma 0.12-0.22. Banned pure `#000`/`#fff` — always tint toward anchor. - **Dark mode never changes hue** — only lightness/chroma move (paper L 12-18%, ink 92-96%, accent chroma -0.02-0.04 + lightness +5-10%). - **Elevation on dark = lightness, not shadow:** each higher surface adds ~3% lightness; a coloured glow/halo on dark is the tell. **Lit-surface dark-on-color:** on a saturated button/fill put near-black ink (e.g. `#171717`), not white — lighter and more confident than white- on-brand. **Semantic up/down/delta stays text-color only**, never a filled pill. 3. **Type voice** — choose TWO faces and the scale logic (why this serif/x). Most AI-slop dies here because it ignores type. Also: overused faces (Inter, Roboto, Space Grotesk, Plus Jakarta, Geist, Satoshi, Sora, Cabinet Grotesk, Bricolage Grotesque, Outfit, DM Sans) read as slop on sight — if the face is one every agent ships, pick the distinctive alternative. Justify the pairing, don't inherit a default. Serif-default ban: a serif only because "serif looks premium" is a tell — it must earn the words. LLM-favorite serifs Fraunces and Instrument Serif are active tells — pick them ONLY when the brand is genuinely editorial/literary, and say why; any other default use of them reads as AI on sight (taste-skill 4.1). **Typecraft mechanics (corpus-proven, apply all):** - **Drive hierarchy with weight, not size/opacity.** Variable font at in-between weights (320/340/480/540): a 20px link @480 next to 20px body @330 reads as emphasis with no scale change and no grey text. Never default to 400-vs-700-plus-grey. - **Fix a display weight ceiling** (Stripe 300, Coinbase 400, Linear 600, Spotify 700/400 binary) and hold it — never unbounded weight-700 shout. - **Negative letter-spacing scales with size, asymptote ~0 at text**: ~-1.4px @ >80px, ~-0.5px @ 48px, ~0 at body. Not constant, not none. - **Whisper vs shout:** pair a thin-300 all-caps mono/sans eyebrow with a 64-107px display; tighten display leading (0.80-1.30), relax body (1.60-2.00). - **Two-tier copy voice:** button/label labels uppercase + wide tracking (0.5-2px); headlines sentence-case, often period-terminated. Don't shout headlines. - **Enable OpenType:** `font-feature-settings` with `ss01/ss03` (stylistic set = brand flavor) + `tnum` (tabular figures on all numerals/data). The AI default never touches font features. **Typecraft precision (Hallmark corpus):** - **2+1 rule:** at most 3 families — display + body + one outlier (wordmark, hero stat, pull quote). The outlier is a capped register (≤2 slots on the page); a third use = it's now a body font. Mono counts as a face outside code. - **Weight contrast ≥300 units:** body 400/350 → headings 700 or 200; never 500/600 next to 400 (reads as un-tuned default). - **Scale by ratio, not increments:** pick ONE of 1.25 / 1.333 / 1.5 / 1.618 off a 16px body. Display cap ≤5.5rem (88px), hard 6rem; a single word ≤12ch may reach 7rem. - **Size the headline to its character count:** ≤20ch → full display; 21-50ch → default; 51-90ch → step DOWN one rung; >90ch → rewrite. Write headlines ≤7 words / ≤50 chars. A huge headline too big for its words is the #1 AI tell. - **All-caps display heads need line-height ≥1.02-1.08** — uppercase has no descenders; below 1.0 line-N+1 caps collide with line-N baselines. - **Minimalist lock (when archetype is minimal):** canvas `#FFFFFF/#F7F6F3/#FBFBFA`, borders strictly `1px solid #EAEAEA`, body `#111111/#2F3437` lh 1.6, CTA `#111111` on `#FFFFFF` radius 4-6px no shadow, bento radius max 8-12px padding 24-40px. - **Type scale law (refero):** ratio 1.2 minor-third off 16px (11/13/16/19/23/28/33/40/48/57), max 6-8 sizes, at most 2 families, weights 400/500/600 only, ALL-CAPS tracking 0.06-0.10em, small text 0.01-0.02em. - **Radius/density law:** dense+corporate 4px, airy+corporate 12px, soft+playful 18px, sharp+corporate 2px. Cards radius 8px or less, buttons 6px, focus-ring offset 2px. - **Single-accent law:** one accent, everything else greyscale. Refined black `#2A2A2A`, never pure `#000`. Shadows 8% opacity or less (4% ideal), one light direction. Numbers:units 2:1 (48px value over 24px unit). Status color marks severity only; normal rows stay grey, never rainbow lists. 4. **Motion/state (MANDATORY, from interaction-patterns.md)** — meet the scene baseline: entrance (fadeInUp + stagger), scroll-reveal, hero layered entrance, hover/focus states. At L2+: sticky-nav blur, reveal-on-scroll. INCLUDE `prefers-reduced-motion` fallback and focus-visible states. A design with no motion or no focus states fails the bar — it's vibecode. **Motion & physics mechanics (corpus-proven, apply all):** - **Three workhorse easings, never `ease-in-out`:** - Enter/arrive: `cubic-bezier(0.16, 1, 0.3, 1)` (decelerating settle) - Mechanical snap / tactile switch: `cubic-bezier(0.18, 0.89, 0.32, 1.28)` (80-120ms sharp snap) - Overshoot/pop: `cubic-bezier(0.34, 1.56, 0.64, 1)` (900ms playful loops) - Exit = shorter `ease-in` at 60-70% of enter duration, capped ~200ms — **exit must resolve faster than enter** or back/forward feels sluggish. - **Tier 1–4 Spring Physics Matrix (stop guessing spring numbers):** - Tier 1 (Snappy Inputs / Buttons / Dropdowns): $k = 400\text{--}500, c = 30\text{--}35, m = 0.8$ (instant response, zero wobble). - Tier 2 (Spatial Sheets / Modals / Drawers): $k = 220\text{--}300, c = 24\text{--}28, m = 1.0$ (fluid settle, smooth deceleration). - Tier 3 (Fluid Drag Trackers / Pointers): $k = 120\text{--}180, c = 12\text{--}16, m = 1.0$ (organic elastic tether). - Tier 4 (Hotkey Actions / Quick Switches): $0\text{ms}$ duration (instant instantaneous jump for pro-keyboard navigation). - **8-State Interactive Contract (every interactive element must define):** 1. Default / Rest 2. Hover (desktop cursor enter) 3. Active / Pressed (mouse down / touch contact, 0.08s scale 0.98 drop, 2.8N simulation) 4. Focus-Visible (keyboard tab navigation, 2px offset ring, never outline: none) 5. Disabled / Inert (reduced opacity, cursor: not-allowed, aria-disabled) 6. Loading / Busy (accessible indicator, aria-busy="true") 7. Error / Invalid (tinted container, aria-invalid="true", descriptive text) 8. Selected / Checked (contrast-verified active state indicator) - **Press state:** 0.08s mechanical tactile drop on transform only, shadow dropped, <120ms; hover lift ≤1.5px with 1px lightened top hairline. - **Canvas & WebGL Zero-Jank Contract:** clamp `renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))`, disconnect RAF when offscreen via `IntersectionObserver`, 1D palette textures over branch-heavy shaders. - **Stagger 30-50ms per item, cap ~8 children** and total cascade ~600ms; on long lists shrink per-item delay, never item duration. - **Animate ≤1-2 key elements per view**; ≤2 heavy backgrounds/page, 1 WebGL scene/page, ≤3 timelines/page. A whole page gets 4-10 signature moments; >10 is noise. - **Opacity never lingers below 0.2** — parked 0.05-0.15 ghost states read as broken. - **Composite-only + FLIP:** animate only `transform`/`opacity` (never width/top/color); for layout-like effects use FLIP (measure, apply class, measure, animate the transform delta, clear). Blur ≤8px, never continuous. A project killed by jank is a failure — see ui-skills. - **Parallax on background/decorative layers only, yPercent 5-15**, never on text/CTAs; `overflow:hidden` wrapper. - **Reduced-motion = a distinct static frame that carries the full meaning**, not just "no animation." Render the complete no-JS state; keep opacity fades, cut large displacement/parallax/auto-scroll. - **Scenes that need immediate scannability (dashboard, app-UI, PPT) FORBID scroll-reveal** — info must be visible at once; use hover border highlight instead of lift. **Timing canon (Hallmark corpus, exact ms — stop inventing durations):** 80-120ms instant feedback (button press, keystroke) / 150-200ms hover + focus rings / 250-300ms modal-sheet-dropdown opens / 400-500ms toasts + page reveals. Exit = 60-75% of enter, never the reverse. Emil ideal 180ms, nothing expressive over 300ms without cause. **Motion slop heuristics (flag as FAIL):** any pulse/glow loop, blur-enter on 3 or more components, same hover-scale on 3 or more, stagger on 2 or more lists, identical fade on 4 or more elements, bounce spring on utility surfaces. **Motion stack rule:** motion only in isolated client leaves, continuous values via motion-value/scroll hooks, never state-driven per-frame updates. **Duration token scale (transitions.dev, match by usage):** stagger 40ms, micro 80ms, quick 150ms (close, text swap, tooltip), fast 250ms (dropdown/modal open, tabs, page slide), medium 350ms (panel/toast close), slow 400ms (panel open, skeleton reveal), very-slow 500ms (badge, text reveal). Toasts cap at 400ms. Easings: smooth-out `cubic-bezier(0.22,1,0.36,1)` for open/close/slide, bounce `cubic-bezier(0.34,1.36,0.64,1)` for pops, linear for shimmer. Distances 4/6/8/12/30px. Scales: modal .96, dropdown .97, tooltip .98. Blurs 2/3/8px. Never `transition:all`. Accordions via `grid-rows 0fr to 1fr`. **Scroll motion (when scope needs it):** Lenis smoother defaults (`duration 1.2`, `lerp 0.1`, `respectReducedMotion`, `data-lenis-prevent` for nested scroll). Dashboards stay calm (no scroll-jack, parallax, or 3D); cinematic scroll-linked reveals belong on landing pages only. **Signature FX menu (pick at most one):** border-beam outline sweep, liquid-gooey morph, thinking-orb loader, metallic sheen, shader-gradient hero (`uSpeed 0.1-0.4`, `pixelDensity 1` on mobile), liquid-glass refraction container. One FX per page; the signature stays structural. **Tooltip delay is asymmetric by intent:** hover = 800-1000ms (no flash on casual movement), focus = 0ms (keyboard user reached it deliberately — never delay them). Equal delays on both = the generated tell. **Motion restraint cap:** ≤3 distinct animation primitives per page (a counter + a hover-lift + a marquee = 3); no single animation >2s except a continuous loop; ONE orchestrated entrance, never per-section fade-up-stagger. Banned curve: the browser default `ease` (flat) — use the three-token canon, overshoot >110% only for physical interactions. **A11y is not a line-item, it's a gate.** Before emit, confirm each: contrast ≥4.5:1 (body)/3:1 (large, UI) on every token pair, all interactives keyboard-reachable with visible focus, no hover-only interactivity, motion has reduced-motion fallback, every image/icon has alt or aria-hidden + aria-label on meaningful ones, links describe destination (no bare "click here"), form fields labeled. Any miss → fix in the spec, not deferred. **Color never carries meaning alone** — pair every color signal with text, shape, or dash (color-blind safe), never hue-only dots. **Dialog/Sheet/Overlay must have an accessible title** (sr-only is fine, absent is a fail); `Avatar` gets an `AvatarFallback`. **Zero-Simulation Interactive Contract (STRICT):** Never emit toy SVG sketches, mock static charts, or simulated widget placeholders. When real-world features are required: - **Real GIS Cartography:** Geographical and regional surfac …(truncated)