design-craft
Constraint + process skill for UI that reads "designed", not "AI-generated". Mandatory two-pass process (token plan grounded in the subject's world + ONE signature element, then self-critique) whose output is the project's root DESIGN.md — the design contract re-read on every UI generation. Navigation selection matrix, logo rule (vary expression not placement), icon discipline (one library, labeled), typography pairing recipe, dominant+accent color, copy rules — on top of a non-negotiable usability floor (focus rings, empty/loading/error states, WCAG AA, <=200ms). Ships with AVOID-LIST.md (versioned AI-tell list) and DESIGN-TEMPLATE.md (DESIGN.md template). Triggers: build UI, new component, design review, polish UI, "looks like AI made it", design system, style guide, /toh-vibe, /toh-ui, /toh-design.
wasintoh · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add wasintoh/toh-framework --skill design-craftAbout this skill
name: design-craft description: > Constraint + process skill for UI that reads "designed", not "AI-generated". Mandatory two-pass process (token plan grounded in the subject's world + ONE signature element, then self-critique) whose output is the project's root DESIGN.md — the design contract re-read on every UI generation. Navigation selection matrix, logo rule (vary expression not placement), icon discipline (one library, labeled), typography pairing recipe, dominant+accent color, copy rules — on top of a non-negotiable usability floor (focus rings, empty/loading/error states, WCAG AA, <=200ms). Ships with AVOID-LIST.md (versioned AI-tell list) and DESIGN-TEMPLATE.md (DESIGN.md template). Triggers: build UI, new component, design review, polish UI, "looks like AI made it", design system, style guide, /toh-vibe, /toh-ui, /toh-design. triggers:
- /toh-vibe (new projects)
- /toh-ui (new components)
- /toh-design (polish)
- Any UI creation or design review request
Design Craft
Two layers — never confuse them:
| Layer | What | Where decided |
|---|---|---|
| Creative layer | Palette, type, nav, signature element — different per project | Root DESIGN.md, generated from DESIGN-TEMPLATE.md |
| Usability floor | Evidence-backed rules that never bend | Bottom of this file |
Sibling files (same folder):
AVOID-LIST.md— versioned AI-tell list. Consult during identity generation and every design review.DESIGN-TEMPLATE.md— template + filled example for the generated per-project rootDESIGN.md.
The contract: root DESIGN.md is the project's design identity. Re-read it before every UI generation — never work from memory of it. If it doesn't exist and UI is about to be written, generate it first (two-pass process below → template). For UI projects it is the first plan task (design-reviewer authors it before any UI work).
Meta-Rule
Defaults are fine when chosen for the brief. Never when inherited.
Inter, indigo-500, rounded-lg, a 3-card feature row — each is legitimate when the brief calls for it, and slop when it appears because it's the training-data median. Every value in the UI must trace to a DESIGN.md token chosen for THIS project.
Two-Pass Process (mandatory before any UI code)
Pass A — compact token plan. Ground it in the subject's actual world — materials, place, era, mood. (A restaurant supply marketplace lives among stainless steel, wet markets, delivery bikes — not "warm and friendly".)
- 4-6 named hex colors incl. hue-biased neutrals (never pure gray)
- Display / body / utility typeface roles + weights
- One-sentence layout concept
- ONE signature element — the single bold, memorable move (distinctive hero treatment, unusual data display, strong typographic motif). One. Everything else stays quiet.
Pass B — self-critique. Ask: "Would I produce this exact plan for any similar brief?" If yes → revise and state what changed. Check the plan against AVOID-LIST.md.
Only after Pass B survives: write the plan into DESIGN.md and code — deriving every color/type/radius/motion value from it. No raw Tailwind palette colors (indigo-500) that bypass the tokens.
Navigation Selection Matrix
| Project type | Navigation pattern |
|---|---|
| Marketing / landing | Visible top bar, 4-7 text links |
| Dashboard / app | Left sidebar with labeled icons |
| Content / docs | Top bar + secondary sidebar / table of contents |
| E-commerce | Top bar + mega menu for categories |
| Peer views (same-level sections) | Tabs |
Hard rules, all patterns:
- Never a hamburger on desktop — hiding nav halves discoverability. Visible links at
md+ always. - Nav items are real links (
<a>/<Link>), never divs with onClick. - URL reflects state — views are shareable and back-button-safe.
Logo Rule — vary expression, not placement
- Top-left, clickable to home — always, for apps and sites (NNGroup: returning home is ~6x harder with a centered logo).
- Brand variety comes from wordmark treatment (typeface, weight, spacing), a motif, or an accent system — not from moving the logo.
- Centered logo ONLY for editorial/luxury briefs that explicitly call for it, and only with a compensating home affordance (visible "Home" link).
Icon Discipline
- Exactly ONE library per project, declared in DESIGN.md: Lucide / Phosphor / Heroicons / Tabler — plus stroke weight and size grid (e.g. 16/20/24).
- Every icon gets a text label — except true universals (search, close ×, chevron).
- Icon-only buttons require
aria-label. - Never emoji as UI icons.
- "No icons" is a valid choice — often the stronger one for editorial identities.
- Icon-tile-above-heading cards are the #1 AI tell (see AVOID-LIST). Icons support content; they don't headline it.
Typography Pairing Recipe
Formula: characterful display + complementary body + optional mono/data face.
- Inter / Geist are body/utility faces ONLY — never the personality carrier.
- Use weight extremes: pair 100-200 against 800-900 instead of everything at 400-600.
- Hero: 3x+ size jump from body. Scale ratio >= 1.25. Body measure 65-75ch.
tabular-numson any column of numbers. - Category starting points — rotate; never converge across projects:
- Editorial / food / lifestyle → Fraunces, Newsreader
- Technical / data → IBM Plex family
- Startup / product → Cabinet Grotesk, Satoshi These are prompts, not defaults. Pick for the brief; if the last project used it, pick differently.
- Thai: IBM Plex Sans Thai / Noto Sans Thai / Anuphan / Sarabun. Next.js: load via
next/font(self-host, no layout shift) — never a raw Google Fonts<link>.
Type scale (Tailwind)
Display / Hero: text-4xl / text-5xl+ display face tracking-tight
Page Title: text-2xl font-semibold (24px)
Section Title:
Read the complete source ↗