RonanCodes/design-foundations

Design Foundations

The documents a UX/brand professional writes before picking a single token or component. Most teams skip straight to colours and buttons; the result is a UI with no point of view. This skill captures the point of view first — who the product is for, who it is, how it speaks, what it looks like and why, how it behaves — then hands a clean brief to the skills that implement it.

This is the front of the design pipeline:

design-foundations  →  generate-design-brief  →  [Claude Design]  →  design-system-create / claude-design-to-code  →  frontend-design  →  design-system-audit  →  app-polish
   (this skill)          (Claude Design brief)                          (tokens + primitives + /styleguide)            (build quality)      (enforce)          (launch)

Voice rules throughout defer to /ro:write-copy. Personal/author voice (the human's) is /ro:voice-profile; this skill defines the product's voice, which is a different thing.

When to use

• Before scaffolding a new app's UI, or when an app has tokens/components but no stated design point of view.
• User says "think about the design language / voice / colour scheme", "how would a UX professional approach this", "give the app a brand", "write design docs we can follow".
• After a mascot is generated (/ro:generate-mascot) — the mascot is a strong anchor for personality + palette; this skill formalises it into a system.

When NOT to use

• For the token module + React primitives + /styleguide route — that's design-system-create (this skill feeds it).
• For a one-page marketing site with no product surface — overkill; write a single brief via generate-design-brief.
• For the human's personal writing voice — that's /ro:voice-profile.

Usage

/ro:design-foundations                     # detect project from cwd, derive + interview the gaps
/ro:design-foundations --app nutmeg        # override app name
/ro:design-foundations --vibe "sharp analyst, cheeky edge"   # pre-seed the direction, skip that question
/ro:design-foundations --consolidate       # emit 4 merged docs instead of 6 (good for small/single-user tools)
/ro:design-foundations --out docs/design   # output dir (default docs/design/ at repo root)
/ro:design-foundations --commit            # commit the docs (repo's commit convention)

How a UX professional approaches this (the method this skill follows)

A designer does NOT start with colour. The order is deliberate — each layer constrains the next:

1. Understand — who is this for, what job are they hiring it to do, what does success feel like, what's the context of use (one expert at a desk? a phone on a commute?). You cannot design voice or colour until you know this.
2. Position & principles — 3-5 design values that resolve future arguments ("clarity over cleverness", "every number auditable"). These are the tie-breakers.
3. Personality — if the product were a person, who? An archetype + 4-6 traits + an explicit is / is-not table. A mascot, if one exists, is the embodiment.
4. Voice & tone — how the personality talks, and how tone shifts by moment (confident on a result, plain on an error, warm on an empty state). Honesty calibration matters most where stakes are real.
5. Visual language — only now: colour (semantic, with rationale + contrast), type, space, radius/elevation, motion, and data-viz conventions if the product is data-dense.
6. Interaction & UX principles — IA, the 2-3 primary flows, density stance, and the states most apps botch (loading / empty / error / partial data).
7. Accessibility — the floor (WCAG AA), stated as commitments, not aspirations.
8. Hand off — to generate-design-brief and design-system-create, which turn this into a Claude Design brief and a token module.

Step 1 — Detect project + gather source

Find the project root (cwd with README.md + a manifest, else walk up). Resolve <app> (flag → package.json/wrangler name → dir basename).

Read for signal, stop when you have enough: README.md; CONTEXT.md; the spec / parent PRD (GitHub issue linked from README — gh issue view); public/brand/<app>-*.png (a mascot is a strong personality + palette anchor — note its colours and character); any docs/adr/* (constraints); the linked wiki vault if one is referenced.

House defaults (the baseline before taste)

Start every app from these unless the product clearly argues otherwise, and if it does, state why in the docs:

• Light mode by default. Most people prefer light. Light is the default and gets the primary design attention; dark ships as an optional toggle (respect prefers-color-scheme, allow a manual override, persist the choice). Do NOT default to dark just because it looks slick in a screenshot.
• Intuitive first, great UX is the priority. Clarity and obviousness beat cleverness. A first-time user should know what to do without a tooltip. Design the boring states (empty / loading / error / first-run) as carefully as the happy path.
• A bit of fun and cheeky. Give it personality: a wink in the microcopy, the mascot showing up, a small delightful touch. Playful, not gimmicky; charming, not corporate-bland, and never at the cost of the task.

Step 2 — Fill the taste gaps (only what you can't derive)

Derive what you can from the source. For what's genuinely a taste call, ask via AskUserQuestion (one round, recommended answers), and ONLY for gaps not already provided via flags:

• Vibe / direction in 3-5 words (skip if --vibe given). Offer 2-4 concrete directions grounded in the product (e.g. "sharp analyst, cheeky edge" vs "bright sporty playful" vs "sober minimal").
• Accent colour / palette anchor — derive from the mascot if present; else ask.
• Mode — default to light (house default; see above). Confirm whether a dark toggle is in scope for v1. Only deviate to dark-first if the audience and context genuinely call for it, and capture the reason.
• Anti-references — 1-2 products this should NOT feel like.

Don't over-interview. Three questions max.

Step 3 — Write the doc set

Default: six focused docs in docs/design/. With --consolidate: merge into four (product-and-principles, brand-and-voice, visual-language, ux-and-accessibility). Each doc leads with a one-paragraph plain-English statement, uses concrete examples with real values, and states what's deliberately out. No em-dashes / AI-tells (/ro:write-copy).

docs/design/00-product-principles.md

• One-line positioning ("X is the Y that does Z for W").
• Target user + primary jobs-to-be-done (the real tasks, in their words).
• Context of use (device, environment, frequency, expertise).
• 3-5 design principles as tie-breakers, each with a "so when in doubt, …" clause.
• North-star: what success feels like in one sentence.

docs/design/01-brand-personality.md

• Archetype (one) + 4-6 personality traits, each with a one-line behavioural meaning.
• Is / is-not table (e.g. "Confident, not arrogant"; "Playful, not silly").
• The mascot's role (if any) and where it shows up vs stays out of the way.

docs/design/02-voice-and-tone.md

• 3-4 voice principles (constant) + how tone shifts by context.
• A tone-by-moment table: success, error, empty state, loading, onboarding, destructive confirm — with a real example line for each.
• Microcopy do/don't pairs. Honesty calibration: where the product must NOT overclaim (critical for anything with real stakes).
• Defer mechanics to /ro:write-copy.

docs/design/03-visual-language.md

• Colour system: semantic roles (bg, surface, border, text, muted, accent, success, warning, danger) with hex + the rationale, and WCAG contrast notes (target AA: 4.5:1 body, 3:1 large/UI). Light/dark per Step 2.
• Typography: family choice + a type scale (size/weight/line-height/use).
• Spacing & layout: base unit + scale, grid/density stance.
• Radius, elevation, borders: the consistent treatment (no radius that changes across states).
• Motion: duration/easing defaults, what animates and what doesn't, reduced-motion stance.
• Data-viz conventions (if data-dense): table density, number formatting, how counts/percentages/positive-negative are coloured, sparkline/chart rules.

docs/design/04-ux-principles.md

• Information architecture: the top-level surfaces and how they relate.
• The 2-3 primary flows, each as a short step list (the happy path).
• Density & clarity stance (how much on screen at once; progressive disclosure).
• State design: loading, empty, error, partial/degraded data — the states most apps skip. Name the real ones for this product.
• Responsive stance (which breakpoints matter; is mobile in scope).

docs/design/05-accessibility.md

• WCAG target (default AA) as concrete commitments: contrast, full keyboard operability, visible focus, hit targets, reduced-motion honoured, semantic markup + labels, error messaging not colour-only.
• A short pre-ship checklist (feeds design-system-audit + app-polish).

docs/design/README.md

• Index of the set + the one-paragraph design statement + the pipeline (what runs next).

Step 4 — Hand off

Print the next steps explicitly:

• → /ro:generate-design-brief — turn these foundations into a paste-ready Claude Design brief (it now reads docs/design/ instead of re-asking).
• → /ro:design-system-create — implement the colour/type/space tokens + primitives + /styleguide from 03-visual-language.md.
• → /ro:frontend-design — build screens to this point of view.
• → /ro:design-system-audit then /ro:app-polish — enforce + launch-polish.

If a mascot exists, remind that its avatar is already the favicon (/ro:generate-mascot Step 6.5).

Step 5 — Commit (optional)

With --commit, stage docs/design/** and commit with the repo's convention (📝 docs: per repo CLAUDE.md; respect the weekday-hours timestamp rule from ~/CLAUDE.md). Do not push automatically.

Idempotent re-run

If docs/design/ exists, update in place rather than duplicating: refresh derived sections, preserve any hand-edited prose (don't clobber a section the user clearly rewrote — diff and ask if unsure).

Related

• /ro:generate-design-brief — consumes this; produces the Claude Design brief.
• /ro:design-system-create — implements 03-visual-language.md as tokens + primitives + /styleguide.
• /ro:frontend-design — build-quality UI that honours the foundations.
• /ro:design-system-audit — enforces the visual language; /ro:app-polish — launch checklist.
• /ro:write-copy — the microcopy mechanics referenced by 02-voice-and-tone.md.
• /ro:generate-mascot — personality + palette anchor; run it first if the product should have a face.

Provenance

• 2026-06-07 — created at Ronan's request ("think about design language, voice, colour scheme … how a UX professional would approach this … should be a skill used when we build any application"). Filled the one gap in the existing design pipeline: the brand/voice/UX foundations layer that sat between "spec" and "tokens". First run produced the doc set for nutmeg (the football results-analysis tool), anchored on its cheeky-fox mascot and a "sharp analyst, cheeky edge" direction.