Product Design
What design decision are you making right now?
This hub is the single source of every measurable design rule in this repo. Every threshold below appears here exactly once. Other pages teach the deeper pattern but reference this table for the numbers — they never restate them. Drift starts when a rule lives in three places; the fix is one place, many readers.
Owner. This hub is the public entry point in the design authority chain. The chain runs public schema (Standards) → public hub (this page) → operational bible (
src/components/DESIGN.md) → runtime tokens (tailwind.config.js). Drift across the chain is owned by thedrmg-design-curatoragent (.claude/agents/drmg-design-curator.md). Invoke the curator after any edit to one of the four layers; it reports mismatches and proposes the fixes.
Design Memory — Where It Lives
Design knowledge lives in four layers. What we cannot share, are still working out, or is about planning lives inside. What we think is worth sharing lives outside, split by intent: /docs/ answers HOW, /meta/ answers WHY. The running code and agent config sit beside the components themselves.
| Layer | Where | What lives there |
|---|---|---|
| Inner | .invisible/ | What we cannot share yet, work in progress, tactical planning — per-venture and per-workchart design memory |
| How | /docs/ (this hub + standards) | Public universal patterns, hard thresholds, schema — worth sharing |
| Why | /meta/ | Public narrative — rhetoric and reflection on why these design decisions matter — worth sharing |
| Operational | src/components/DESIGN.md + tailwind.config.js + .claude/skills/design-*/ | Runtime memory the agents read while building |
One file format across all four layers. The Google Labs design.md standard — YAML front matter (typed design tokens) + Markdown body (human rationale) — describes a design system to any AI agent in any tool. Schema, scope rules (system / per-venture / per-workchart / per-deck), and lint enforcement live in Design System Standards §The DESIGN.md Standard.
# Lint the operational bible before shipping
npx @google/design.md lint src/components/DESIGN.md
The Four-Pass Audit Sequence
The four-pass sequence (Rendering → Visual → Responsive → Interaction) is the canonical loop — see How to Audit a Page. Then pick the situation-specific deep dive from the router below.
Browser Canvas Storytelling
Some ideas should not stay as prose. When a page asks the reader to compare, sequence, diagnose, or hold several dimensions in working memory, climb the ladder from markdown to MDX/React and make the relationship visible.
Use this pass before component styling:
| Question | Browser-canvas move | Pass condition |
|---|---|---|
| What is the reader trying to decide? | Open with a single decision surface, not an abstract intro | A new reader can state the decision in 5 seconds |
| What relationship carries the meaning? | Choose sequence, comparison, matrix, loop, or ledger | The layout shape teaches the concept before the body copy |
| What can be collapsed into a reusable pattern? | Use Section, Container, SectionHeader, Card, Rhythm, TightFive, DataListTable, Stat | The page imports primitives before hand-rolling surfaces |
| What should the reader do next? | End with a prompt, checklist, or routed link that continues the job | The final viewport has one clear next action |
Docs rule. /docs/ pages stay MDX. They may use JSX and design-system primitives, but they do not become .tsx pages. A visual block is justified when it reduces cognitive load, not when it merely decorates text.
Story arc for teaching pages:
Problem tension → Operating principle → Visual model → Application → Proof/loop → Next action
Use the arc flexibly. The important constraint is state change: the reader should leave with a sharper question, a simpler model, and a next move they can run.
Situation Router
| You're doing this | Use this |
|---|---|
| Deployed but something looks wrong | Audit Loop — Rendering layer |
| Making it look professional | Design Language — tokens + composition |
| Testing on phones or checking speed | Responsive + Performance |
| Ensuring everyone can use it | Interaction + Accessibility |
| Building a page that needs to convert | Landing Page Review |
| Building reusable UI components | Design Language — component hierarchy |
| Building admin/data management UI | Data Interfaces |
| Reviewing someone's work | Audit Loop — Review section |
| Building or auditing a marketplace | Marketplace Design |
| Setting up Tailwind v4 theme tokens (greenfield app) | Tailwind v4 Theme |
| Working in THIS Docusaurus repo (v3 fallback) | src/css/CLAUDE.md |
| Composing components into a system | Design Language — boundaries + composition |
| Using AI to build and review pages | Audit Loop |
| Looking for the brand identity, component inventory, landing page sequence | Design System |
Hard Thresholds — The Single Source
Every measurable design rule in this repo. The "deep dive" column says where to learn the why; the threshold here is the law.
| # | Check | Threshold | Deep dive |
|---|---|---|---|
| 1 | Contrast (body text) | ≥ 4.5:1 | a11y |
| 2 | Contrast (large text — 18px+bold or 24px+) | ≥ 3:1 | a11y |
| 3 | Contrast (UI elements + borders) | ≥ 3:1 | a11y |
| 4 | Touch target | 44×44 px (WCAG 2.2 SC 2.5.8 absolute minimum: 24×24 px) | a11y |
| 5 | Focus ring contrast | ≥ 3:1 against adjacent | a11y |
| 6 | Body text minimum | 16px at every breakpoint | perf |
| 7 | Mobile reflow | 320px viewport, zero horizontal scroll | perf |
| 8 | Line length | 45–75 characters | design-language |
| 9 | H1 per page | Exactly 1 | design-language |
| 10 | Heading hierarchy | No skipped levels (H1 → H2 → H3) | a11y |
| 11 | Visual focal point | 1 element ≥ 1.5× larger per viewport | audit-loop |
| 12 | File length (component) | ≤ 150 lines | design-language |
| 13 | Props per component | ≤ 7 (split if more) | design-language |
| 14 | Nesting depth | ≤ 3 levels | design-language |
| 15 | Prop drilling depth | ≤ 2 levels (else context or composition) | design-language |
| 16 | Composition score | > 80% library imports per page | design-language |
| 17 | Tokens in components | Zero hex literals; reference var(--*) or Tailwind token utility | design-language |
| 18 | Arbitrary Tailwind values | Forbidden (text-[#b91c1c], p-[7px]) — tokens exist | design-language |
| 19 | Modal primary actions | ≤ 2 | data-interfaces |
| 20 | Form fields — inline | 1–3 | data-interfaces |
| 21 | Form fields — modal | 4–6 (> 6 = full page or wizard) | data-interfaces |
| 22 | Modal content height | Fits viewport, no inner scroll | data-interfaces |
| 23 | Table columns visible at once | ≤ 7 | data-interfaces |
| 24 | Table row height | 40–56 px | data-interfaces |
| 25 | Row actions visible | ≤ 3 (overflow menu for more) | data-interfaces |
| 26 | Data list pagination — < 20 items | Show all | data-interfaces |
| 27 | Data list pagination — 20–100 | Paginate (10–25/page) | data-interfaces |
| 28 | Data list pagination — > 100 | Search required | data-interfaces |
| 29 | Data list pagination — > 1000 | Server-side filter + load-on-demand | data-interfaces |
| 30 | Soft-delete undo window | 10 seconds | data-interfaces |
| 31 | LCP (Largest Contentful Paint) | < 2.5s good · 2.5–4.0s needs work · > 4.0s poor | perf |
| 32 | INP (Interaction to Next Paint) | < 200ms good · 200–500ms needs work · > 500ms poor | perf |
| 33 | CLS (Cumulative Layout Shift) | < 0.1 good · 0.1–0.25 needs work · > 0.25 poor | perf |
| 34 | First Contentful Paint | < 1.5s | perf |
| 35 | Page weight total | < 1 MB | perf |
| 36 | JS transferred | < 300 KB | perf |
| 37 | CSS transferred | < 100 KB | perf |
| 38 | Image budget — total | < 500 KB | perf |
| 39 | Image budget — single image | < 200 KB | perf |
| 40 | Fonts | < 100 KB total, max 2–3 families, WOFF2, font-display: swap | perf |
| 41 | Breakpoints (no exceptions) | 375 / 768 / 1024 / 1440 px | perf |
| 42 | 5-second test | 5 of 5 readers identify what/who/action | audit-loop |
| 43 | Confirmation feedback | Visible within 200ms of action | audit-loop |
| 44 | Hover transition | 100–200ms | a11y |
| 45 | Animation duration (UI transitions) | < 400ms | a11y |
| 46 | Auto-playing animation | None except loading indicators | a11y |
| 47 | prefers-reduced-motion | All non-essential animation disabled when set | a11y |
| 48 | Color independence | Status never by colour alone — icon + text required | a11y |
| 49 | alt text on <img> | 100% coverage; decorative images carry alt="" + aria-hidden="true" | a11y |
| 50 | Form labels | Every input has <label for> or aria-label/aria-labelledby | a11y |
| 51 | Keyboard reachability | 100% of interactive elements reachable via Tab | a11y |
| 52 | Skip link | First Tab stop is "Skip to main content" | a11y |
| 53 | Landing page form fields (conversion) | 1–3 preferred; minimum-viable | landing-page |
| 54 | Landing page conversion benchmark | 2–5% good · 5–10% great | landing-page |
| 55 | CTA colour uniqueness | Reserved for clickable elements only; zero non-clickable use | landing-page |
| 56 | Teaching-page story arc | Problem → principle → visual model → application → proof/loop → action | design-language |
| 57 | Browser-canvas trigger | Use MDX/JSX when comparison, sequence, loop, matrix, or ledger carries meaning | design-language |
| 58 | Visual block purpose | Every visual block must answer a named reader question | design-language |
| 59 | Docs implementation format | /docs/ visual pages remain .mdx; never .tsx | design-language |
| 60 | Next-action close | Final viewport contains one prompt, checklist, or routed next link | audit-loop |
The Five-Question Audit (run on every page)
These five questions sit upstream of every checklist. If a page fails any of them, the checklists are decoration.
- Who is this for? A specific person — not "everyone."
- What do they need to know? One essential piece, not five.
- What do they need to do? One clear action, not a menu.
- Why should they trust us? Specific proof, not adjectives.
- What's stopping them? A real objection, named and answered.
If you cannot answer all five in plain prose before opening DevTools, no audit will save the page.
Tailwind: This Repo vs Greenfield Apps
The v3/v4 comparison and the principle behind both lives in Design Language — Tailwind mechanism per context.
Context
- Dreamineering Design System (live reference)
- Process Optimisation — checklists as expert tools
- Value Speed — speed as a design principle
- Standards — why measurable thresholds matter