# Cowork UI Kit > Production-grade design system cho 7 brand × 6 archetype. HSL-math tokens (W3C + Figma exports), Atomic Design layers, 100% accessibility, 100/100 Lighthouse, Vietnamese-first font subset. Drop tokens vào project bất kỳ → brand swap qua 1 CSS class. **Status:** v0.5.0 production-ready · **Live:** 🌐 https://ui.dang.pm/ --- ## Live preview Every preview link below pairs the live URL (🌐 internet, requires deployed copy) with the local file inside this repo (📄 click to open in browser from your clone). External devs reading the local README can still click through. - 🌐 https://ui.dang.pm/ · 📄 [local index](demo/brand-switcher.html) — entry point cho mọi demo - 🌐 https://ui.dang.pm/demo/brand-switcher.html · 📄 [local](demo/brand-switcher.html) — interactive 7-brand swap - 🌐 https://ui.dang.pm/showcase/ · 📄 [local](showcase/index.html) — atoms / molecules / organisms / data-viz / patterns - 🌐 https://ui.dang.pm/pages/ · 📄 [local A](pages/page-A-dashboard.html) · 📄 [B](pages/page-B-tool.html) · 📄 [C](pages/page-C-landing.html) · 📄 [D](pages/page-D-editorial.html) · 📄 [E](pages/page-E-deck.html) · 📄 [F single](pages/page-F-pwa.html) · 📄 [F flow](pages/page-F-pwa-app-flow.html) — 6 archetype reference - 🌐 https://ui.dang.pm/brands/ · 📁 [local](brands/) — 7 brand × 7 archetype demo grid - 🌐 https://ui.dang.pm/motion/ · 📄 [local](motion/index.html) — **NEW v0.5.10** 15 motion patterns demo, 28 tokens, `prefers-reduced-motion` contract - 🌐 https://ui.dang.pm/uxstate/ · 📄 [local](uxstate/index.html) — **NEW v0.5.10** loading + empty + error + toast showcase (4 atoms + 2 molecules + 1 organism) - 🌐 https://ui.dang.pm/tokens/tokens.figma.json · 📄 [local](tokens/tokens.figma.json) — pullable URL cho Figma Tokens Studio --- ## 5-minute quick start > ⚠️ **Recommended path: clone `starter/` (canonical scaffold).** Archetype pages in `pages/` use relative paths (`../tokens/`, `../fonts/`, `../brands/`) — copy them to project root sẽ 404. Either keep the kit folder structure intact, or rewrite paths khi copy. ```bash # Option A (recommended): clone full starter scaffold cp -r starter/ my-project/ # starter/ already wires tokens + fonts + 1 archetype with correct relative paths. # Edit my-project/index.html, swap brand class, ship. ``` ```bash # Option B (copy-only flow): mirror kit structure so ../tokens/ etc. still resolve mkdir -p my-project/{css,fonts,brands} cp pages/page-C-landing.html my-project/index.html cp tokens/foundation.css my-project/css/ cp tokens/semantic.css my-project/css/ cp brands/khi.brand.css my-project/css/brand.css cp -r fonts/ my-project/fonts/ # For F · PWA archetype, also copy mobile tokens + manifest: cp mobile/tokens-mobile.css my-project/css/ # --touch-min, --sa-bottom, no-zoom inputs cp mobile/manifest-template.json my-project/manifest.json # see mobile/manifest-howto.md # Then rewrite in index.html: # ../tokens/foundation.css → css/foundation.css # ../tokens/semantic.css → css/semantic.css # ../tokens/brand-default.css → css/brand.css (canonical brand override) # ../fonts/... → fonts/... ``` ```html ``` Done. Brand swap = đổi class. Font/colors/spacing auto cascade. Live testing: open `pages/page-C-landing.html` trong browser, đổi `` xem brand shift realtime. --- ## Which archetype do I need? | Building... | Archetype | Aesthetic | Reference | |---|---|---|---| | Analytics, KPI cards, charts, ops dashboard | **A · Dashboard** | dark | 📄 [page-A-dashboard.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/pages/page-A-dashboard.html) | | Admin CRUD, sidebar + list/detail, internal tool | **B · Tool** | dark | 📄 [page-B-tool.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/pages/page-B-tool.html) | | Marketing landing, hero + pricing + FAQ | **C · Landing** | warm | 📄 [page-C-landing.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/pages/page-C-landing.html) | | Blog, article, long-form content | **D · Editorial** | warm | 📄 [page-D-editorial.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/pages/page-D-editorial.html) | | Pitch deck, proposal slides | **E · Deck** | warm | 📄 [page-E-deck.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/pages/page-E-deck.html) | | Mobile / PWA / iPhone shell — single screen | **F · PWA single screen** | warm | 📄 [page-F-pwa.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/pages/page-F-pwa.html) | | Mobile / PWA / iPhone shell — full app flow (4-5 screens stacked) | **F · PWA multi-screen flow** | warm | 📄 [page-F-pwa-app-flow.html](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/pages/page-F-pwa-app-flow.html) | > **For real PWAs, forking the multi-screen flow is canonical.** `page-F-pwa.html` is a single-screen showcase only — useful for testing 1 screen, not for production fork. **Rule:** Don't invent new layouts. Fork a reference, override brand vars, ship. Rationale → ADR-002 trong DESIGN-DECISIONS.md. --- ## File map | Folder | Contains | Use for | |---|---|---| | `tokens/` | `foundation.css` + `semantic.css` + W3C/Figma JSON exports | Source of truth — copy vào project | | `brands/` | 7 brand presets (`*.brand.css`) — HSL triplets only | Pick 1 → brand swap | | `atoms/` `molecules/` `organisms/` `templates/` | Atomic Design layers | Compose custom pages | | `pages/` | 6 archetype reference (A-F) + 4 PWA brand variants | Fork starter skeleton | | `blocks//` | Section snippets (hero, faq, pricing, etc.) per archetype | Mix-match within archetype | | `mobile/` | Touch patterns + safe-area tokens + checklist + 📄 [manifest-template.json](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/mobile/manifest-template.json) + 📄 [manifest-howto.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/mobile/manifest-howto.md) | F · PWA enrichment | | `motion/` | **v0.5.10** — 15 motion patterns demo + 📄 [MOTION.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/motion/MOTION.md). 28 motion tokens + `prefers-reduced-motion` global | Motion design | | `uxstate/` | **v0.5.10** — Loading/empty/error/toast showcase + 📄 [UXSTATE.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/uxstate/UXSTATE.md). 4 loading atoms + 2 state molecules + toast + 2 JS utils | UX state design | | `showcase/` | Interactive component catalog (primitives → patterns) | Reference + visual testing | | `react/` | 45 TS/TSX components, 0 hex | React projects only | | `demo/` | Brand switcher interactive | Demo to stakeholders | | `starter/` | Minimal copy-paste bundle | Init new project | | `_build/` | Token export + Tailwind preset + audit scripts | Maintenance | | `fonts/` | woff2 self-host (Inter + Source Serif 4 + Lora + IBM Plex Mono + Fraunces + Plus Jakarta Sans, VN subset) | Self-host | --- ## Production usage ### Pin to a version (recommended for production) If you're embedding the kit in a real project, pin to an immutable version URL instead of root: ```html ``` vs. ```html ``` Latest: **v0.5.10** (see 📄 [VERSION.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/VERSION.md)). --- **Designers** — Import 📄 [tokens.figma.json](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/tokens.figma.json) qua Tokens Studio plugin. 7 brand theme + global tokens auto-load. Setup chi tiết → 📄 [tokens/README.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/README.md). **Devs (any framework)** — Copy 3 file: 📄 [foundation.css](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/foundation.css) + 📄 [semantic.css](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/semantic.css) + 1 brand từ 📁 [brands/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/brands/). HSL math + `calc()` chạy native, không build step. **Tailwind users** — Extend ⚙️ [tailwind.preset.js](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/starter/tailwind.preset.js) trong `tailwind.config.js`. Tokens map sang `theme.colors`, `theme.spacing`, etc. **React users** — Import từ 📁 [react/src/](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/react/src/). 45 component dùng CSS variables, brand swap qua provider. **AI-driven (`/kry-ui` skill)** — Auto-detect brand từ CWD, propose archetype, scaffold tokens + 1 page skeleton vào project. Triggered by `/kry-ui` slash command. **Verify integration** — `node _build/token-audit.js` scan ra hex literals, missing vars, contrast violations. ### Pre-commit guard Run all 4 guards in 1 command before committing: ```bash bash _build/ci-check.sh # Unix / Git Bash powershell -File _build/ci-check.ps1 # Windows ``` This chains **token-audit + path-audit + contrast-check** across 3 sample brands (annhien / khi / betterbuy). Exits non-zero if any fail. > **Lenient mode** — if your brand intentionally trades AA for fidelity (e.g. coral `h:12 l:60`), opt into known-failure list: > ```bash > BRAND_KNOWN_FAILURES="betterbuy" bash _build/ci-check.sh > ``` > Listed brands' contrast failures are logged as `[LENIENT]` and don't propagate exit. See 📄 [CI.md § Lenient mode](CI.md#lenient-mode--known-failure-brands). For GitHub Actions integration see ⚙️ [.github/workflows/ci.yml](.github/workflows/ci.yml). Full guide in 📄 [CI.md](CI.md). --- ## Architecture - **Color:** HSL + `calc()` math, 7 brand override 3-5 primitives → 40 semantic derive (ADR-001) - **Layout:** 6 archetype × 2 aesthetic enforced by agent (ADR-002, ADR-003) - **Composition:** Atomic Design (atoms → molecules → organisms → templates → pages) - **A11y:** 0 axe violations, WCAG AA contrast verified on all 7 brand × 6 archetype - **Perf:** 100/100 Lighthouse (Perf/A11y/BP/SEO) trên 6 URLs, prebuilt Tailwind, self-hosted fonts Full rationale: 📄 [DESIGN-DECISIONS.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/DESIGN-DECISIONS.md) (10 ADRs). --- ## Status & changelog **v0.5.0** — Production-ready. Cross-iteration: 0 axe violations (was 1063), 100/100 Lighthouse all categories, 0 mobile overflow, VN font fixed, keyboard nav 6/6 pass. Full release notes: 📄 [CHANGELOG-v0.5.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/CHANGELOG-v0.5.md) --- ## Contributing - **Add a brand:** Copy 📄 [_template.brand.css](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/brands/_template.brand.css) → fill 3 HSL triplet (primary/accent/highlight) → register slug ở 📄 [tokens.json](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/tokens.json) → run `node _build/export-tokens.js`. Detail → ADR-004. - **Add an archetype:** Not supported by design (ADR-002). Propose discussion before exception. - **Add a block:** Drop HTML snippet vào 📁 [blocks//](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/blocks/). Must reference existing tokens — no hex literals (enforced by `_build/token-audit.js`). - **File issues / discussion:** Outline collection 🤖 AI & Tooling, doc ID `cowork-ui-kit` (internal workspace). --- ## Related docs - 📄 [INDEX.md](INDEX.md) — full file map (folder tree + role per file, start here when lost) - 📄 [REFERENCE.md](REFERENCE.md) — semantic token list with examples (surfaces, text, brand, status, spacing, type, motion) - 📄 [FINAL-STATE.md](FINAL-STATE.md) — 28-iteration learnings (8 gotchas + 5 patterns, durable artifact of the v0.5 cycle) - 📄 [DESIGN-DECISIONS.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/DESIGN-DECISIONS.md) — 10 ADRs (why HSL, why 6×2, why warm default, ...) - 📄 [USAGE-GUIDELINES.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/USAGE-GUIDELINES.md) — pattern usage rules - 📄 [GOVERNANCE.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/GOVERNANCE.md) — change process - 📄 [NAMING.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/NAMING.md) — token + class naming convention - 📄 [LAYOUT-SYSTEM.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/LAYOUT-SYSTEM.md) — grid + spacing scale - 📄 [A11Y-RULES.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/A11Y-RULES.md) — accessibility floor - 📄 [INTERACTION-RULES.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/INTERACTION-RULES.md) — hover/focus/motion - 📄 [tokens/README.md](file:///C:/Users/DANG/AI-Cowork/00-templates/ui-kit/tokens/README.md) — designer Figma handoff