Design Bible

The Design Bible is the single source of truth for tokens. Every UX spec, every component, every asset must reference its tokens — no inline color hexes, no inline spacing values. This skill produces that file.

Output: design/design-bible.md

Purpose / When to Run

Run when:

• design/concept.md is approved and design/design-bible.md does not exist
• Visual identity needs to be tightened before UX work begins
• The user wants to refresh the bible after a rebrand

The bible should exist before /map-systems and any /design-system UI section, so PRDs reference real tokens, not placeholders.

Inputs

• design/concept.md (required)
• .claude/docs/technical-preferences.md (for platform target — iOS HIG / Material 3 conventions affect token decisions)
• Optional: existing partial design/design-bible.md

Outputs

• design/design-bible.md — token definitions and identity
• Optional: hands a token export task to /asset-spec for icon/splash generation prompts

Phase 1: Context

Read concept.md. Extract Section 6 (Tone & Visual Anchor) and the named reference apps. If concept doc is missing, stop.

Identify platform target from technical-preferences:

• iOS only → use iOS HIG (Apple Human Interface Guidelines) sizing language
• Android only → Material 3 sizing language
• Both / cross-platform → describe both, with one canonical token system that maps to each

Optionally use WebSearch to fetch fresh visual reference for the named comp apps if their tone has shifted.

Phase 2: Skeleton

Write design/design-bible.md skeleton:

# Design Bible — <App Name>

> **Status**: In Design
> **Last Updated**: <date>
> **Platform target**: <iOS / Android / both>

## 1. Identity & Tone
[To be designed]

## 2. Color Tokens
[To be designed]

## 3. Typography Tokens
[To be designed]

## 4. Spacing & Layout
[To be designed]

## 5. Radius
[To be designed]

## 6. Elevation & Shadow
[To be designed]

## 7. Motion
[To be designed]

## 8. Iconography
[To be designed]

## 9. Imagery & Illustration
[To be designed]

## 10. App Icon
[To be designed]

## 11. Splash / Launch
[To be designed]

## 12. Dark Mode
[To be designed]

## 13. Accessibility
[To be designed]

## 14. Token Naming Conventions
[To be designed]

Ask: "May I create the skeleton at design/design-bible.md?"

Phase 3: Section-by-Section Authoring

For each section, follow:

Context → Question(s) → Options → Decision → Draft → Approval → Write

Section 1: Identity & Tone

Pull from concept.md tone direction. Ask:

• "Distill the brand into 3 adjectives." (free text)
• "What is one word the brand is not?" (free text — anti-tone is as useful as tone)
• "Pick a metaphor for the app's voice." (free text — e.g., "calm mentor", "playful teammate")

Spawn visual-design-director via Task to crystallize the tone into one paragraph plus 3-5 design principles (e.g., "favor whitespace over density"). Present specialist's draft for approval.

Section 2: Color Tokens

Define semantic tokens (not raw colors):

• color.bg.primary / bg.elevated / bg.muted
• color.fg.primary / fg.muted / fg.inverse
• color.brand.primary / brand.secondary / brand.accent
• color.semantic.success / warning / danger / info
• color.border.subtle / border.strong

For each, capture:

• Light mode hex
• Dark mode hex (Section 12 covers nuance)
• WCAG AA contrast against primary background — verify before approving
• Source rationale (why this color, what it evokes)

Use AskUserQuestion to drive palette decisions:

• "Pick a brand-primary direction":
  • Cool (blue/teal/violet)
  • Warm (orange/red/yellow)
  • Neutral with accent (greys + 1 pop)
  • Earthy (greens/browns)
  • Custom — describe

After picking, propose 3-5 candidate brand primaries (with hex). Show contrast scores against white and black. User picks.

For dark mode, propose mirrored values; never copy light-mode hexes — dark mode needs lighter brand and softened backgrounds.

Spawn visual-design-director via Task to refine the candidate palette and recommend semantic mappings.

Section 3: Typography Tokens

Capture:

• Display / heading / body / caption / mono — at minimum
• For each: family, weight, size (in pt or sp), line height, letter spacing
• iOS Dynamic Type / Android scaled text behavior — every size must support scaling

Ask about font family choice:

• System (SF Pro / Roboto) — recommended, accessible
• Custom — name and load via app
• Mixed — system body + custom display

Verify license for any custom font. Note in the bible.

Sizes (rough starting points — adjust per concept tone):

• Display: 32-48pt
• Heading 1-3: 24-30pt
• Body: 17pt iOS / 16sp Android (default per HIG / Material)
• Caption: 13-14pt
• Mono: only if shown to users (timestamps, codes)

Section 4: Spacing & Layout

Define a base grid:

• Base unit: 4pt (most common — half-grid for fine-tuning)
• Tokens: space.0 through space.12 (0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64)
• Container max widths if applicable
• Safe area conventions (iOS notches, Android system bars)

Section 5: Radius

Tokens: radius.none, radius.sm, radius.md, radius.lg, radius.full (pill). Pick concrete values per the tone — minimal apps use 8-12, playful apps use 16-24.

Section 6: Elevation & Shadow

iOS uses subtle shadows; Material 3 uses tonal elevation. Tokens: elevation.0 (flat), elevation.1 (cards), elevation.2 (sheets), elevation.3 (modals), elevation.4 (popovers).

For each, define iOS shadow params (color, offset, blur, opacity) and Material 3 tonal-elevation step.

Section 7: Motion

Tokens:

• Durations: motion.fast (~150ms), motion.medium (~250ms), motion.slow (~400ms)
• Easing: ease.standard, ease.emphasized, ease.linear
• Reduce-motion alternative for every animated transition (Section 13 cross-references this)

Section 8: Iconography

• Family: SF Symbols (iOS) / Material Symbols (Android) / custom set
• Stroke weight, fill behavior, sizes per token (icon.sm, icon.md, icon.lg)
• Anti-pattern callouts: never mix two icon families in the same screen

Section 9: Imagery & Illustration

• Photography style (if any) — saturation, framing, mood
• Illustration style — flat, hand-drawn, isometric, 3D — pick one
• Empty-state illustration role: present? per-screen? canonical?
• AI-generation prompt seed (a 1-line style anchor used by /asset-spec)

Section 10: App Icon

Spawn visual-design-director (Task) to propose 3-5 icon directions consistent with Sections 1-3. For each, capture:

• Concept (visual metaphor)
• Composition (centered glyph, gradient field, monogram, etc.)
• Color
• Size variants required (iOS: 1024×1024 master + many derived; Android: adaptive icon foreground + background + monochrome)

User picks one direction. The bible records the chosen direction and the production specs.

Section 11: Splash / Launch

iOS: Launch Screen uses storyboards or asset catalogs — must be silent / non-functional, no animations beyond the OS-controlled fade.

Android: launch theme + (optional) splash screen API on Android 12+.

Capture: background token, logo size, centering, dark-mode variant.

Section 12: Dark Mode

Confirm dark-mode strategy:

• Mirrored — every token has a dark variant
• Lights-only at v1 — explicit deferral; PRDs must reference this
• System-controlled only — follows OS, no in-app override
• User-toggleable — settings switch

For mirrored mode, list every color token's dark hex (Section 2 cross-reference).

Section 13: Accessibility

• WCAG 2.2 AA contrast verified for every fg/bg pair — list ratios
• Dynamic Type / scaled text supported up to at least Large (iOS) / 200% (Android)
• Reduce-motion alternatives for every motion token
• Touch target floor (44×44pt iOS / 48×48dp Android)
• VoiceOver / TalkBack: focus order, labels, hint conventions
• Color is never the only differentiator — every state has a non-color cue

Section 14: Token Naming Conventions

Decide once:

• Casing: kebab-case / dot.case / camelCase
• Theme prefix: --theme-color-bg-primary or --color-bg-primary (no theme prefix)
• Export format: CSS variables / Swift constants / Compose Theme / Tailwind config / Style Dictionary

If the team uses Style Dictionary or similar, link the export config path.

Phase 4: Specialist Validation

Spawn visual-design-director for a final visual pass once all sections are written. They validate:

• Tokens are internally consistent (motion / radius / spacing scales make sense together)
• Dark-mode pairs all pass contrast
• The identity captures the concept tone

Surface findings; user decides on changes.

For accessibility, optionally spawn accessibility-specialist to verify Section 13.

Phase 5: Update Concept and Hand Off

After the bible is complete, ask: "Update design/concept.md Section 6 to point at the bible?" — replace the rough tone notes with a link.

Print:

"Design Bible written. Run /asset-spec app-icon and /asset-spec splash to produce production specs and AI-gen prompts. Then /map-systems and /design-system PRDs can reference the bible's tokens directly."

Use AskUserQuestion:

• Options:
  • Run /asset-spec app-icon
  • Run /asset-spec splash
  • Run /map-systems
  • Stop here

Quality Gates

• Every section is non-empty (no [To be designed] left)
• Every color pair listed in Section 2 has a verified contrast ratio in Section 13
• Token names follow the convention from Section 14 — no inline raw values used inside any other section
• Dark-mode strategy is explicit, not deferred without a date
• App icon and splash specs reference real tokens from Sections 2-3

Examples

/design-bible for a calm-tone meditation app:

• Tokens use a single primary slate-700 plus accent lavender-400; type ramp is two display sizes + three body sizes; motion budget is 200 ms standard / 400 ms emphasized; haptics are reserved for breath cues only.
• App icon spec: monochrome silhouette of a bowed leaf, full-bleed lavender background; meets iOS dark and tinted icon variants.
• Splash spec: lavender-400 background, leaf glyph centered, no copy.

/design-bible for a bouldering log:

• Bold high-contrast palette (charcoal background, chalk foreground, accent-orange for grade highlights); type ramp emphasizes numerals (V-grades) at display sizes; motion budget allows 600 ms celebrate animations on send.
• Iconography spec: thick-stroke line set; strokes scale with Dynamic Type / Font Scale.