# Cowork UI Kit v0.5 — Release Notes

Released: 2026-05-20
Live: https://ui.dang.pm/

## v0.5.12 — Iter 44-45 (2026-05-20) [CURRENT]

Arc consolidation: 3 new components closing final 3 of ROADMAP top-10 (TreeView R6, Tag R9, Resizable Panels R10) + 2 new doc tracks (MICROCOPY + FLOWS) with HTML demos + a11y remediation on date-picker/file-uploader + G20 gotcha codified + snapshot 403 fix + Lighthouse per-component CI gate.

### Iter 44A — TreeView (closes R6)

📄 [organisms/treeview.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/treeview.html) + 📄 [organisms/TREEVIEW.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/TREEVIEW.md). APG TreeView pattern. File explorer / nav tree / taxonomy editor primitive — moved out of "DIY" territory.

### Iter 44B — Tag interactive (closes R9)

📄 [atoms/tag.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/tag.html) + 📄 [atoms/TAG.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/TAG.md). Dismissable filter chips with `×` close + keyboard. Badge atom is display-only — Tag now covers the interactive case.

### Iter 44C — MICROCOPY library

📄 [MICROCOPY.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/MICROCOPY.md) (root) + 📄 [microcopy/index.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/microcopy/index.html). Voice + tone rules for button labels, empty states, error messages, CTA copy. Brand-agnostic baseline, Vietnamese-first.

### Iter 44D — FLOWS catalogue

📄 [FLOWS.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/FLOWS.md) (root) + 4 HTML demos: 📄 [flows/login.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/flows/login.html), 📄 [flows/checkout.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/flows/checkout.html), 📄 [flows/onboarding.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/flows/onboarding.html), 📄 [flows/settings.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/flows/settings.html). Multi-step journey patterns.

### Iter 45A — Resizable Panels / Splitter (closes R10 — ROADMAP top-10 10/10)

📄 [organisms/resizable-panels.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/resizable-panels.html) + 📄 [organisms/RESIZABLE-PANELS.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/RESIZABLE-PANELS.md). APG Window Splitter pattern. B-Tool archetype no longer needs hand-rolled splitter — primitive available.

### Iter 45B — a11y remediation + G20 codified

Applied a11y fixes to 📄 [molecules/date-picker.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/date-picker.html) + 📄 [atoms/file-uploader.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/file-uploader.html). Lighthouse a11y 100/100 confirmed in 📁 [_lighthouse/postfix-iter43k-a11y/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/postfix-iter43k-a11y/) (page-1.json + page-2.json).

G20 codified in 📄 [FINAL-STATE.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/FINAL-STATE.md).

### Iter 45C — Snapshot 403 fix + Lighthouse per-component CI + v0.5.12 cut

- **403 fix**: nginx `autoindex off` returned 403 on `/v0.5.10/`, `/v0.5.11/` snapshot roots. Added `index.html` (archetype C warm, brand-tinted gradient hero + 3-col card grid linking foundation/atomic-design/patterns/docs/flows) to all three current snapshots. Template lives in 📁 [_releases/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_releases/) — reusable for future snapshots.
- **Lighthouse per-component CI gate**: new 🔧 [scripts/ci/lighthouse-component-gate.sh](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/scripts/ci/lighthouse-component-gate.sh). Headless Lighthouse run on N component URLs, threshold a11y ≥95, fail build under threshold. Documented in 📄 [CI.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/CI.md) § Lighthouse per-component check. Reference: Iter 45B already evidenced 100/100 on the 2 fixed components in 📁 [_lighthouse/postfix-iter43k-a11y/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/postfix-iter43k-a11y/).
- **v0.5.12 immutable snapshot cut**: 565 files / ~42 MB. Allowlist now includes `microcopy/` + `flows/` + `MICROCOPY.md` + `FLOWS.md` + `UX-PATTERNS.md` + `ROADMAP-COMPLETENESS.md` (allowlist expanded from 22 root files → 24).
- **ROADMAP-COMPLETENESS 72% → 100% Tier-1 top-10**: 10/10 top-missing closed. Atoms 82% → 88% (Tag added). Organisms 40% → 55% (TreeView + Resizable Panels added). Aggregated weighted avg +8pt.

## v0.5.11 — Iter 42-43K (2026-05-20)

Arc consolidation: 4 new form atoms (DatePicker, NumberInput, Slider, FileUploader) shipped Iter 42B-D, motion + uxstate cleanup Iter 42A, G19 gotcha codified, templates/ 7 pre-existing fails triaged as decorative-by-design (`aria-hidden="true"`), CI gate URL count Lighthouse 42→46 + Probe 16→20.

### Iter 42A — cleanup + G15 clamp backoff + G19 candidate flagged

- Cleanup pass on 📄 [atoms/loading-progress.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/loading-progress.html) + 📁 [uxstate/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/uxstate/). G15 clamp on `.progress-circle__label` had backfired (clamped color same-hue family as conic-gradient bg = 1.81:1 worse contrast).
- Replaced G15 clamp with **G19 pattern**: gave text element its own opaque self-bg `var(--surface)` — visually identical to "label floating on cream", probe-truthful (probe walks parent chain, sees opaque parent as effective bg, no longer misled by gradient first-stop).
- Motion a11y remediation 97 → 100.
- G19 candidate flagged for codification (closed Iter 43K).

### Iter 42B — DatePicker

📄 [molecules/date-picker.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/date-picker.html) (4 variants: single date input, calendar dialog, date range, inline calendar) + 📄 [molecules/DATEPICKER.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/DATEPICKER.md). 131/131 probe PASS. Closes Roadmap top-missing #1.

### Iter 42C — NumberInput + Slider

- 📄 [atoms/number-input.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/number-input.html) (5 variants: basic spinbutton, stepper buttons, with prefix/suffix, currency input, percentage) + 📄 [atoms/NUMBER-INPUT.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/NUMBER-INPUT.md). 135 probe PASS. Closes Roadmap top-missing #2.
- 📄 [atoms/slider.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/slider.html) (6 variants: single thumb, range, step ticks, labeled, vertical, with tooltip) + 📄 [atoms/SLIDER.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/SLIDER.md). 116 probe PASS. Closes Roadmap top-missing #3.

### Iter 42D — FileUploader

📄 [atoms/file-uploader.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/file-uploader.html) (4 variants: dropzone with click, with preview list, multi-file with progress, image-specific with thumbnail) + 📄 [atoms/FILE-UPLOADER.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/FILE-UPLOADER.md). 162/162 probe PASS. Closes Roadmap top-missing #4.

### Iter 43K — Consolidation [THIS RELEASE]

- **G19 codified** in 📄 [FINAL-STATE.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/FINAL-STATE.md): gradient parent + `::after` opaque mask probe blind spot. Probe `getEffectiveBg()` walks parent chain but doesn't introspect `::before`/`::after` pseudo-elements. Fix: text element gets its own opaque self-bg to bypass probe ambiguity — structurally CORRECT (probe AND user see same color now).
- **templates/ triage**: 7 pre-existing probe fails (flagged Iter 42A on `https://ui.dang.pm/templates/`) — all 7 are **decorative-by-design wireframe annotations**:
  - 4× numbered step circles `01`/`02`/`03`/`04` with `fg==bg` 1:1 (intentional design device — ornamental "tonal" numbers behind filled circle)
  - 2× `.cta-primary-ghost` bracket-wrapped placeholder labels `[Primary action]`/`[Action]` (wireframe annotations signaling "this is where CTA goes", not real button text)
  - 1× `.zone-note` "/ workspace switcher" (template region label, similar wireframe annotation)
  - Applied `aria-hidden="true"` on all 7 + HTML comment documenting why low-contrast is intentional. Probe MAY still flag (it doesn't read aria-hidden) — they're now marked source-of-truth as DECORATIVE.
- **Decorative-low-contrast policy** documented in 📄 [CI.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/CI.md): when text is genuinely DECORATIVE (vd numbered ornaments, wireframe placeholders, bracket-wrapped sample labels), apply (1) `aria-hidden="true"` so screen readers skip, (2) HTML comment `<!-- DECORATIVE by design: ... -->` documenting intent, (3) accept probe FAIL as known/intentional.
- **ROADMAP-COMPLETENESS bumped**: 62% → **72%**. 5/10 top-missing closed (EmptyState + 4 Iter 42 components). Iter 43L's Toolbar + SegmentedControl not counted (still in progress).
- **CI URL expansion**: Lighthouse DEFAULT_URLS 42 → **46** (added date-picker, number-input, slider, file-uploader). Probe DEFAULT_URLS 16 → **20** (same 4 URLs). Wired in all 4 scripts (🔧 .sh + .ps1 mirrors for both lighthouse-check + gradient-contrast-probe).
- **Immutable snapshot** at 🌐 https://ui.dang.pm/v0.5.11/ — mirrors v0.5.10 + Iter 42 arc deltas.

### Iter 43K — known a11y candidates (not auto-fixed, future iter)

Iter 43K smoke verification surfaced 2 new components below brief's a11y ≥95 target (date-picker 92, file-uploader 90). NOT auto-fixed per brief constraint "document any new violations as G20+ candidates, don't auto-fix". Tracked as G20+ candidates for next iter:

- **date-picker.html** (a11y 92): `aria-allowed-attr` (ARIA attributes don't match roles — likely on calendar grid cells), `landmark-one-main` (missing `<main>` wrapper around `#stage`).
- **file-uploader.html** (a11y 90): `aria-progressbar-name` (progressbar without accessible name — multi-file upload variant has progress with no label), `label` (file input without associated label visible to Lighthouse), `landmark-one-main` (missing `<main>` wrapper).

All 4 fail with the same pattern as Iter 35a/c galleries fixed prior — `<main>` landmark + targeted aria-label adds via JS or markup. Quick fix candidate for next iter (~10min each).

### v0.5.11 metrics

| Metric | v0.5.10 | v0.5.11 |
|---|---|---|
| CI gate URL count (Lighthouse) | 42 | **46** |
| Probe gate URL count | 16 | **20** |
| CI guards default-on | 7 | **7** (unchanged) |
| New components (atoms+molecules) | 0 (motion/uxstate were Iter 40) | **4** (DatePicker + NumberInput + Slider + FileUploader) |
| Demo variants shipped (Iter 42) | 0 | **19** (4 + 5 + 6 + 4) |
| FINAL-STATE.md gotchas documented | 18 (G1-G18) | **19** (G15-G19, G19 = probe + `::after` blind spot) |
| ROADMAP-COMPLETENESS top-10 closed | 1/10 (EmptyState) | **5/10** (+ DatePicker/NumberInput/Slider/FileUploader) |
| Kit completeness vs Tier-1 estimate | 62% | **72%** |

---

## v0.5.10 — Iter 37-41 (2026-05-20) [superseded by v0.5.11]

Arc consolidation: motion system + UX state components + gotcha codification (G15-G18) + probe stabilization (timeout fix + CI default-on). Adds reference docs (ROADMAP-COMPLETENESS, UX-PATTERNS) without changing archetype tokens beyond Iter 40A motion additions.

### Iter 37/38a/38c — brands/ + demo a11y fixes

Iter 37: `brands/.brand-vibe` clamp tighter (L≤24%) + `.meta-tag` opaque bg + `.sale-timer` clamped → 0 fails on brands/. Iter 38a: discovered + fixed `demo/brand-switcher.html .eyebrow` raw `--primary` (mid-tone brand L≥45% breakage on cream — G15). Iter 38c: `.brand-head` blend-mode multiply discovered (G17 — required +1-stop tighter clamp). Together: brands/ + demo at 0 gradient-probe fails.

### Iter 38b — gradient-contrast-probe (probe-runner.html, .sh, .ps1)

Built reusable probe HTML deployed to `https://ui.dang.pm/_probe/` (same-origin to ui.dang.pm). CLI scripts in 🔧 [_build/gradient-contrast-probe.sh](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_build/gradient-contrast-probe.sh) + 🔧 [_build/gradient-contrast-probe.ps1](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_build/gradient-contrast-probe.ps1) invoke Chrome headless against probe URL with `?url=<target>`, parse `PROBE_JSON:{…}` from `document.title`. Wired as Guard 6 in 🔧 [_build/ci-check.sh](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_build/ci-check.sh) (opt-in env `CI_GRADIENT_PROBE=1`, default 0 at Iter 38b — see Iter 41 for flip).

### Iter 39a — _previews/ G14 elimination via inline hex

Fixed 10 G14 failures on 📄 [_previews/01-landing.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_previews/01-landing.html) + 📄 [_previews/02-admin.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_previews/02-admin.html) — Tailwind classes `from-rose-700`, `to-violet-800` were silently dropped because 🐍 [tokens/tailwind-prebuilt.css](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/tailwind-prebuilt.css) doesn't include 700/800 shades (G18 codified). Workaround: inline hex `style="background: linear-gradient(to right, #9f1239, #c2410c);"` — ADR-001 deviation noted. Proper fix (regen prebuilt) tracked.

### Iter 39b — ROADMAP-COMPLETENESS.md

Shipped 📄 [ROADMAP-COMPLETENESS.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/ROADMAP-COMPLETENESS.md): kit at 62% vs Tier-1 (Material/Radix/Ark) component coverage. Top 10 missing components (date picker, command palette, autocomplete, tabs, accordion, drawer, popover, breadcrumbs, stepper, file upload). Roadmap v0.6 → v1.0.

### Iter 39c — UX-PATTERNS.md

Shipped 📄 [UX-PATTERNS.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/UX-PATTERNS.md): 20 patterns codified (auth, search, list/detail, infinite scroll, virtualization, optimistic UI, error boundary, etc.). Gap matrix per pattern + AI-agent decision trees ("if user wants X, pick pattern Y").

### Iter 40A — Motion system

📁 [motion/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/motion/) shipped. **28 motion tokens** added to 🐍 [tokens/foundation.css](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/foundation.css) + 🐍 [tokens/semantic.css](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/semantic.css) (durations, easings, animation primitives). `prefers-reduced-motion` global contract via foundation.css rule wraps all motion (fallbacks to instant when user opts-in to reduced-motion). `.motion-essential` escape hatch class for loading indicators / focus rings that must remain animated even with reduced-motion. 📄 [motion/index.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/motion/index.html) 15-pattern demo. 📄 [motion/MOTION.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/motion/MOTION.md) full doc.

### Iter 40B — UX state components

📁 [uxstate/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/uxstate/) shipped. **4 loading atoms** (📄 [loading-skeleton.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/loading-skeleton.html), 📄 [loading-spinner.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/loading-spinner.html), 📄 [loading-progress.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/loading-progress.html), 📄 [loading-dots.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/loading-dots.html)) + **2 state molecules** (📄 [empty-state.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/empty-state.html), 📄 [error-state.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/error-state.html)) + **toast organism** (📄 [organisms/toast.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/toast.html)) + **2 JS utilities** (🐍 [_assets/focus-trap.js](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_assets/focus-trap.js), 🐍 [_assets/keyboard.js](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_assets/keyboard.js)) + showcase 📄 [uxstate/index.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/uxstate/index.html) + doc 📄 [uxstate/UXSTATE.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/uxstate/UXSTATE.md). All artifacts have full ARIA (status/alert roles, aria-live regions, aria-busy).

### Iter 41 — Probe timeout fix + CI default-on + URL expansion + lock-in [THIS RELEASE]

- **Probe timeout fix**: 40B agent reported probe returning `"probe:init"` with default `--virtual-time-budget=20000` (20s) — inline scripts on uxstate pages need >20s to settle. Bumped `PROBE_TIMEOUT` default `20000 → 45000` in 🔧 [_build/gradient-contrast-probe.sh](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_build/gradient-contrast-probe.sh) + 🔧 [_build/gradient-contrast-probe.ps1](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_build/gradient-contrast-probe.ps1). `PROBE_TIMEOUT` env override preserved.
- **CI default-on flip**: After Iter 41 verification (brands/ + motion/ both `[PASS]` 231 + 139 text elements), flipped `CI_GRADIENT_PROBE` default `0 → 1` in 🔧 [_build/ci-check.sh](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_build/ci-check.sh) + 🔧 [_build/ci-check.ps1](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_build/ci-check.ps1). Guard count rises 6 → 7. Opt-out via `CI_GRADIENT_PROBE=0`.
- **CI URL expansion**: 9 new URLs added to 🔧 [_build/lighthouse-check.sh](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_build/lighthouse-check.sh) + 🔧 [_build/lighthouse-check.ps1](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_build/lighthouse-check.ps1) DEFAULT_URLS: motion + uxstate + 4 loading atoms + 2 state molecules + toast — gate count rises 33 → 42. Same 9 URLs also added to gradient probe DEFAULT_URLS (rises 7 → 16).
- **G15-G18 codified** in 📄 [FINAL-STATE.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/FINAL-STATE.md): G15 (`--primary` raw 11px text on cream — mid-tone brand fail), G16 (`color-mix(... transparent)` chip bleed), G17 (`background-blend-mode: multiply` darker than math), G18 (Tailwind prebuilt shades silently dropped).
- **Immutable snapshot** at 🌐 https://ui.dang.pm/v0.5.10/ — mirrors v0.5.9 + Iter 37-41 deltas (motion/, uxstate/, _assets/, 4 atoms, 2 molecules, toast, edited brands/+demo+previews, updated _build/, ROADMAP-COMPLETENESS.md + UX-PATTERNS.md, updated docs).

### v0.5.10 metrics

| Metric | v0.5.9 | v0.5.10 |
|---|---|---|
| CI gate URL count (Lighthouse) | 33 | **42** |
| Probe gate URL count | 7 | **16** |
| CI guards default-on | 6 | **7** |
| Tokens documented | 75+ | **103+** (Iter 40A added 28 motion) |
| FINAL-STATE.md gotchas documented | 14 | **18** (G15-G18) |
| Loading + state components | 0 | **7** (4 atoms + 2 molecules + 1 organism) |
| Reference docs | 4 (REFERENCE, FINAL-STATE, DESIGN-DECISIONS, CI) | **6** (added ROADMAP-COMPLETENESS, UX-PATTERNS) |

---

## v0.5.9 — Iter 33-36 (2026-05-20)

Consolidated entry covering Iter 33 (brand gallery) → 34 (full sweep audit) → 35a/b/c (3 parallel a11y fix waves) → 36 (CI gate expansion + immutable snapshot). (Superseded by v0.5.10 — see top.)

**Final state:** All 33 public URLs on `ui.dang.pm` pass strict Lighthouse threshold (perf≥90 / a11y≥95 / bp≥90 / seo≥90). A11y specifically: **100/100 on 28/28 URLs measured in Iter 35a/b/c sweeps**. CI gate `_build/lighthouse-check.{sh,ps1}` DEFAULT_URLS expanded 7 → 33.

### Iter 33 — brand gallery a11y 80 → 100

User caught visually ("sao màu chữ với màu nền y nhau vậy?") before any CI gate. Root cause: demo components used raw `var(--primary)` as bg with white text — for brands with primary L ≥ 50% (BetterBuy, Xanh, AI Tools), white-on-primary was 2.93-3.20:1 (fails AA 4.5). Fix: new card-scope token `--primary-text-bg: hsl(... min(L-12%, 32%))` — guaranteed-AA-safe bg for any white-text context. 23 contrast nodes → 0. See G10 in FINAL-STATE.md.

### Iter 34 — full-sweep audit (15 URLs failing baseline)

Ran Lighthouse on every public URL beyond the 6 archetypes. Surfaced 15 URLs scoring below threshold (range 61-96). Triaged into 3 fix waves: a) USAGE+templates+mobile (highest leverage, ~217 contrast nodes), b) 7 _previews/, c) atoms+molecules+organisms+demo+matrix (Atomic Design galleries).

### Iter 35a — USAGE/templates/mobile a11y lift to 100

3 highest-leverage URLs containing ~56% of total contrast violations. Token nudges, no design rebuild. New scoped `--muted-text` variable pattern (G12) avoided `!important` wars. `<main>` landmark added to mobile/. USAGE 88→100, templates 85→100, mobile 96→100.

### Iter 35b — 7 _previews/ a11y lift to 100

All 7 previews scored 71-89 a11y. Fixes per file: `<main>` wrapping (7/7), image alts (33 imgs), icon-only button aria-labels (13 buttons in 03-ecom), Tailwind text-step shifts (lighter steps on dark, darker on cream), HSL token swaps in trend-06 inline `<style>`. All 7 → 100.

### Iter 35c — atoms/molecules/organisms/demo/variant-matrix a11y lift to 100

5 remaining failing URLs. molecules worst at 61. Root causes: 21+8 unlabeled inputs (atoms in isolation), 33+5+32 contrast on dark accent tokens with white text (L=68% violet → 52%, L=53% cyan → 30% etc.), 6 icon-only buttons, 2 target-size fails, opacity-50 transparency bleed. Major learning: G11 (`:root` beats `body` in cascade specificity — overrides on `body` selector were silently failing), G13 (auto-aria-label IIFE — 1 script closed 29 label violations without markup edits). All 5 → 100.

### Iter 36 — CI gate expansion + v0.5.9 immutable snapshot [THIS RELEASE]

Consolidation. DEFAULT_URLS in 🔧 [_build/lighthouse-check.sh](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_build/lighthouse-check.sh) + 🔧 [_build/lighthouse-check.ps1](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_build/lighthouse-check.ps1) expanded 7 → 33. Smoke-test verified post-update on USAGE.html: perf=93 a11y=100 bp=100 seo=100 — strict gate passes. HTTP 200 verified on all 33 URLs. G11/G12/G13 added to FINAL-STATE.md. Immutable snapshot at 🌐 https://ui.dang.pm/v0.5.9/ contains all edited HTML + iter33/34/35a/35b/35c lighthouse medians + updated docs (~26 MB).

### v0.5.9 metrics

| Metric | v0.5.8 | v0.5.9 |
|---|---|---|
| CI gate URL count | 7 | **33** |
| Public URLs at a11y 100 | 7/7 archetypes + brands | **28/28** measured (full public surface) |
| Score-checks per CI run | 28 | **132** |
| FINAL-STATE.md gotchas documented | 10 | **13** |
| Immutable snapshot bytes | ~12 MB | ~26 MB (added iter33-35c medians) |

---

## Cross-iteration metrics

| Metric | v0.4 Baseline | v0.5 Final | Δ |
|---|---|---|---|
| Axe violations (10 URLs) | 1063 | **0** | -100% |
| Color-contrast nodes | 733 | **0** | -100% |
| Lighthouse Perf (avg 6 URLs) | 78 | **100.0** | +28% |
| Lighthouse A11y (avg 6 URLs) | 86 | **100.0** | +16% |
| Lighthouse BP (avg 6 URLs) | 96 | **100.0** | +4 |
| Lighthouse SEO (avg 6 URLs) | 90 | **100.0** | +11 |
| Lighthouse sum (6 × 4 cats) | n/a | **2400 / 2400** | perfect |
| Mobile real overflow | (clip masked) | **0 / 48** files | clean |
| VN font rendering | broken (system fallback) | Source Serif 4 + Lora VN subsets | fixed |
| Keyboard navigation | not tested | **6/6** pages pass | new |
| Reduced motion | not respected | **111** transitions wrapped | new |
| `color-scheme` | manual class only | auto-flip per aesthetic | new |

## What's new in v0.5

### Tokens (Iter 1)

- HSL math clamp-bounded — prevent `L` blowing past safe ranges when brand hue shifts
- `sign()` fallback removed — Chrome silent fail on unsupported math function
- Status colors darkened to AA contrast (success 27% / warning 28% / danger 44% / info 30%)
- New `--focus-ring` token (per aesthetic, tinted by brand)

### A11y (Iter 2)

- Skip links on all 6 archetypes (A Dashboard / B Tool / C Landing / D Editorial / E Deck / F PWA)
- `<main>` landmark on all pages
- ARIA labels VN on icon-only buttons
- iframe titles
- Heading order fixed (no H3 before H2)
- Region semantics for sidebar / aside
- **100 % color-contrast pass** — every text node WCAG AA verified

### Performance (Iter 3)

- Self-hosted fonts (66 woff2 files, VN subset included)
- Tailwind prebuilt CSS replaces 121 KB CDN JS (`_build/tailwind-prebuilt.css`)
- Async font load with metric-matched fallback (CLS 0.25 → 0.01)
- `content-visibility: auto` on heavy below-fold sections
- 5/6 URLs Lighthouse Perf ≥ 85 on Iter 5; all 6/6 = 100 on Iter 6 desktop sweep

### Mobile (Iter 4)

- Body padding ramp 24 → 16 px @ `<420px`
- Card padding cap 32 → 20 px @ `<420px`
- Critical grid `min-width: 0` for all flex / grid children (CSS Grid minmax trap fix)
- Element-level overflow scan distinguishes intentional (carousel) vs accidental (oversized text)
- **0 / 48 real overflow** on 375 × 812 viewport

### UX (Iter 5)

- Reduced motion universal short-circuit (`@media (prefers-reduced-motion: reduce)`)
- `color-scheme: light` / `dark` per aesthetic (warm = light, dark = dark)
- Keyboard nav 100 % pass on 6 archetypes (Tab order, focus visible, no traps)
- Focus ring tuned per aesthetic (warm = brand-tinted, dark = cyan)

### Brand (Iter 5)

- 7 brand presets all pass contrast: `annhien`, `khi`, `betterbuy`, `xanh-mkt`, `akr`, `hgg`, `ai-tools`
- 0 brand-blind pages (each archetype renders intact across all 7 presets)
- BetterBuy contrast 3.20 → 6.56 (AA passing for normal body text)

## Iter 6 final regression scan

### Axe sweep — 10 URLs

| URL | Violations |
|---|---|
| `/` | 0 |
| `/showcase/` | 0 |
| `/showcase/01-primitives.html` | 0 |
| `/showcase/02-composites.html` | 0 |
| `/showcase/03-dataviz.html` | 0 |
| `/showcase/04-patterns.html` | 0 |
| `/pages/page-A-dashboard.html` | 0 |
| `/pages/page-B-tool.html` | 0 |
| `/pages/page-C-landing.html` | 0 |
| `/pages/page-F-pwa-app-flow.html` | 0 |

Result: **0 axe violations, no regression vs Iter 4 final.**

### Lighthouse — 6 URLs × 4 categories

| URL | Perf | A11y | BP | SEO |
|---|---|---|---|---|
| `/_previews/` | 100 | 100 | 100 | 100 |
| `/showcase/` | 100 | 100 | 100 | 100 |
| `/showcase/01-primitives.html` | 100 | 100 | 100 | 100 |
| `/showcase/02-composites.html` | 100 | 100 | 100 | 100 |
| `/showcase/03-dataviz.html` | 100 | 100 | 100 | 100 |
| `/pages/page-A-dashboard.html` | 100 | 100 | 100 | 100 |
| **AVG** | **100.0** | **100.0** | **100.0** | **100.0** |

Sum: **2400 / 2400** (perfect score across all 4 categories on all 6 URLs).

> Note: Iter 5 audit reported `/showcase/02-composites.html` Perf 83. Iter 6 sweep run from same network in desktop mode (`--form-factor=desktop --screenEmulation.disabled --throttling-method=provided`) records 100 — improvement attributable to CDN warm cache + iter5c postfix carrying through. The original "heavy page" caveat below is kept for awareness on slow networks.

### Visual regression — 10 URLs × 2 breakpoints (1280 / 375)

- Desktop captures stable (most within ±15 % file-size delta vs Iter 3 baseline)
- Mobile captures smaller because Iter 6 used viewport-only (`fullPage: false`) vs Iter 3 baseline (`fullPage: true`) — **not a layout regression**, just a different capture mode
- Visual inspection of key URLs (page A dashboard, page C landing, showcase 04 patterns) — layouts intact, brand presets render correctly

**Result: 0 unexpected layout shifts.**

## Known issues (push to v0.6)

- `02-composites` Perf shows 83 on cold cache / throttled network (Iter 5 finding) — needs split into 2 pages or below-fold lazy hydration
- AAA contrast (7:1) for body text not yet implemented
- Print stylesheet not implemented
- Real screen reader testing not done (NVDA / VoiceOver / TalkBack)
- ~70 dead Tailwind classes in HTML (housekeeping, no functional impact)

## Files

- 7 brand CSS presets (`brands/*.brand.css`)
- 5 token CSS files (`tokens/foundation.css`, `semantic.css`, `brand-default.css`, `tokens.css`, `tailwind-prebuilt.css`)
- 6 page archetypes (`pages/page-{A..F}*.html`) — A Dashboard / B Tool / C Landing / D Editorial / E Deck / F PWA
- 5 showcase pages (`showcase/{index,01-primitives,02-composites,03-dataviz,04-patterns}.html`)
- 38 block files (`blocks/`)
- Atomic Design directory: atoms / molecules / organisms / templates (1 index each)
- React lib — 45 TS / TSX components
- Self-hosted fonts — 66 woff2 files (VN subset)
- `_build/` Tailwind preset
- Live preview: https://ui.dang.pm/

## Patch v0.5.1 — 2026-05-20 (Iter 15 T · F3 blocker resolved)

- **`brand-default.css` vs `brands/<slug>.brand.css` ambiguity resolved** (ADR-011)
  - Verified split: 12 archetype starter files link `brand-default.css` (fallback role); ~130+ production/block/showcase/stress-test files link `brands/<slug>.brand.css` (canonical role)
  - `tokens/brand-default.css` header rewritten to make "FALLBACK only" role explicit + production warning
  - `INDEX.md` updated: folder tree comment + Section B/C `<link>` examples + new "Brand override model" table (2-row comparison)
  - `DESIGN-DECISIONS.md` ADR-011 added documenting Option A/B rejection rationale
  - Zero file moved, zero breaking change on 12 archetype pages

## Patch v0.5.2 — 2026-05-20 (Iter 16 V · BRAND-RECIPE Step 5.2 CLI fix)

- New `_build/contrast-check-brand.js` zero-deps CLI — external devs verify any HSL triplet against warm + dark surfaces without editing internal preset files; exits 1 on AA fail (CI-friendly). BRAND-RECIPE Step 5.2 updated to point at the new script.

## Patch v0.5.3 — 2026-05-20 (Iter 17 X · M1 brand-swap clarity + M3 README path fix)

Resolves the two Major frictions surfaced by Iter 16 W blind dogfood (M2 was already fixed by Iter 16 V — re-verified live).

- **M1 — Archetype starter brand-swap now self-documenting.** Added prominent inline FORK comment directly above `<link rel="stylesheet" href="../tokens/brand-default.css">` in all 5 archetype starters (page-A through page-E). External devs forking a starter now see the swap instruction at the exact line they need to edit, with a pointer to BRAND-RECIPE.md Step 3. No path change — Iter 15 T visual baseline preserved (page-C PNG hash identical).
- **M3 — README quick-start path conflict resolved.** Replaced the single `cp pages/page-C-landing.html my-project/index.html` block (which 404'd because archetype pages use relative `../tokens/`, `../fonts/`, `../brands/` paths) with a two-option flow: **Option A (recommended)** clone `starter/` as canonical scaffold; **Option B (copy-only)** mirror the kit folder structure + explicit path-rewrite checklist. Added a warning callout above the snippet.
- **M2 re-verified live.** `curl -s https://ui.dang.pm/BRAND-RECIPE.md | grep contrast` confirms Step 5.2 now points at `_build/contrast-check-brand.js` (not the deprecated `_a11y/contrast-aaa-iter7.js` path).

### Iter 18 Z — 4 Minor doc polish + visual-diff infra (2026-05-20)

- **m1 — README INDEX.md link.** Added `📄 [INDEX.md](INDEX.md)` at the top of "Related docs" so external devs reading local README can jump to the full file map.
- **m2 — README live preview links dual-mode.** Every preview link in the "Live preview" section now pairs the 🌐 live URL with 📄 local-clone path (or 📁 for the brands gallery), so devs reading the README without internet still click through. Explanatory sentence added above the list.
- **m3 — BRAND-RECIPE Step 1 slider clarification.** Added a 1-line callout under the "Sanity test" paragraph explaining the slider previews ANY HSL triplet live without needing a brand file yet — removes confusion about needing Step 2 before Step 1's slider check.
- **m4 — BRAND-RECIPE Step 2 highlight hue pairing.** Added a callout under the `_template` block explaining warm aesthetic wants highlight in warm band (0–60° / 300–360°), dark aesthetic tolerates cool (180–260°). Prevents jarring two-tone preset.
- **Visual-diff infra.** Replaced exact PNG-hash baseline check with **3-tier threshold diff** (IDENTICAL / EQUIVALENT / DIFFERENT). New zero-deps `_build/visual-diff.js` parses PNG IHDR for dimensions, compares sha256 + file size with configurable tolerance (default ±2%), prints verdict + exit code. False-positive font/timing drift no longer flags regressions; real layout shifts still caught. Calibration test: iter15t (701342 B) vs iter17x (701383 B) page-C-landing PNGs → `EQUIVALENT (+0.006%, exit 0)` ✓
- **VISUAL-REGRESSION.md.** New workflow doc covering why 3-tier (not exact hash), how to baseline via Chrome headless, CLI reference, when to bump baseline, 5 anti-patterns (don't trust IDENTICAL alone, don't set threshold 50%, eyeball every N iters).

### v0.5.3 RELEASE (2026-05-20)

- First immutable versioned URL: https://ui.dang.pm/v0.5.3/
- Production users SHOULD pin to this version
- VERSION.md tracks future releases

## Patch v0.5.4 — RELEASED (2026-05-20 · Iter 21 L cut snapshot)

Combined release of Iter 20 J + K work. Two parallel polish streams:

- **Dashboard archetype A** — regression fix (CLI primary-on override) + minimal starter (110-line scaffold) + REFERENCE.md (68 semantic tokens)
- **PWA archetype F** — manifest template + how-to + hue-band perceptual table + README F-row split + scope-substitution gotcha

Immutable URL: https://ui.dang.pm/v0.5.4/

Snapshot stats: 385 files / 12.25 MB (delta v0.5.3: +8 files, +0.04 MB for REFERENCE.md, A-dashboard-minimal.html, manifest-template.json, manifest-howto.md).

Pin guidance updated in README.md + VERSION.md. External users SHOULD now link to `https://ui.dang.pm/v0.5.4/`.

### v0.5.4 — PWA F polish (Iter 20 K · 2026-05-20)

Resolves Iter 19 BB blind dogfood PWA F findings (2 Major + 5 Minor):

- **M1 (Major) — BRAND-RECIPE hue-band perceptual luminance table.** Added 6-row table to Step 1 mapping hue → safe `l` range on warm vs dark surfaces, with explicit callout for 170-220° (teal/cyan-blue) band needing 3-5pt L-bump. Real-world AcmeCo example (`h:200 s:50 l:45`) now annotated as fails AA on cream → bump to `l:37`. External devs no longer have to iterate L 2-3 times by trial-and-error.
- **M2 (Major) — PWA manifest template + how-to.** New `mobile/manifest-template.json` (drop-in, 3 placeholders: `BRAND_NAME`/`BRAND_SLUG`/`BRAND_PRIMARY_HEX`) + `mobile/manifest-howto.md` (5-step setup + iOS quirks + 8 `<head>` metas copy-paste). Closes "PWA enrichment" gap — kit now ships canonical HTML PWA manifest, not just nextjs-pwa/vite-pwa starters.
- **m1 (Minor) — INDEX.md QC criterion touch target updated.** `Tap target ≥32px` → `Tap target ≥32px desktop / ≥44px mobile-F (Apple HIG)`.
- **m2 (Minor) — README Option B mentions mobile/tokens-mobile.css + manifest.** F archetype path now lists `cp mobile/tokens-mobile.css` + `cp mobile/manifest-template.json` as required extras alongside foundation/semantic/brand.
- **m3 (Minor) — README archetype F row split.** Table now has 2 F rows: F single-screen (`page-F-pwa.html`, showcase only) vs F multi-screen flow (`page-F-pwa-app-flow.html`, canonical fork). Note added: "For real PWAs, forking the multi-screen flow is canonical."
- **m4 (Minor) — BRAND-RECIPE gotcha #6 CSS scope substitution.** New gotcha entry covers `var()` resolving at declare site — multi-brand same page needs derived var redeclaration at nested scope. Points to `page-F-pwa-app-flow.html` lines 40-50 as working pattern.
- **m5 (Minor) — Filter chip 44px touch target.** Added to `mobile/checklist-mobile.md` M.2: chips on mobile must ≥44px (web 36px convention not enough) or use `.touch-expand` wrapper. Dedicated `mobile/patterns/filter-chip.html` deferred — note added to checklist instead (smallest-doc-touch fix).

INDEX.md folder tree gains a `mobile/` section listing tokens-mobile.css + checklist + manifest-template.json + manifest-howto.md.

### v0.5.4 — Dashboard A polish (Iter 20 J · 2026-05-20)

Resolves Iter 19 AA blind dogfood Dashboard A findings (3 Major):

- **A1 (Major) — `_build/contrast-check-brand.js` honors `--primary-on` brand override.** Regression from v0.5.2 where CLI hardcoded JS rule (white if L<50, dark if L≥50) ignored brand file's own override. Added optional `--brand-file <path>` arg: zero-dep regex parses `--primary-on:` declaration from brand CSS (supports `hsl(h s% l%)`, `white`, `black`, `#fff`, `#ffffff`). Without flag → legacy fallback. Test: pulse (`h:270 s:75 l:55`) with `brands/pulse.brand.css` (declares `--primary-on: hsl(0 0% 100%)`) now PASS AA at 5.61:1 (was misleading FAIL 3.10:1 + exit-1). Output prints `primary-on: rgb(R,G,B) [source: brand-file (X) | auto]` for transparency.
- **A2 (Major) — `starter/archetypes/A-dashboard-minimal.html` (~110 lines).** External devs forking the 948-line A starter showcase had too much surface to strip. New minimal version ships scaffold-only: topbar (logo + 3 nav + avatar), 4 KPI cards, 1 chart placeholder slot (`#chart` div with "swap với recharts/d3"), 5-row table with semantic status badges (ok/warn/err), 3-alert sidebar (danger/warn/info). Uses only semantic tokens (`--surface-2`, `--rule`, `--primary-bg`, `--danger-soft`, etc.) — no foundation HSL leak. FORK guide in header comment links to full A reference + REFERENCE.md.
- **A3 (Major) — `REFERENCE.md` enumerating 68 semantic tokens.** External devs were re-writing `hsl(... / 0.15)` inline instead of using `--primary-bg`. New top-level reference doc organized in 12 sections (surfaces / text / brand / accent / status / aesthetic / spacing / type / radius / shadow+elevation / motion / focus-ring). Each token gets 1-line description + example use. README.md "Related docs" linked. Doc covers tokens external devs touch 90% of the time; defers full enumeration to `tokens/foundation.css` + `tokens/semantic.css`.

## v0.5.5 — RELEASED (2026-05-20)

Combined release of Iter 22-23 polish work. Three streams cut into a single immutable snapshot at https://ui.dang.pm/v0.5.5/ :

- **Iter 22 N** — Path bug fix (7/7 starter files restored to canonical `../../tokens/X.css`)
- **Iter 23 R** — Token additions (`--type-mega/-hero`, `--prose-width{,-narrow,-wide}`, `--lh-prose/-pull-quote`, `--brand-mesh-1/2/3`) + D archetype hex regression fix
- **Iter 23 S** — REFERENCE.md §13 Editorial + §14 Deck patterns + `_build/path-audit.js` pre-commit guard + Fraunces font reconciled

Immutable URL: https://ui.dang.pm/v0.5.5/ (snapshot 380 files / 12.12 MB)

### Iter 22 N — Path bug fix (starter relative paths)

- **Fixed broken relative paths in `starter/archetypes/*.html`.** All 7 archetype starter files (A-dashboard, A-dashboard-minimal, B-tool, C-landing, D-editorial, E-deck, F-pwa) had `<link>` references to foundation/semantic/brand-default that resolved 1 level short of the actual `tokens/` folder. External devs forking from `starter/archetypes/` hit a 404 storm — page rendered as unstyled grey wall (tokens never load, brand color absent, semantic tokens undefined).
- **Two bug variants observed.** B/C/D/E/F-pwa used `../tokens/X.css` (1 level shy, off-by-one); A-dashboard + A-dashboard-minimal used `../X.css` (missing the `tokens/` segment entirely — would have resolved into `starter/foundation.css` non-existent). Both fixed to canonical `../../tokens/X.css`.
- **21 link references corrected** across 7 files (3 css per file: foundation + semantic + brand-default). Tailwind-prebuilt + fonts paths were already correct at `../../`.
- **A-dashboard-minimal fork guide comment also patched** — lines referencing `../brand-default.css` updated to `../../tokens/brand-default.css` so the in-file FORK instructions match real file location.
- **Caught by Iter 21 M dogfood** of Tool B archetype — confirmed same bug class in N starter files via grep audit, not just B-tool.
- **Verified via Chrome headless** screenshots of all 7 files post-fix: brand colors visible (coral default warm + violet dark), Instrument Serif italic headlines load, semantic surface tones layer correctly, no FOUT/grey-wall failures. Live URLs all HTTP 200 + CSS resources resolve from root.

### Iter 23 R — Token additions + D hex regression fix (2026-05-20)

- **Added 7 new tokens** to close gaps surfaced by Iter 22 P (Deck) + O (Editorial) dogfoods:
  - `--type-mega: clamp(120px, 12vw, 180px)` + `--type-hero: clamp(180px, 16vw, 240px)` — display scale beyond `--type-8xl` (128px) for deck hero numbers / magazine display where the modular ramp tops out.
  - `--prose-width: 680px`, `--prose-width-narrow: 580px`, `--prose-width-wide: 760px` — editorial reading column variants (no semantic prose width token previously existed).
  - `--lh-prose: 1.7` + `--lh-pull-quote: 1.3` — editorial line-heights distinct from generic `--lh-relaxed: 1.65`.
  - `--brand-mesh-1/2/3` (semantic.css) — brand-relative radial-gradient layers with fallback chain `accent → primary`, `highlight → primary`. Replaces coral-fixed `--mesh-warm-*` for canvases that must swap with brand.
- **Fixed pages/page-D-editorial.html hex regression: 6 hex literals → 0.** `.img-hero`, `.img-inline`, `.img-related-1/2/3`, `.img-author` linear-gradient stops hardcoded coral/sage hex (`#F5C9A8`, `#EEAE92`, `#D89B82`, `#DCE7CF`, `#F3EBD6`, `#E8DCB8`, `#B8C9A8`, `#D4A574`, `#B5604F`) replaced with `hsl(var(--brand-primary-h) ...)`, `hsl(var(--brand-accent-h, var(--brand-primary-h)) ...)`, `hsl(var(--brand-highlight-h, var(--brand-primary-h)) ...)` derivations. Existing `rgba()` halo radials also rebuilt brand-relative.
- **Brand-swap proof.** Captured D with KHI brand (`brands/khi.brand.css`, primary-h=140 sage): all gradients shifted from coral peach to sage green. Default brand (h=12 coral) capture confirms baseline aesthetic preserved. Visual-diff EQUIVALENT (D-before 442 KB → D-after 450 KB, +1.65% within ±2% threshold).
- **Files edited**: `tokens/foundation.css` (type-mega/hero + prose-width set + lh-prose/pull-quote), `tokens/semantic.css` (brand-mesh-1/2/3 block before `.mesh-warm`), `pages/page-D-editorial.html` (6 hex literals removed).
- **Verified via Chrome headless** + live curl: `--type-mega`, `--prose-width*`, `--lh-prose`, `--brand-mesh-*` all served at HTTP 200 from `https://ui.dang.pm/tokens/`. ADR-006 no-hex rule restored for archetype D editorial.

### Iter 23 S — Doc + guard (2026-05-20)

- **REFERENCE.md gained §13 Editorial patterns + §14 Deck patterns** (~5 KB, ~225 lines added). §13 surfaces the prose width + lh-prose + font-serif/display tokens added in Iter 23 R, plus copy-paste recipes for drop cap, pull quote, and footnote — three patterns that Iter 22 O dogfood (Slow Press editorial) had to invent from scratch. §14 surfaces `--type-mega/hero` + `--brand-mesh-*` tokens with deck-specific guidance: ratio choice (16:9 / 16:10 / 4:5), slide-stack pattern, big-number stat recipe, Chrome PDF export workflow with `@page` margin reset, and slide indicator pattern. Closes both Iter 22 O #1 (editorial pattern gap) + Iter 22 P F1/F2 (deck scale + slide ratio + print export gaps).
- **Fraunces font reference reconciled — kept (path A).** Decision: Fraunces IS shipped (15 woff2 weights 300/400/500/600/800 × 3 subsets) and IS used in 3 starter archetypes (D-editorial, E-deck) + page-D + page-E references. Path A (keep + document) preferred over path B (replace) because (a) font-face block already in `fonts/fonts.css` lines 353-488, (b) display fallback chain to Source Serif 4 / serif handles non-load gracefully via `font-display: optional`, (c) Plus Jakarta Sans is in similar state (shipped, used, undocumented). Fix: README font list updated `Inter + Source Serif 4 + Lora + Plex Mono` → `Inter + Source Serif 4 + Lora + IBM Plex Mono + Fraunces + Plus Jakarta Sans`. Added 2 Fraunces preload links to `starter/archetypes/D-editorial.html` (400 latin + vietnamese) since editorial display headlines are above the fold.
- **New `_build/path-audit.js` — pre-commit guard for starter relative paths.** Scans `starter/archetypes/*.html` for `href="../X"` / `src="../X"` references that target kit assets (tokens/fonts/brands/...) at 1 level deep when canonical is 2 levels (`../../`). Catches both Iter 22 N bug variants: off-by-one (`../tokens/X.css`) and missing-segment (`../X.css`). Also flags same-dir (`./tokens/X.css`) broken refs. Skips absolute URLs, data:, mailto:, in-page anchors. Exit 0 = clean, exit 1 = violations (CI-friendly).
- **Verified guard.** `node _build/path-audit.js` post-fix reports `0 violations across 7 files` (A-dashboard, A-dashboard-minimal, B-tool, C-landing, D-editorial, E-deck, F-pwa). Regression test: temporarily injecting `../tokens/foundation.css` (1-level) triggered exit 1 with line-precise violation report.
- **README mentions guard.** New "Pre-commit guard" subsection under Production usage links the script + explains intent + exit codes.
- **Files edited**: `REFERENCE.md` (+§13 +§14), `README.md` (font list expanded + Pre-commit guard subsection), `starter/archetypes/D-editorial.html` (2 Fraunces preload links), `_build/path-audit.js` (new, ~100 lines).

### v0.5.6 — CI gate (Iter 25 U · 2026-05-20)

Consolidates 4 standalone guards (token-audit / path-audit / contrast-check-brand / visual-diff) built across v0.5.x into a single CI gate command. Closes the "guards exist but external dev has to remember 4 invocations" friction.

- **New `_build/ci-check.sh`** (~70 lines). Bash entry point chains guards 1-3 in sequence (token-audit → path-audit → contrast-check across 3 sample brands annhien/khi/betterbuy). Aggregates exit codes (does NOT abort on first failure — surfaces all errors in one run). Parses HSL triplet from each brand CSS via `grep -oE`. Outputs section headers + summary. Safe for pre-commit hooks + GitHub Actions.
- **New `_build/ci-check.ps1`** (~60 lines). PowerShell equivalent for Windows native (no Git Bash required). Uses `-match` regex on brand CSS files to extract H/S/L. Same aggregation logic + summary as bash variant.
- **New `.github/workflows/ci.yml`** — ready-to-use GitHub Actions scaffold. Triggers on push/PR touching `tokens/`, `brands/`, `starter/archetypes/`, `_build/`. Runs on Ubuntu + Node 20. Uploads `token-audit-report.json` + `token-audit-dashboard.md` as artifacts (always, even on failure). Fork the kit + push to your repo → workflow runs automatically.
- **New `CI.md`** (~140 lines). Full CI guide: quick start, guard table, sample clean run output, pre-commit hook setup, GitHub Actions explanation, when-to-update visual-diff baselines, troubleshooting section (contrast fails on brand X, token-audit threshold, path-audit after new archetype, PowerShell HSL parsing edge cases). Links to all guard scripts.
- **README "Pre-commit guard" subsection expanded** from path-audit-only (Iter 23 S baseline) to all-4-guards 1-command flow. Links to CI.md + workflow YAML.
- **Verified local run.** `bash _build/ci-check.sh` reports: token-audit 380 hex / 247 rgb / 535 hsl_raw / 17 undef_var (informational, exit 0), path-audit 0 violations across 7 files (exit 0), contrast-check annhien PASS / khi PASS / betterbuy FAIL AA (expected — known h=12 l=60 issue, exit 1). Summary aggregates correctly. PowerShell variant mirrors output.

Files added: `_build/ci-check.sh`, `_build/ci-check.ps1`, `.github/workflows/ci.yml`, `CI.md`. Files edited: `README.md` (Pre-commit guard subsection), `CHANGELOG-v0.5.md` (this entry).

### Iter 27 A2 — CI lenient mode (2026-05-20)

Solves Iter 25 U finding: betterbuy (intentional `h:12 l:60` brand-fidelity trade-off, documented ADR-008) makes default `ci-check.sh` always exit 1. External dev running gate → noise. Lenient mode lets opt-in known-failure list.

- **Added `BRAND_KNOWN_FAILURES` env var** to `_build/ci-check.sh` + `_build/ci-check.ps1`. Space-separated brand list. Contrast failures on listed brands log `[LENIENT] <brand> expected to fail — masking exit` and do NOT propagate exit. Unexpected pass logs `[LENIENT] <brand> listed but PASSED — consider removing`. Token-audit + path-audit failures still propagate (only contrast-check leniency-eligible).
- **3 test runs verified**: strict `bash _build/ci-check.sh` → exit 1 (betterbuy fail propagates). Lenient `BRAND_KNOWN_FAILURES="betterbuy" …` → exit 0 with `[LENIENT]` log. Unrelated `BRAND_KNOWN_FAILURES="acme calm" …` → exit 1 (betterbuy still fails, not in list).
- **CI.md gained "Lenient mode" section** (~40 lines) — usage, behaviour table (4 scenarios × exit), when-to-use / when-NOT-to-use guidance.
- **README "Pre-commit guard" subsection** got blockquote callout pointing to lenient mode + CI.md anchor.

Files edited: `_build/ci-check.sh`, `_build/ci-check.ps1`, `CI.md`, `README.md`, `CHANGELOG-v0.5.md` (this entry).

## v0.5.6 — RELEASED (2026-05-20)

Combined Iter 25 (U + V) + Iter 26 W. Immutable URL: https://ui.dang.pm/v0.5.6/ (snapshot 384 files / 13 MB).

Streams cut:
- **Iter 25 U** — CI gate consolidation (`_build/ci-check.sh` + `.ps1`, `.github/workflows/ci.yml`, `CI.md`). Detail above under "v0.5.6 — CI gate (Iter 25 U)" subsection.
- **Iter 25 V** — Responsive audit across 5 archetype × 3 breakpoint (15 captures).
- **Iter 26 W** — E Deck mobile responsive fix + D Editorial caption word-break fix. B Tool truncate UNRESOLVED → v0.5.7 candidate.

### Iter 25 V — Responsive audit

- Captured 15 screenshots (5 archetype × 3 breakpoint 375/768/1280)
- Verdict: 11/15 PASS, 3/15 MINOR, 1/15 BREAK
- 🔴 BREAK: E Deck 375 (text cuts mid-word, BEFORE/AFTER cols truncate)
- 🟡 MINOR: B Tool 375 (task title hard-cut, no ellipsis), D Editorial 375 (caption right-edge bleed), C Landing 375 (showcase chrome only)
- 768/1280 universal PASS
- See `_iter25_responsive/RESPONSIVE-AUDIT.md`

### Iter 26 W — Partial responsive fix

- ✅ **E Deck mobile FIXED**: added `@media (max-width: 600px)` — release `aspect-ratio` (16/9 → auto), `min-height: 80vh` per slide, force 2-col grids to 1fr, scale `text-7xl/8xl/9xl` to `clamp(48px, 14vw, 96px)`. First attempt with `min-height: auto` collapsed slides to gradient strips — rolled back, picked 80vh.
- ✅ **D Editorial caption FIXED**: `.caption` selector gained `word-break: break-word; overflow-wrap: anywhere; max-width: 100%` — caption now wraps multi-line instead of right-edge bleed.
- 🟡 **B Tool truncate UNRESOLVED**: added `overflow: hidden + min-width: 0` to row + title span at 720px breakpoint. Visual check shows title still hard-cut, ellipsis not triggering. Suspect Tailwind CDN load order vs inline `<style>` specificity. Defer Iter 27 deeper debug. Severity remains MINOR.

### Iter 28 — B Tool truncate RESOLVED (2026-05-20)

- ✅ **B Tool ellipsis now renders at 375 mobile**: titles like "Implement webhook retry with **...**" / "Migrate billing service to async**...**" verified across all rows (IN PROGRESS / TODO / DONE) on both local + live https://ui.dang.pm/pages/page-B-tool.html
- Root cause (pixel-traced): @media + flex constraints DID apply, but `flex: 1 1 0 + max-width: 100%` resolved against an oversized parent (parent's `min-w-0` allows shrink but rows extend via content). Title's intrinsic content exceeded what parent should constrain → ellipsis never triggered because the SPAN itself wasn't narrower than its content (text was being clipped by outer container's `overflow-x: hidden` instead, which gives a hard cut not ellipsis).
- Fix: hard pixel cap on title span — `max-width: 220px !important; flex: 0 1 220px !important; display: inline-block` at `@media (max-width: 600px)`. With span's own width < content width, `text-overflow: ellipsis` triggers correctly.
- Also: added `html, body, body > div.flex, main, main .divide-y` chain of `max-width: 100vw + overflow-x: hidden` to belt-and-braces prevent any horizontal scroll leak.
- All chips hidden at 600px (was: 2nd onwards) for max title breathing room.
- Visual proof: 📁 [_iter28_verify/](_iter28_verify/) — `B-tool-375-v3.png` (local), `B-tool-375-LIVE.png` (live), `B-tool-375-debug2-crop.png` (diagnostic pixel-trace step).
- Pixel scan: only 12 pixel rows past x=370 (vs viewport 374), all border lines not text → ellipsis enforced.

## v0.5.7 — RELEASED (2026-05-20)

Combined Iter 27 A2 + Iter 28 + Iter 29 work cut into a single immutable snapshot at https://ui.dang.pm/v0.5.7/ (~12.3 MB / ~391 files).

### What ships in v0.5.7

- **CI lenient mode (Iter 27 A2)** — `BRAND_KNOWN_FAILURES` env var in `_build/ci-check.{sh,ps1}` lets opt-in known-failure list (vd `betterbuy`) suppress expected contrast fails while still propagating unexpected regressions. `CI.md` § Lenient mode + README blockquote callout document usage. Detail in CHANGELOG entry above.
- **B Tool truncate FIXED (Iter 28)** — hard pixel cap `max-width: 220px + flex: 0 1 220px + display: inline-block` at `@media (max-width: 600px)` replaces broken `max-width: 100%` (which resolved against overflowing parent, never triggering ellipsis). Verified on local + live https://ui.dang.pm/pages/page-B-tool.html. Detail in CHANGELOG entry above.
- **FINAL-STATE.md (Iter 29)** — new top-level doc capturing 28-iteration learnings: 8 gotchas + 5 patterns + trend evidence table (friction declining 7 → 4, time-to-first-render halving 22 → 8 min) + what's left for v0.6. Companion to this CHANGELOG (which lists what shipped); FINAL-STATE.md lists what was *learned*.
- **Snapshot allowlist expanded (Iter 29)** — 8 additional root `.md` files now pinned to immutable URL: A11Y-RULES, GOVERNANCE, INTERACTION-RULES, LAYOUT-SYSTEM, MAPPING-SHADCN, NAMING, USAGE-GUIDELINES, FINAL-STATE. External devs forking v0.5.7 now get the full doc set, not just the highlights.

Files added: `FINAL-STATE.md`. Files edited: `VERSION.md` (v0.5.7 row + allowlist expanded), `README.md` (pin → v0.5.7 + FINAL-STATE link), `CHANGELOG-v0.5.md` (this entry).

External users SHOULD now pin to `https://ui.dang.pm/v0.5.7/`.

## v0.5.8 — RELEASED (2026-05-20)

Consolidates Iter 30 (Lighthouse gate added) + Iter 31a (nginx gzip persisted in `_build/nginx.conf` lifted perf 84-88 → 92-98 on 4 archetype URLs) + Iter 31b (page-B a11y 93 → 100 via aria-label on icon-only Filter/Sort buttons) + Iter 32 (verified all-pass gate flip + immutable snapshot).

### What ships in v0.5.8

- **CI Lighthouse gate flipped to default ON** — `_build/ci-check.{sh,ps1}` now run the Lighthouse step by default. Override `CI_LIGHTHOUSE=0` (sh) or `$env:CI_LIGHTHOUSE="0"` (ps1) to skip for local debug. All 6 URLs verified pass strict threshold (perf≥90 / a11y≥95 / bp≥90 / seo≥90).
- **Lighthouse final scores (Iter 32 measurement, 2026-05-20)** — fresh 2 runs per URL on root mutable path (`https://ui.dang.pm/pages/page-{A..F}*.html`), min-of-2 conservative aggregation. JSON in 📁 [_lighthouse/v0.5.8/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/v0.5.8/).

  | Page | perf | a11y | bp | seo | total |
  |------|------|------|----|----|-------|
  | A dashboard | 97 | 100 | 100 | 100 | 397 |
  | B tool      | 99 | 100 | 96  | 100 | 395 |
  | C landing   | 92 | 100 | 96  | 100 | 388 |
  | D editorial | 93 | 100 | 96  | 100 | 389 |
  | E deck      | 97 | 100 | 96  | 100 | 393 |
  | F PWA flow  | 92 | 100 | 100 | 100 | 392 |
  | **Aggregate** | **570** | **600** | **584** | **600** | **2354 / 2400** |

  All 6 URLs ≥ threshold. a11y + seo are perfect across the board.

- **nginx.conf persisted in kit (Iter 31a)** — ⚙️ [_build/nginx.conf](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_build/nginx.conf) carries gzip config (`gzip on`, comp_level 6, types text/html text/css application/javascript image/svg+xml font/woff2) so future redeploys don't lose it on the VPS.
- **G9 gotcha added to FINAL-STATE.md** — "Lighthouse perf fails can be infra (nginx gzip), not code". Memorialises the Iter 31a lesson.
- **What's-left list updated** — removed completed Lighthouse perf + CI gate items; remaining v0.6+ work = variant matrix test, production adoption, screen reader testing, component library extraction, migration guide.

Files added: `_build/nginx.conf` (persisted in kit), `_lighthouse/v0.5.8/page-{A..F}.json` (median artefacts). Files edited: `_build/ci-check.sh` + `.ps1` (CI_LIGHTHOUSE default 0 → 1), `FINAL-STATE.md` (G9 + at-a-glance row + v0.5.8 pin + what's-left reordered), `README.md` (pin → v0.5.8), `VERSION.md` (v0.5.8 row), `CI.md` (baseline all-PASS + default-on note), `CHANGELOG-v0.5.md` (this entry).

External users SHOULD now pin to `https://ui.dang.pm/v0.5.8/`.

### v0.5.8.4 patch — Iter 35c (2026-05-20): Atomic galleries + misc a11y lift to 100

Parallel agent to Iter 35a/b, scoped to the 5 remaining failing URLs in the Iter 34 sweep (📄 [SWEEP-REPORT.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/v0.5.8-iter34/SWEEP-REPORT.md)): 📁 [atoms/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/atoms/) (81), 📁 [molecules/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/molecules/) (61, worst), 📁 [organisms/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/organisms/) (95 borderline), 📄 [demo/brand-switcher.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/demo/brand-switcher.html) (89), 📁 [_variant-matrix/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_variant-matrix/) (90). All 5 hit **100** after one + one targeted second pass.

Root causes (mixed: token defaults + gallery-specific markup):
- **atoms/molecules**: 21+8 unlabeled inputs — galleries DEMONSTRATE bare atoms (the point is to show the bare `<input>` shape), but Lighthouse can't tell. Plus 33+5 color-contrast on white-on-dark-accent buttons (--dark-violet L=68 with white = 4.34 fails 4.5). Plus 6 icon-only molecules buttons (search clear, pagination prev/next) and 2 target-size 18px nodes.
- **organisms**: 32 contrast spread across primary-soft/-deep terracotta pair (3.22 on warm), white-on-dark-violet buttons (4.34), warning-soft amber pair (4.08), dark-violet text on dark bg (4.03). Inverted token usage (one token doing double duty as button-bg-with-white AND accent-text-on-dark) — impossible to satisfy with single L value.
- **brand-switcher**: 9 contrast all from `opacity: 0.5-0.7` tonal compression on greys — `.field-label`/`.hero .tag`/`.snippet-title`/`.c-com` at 11-12px on cream = 2.92-4.49. Plus missing `<main>` + form-row `<select>` w/o label.
- **_variant-matrix**: missing `<main>` + heading-order (h1 → h3 cards, no h2 between).

Fix strategy (in priority order, biggest leverage first):
1. **Token override at `:root` scope** for dark accent tokens (lower L so white text wins 4.5:1): `--dark-violet` 68→52, `--dark-cyan` 53→30, `--dark-emerald` 39→28, `--dark-amber` 50→30, `--dark-danger` 60→42. **Critical**: had to use `:root` selector NOT `body`, because `:root` (0,0,1,0) beats `body` (0,0,0,1) in CSS specificity — token redeclarations on `body` were silently being lost to foundation.css `:root` declarations. Also lowered warm text token L (`--warm-text-3` 38→30, default failed AA normal-text 4.5:1 with 3.46).
2. **Sibling brighter accent** via `.accent-on-dark` utility (`hsl(252 100% 78%)`) + `[style*="background: var(--dark-X-soft)"]` attribute selectors for the 8 soft-badge cases where the same token needed brighter L for text role.
3. **Auto-aria-label IIFE script** at end of atoms + molecules — walks every form control without label, copies text from preceding-sibling `<label>` or caption div. Single function eliminates 29 violations without touching markup. Cleaner than wrapping every input in `<label>` (would break atomic gallery's "bare atom" intent).
4. **organisms primary-soft/-deep terracotta** pair (8 nodes): bulk-replaced inline `color: var(--primary-deep)` with `color: hsl(var(--brand-primary-h) var(--brand-primary-s) calc(var(--brand-primary-l) - 22%))` via single `replace_all` — brand-agnostic, works for every preset.
5. **organisms warning-soft amber** (5 nodes): `hsl(38 80% 35%)` → `hsl(38 90% 22%)` + `font-weight: 600` on mono tags.
6. **brand-switcher**: removed `opacity: 0.5-0.7` on muted labels (replaced with direct `var(--text-2/-3)`); wrapped page in `<main>`; added `aria-label="Gói dịch vụ"` on the form-row select.
7. **_variant-matrix**: wrapped page in `<main>`; added `<h2>Atoms</h2>` between h1 hero and card h3 grid to fix heading hierarchy.
8. **molecules target-size**: 18×18 search clear button → 24×24 min-width/height + 12px SVG.
9. **molecules button-name** (6): aria-labels "Clear search" / "Previous page" / "Next page" / "Page N" / "Page N, current". 2 ellipsis "…" buttons → `<span aria-hidden>` (not interactive anyway).
10. **opacity-50 disabled toggles in atoms** (2 nodes): root cause was `opacity-50` on a parent flex row blending text-on-bg through transparency — Lighthouse correctly computes effective color `mix(text, bg, 0.5)` and fails 4.5:1 (impossible at 50% opacity). Fix: removed parent opacity, applied opacity ONLY to switch graphic; text uses muted-direct color + `aria-disabled="true"`.
11. **organisms 1 stubborn KPI node** ($48.07): Lighthouse couldn't trace bg through `var()` chain on transparent ancestor card — mis-reported warm body bg. Fix: added explicit `background: var(--dark-surface-2)` on immediate parent so Lighthouse traces correctly. Visually identical, just makes the auditor's color tracing work.

Result (one cycle + 1 targeted retest, JSONs in 📁 [_lighthouse/v0.5.8-iter35c/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/v0.5.8-iter35c/)):
- atoms **100** (was 81) — 33 contrast + 21 label resolved
- molecules **100** (was 61, was worst URL in sweep) — 6+5+8+2 resolved
- organisms **100** (was 95) — 32 contrast resolved, headroom achieved
- demo/brand-switcher **100** (was 89)
- _variant-matrix **100** (was 90)

Visual proof:
- 🖼 [atoms-1280-after-v2.png](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/v0.5.8-iter35c/atoms-1280-after-v2.png) — warm + dark button galleries balanced, accent buttons readable.
- 🖼 [molecules-1280-after.png](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/v0.5.8-iter35c/molecules-1280-after.png) — was worst URL (61), now Card section shows clean warm/dark contrast, ELEVATED violet accent badge visible on dark.

Patch on v0.5.8 mutable — not a new snapshot. Token-overrides + small structural fixes + 1 JS script.

Pattern learnings (added to memory):
- CSS specificity: `:root` (0,0,1,0) > `body` (0,0,0,1). When overriding tokens declared at `:root` in foundation.css, use `:root` not `body`.
- Opacity on parent blends children: `opacity: 0.5` on a wrapper div makes text + bg blend visually, and Lighthouse computes effective post-blend color which fails contrast. Apply opacity to graphic only, use direct muted color for text + `aria-disabled`.
- One token can't do double duty: button-bg-with-white-text needs L≤50%, accent-text-on-dark-bg needs L≥75%. Same token name with one L value can't pass both. Solution: scope-override or sibling utility class with brighter value.

### v0.5.8.3 patch — Iter 35b (2026-05-20): 7 `_previews/` a11y lift to 100

Parallel agent to Iter 35a, scoped to the remaining 7 failing preview URLs in the Iter 34 sweep (📄 [SWEEP-REPORT.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/v0.5.8-iter34/SWEEP-REPORT.md)): 03-ecom (71), trend-06-warm-friendly (78), 01-landing (80), trend-01-bento (81), 02-admin (84), trend-04-editorial (87), trend-05-dark-mesh (88), trend-02-ai-tool-dark (89). All 7 hit **100** after one fix cycle + one targeted second pass on 6/7.

Root causes (varied because previews each have their own bespoke styling, no shared token):
- 03-ecom: 17 image-alt (product/thumb placeholders), 13 button-name (9 image-gallery thumbnails + 4 color swatches), 19 color-contrast (amber-200/50-60-70 on `#1a1410` premium dark = 4.47; `bg-orange-500 text-white` flash-sale chips = 2.8; voucher chips `text-orange-600/emerald-600` on white = 3.55-3.76; variant-A breadcrumb on dark), `<main>` missing.
- trend-06-warm: 13 color-contrast all from page-level CSS classes — `.text-warm-soft` (#9D8F7D on `#fffaf1` = 3.03), `.bg-coral` (`#C97464` with white text = 3.4), `.text-coral` (#B5604F on cream = 4.1). Fixed by editing the `<style>` block to use `hsl()` syntax with lower L value (38% / 42%), preserving brand hue. Plus `<main>` + 1 image-alt where onerror-emoji-fallback markup had broken HTML alt placement.
- 01-landing: 17 contrast (`text-stone-500` #78716c on cream `#faf6ef` = 4.45 used pervasively for captions, plus `text-neutral-400 line-through` strikethrough size labels on white = 2.52), 10 image-alt (avatar pravatar + testimonial pictures), `<main>` missing.
- trend-01-bento: 9 contrast where `text-neutral-400` (#a3a3a3) labels rendered on `#FAFAF9` page bg (2.52) — bumped to -600. After bump, 3 NEW nodes appeared inside 2 dark `bg-neutral-900` bento cards where neutral-600 (#525252) on near-black = 2.29 — those reverted to -300. Heading-order: h1 → h3 skip fixed by promoting first card's h3 to h2 (it's a peer of hero h1, not child), then h4 cards demoted to h3 for proper h2-h3 chain. `<main>` missing.
- 02-admin: 10 contrast (sidebar nav `text-neutral-400` on `#fafafa` = 2.41; status badges `text-emerald-600` on white = 3.76; chips `text-neutral-500`), 2 image-alt (sidebar avatars), `<main>` missing.
- trend-04-editorial: 4 image-alt (editorial photos), `<main>` missing. One photo had onerror fallback using `&quot; alt="">` which confused the HTML parser into seeing alt=""+innerHTML in same attr value — rewrote with `&lt;`/`&gt;` entities to escape.
- trend-05-dark-mesh: 6 contrast where `text-neutral-500` (#737373) labels on dark mesh `#06060b`-`#111119` = ~4.0-4.3 (below 4.5). Bumped to -400. One CTA `bg-white` card flipped — its `text-neutral-400` became 2.52 on white, reverted to -600 for that 1 card only. `<main>` missing.
- trend-02-ai-tool-dark: 38 contrast — the heaviest single fail in this batch, all `text-neutral-500/600/700` (#737373/#525252/#404040) chained across captions on `#0A0A0A`. Bumped entire scale: -500→-400, -600→-400, -700→-500. After deployment, 2 leftover -600 nodes in code-block tooltips bumped to -400 in second pass. `<main>` missing.

Fix strategy — same as Iter 35a: token attribute edits only, NO archetype/aesthetic change. Preserved every brand identity — premium amber + Cormorant for trầm hương, modern monochrome for COS-style fashion, warm cream + coral for Bloom, near-black + serif for AI tool, etc.

Result (single-pass + targeted second pass on 6, JSONs in 📁 [_lighthouse/v0.5.8-iter35b/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/v0.5.8-iter35b/)):

| File | Before | After |
|---|---:|---:|
| 03-ecom.html | 71 | **100** |
| trend-06-warm-friendly.html | 78 | **100** |
| 01-landing.html | 80 | **100** |
| trend-01-bento-grid.html | 81 | **100** |
| 02-admin.html | 84 | **100** |
| trend-04-editorial-maximalist.html | 87 | **100** |
| trend-05-dark-mesh-fusion.html | 88 | **100** |
| trend-02-ai-tool-dark.html | 89 | **100** |

Visual proof (1280px): 🖼 [03-ecom-after.png](file:///C:/Users/DANG/AppData/Local/Temp/iter35b-shots/03-ecom-after.png), 🖼 [trend-06-after.png](file:///C:/Users/DANG/AppData/Local/Temp/iter35b-shots/trend-06-after.png), 🖼 [trend-02-after.png](file:///C:/Users/DANG/AppData/Local/Temp/iter35b-shots/trend-02-after.png), 🖼 [01-landing-after.png](file:///C:/Users/DANG/AppData/Local/Temp/iter35b-shots/01-landing-after.png). Brand identity preserved across all aesthetics.

Files edited: `_previews/01-landing.html`, `_previews/02-admin.html`, `_previews/03-ecom.html`, `_previews/trend-01-bento-grid.html`, `_previews/trend-02-ai-tool-dark.html`, `_previews/trend-04-editorial-maximalist.html`, `_previews/trend-05-dark-mesh-fusion.html`, `_previews/trend-06-warm-friendly.html`, `VERSION.md`, `CHANGELOG-v0.5.md` (this entry). All deployed to VPS 5 `/opt/cowork-ui-kit/site/_previews/`. Patch on v0.5.8 mutable — NO new immutable snapshot.

**`_previews/` directory now fully green** (10/10 URLs at 100 a11y including the already-passing trend-03-mesh, index.html, root).

### v0.5.8.2 patch — Iter 35a (2026-05-20): USAGE/templates/mobile a11y lift

Highest-leverage 3-URL focus chosen from v0.5.8.1 sweep findings (📄 [SWEEP-REPORT.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/v0.5.8-iter34/SWEEP-REPORT.md)). USAGE.html + templates/ + mobile/ accounted for ~217 of ~390 contrast nodes across the sweep (56%). One focused pass collapsed all three to 100.

Root causes:
- USAGE.html (88 → 100): `.code-inline` color #B5604F on #F4F1E8 = 3.91:1 (58 uses), `.code-block .c-com` #64748B on #1A1A24 = 3.62:1 (18 uses), inline `color: #B5604F` mono labels = 4.10:1 (25 uses), archetype pill bg #C97464 with white text = 3.40:1 (8 uses), `.text-neutral-500` #737373 on cream = 4.39:1 (10 uses on body), `text-neutral-500` on dark #0A0A12 = 4.15:1 (7 uses in cheatsheet), `<main>` element missing.
- templates/index.html (85 → 100): `--primary` (L=48%) rendered as #b8563d at 4.42:1 across 47 nodes (zone-label, inline accent labels, cta-primary-ghost). Mono labels with `opacity-40/50/55/60/65` faded warm-text from AAA to 2.95–3.41:1 across ~25 nodes. Dark-skin `--dark-text-2` (L=60%) = 4.46:1 across 18 nodes inside `.skin-dark` containers. Inline `font-size: 9px` on 8 wireframe labels violated the kit's 12px min rule. `<main>` missing.
- mobile/index.html (96 → 100): just `<main>` landmark missing.

Fix strategy:
1. USAGE.html — code-inline color → #8F3F2D (5.43:1), c-com → #94A3B8 (5.66:1), archetype pill bg → #B25240 (6.07:1 with white). CSS overrides in page-level style block: `body .text-neutral-500 { color: #595959 }` (5.74:1 on cream), `.bg-[#0A0A12] .text-neutral-500 { color: #A3A3A3 }` (6.92:1 on near-black). Wrapped content in `<main>`.
2. templates/index.html — `.zone-label` + `.cta-primary-ghost` switched to `var(--primary-deep)` (L=38%, 5.6:1 on cream). New scoped `--muted-text` variable: warm-text-2 in `body.aesthetic-warm`, dark-text-2 in `.skin-dark`. CSS rule for `.opacity-40..65` mono/non-bar elements sets `color: var(--muted-text)` + `opacity: 1` — solid muted color preserves wireframe hierarchy without faded contrast. `.skin-dark` re-binds `--dark-text-2` to L=70% for AA buffer. Universal `[style*="color: var(--primary)"]` selector lifts inline accent labels to `--primary-deep` (warm) or L=75% lifted brand (dark). Same pattern for `var(--accent)` + `var(--dark-violet)` in dark scope. `.skin-dark .zone-label` re-tinted to lifted violet. 8 inline `font-size: 9px` → 12px. Wrapped content in `<main>`.
3. mobile/index.html — wrapped container in `<main>`.

Result (2 runs each, identical both passes — confidence high): USAGE **100/100** (was 88), templates **100/100** (was 85), mobile **100/100** (was 96). 0 contrast nodes across all three (was 218). JSON in 📁 [_lighthouse/v0.5.8-iter35a/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/v0.5.8-iter35a/).

Visual proof: 🖼 [USAGE-after-1280.png](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/v0.5.8-iter35a/USAGE-after-1280.png) (cream/coral page, archetype pills now deeper terracotta but identity preserved), 🖼 [templates-after-1280.png](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/v0.5.8-iter35a/templates-after-1280.png) (wireframe skeleton readable, dark zones with lifted violet zone-labels), 🖼 [mobile-after-375.png](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/v0.5.8-iter35a/mobile-after-375.png) (no visual regression).

Files edited: `USAGE.html`, `templates/index.html`, `mobile/index.html`, `VERSION.md`, `CHANGELOG-v0.5.md` (this entry). All edits also deployed to VPS 5 (krycloud) `/opt/cowork-ui-kit/site/`. Patch on v0.5.8 mutable — NO new immutable snapshot. Other Iter 35 sub-agents (35b, 35c) cover the remaining 11 failing URLs in the sweep.

### v0.5.8.1 patch — Iter 33 (2026-05-20): brand gallery a11y 80 → 100

- User flagged ("sao màu chữ với màu nền y nhau vậy?") → confirmed: 📄 [brands/index.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/brands/index.html) had never been a11y-audited. Fresh Lighthouse on `https://ui.dang.pm/brands/` showed **a11y 80** with 23 color-contrast fails + missing `<main>` landmark + 3 link-in-text-block fails.
- Systemic root cause: demo components (`.btn-pri`, `.toggle button.on`, `.discount`, `.swatch .sw-1/sw-2`, `.ingredient-pct`, `.benefit-pill`) used raw `var(--primary)` as bg with white text. For brands with primary L ≥ 50% (BetterBuy L=60, Xanh L=45, AI Tools L=60), white-on-primary 2.93–3.20:1, fails 4.5. Plus AI Tools dark-aesthetic palette legend `<strong>` rendered raw L=48% purple on near-black = 1.86:1.
- Principled fix (no per-brand hex overrides — ADR-001 compliant):
  1. New card-scope token `--primary-text-bg: hsl(... min(L-12%, 32%))` — guaranteed-AA bg via `min()` clamp.
  2. All white-text-on-primary surfaces swapped to `--primary-text-bg`.
  3. Card-scope dark aesthetic added overrides for `--success` (→ lighter emerald), `.label-tiny` (→ `--text-2`), `.hsl-inline strong` + `.kpi-foot a` (→ `hsl(brand-h 70% 72%)`).
  4. `.benefit-pill` text → `--text` (was `--primary-deep` on `--primary-soft` = 3.24:1).
  5. `.ingredient-pct` text → `--text` (Xanh primary hue too close to accent for HSL math to guarantee AA).
  6. `.slot.booked` replaced `opacity: 0.4` (grey 2.32:1) with explicit `var(--text-2)` color.
  7. Footer link color clamped to `min(L-12%, 32%)` + persistent `text-decoration: underline` (fixes both contrast AND color-only-link audit).
  8. Wrapped main content in `<main>` element; `<footer>` moved outside.
- Result (2 runs, median 100): a11y **100 / 100**. color-contrast 0 failing, landmark-one-main PASS, link-in-text-block PASS. JSON in 📁 [_lighthouse/v0.5.8-iter33/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/_lighthouse/v0.5.8-iter33/).
- Visual diff: 🖼 [before](file:///C:/Users/DANG/AppData/Local/Temp/brand-gallery-audit/brands-tall-1280.png) vs 🖼 [after](file:///C:/Users/DANG/AppData/Local/Temp/brand-gallery-audit/brands-tall-after.png). Brand identity preserved — sw-3/sw-4/sw-5 swatches still show lighter brand tones, only the white-text surfaces deepened.
- Patch on v0.5.8 mutable — NO new immutable snapshot.
- Files edited: `brands/index.html` (~12 CSS rules + 1 markup change), `VERSION.md`, `CHANGELOG-v0.5.md`, `FINAL-STATE.md`, `_build/lighthouse-check.{sh,ps1}` (brands/ added to DEFAULT_URLS).

## Acknowledgments

- Cross-iteration AI agents: 28 + parallel sub-agents over 6 iterations
- Visual proof: ~150 screenshots captured
- QC iterations: 5 (Iter 1 — 5) + 1 final regression sweep (Iter 6)
- Time invested: ~5 hours (extended through Iter 29 reflective close)