@brunosps00/dev-workflow 0.11.0 → 0.15.0

package/scaffold/skills/dw-ui-discipline/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: dw-ui-discipline
+description: Use BEFORE any UI work — runs a 4-question grounding (where do design decisions come from, what does this surface help the user do, what states does it have, who uses it where), then enforces the WCAG 2.2 AA floor and 14 visual-slop checks so UI ships with intent instead of training-data defaults.
+---
+
+# UI Discipline
+
+Training-data defaults are the enemy. An ungrounded LLM proposing UI will reach for `#3B82F6` blue, `rounded-lg` radius, center-aligned text, and gradient backgrounds — because those screenshots dominate training data. The surface ends up looking like every other SaaS dashboard, and users can't tell what to look at first.
+
+This skill blocks that autopilot at four grounding questions before any visual decision lands. After the questions pass, it enforces an accessibility floor and runs a visual-slop catalog as the proposed design comes together.
+
+## When to use
+
+- Inside `/dw-redesign-ui` — both proposal and validation steps.
+- Inside `/dw-create-techspec` when the spec has UI sections.
+- Inside `/dw-functional-doc` when documenting screen-level patterns.
+- Inside `/dw-code-review` when the diff touches UI files (CSS, JSX, templates).
+- Inside `/dw-brainstorm` when the conversation drifts into visual direction.
+
+If you're tempted to skip this "because it's just a small tweak" — that's the trigger. Run the grounding.
+
+## The four grounding questions
+
+Answer all four before proposing colors, layouts, components, or any visual decision.
+
+### 1. Where do design decisions come from?
+
+Find the project's design source-of-truth in this order:
+1. `.dw/rules/<frontend-module>.md` design system section.
+2. `DESIGN.md`, `BRAND.md`, `STYLE_GUIDE.md` at project root.
+3. Design token config — Tailwind theme, CSS variables in `theme.css`/`globals.css`, MUI/Chakra theme.
+4. Component library config — `components.json` for shadcn, theme exports.
+5. Storybook stories (implicit canonical components).
+
+If **at least one** exists: it wins. Defer to it. If a needed token is missing (e.g., a danger-secondary color), propose adding it to the authority FIRST, not inline.
+
+If **none exists**: read `references/curated-defaults.md` and pick one of the 10 neutral palettes + one of the 10 font pairings shipped there. Mark the choice in the techspec/PR description: "Design source: no project authority found; using curated default `<name>`; recommend establishing `DESIGN.md`."
+
+**Anti-patterns at this question:**
+- Inventing color hex values inline (`bg-[#FF6B35]`).
+- "I'll use Tailwind defaults" — that's training-data defaults, not project authority.
+- Copying values from "a site I like" without understanding what it solved.
+
+### 2. What does this surface help the user do?
+
+Write one sentence: **"This surface helps the user `<verb-phrase>` so that `<outcome>`."**
+
+Good examples:
+- "...helps the user filter overdue invoices so they can chase late payers in under 30 seconds."
+- "...helps the on-call engineer diagnose which deploy caused the spike so they can roll back without paging the team."
+- "...helps the manager approve or reject expense reports without leaving Slack."
+
+Bad examples:
+- "This surface displays invoice data." (no user, no outcome)
+- "Settings page for managing the account." (vague, no specificity)
+- "Dashboard." (one word)
+
+If you can't write the sentence, the requirements are unclear. Stop and clarify before proceeding.
+
+### 3. What states does the surface have?
+
+Enumerate all states before designing the happy path. Minimum nine, plus domain-specific ones — see `references/state-matrix.md`:
+
+`default`, `hover`, `active`, `focus-visible`, `disabled`, `loading`, `empty`, `error`, `success` plus any domain states (read/unread, online/offline, stale/fresh, pending/approved/rejected, draft/saved/dirty, partial/complete, etc.).
+
+Missing a state at design time = production bug later. The "we'll add empty state later" trap is real.
+
+### 4. Who uses this surface, where, and in what mood?
+
+One sentence: **"`<Who>` uses this on `<where>` in `<what light>` while `<what mood>`."**
+
+Good examples:
+- "An on-call engineer uses this on a dark-room laptop at 3am while troubleshooting a fire."
+- "A field nurse uses this on a phone in bright outdoor light while juggling clipboards."
+- "A receptionist uses this on a 24″ monitor at a busy front desk while talking to a visitor."
+
+Decisions cascade from the answer:
+- 3am dark room → dark mode, high contrast, no flashing animations.
+- Bright outdoor → minimum 7:1 contrast, larger touch targets, no thin fonts.
+- Busy front desk → glanceable info, no nested menus, large numbers.
+
+Without this sentence, defaults take over: light mode, default contrasts, animations, regular touch targets. Production users hate it; you can't articulate why.
+
+## Required reading by context
+
+| Doing what | Read |
+|------------|------|
+| Any UI work (the full version of the grounding) | `references/hard-gate.md` |
+| Reviewing or proposing a design | `references/visual-slop.md` (14 patterns + specific anti-default values) |
+| Designing state coverage | `references/state-matrix.md` |
+| Interactive widget (button, form, modal, anything clickable) | `references/accessibility-floor.md` |
+| No design authority exists in the project | `references/curated-defaults.md` (palettes / fonts / scales) |
+
+## The 14 visual-slop patterns (full catalog in `references/visual-slop.md`)
+
+Watch for these in proposed designs and PR diffs:
+
+1. **Uniform-section flatness** — every section looks like every other section; no anchor for the eye.
+2. **Soft hierarchy** — headings barely larger than body; primary CTA same color as secondary.
+3. **Decorative hover** — hover states that don't change anything functional or clickable.
+4. **Emoji as ornament** — emojis in headers, CTAs, section labels where they add no information.
+5. **Gradient cover** — gradients used to mask weak composition rather than serve a poetic hero.
+6. **Glass-on-everything** — frosted-glass effect on every panel, including ones with nothing behind.
+7. **Center-aligned by default** — body paragraphs and forms reading center where left would read better.
+8. **Grayscale wash** — neutral grays everywhere, no accent personality, no character.
+9. **Verb-less CTAs** — "Get Started", "Learn More", "Click Here", "Submit", "OK".
+10. **Stock-illustration hero** — figure-with-laptop, diverse-team-around-table, abstract floating shapes.
+11. **Shadow soup** — shadows on cards on shadows on borders on gradients on one element.
+12. **Generic spinner** — wall-clock spinner as the only loading state for every operation.
+13. **Silent empty state** — "No items found." centered. Nothing else. No guidance.
+14. **Toast everywhere** — every UI event becomes a toast; five stack up and none get read.
+
+Plus 17 anti-default values (specific colors, radii, font choices, spacing presets) that signal "no thought went into this" — full list in `references/visual-slop.md`.
+
+## Accessibility floor — non-negotiable
+
+Before any interactive widget ships:
+
+- [ ] Color contrast meets WCAG 2.2 AA (4.5:1 body, 3:1 large text and UI components).
+- [ ] Focus-visible state distinct from hover.
+- [ ] Keyboard navigation works end-to-end.
+- [ ] ARIA labels for icon-only buttons.
+- [ ] Form errors announced to screen readers.
+- [ ] No keyboard traps.
+- [ ] Touch targets ≥24×24 CSS pixels (≥44×44 recommended on mobile).
+- [ ] Heading hierarchy is semantic (no skipped levels).
+- [ ] `prefers-reduced-motion` honored.
+
+Full verification recipes in `references/accessibility-floor.md`. `/dw-code-review` rejects the verdict if any interactive widget ships without these.
+
+## When the grounding bends
+
+- **Bug fix in existing UI** — grounding applies only to the area touched, not the whole surface.
+- **Pure copy change** — only the "what does this help the user do" question still applies as a sanity check.
+- **Throwaway spike** — grounding skippable if the spike is explicitly marked non-production.
+
+In all bend cases, document the bend in the PR (one line). "I skipped the state matrix because this is a one-line copy fix" is fine. "I skipped because I was in a hurry" is not.
+
+## Integration with dev-workflow commands
+
+- `/dw-redesign-ui` runs the grounding end-to-end. Steps 4 (propose) and 7 (validate) consult this skill explicitly.
+- `/dw-create-techspec` UI sections must answer the 4 grounding questions and reference the state matrix.
+- `/dw-code-review` checks UI diffs against the 14 visual-slop patterns and the accessibility floor.
+- `/dw-functional-doc` records the surface-job and scene sentences in the overview for each screen.
+
+## Why this approach
+
+The shorter route — "agent loads a 161-palette catalog and picks one" — produces dashboards that look like every other dashboard because the agent has no constraint that pulls it away from training-data centers of mass.
+
+The grounding pulls the design toward the specific surface, the specific user, the specific moment. Even with the same palette catalog, a "3am on-call dark room troubleshooting" design lands different choices than a "morning manager approving expenses" design. That difference is where surface quality lives.

package/scaffold/skills/dw-ui-discipline/references/accessibility-floor.md

@@ -0,0 +1,225 @@
+# Accessibility floor — WCAG 2.2 AA is the minimum, not the goal
+
+This reference is read in full before any interactive widget ships. Skipping any item below is a hard-block in `/dw-code-review`.
+
+## The non-negotiables
+
+### 1. Color contrast
+
+| Element | Minimum ratio (WCAG 2.2 AA) |
+|---------|----------------------------|
+| Body text (under 18pt or under 14pt bold) | 4.5:1 |
+| Large text (18pt+ or 14pt+ bold) | 3:1 |
+| UI components (button borders, icons, focus rings) | 3:1 |
+| Decorative graphics | No requirement |
+
+**Verification:**
+- Use `axe DevTools` browser extension OR `playwright/test` with `@axe-core/playwright`.
+- Manual quick check: `chrome://flags` → Enable "Simulate Vision Deficiencies" + try "Achromatopsia" (no colors). If buttons still legible, contrast is doing its job.
+
+**Common violation:** Light gray text on white. `#9CA3AF` on white = 2.85:1. FAIL.
+
+### 2. Focus-visible state
+
+Every interactive element must have a distinct focus-visible state when keyboard-focused.
+
+**Rules:**
+- `:focus-visible` MUST be distinct from `:hover` — keyboard users need an affordance.
+- Default browser outline is acceptable; replacing with `outline: none` requires alternative (border, ring, shadow).
+- Focus must be visible against any background the element can appear on (dark + light themes).
+
+**Tailwind pattern:**
+```css
+focus-visible:outline-none
+focus-visible:ring-2
+focus-visible:ring-offset-2
+focus-visible:ring-blue-500
+```
+
+**Verification:**
+- Tab through the entire surface with keyboard. Every interactive element must light up visibly.
+- If you can't tell what's focused, the contrast on the focus ring is too low.
+
+### 3. Keyboard navigation
+
+| Capability | Requirement |
+|------------|-------------|
+| Tab order | Logical (left-to-right, top-to-bottom in LTR) |
+| Modals | Tab cycles WITHIN modal; Escape closes; focus returns to trigger |
+| Dropdowns / select | Arrow keys navigate options; Enter selects; Escape closes |
+| Forms | Enter submits; Tab moves to next field; Shift+Tab moves back |
+| Custom widgets | Match the ARIA Authoring Practices Guide patterns |
+
+**Verification:**
+- Unplug mouse. Complete the primary user flow with keyboard only.
+- If you got stuck or couldn't reach an element, keyboard nav is broken.
+
+### 4. ARIA labels for icon-only interactives
+
+Icon-only buttons (e.g., a trash can icon as a delete button) need `aria-label` describing the action.
+
+```html
+<!-- BAD -->
+<button><TrashIcon /></button>
+
+<!-- GOOD -->
+<button aria-label="Delete invoice"><TrashIcon /></button>
+```
+
+Same applies to:
+- Icon-only links
+- Icon-only toggles
+- Tooltips (the trigger needs aria-describedby pointing to the tooltip)
+- Decorative images (`aria-hidden="true"` if purely decorative; `alt=""` not enough)
+
+### 5. Form errors announced to screen readers
+
+When a form field errors:
+
+```html
+<label for="email">Email</label>
+<input
+  id="email"
+  type="email"
+  aria-describedby="email-error"
+  aria-invalid="true"
+/>
+<span id="email-error" role="alert">
+  Email is required
+</span>
+```
+
+Key points:
+- `aria-invalid="true"` on the input.
+- `aria-describedby` links the input to the error message.
+- `role="alert"` on the error message announces it.
+
+**Anti-pattern:** Red border + tooltip on hover. Screen reader users get nothing.
+
+### 6. No keyboard traps
+
+A "keyboard trap" is when focus enters a widget and can't leave with the keyboard. Most common cause: custom-built modals or carousels.
+
+**Rule:** Every modal, drawer, or overlay must let Escape close it and return focus to the trigger element.
+
+**Verification:**
+- Open the widget with keyboard. Press Escape. Does focus return to where it was?
+- Tab through the widget. After last element, does Tab cycle to first (within widget) instead of leaving the page?
+
+### 7. Touch target size (mobile)
+
+Minimum 24x24 CSS pixels (WCAG 2.2 AA minimum). Recommended 44x44 (Apple HIG / Android touch target).
+
+**Pattern:** Even when the visual icon is 16x16, give the button 44x44 hit area:
+
+```css
+button {
+  width: 24px; height: 24px;  /* WCAG 2.2 AA minimum */
+  /* Or */
+  width: 44px; height: 44px;  /* Recommended */
+  padding: 14px;  /* Visual icon inside */
+}
+```
+
+### 8. Heading hierarchy
+
+H1 → H2 → H3 etc. Don't skip levels. Don't use heading tags for visual sizing — use semantic level + CSS for size.
+
+```html
+<!-- BAD -->
+<h2>Section A</h2>
+<h4>Subsection</h4>  <!-- skipped h3 -->
+
+<!-- GOOD -->
+<h2>Section A</h2>
+<h3>Subsection</h3>
+```
+
+Screen readers navigate by heading; broken hierarchy disorients.
+
+### 9. Language attribute
+
+Root `<html lang="en">` (or correct ISO code) for primary language. Sections in other language need `lang` attribute too.
+
+```html
+<html lang="en">
+  <p>Welcome.</p>
+  <p lang="pt-br">Bem-vindo.</p>
+</html>
+```
+
+Screen readers switch pronunciation based on this.
+
+### 10. Reduced motion respect
+
+Honor `prefers-reduced-motion`:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+Or in Tailwind:
+```html
+<div className="transition-all motion-reduce:transition-none">
+```
+
+Vestibular disorders trigger on parallax, large slide-ins, infinite scroll animations.
+
+## Verification recipes
+
+### Automated (CI)
+
+```ts
+// playwright + axe-core
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test('homepage a11y', async ({ page }) => {
+  await page.goto('/');
+  const results = await new AxeBuilder({ page })
+    .withTags(['wcag2a', 'wcag2aa', 'wcag22a', 'wcag22aa'])
+    .analyze();
+  expect(results.violations).toEqual([]);
+});
+```
+
+Run on every PR. Block merge on violations.
+
+### Manual (PR review)
+
+1. Open the changed page.
+2. Tab through with keyboard only. Verify focus visible at every stop.
+3. Run axe DevTools, fix violations.
+4. Toggle prefers-reduced-motion in DevTools rendering panel. Verify animations stop.
+5. Test with screen reader (VoiceOver on Mac, NVDA on Windows) on at least one critical flow.
+
+### Spot checks
+
+Color contrast: chrome devtools → element inspector → "Contrast" indicator next to text color. Click for actual ratio.
+
+Touch target: Inspect element → check computed width/height. If < 24, flag.
+
+## When the floor bends
+
+- **Iframes you don't control** — your wrapper still has to be accessible, the iframe is best-effort.
+- **Third-party widgets** (analytics dashboards, payment SDKs) — wrap with ARIA landmarks; report violations upstream.
+- **Legacy code being patched** — bring touched components up to floor; leave untouched ones for separate accessibility-debt work.
+
+In all bend cases, file a tracking issue. Don't pretend the floor was met.
+
+## Common AI-generated UI violations
+
+LLM-produced UI commonly fails on:
+- `<div onClick>` instead of `<button>` (not keyboard-accessible).
+- Icon-only buttons with no aria-label.
+- `text-gray-400` on white (contrast 2.8:1 — fail).
+- `outline: none` with no replacement focus state.
+- Modals that trap focus only on success path, not on error.
+- Auto-playing carousels with no pause control.
+
+`/dw-code-review` runs axe-style checks on the diff for these.

package/scaffold/skills/dw-ui-discipline/references/curated-defaults.md

@@ -0,0 +1,195 @@
+# Curated defaults — 10 palettes + 10 font pairings + spacing scale
+
+Use this reference when the project has **no design authority** (no `.dw/rules/` design section, no `DESIGN.md`, no Tailwind theme tokens, no component library config).
+
+The values below cover ~90% of cases that need a starting point. Not opinionated branding — neutral, accessible, professional defaults.
+
+## How to use
+
+1. Pick ONE palette + ONE font pairing + the spacing scale.
+2. Commit the choice to the project (`.dw/rules/<frontend>.md` design section OR a new `DESIGN.md`).
+3. From there, the project HAS a design authority; downstream `dw-ui-discipline` invocations defer to that authority.
+
+This is bootstrap, not destination. The goal is to escape "no authority" mode within the first feature.
+
+## The 10 palettes
+
+Each palette below: neutral scale (gray, slate, etc.) + 1 accent + semantic colors. All WCAG 2.2 AA compliant for body text.
+
+### 1. Cool Stone
+- Neutrals: Tailwind `slate` (50-950)
+- Accent: `#3B82F6` (blue-500) — wait, no, see Anti-Slop. Use `#0066CC` instead.
+- Semantic: success `#16A34A`, warning `#D97706`, danger `#DC2626`
+- **Tone:** Calm, corporate, trustworthy. Default for SaaS dashboards.
+
+### 2. Warm Sand
+- Neutrals: Tailwind `stone` (50-950)
+- Accent: `#CA8A04` (warm amber)
+- Semantic: success `#16A34A`, warning `#EA580C`, danger `#DC2626`
+- **Tone:** Approachable, hospitality-adjacent, organic.
+
+### 3. Forest Pine
+- Neutrals: Tailwind `gray` (50-950)
+- Accent: `#15803D` (deep green)
+- Semantic: success `#16A34A`, warning `#D97706`, danger `#B91C1C`
+- **Tone:** Steady, financial, sustainable.
+
+### 4. Plum Velvet
+- Neutrals: Tailwind `zinc` (50-950)
+- Accent: `#7C3AED` (violet-600)
+- Semantic: success `#22C55E`, warning `#EAB308`, danger `#E11D48`
+- **Tone:** Creative, premium, design-tool.
+
+### 5. Coral Reef
+- Neutrals: Tailwind `neutral` (50-950)
+- Accent: `#E11D48` (rose-600)
+- Semantic: success `#16A34A`, warning `#F59E0B`, danger `#B91C1C`
+- **Tone:** Energetic, consumer, retail.
+
+### 6. Steel Blue
+- Neutrals: Tailwind `slate` (50-950)
+- Accent: `#0F766E` (teal-700)
+- Semantic: success `#16A34A`, warning `#D97706`, danger `#DC2626`
+- **Tone:** Technical, infrastructure, devops.
+
+### 7. Burnt Sienna
+- Neutrals: Tailwind `stone` (50-950)
+- Accent: `#C2410C` (orange-700)
+- Semantic: success `#15803D`, warning `#A16207`, danger `#B91C1C`
+- **Tone:** Bold, news, sports.
+
+### 8. Ink and Paper
+- Neutrals: Pure `#000` and `#FFF` with `#E5E5E5` divider
+- Accent: `#000` (no accent — minimal)
+- Semantic: success `#16A34A`, warning `#D97706`, danger `#DC2626`
+- **Tone:** Editorial, brutalist, magazine. Pair with serif body.
+
+### 9. Midnight Indigo
+- Neutrals: Tailwind `slate` dark-mode-first (900-50)
+- Accent: `#6366F1` (indigo-500)
+- Semantic: success `#22C55E`, warning `#FACC15`, danger `#EF4444`
+- **Tone:** Tech-forward, dark-mode-default, on-call tooling.
+
+### 10. Sea Salt
+- Neutrals: Tailwind `gray` cool (50-950)
+- Accent: `#0891B2` (cyan-600)
+- Semantic: success `#10B981`, warning `#F59E0B`, danger `#F43F5E`
+- **Tone:** Fresh, healthcare, education.
+
+## The 10 font pairings
+
+Each pairing: heading font / body font. All available on Google Fonts. Variable fonts where possible.
+
+| # | Headings | Body | Tone |
+|---|----------|------|------|
+| 1 | Inter | Inter | Modern SaaS default. Workhorse pairing. |
+| 2 | Geist Sans | Geist Sans | Vercel-aesthetic; clean, geometric. |
+| 3 | Söhne (or Manrope) | Söhne (or Manrope) | Editorial-modern; replaces Inter when Inter feels overused. |
+| 4 | DM Serif Display | Inter | Editorial-meets-product. Strong headlines, neutral body. |
+| 5 | Fraunces | Inter | Variable serif headlines, sans body. Premium feel. |
+| 6 | Source Serif 4 | Source Sans 3 | Adobe pairing; balanced editorial. |
+| 7 | Space Grotesk | Inter | Slightly quirky headlines, neutral body. Tech with personality. |
+| 8 | IBM Plex Serif | IBM Plex Sans | Industrial, opinionated. Good for enterprise tooling. |
+| 9 | Playfair Display | Manrope | High contrast pairing; hospitality, lifestyle. |
+| 10 | JetBrains Mono | Inter | Code-first products; mono for headlines and accents. |
+
+**Anti-default reminder:** Inter / Inter is fine. Inter / Inter as the ONLY pairing you ever pick is a tell.
+
+## Spacing scale
+
+Use a 4px-base scale with intentional jumps:
+
+```
+0:   0px
+1:   4px   (tight controls, icon padding)
+2:   8px   (compact spacing)
+3:   12px  (default gap in form fields)
+4:   16px  (default gap between blocks)
+6:   24px  (section padding)
+8:   32px  (large section spacing)
+12:  48px  (page header / hero padding)
+16:  64px  (between major sections)
+24:  96px  (hero / landing block separators)
+32:  128px (rare; signature spacing)
+```
+
+**Skip these by default:** 5, 7, 9, 10, 11, 13, 14, 15. Picking exactly 4-6-8-12-16 reads more intentional than 1-2-3-4-5-6-...
+
+## Border radius scale
+
+Pick a "personality" once and use it consistently:
+
+| Radius | Tone |
+|--------|------|
+| 0 (square) | Brutalist, editorial |
+| 2px | Subtle modernist |
+| 4px (Tailwind `rounded`) | Standard |
+| 6px | Slightly friendly |
+| 8px (Tailwind `rounded-lg`) | Default SaaS; **anti-default if used universally** |
+| 12px | Softer, consumer |
+| 16px+ | Rounded everything; friendly/youth-oriented |
+| Full / 9999px | Pills, buttons, avatars only |
+
+Don't mix more than 2 radii in one surface (e.g., 4px for inputs, 8px for cards). Three+ radii = visual noise.
+
+## Type scale
+
+For body=16px baseline:
+
+```
+xs:    12px  (captions, helper text — minimum 11px)
+sm:    14px  (secondary, labels)
+base:  16px  (body)
+lg:    18px  (lead paragraphs)
+xl:    20px  (small headings)
+2xl:   24px  (subheadings)
+3xl:   30px  (section headings)
+4xl:   36px  (page titles)
+5xl:   48px  (hero, marketing)
+6xl+:  60-96px (display, marketing only)
+```
+
+Line-height pairs:
+- Body text: 1.5 to 1.6
+- Headings: 1.1 to 1.25
+- Buttons: 1 (tight)
+
+## How to commit a choice
+
+After picking a palette + pairing + spacing, write `.dw/rules/<frontend>.md` (or `DESIGN.md`) with:
+
+```markdown
+## Design System (bootstrap)
+
+**Source:** Curated default — `dw-ui-discipline/references/curated-defaults.md`, picked Cool Stone + Inter/Inter + 4px-base scale on 2026-05-12.
+
+### Colors
+- Neutrals: Tailwind slate (50-950)
+- Accent: #0066CC (links, primary buttons, focus rings)
+- Success: #16A34A · Warning: #D97706 · Danger: #DC2626
+
+### Typography
+- Headings: Inter, weight 600-700
+- Body: Inter, weight 400-500
+- Mono: JetBrains Mono (code blocks only)
+
+### Spacing
+4px base scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96.
+
+### Border radius
+4px on inputs, 8px on cards, full on pills/avatars.
+
+### Updates
+This file is the canonical design source. To change a value, propose a PR
+that updates this file FIRST, then propagates through code.
+```
+
+Once written, `dw-ui-discipline` reads this file instead of `curated-defaults.md`. The bootstrap step is done.
+
+## What this catalog is NOT
+
+- Not 161 palettes. Not 57 fonts. By design.
+- Not a substitute for brand work — for a serious product, hire a designer.
+- Not opinionated about industry-specific aesthetics (med-tech, gaming, kids' content). Those need real design pass.
+
+The point is: have ONE intentional starting point so the agent isn't reaching for `#3B82F6` and `rounded-lg`. Project-specific design follows.