Claude Design — how design works in this repo

ADR 0027 — Web Frontend & Design-System Tooling is the Accepted decision record that locks Claude Design as the sole sanctioned UI tool, the @hch/ui import rule, and the background token resolution (#F5F6F8). It is amended by ADR 0031 — Code-First Design Workflow and Cross-Platform Delivery, which establishes that packages/ui/src/ is the source of truth for components and that Claude Design receives mirrored mockups. This document is the workflow spec and canonical visual language that both ADRs reference.

This is the single document for how Heritage Virginia Community Hub does product design. We use Claude Design (Anthropic Labs). Google Stitch is no longer part of the workflow — its old prompt files were retired to docs/archive/stitch-prompts/.

If you are looking for "where do the app's colors / fonts / components come from" or "how do I change a screen" — this is the file.

Hard constraint (ADR 0027): every page and component in apps/web and apps/mobile must import presentational components and design tokens from @hch/ui only — no inline-styled, hand-coded pages. Use import { Button, Card, colors } from '@hch/ui'.

---

1. The tools and where they live

Thing	Where	What it is
Claude Design project	claude.ai/design → project "Heritage Virginia Community Hub" (id ceb2fb20-8346-4a74-8683-a96e4663b525, type DESIGN_SYSTEM)	The canvas. Where screens and prototypes are designed against our published design system.
Design-system source	packages/ui/design-system/	The repo-side source of the design system — HTML preview cards that sync up to the Claude Design project. This is the only folder tied to Claude Design.
Runtime components	packages/ui/src/	The real React components the app ships (Button, Card, Badge, tokens). Claude Design hands prototypes back here as real code.
This document	docs/internal/design/claude-design.md	How it all fits together + the canonical visual tokens (below).

There is no Stitch, no DESIGN.md, no prompts/ folder in the active workflow. Anything referencing those is historical and lives under docs/archive/.

---

2. Repo structure around Claude Design

packages/ui/
├── design-system/            ← Claude Design sync source (the bridge)
│   ├── README.md             ← short pointer back to THIS document
│   ├── foundations/
│   │   ├── colors.html       ← @dsCard group="Colors"
│   │   └── typography.html   ← @dsCard group="Type"
│   └── components/
│       ├── buttons.html      ← @dsCard group="Components"
│       ├── list-and-cards.html
│       ├── tab-bar.html
│       └── message-row.html
├── src/                      ← real React components (runtime + Handoff target)
│   ├── components/  (Button, Card, Badge, Spinner, Modal, Table)
│   └── tokens.ts             ← colors + fonts, must match §4 below
└── README.md

docs/internal/design/
└── claude-design.md          ← THIS document (the spec + workflow)

docs/archive/
└── stitch-prompts/           ← retired Google Stitch files (DESIGN.md, screen prompts) — reference only

Rule of thumb: design-system/ is what Claude Design reads; src/ is what the app runs; this doc is the truth both must agree with.

---

3. The workflow (the loop)

   THIS DOC (§4 tokens, the spec)
        │  author cards to match
        ▼
   packages/ui/design-system/*.html   ──/design-sync──►   Claude Design project
   (HTML @dsCard previews)                                  "Heritage Virginia Community Hub"
        ▲                                                          │
        │  extract cards from real components (later)              │  design screens / prototypes
        │                                                          ▼
   packages/ui/src/*  ◄──── Handoff to Claude Code ──────  finished prototype
   (real React, what the app ships)

1. Spec — §4 of this doc is the canonical visual language (palette, type, component rules).
2. Bridge — packages/ui/design-system/*.html are preview cards that encode that spec. Each file's first line carries a <!-- @dsCard group="…" --> marker so Claude Design indexes it into the right pane (Colors / Type / Components).
3. Sync up — from Claude Code, the DesignSync tool (the /design-sync flow) pushes the cards into the Claude Design project. Push incrementally, one card at a time — never a wholesale replace. After uploading fresh cards, call register_assets (auto-index does not reliably build the manifest), then reload the project page.
4. Design — in claude.ai/design, build/iterate screens. They automatically inherit our published design system.
5. Hand off down — "Handoff to Claude Code" brings a finished prototype back into the repo as real React / React Native code in packages/ui/src/ (and apps/web / apps/mobile).
6. Converge — once packages/ui/src/ has real components (ADR 0001 / AB#3160), regenerate the design-system cards from those components instead of hand-writing HTML. At that point the spec, the Claude Design project, and the shipping library all express one identical system.

Keeping it in sync — the one rule

If §4 below changes (a colour, a font, a component rule), update both the matching design-system/*.html card and packages/ui/src/tokens.ts, then re-run /design-sync. The spec is upstream of the cards; the cards are upstream of the Claude Design project.

---

4. Canonical visual language

This section replaces the old Stitch DESIGN.md as the source of truth for the look. The design-system/*.html cards and packages/ui/src/tokens.ts must match it exactly.

Atmosphere

A simple, classic, reverent digital home for a single church family — calm, warm, trustworthy; the quiet of a sanctuary, not the buzz of a social network. Spacious, uncluttered, plain conventional layouts. Flat surfaces over gradients/effects. One restrained gold accent reserved for what is sacred or "now playing". A 70-year-old and a teenager should both feel at home on the first try.

Palette

Name	Hex	Role
Heritage Blue	#2C5AA0	Primary — headers, primary buttons, active states, links
Sage Green	#4A7C59	Affirming — success, RSVP, active ministry, secondary actions
Reverent Gold	#D4AF37	Sole decorative accent (sparingly) — now-playing, logo glyph, play button. Never a background fill.
Soft Cloud White	#FFFFFF	Surfaces — cards, sheets, rows
Quiet Mist Gray	#F5F6F8	App background behind cards
Near-Black Ink	#1A1A1A	Primary text
Soft Slate Gray	#6B7280	Secondary text, metadata, helper copy
Hairline Gray	#E5E7EB	Dividers, 1px borders
Caution Amber	#B45309	Non-critical warnings
Alert Red	#B91C1C	Destructive actions, errors

Typography

• Native iOS: SF Pro (San Francisco) — clean, neutral, classic.
• Web + design tools (Claude Design): Inter as the loadable stand-in for SF Pro — close match, resolves "missing brand font" warnings.
• Scale: large titles ~34pt bold; section headers ~20pt semibold; row titles ~17pt medium/semibold; body ~17pt regular (~1.4 line-height); captions ~13pt in Soft Slate Gray; buttons ~17pt semibold.
• WCAG AA minimum contrast; fully Dynamic-Type friendly.

Components

• Buttons: primary = solid Heritage Blue fill, white text, pill shape; secondary = Heritage Blue outline, transparent fill, soft blue tint on press; destructive = Alert Red, always behind a confirmation.
• Cards: Soft Cloud White on Quiet Mist Gray, ~14–16px rounded corners, flat by default with an optional whisper-soft shadow (0 1px 4px rgba(0,0,0,0.06)) and optional 1px Hairline Gray border.
• Lists & forms: classic grouped iOS style — inset rounded sections, label left / value right, hairline dividers; inputs with 1px border, focus border shifts to Heritage Blue.
• Bottom tab bar: 5 line-icon tabs, active in Heritage Blue, inactive in Soft Slate Gray, flat white bar with a hairline top border.
• Empty states: gentle glyph, one warm line, a single clear action — encouraging, never error-like.

Layout & depth

Amended 2026-06-22 — responsive web (owner correction). The app is a single responsive React web application. It is not a fixed-390px phone frame. Layout adapts across three breakpoints:

Breakpoint	Viewport	Navigation	Content width
Phone	<640px	Bottom tab bar (5 tabs)	Full-width, 16–20px edge padding
Tablet	640–1023px	Bottom tab bar (5 tabs)	Centered column, max 640px
Desktop	≥1024px	Left sidebar (220px) — same 5 destinations	Content area fluid, max ~860px

OWNER REVIEW REQUIRED — flagged ambiguities (do not silently lock these):

• 1024px as the desktop breakpoint is a reasonable default; adjust to 960px or 1280px if preferred.
• Left sidebar is proposed for desktop nav. Top nav bar is a viable alternative. Owner should decide before AppLayout.tsx is updated.
• Max content width of 860px on desktop is a proposal; adjust to match preference (720px–1280px range).

Base spacing: 8px unit; ~16px between related elements; ~24–32px between sections. Single-column vertical scroll of grouped cards under a large title on phone/tablet. On desktop the same content fills the wider column — no dense dashboard grids at any breakpoint. The bottom tab bar is the phone/tablet primary nav pattern; on desktop it is replaced by the left sidebar showing the same five destinations (Home, Watch & Listen, Calendar, Messages, Me). Predominantly flat; elevation via spacing and Mist-Gray-vs-White contrast, not heavy shadows. 44×44pt minimum touch targets on phone; standard click targets on desktop.

Do / Don't

• Do: keep it simple and classic; generous whitespace; grouped card lists; reserve gold for the sacred/now-playing; warm pastoral copy; one clear primary action per screen; let content breathe at every breakpoint.
• Don't: gradients (except a very subtle splash), neon, glass, heavy shadows, busy animation, dense dashboards, over-used gold, error-like empty states, trendy fads that date quickly, fixed pixel widths that prevent the layout from adapting.

---

5. App identity (locked)

• App name: Heritage Virginia Community Hub — the church-family app for Heritage Virginia, Nickelsville, VA. iOS Home-screen short name: Heritage.
• Logo / app mark (placeholder — swap for the real logo later): a gold open book whose centerfold forms an upright cross, on a Heritage Blue rounded-square icon. Single colour (Reverent Gold on Heritage Blue), simple and classic — no gradients or 3D.

---

6. Code-first source of truth and platform delivery (ADR 0031)

ADR 0031 amends the workflow described above in one important respect: packages/ui/src/ is the source of truth, not the Claude Design canvas.

Source of truth

Components and design tokens are built in packages/ui/src/ first — authored to the spec in §4 below. The design-system/*.html @dsCard cards are then extracted from real components and pushed to the Claude Design project via /design-sync. The Claude Design project holds mirrors of the code, not originals.

The corrected chain:

§4 of this doc (canonical visual spec)
        │  author components to match
        ▼
packages/ui/src/*                    ← real runtime components (source of truth)
        │  extract @dsCard HTML cards
        ▼
packages/ui/design-system/*.html     ── /design-sync ──►  Claude Design project (shareable mockups)

If a Handoff from the Claude Design canvas is used, its output is treated as scaffold — reviewed and refined before merging. It does not land directly in packages/ui/src/ unreviewed.

Web / PWA: verified cross-platform path

Web (React/Vite, apps/web) deployed to heritageva.app is the primary verified surface. The app is installable as a PWA on iOS and Android home screens, providing a cross-platform experience from one codebase without a separate native release pipeline.

React Native (apps/mobile) is the eventual native app surface per ADR 0002 and ADR 0009/0014. Its fidelity through the Claude Design pipeline is not yet verified — that verification is scoped to the iOS delivery phase (AB#3077). No current delivery commitment in Epic AB#3074 depends on React Native being pixel-perfect with Claude Design output.

What this changes

Aspect	ADR 0027 (original)	ADR 0031 (current)
Source of truth	Implied: Claude Design canvas → Handoff → code	packages/ui/src/ (real components)
Claude Design role	Design canvas; Handoff produces real code	Mockup / communication tool; receives mirrors
design-system/*.html	Cards authored to spec, pushed to canvas	Cards extracted from real components, then pushed
Cross-platform primary	Web + React Native (implied)	Web/PWA (verified); React Native (deferred to iOS phase)

Everything else in this document — the @hch/ui import rule, the /design-sync push process, the register_assets call, the incremental card push discipline — remains in force.

---

7. History

• Google Stitch was the earlier design-exploration tool. Its files (DESIGN.md, ios-app-screen-prompts.md) are retired to docs/archive/stitch-prompts/ for reference only and are not part of the active workflow.
• This document and packages/ui/design-system/ are the Claude Design system of record going forward.
• ADR 0031 (2026-06-22) amended ADR 0027 to establish code-first source of truth and web/PWA as the verified cross-platform path. Section 6 above captures that amendment.
• Responsive layout correction (2026-06-22, owner): The §4 Layout & depth section was amended to remove the fixed-390px phone-frame framing. The app is a responsive web application (phone / tablet / desktop breakpoints), not a single fixed-width phone layout. The packages/ui/design-system/screens/*.html mockups were updated to use width=device-width viewport and CSS media queries. ADR 0031 carries the full amendment record.