# Cowork UI Kit — Governance

> Ai được update? Khi nào bump version? Process review? Đây là "luật game" của kit.

Governance này pragmatic cho 1-person team (Dang) + AI agents, nhưng scaffold sẵn để scale lên team thật khi cần. Không over-engineer, không hành chính rườm rà — chỉ những rule giữ kit không bị entropy phá nát.

---

## 1. Owners

| Role | Person/Entity | Scope |
|---|---|---|
| **Owner** | Dang (Phan Dang, dangphan.work@gmail.com) | Final approval mọi change. Quyết định breaking, brand preset, MAJOR bump. |
| **AI Agents** | Claude Code (cli + ccd), Cursor, future MCP agents | Generate code dưới rule § 5. Auto-approve cho additive change. |
| **Maintainer (future)** | TBD nếu kit mở rộng team | Daily review PR, triage backlog. |
| **Contributors (future)** | Anh chị em team Dang | Submit changes via skill commands hoặc PR. |

**Hiện tại (v0.4):** Dang là single owner. AI agents tự chạy theo rule, Dang gate-keep ở breaking change + brand decisions.

---

## 2. Versioning — SemVer

**Format:** `vMAJOR.MINOR.PATCH` (e.g., `v0.4.0`)

| Bump | When |
|---|---|
| **MAJOR** | Breaking change: token removed, variant removed, component API change incompatible, layer convention rewrite |
| **MINOR** | New feature: new component, new token category, new brand preset, new archetype |
| **PATCH** | Bug fix, doc update, refactor không touch public API |

**Pre-v1.0 reality:**
- MINOR có thể chứa breaking change (early days, expect churn)
- Token rename → MINOR cho phép pre-v1.0, sẽ là MAJOR sau v1.0
- Document kỹ trong CHANGELOG để Dang track

**Sau v1.0:** Strict SemVer. Breaking → MAJOR, no exception.

**Current:** `v0.4.0` (HSL math + Atomic Design + Mobile layer + Tokens build script).

**Version source of truth:** `tokens/build-tokens.js` output `tokens.json` field `version` + git tag `v<x.y.z>`.

---

## 3. Changelog

**File:** `CHANGELOG.md` (root `ui-kit/`)

**Format:** [Keep a Changelog](https://keepachangelog.com) — sections `Added` / `Changed` / `Fixed` / `Deprecated` / `Removed` / `Security`.

**Template:**

```markdown
# Changelog

All notable changes to Cowork UI Kit documented in this file.

## [Unreleased]

## [0.5.0] - 2026-05-25
### Added
- Motion tokens (`--duration-*`, `--ease-*`)
- Elevation system (5 levels: `--elevation-0` → `--elevation-4`)
- Governance docs: GOVERNANCE.md, NAMING.md, LAYOUT-SYSTEM.md
- 20 mobile patterns + checklist (`mobile/`)
- 30+ blocks across A-F archetype (`blocks/`)

### Changed
- `aesthetic-warm` class now baked into archetype F template (anti-bug từ 2026-05-20)
- Token build script regen on every save (watch mode)

### Fixed
- Body missing aesthetic class → `--bg` / `--text` undefined → invisible (2026-05-20)
- Grid `minmax(280, 380)` không enforce max → fix bằng `min-width: 0` (2026-05-19)

### Deprecated
- `--shadow-xl-alias` (use `--elevation-4` instead)

### Removed
- (none)
```

**Rule:**
- Mỗi user-visible change → 1 entry CHANGELOG
- AI agent tự append [Unreleased] sau mỗi commit có impact
- Dang move [Unreleased] → version mới khi tag release

---

## 4. Update process

### 4.A. Tokens change (foundation/semantic/brand)

**Who:** AI agent qua `/kry-ui --add-token` hoặc Dang manual edit `tokens/*.css`

**Process:**
1. Edit `.css` file (foundation/semantic/brand layer phù hợp)
2. Run `node tokens/build-tokens.js` → regen `tokens.json` + `tokens.d.ts`
3. Test sample component visual không broken (Chrome headless screenshot 3 breakpoint)
4. Append `CHANGELOG.md` dưới [Unreleased] § Added/Changed
5. Commit: `feat(tokens): add <category> (<count> tokens)` hoặc `fix(tokens): ...`

**Approval matrix:**
| Change | Approval |
|---|---|
| ADD token mới (additive) | Auto-approve (AI tự chạy) |
| MODIFY giá trị token | Dang chốt (visual regression risk) |
| REMOVE token | Dang chốt + deprecation cycle § 6 |
| RENAME token | Dang chốt (breaking) |

### 4.B. Component change (atoms/molecules/organisms/templates)

**Who:** AI agent qua `/kry-cook` hoặc Dang

**Process:**
1. Update TSX + matching `<component>.md` doc trong cùng folder
2. Regen variant matrix nếu thêm variant (`react/<Component>.variants.ts`)
3. Visual verify Chrome headless 4 viewport: 390x844 (mobile), 768x1024 (tablet), 1280 (laptop), 1920 (desktop)
4. `/kry-qc ui` pass trước commit
5. Update CHANGELOG dưới [Unreleased]

**Approval matrix:**
| Change | Approval |
|---|---|
| New component (follow layer convention) | Auto-approve |
| Add variant (additive) | Auto-approve |
| Modify existing variant behavior | Dang review |
| Change component public API (prop signature) | Dang chốt (breaking) |
| Remove component / variant | Dang chốt + deprecation § 6 |

### 4.C. Brand preset add/remove

**Who:** Dang only (brand decision không AI tự quyết)

**Process:**
1. Create `brands/<name>.brand.css` fork từ `brands/_template.brand.css`
2. Document HSL choice với rationale (comment header trong file)
3. Add to brand registry: `CLAUDE.md` root + `INDEX.md` + `tokens/build-tokens.js` list
4. Test all 6 archetype × 2 aesthetic với brand swap (Chrome headless full grid)
5. Live preview ở `https://ui.dang.pm/brands/` update

**Approval:** Dang explicit. AI không tự add brand.

### 4.D. Doc change (`.md` files)

**Who:** AI agent freely

**Process:**
1. Edit `.md`
2. Update word count footer nếu có
3. Cross-link related docs (vd USAGE-GUIDELINES ↔ A11Y-RULES ↔ INTERACTION-RULES)

**Approval:** No approval (docs non-critical). Trừ GOVERNANCE.md / NAMING.md / SemVer doc → Dang review (process docs).

### 4.E. Mobile patterns / blocks

**Who:** AI agent qua `/kry-cook` hoặc `/kry-ui --scaffold-block`

**Process:**
1. New file `mobile/<pattern>.html` hoặc `blocks/<archetype>/<block>.html`
2. Archetype header comment bắt buộc (`<!-- Archetype: X · Aesthetic: warm/dark -->`)
3. `aesthetic-warm` hoặc `aesthetic-dark` class trên `<body>`
4. Visual verify viewport phù hợp (mobile pattern → 390x844)
5. Update INDEX.md + mobile/CHECKLIST.md nếu pattern mới

**Approval:** Auto-approve nếu follow archetype rule. Pattern mới không match A-F → Dang chốt.

---

## 5. AI Agent rules

**MUST (✅) — required mọi khi AI generate code:**

1. ✅ MUST follow `NAMING.md` convention (file, class, token, variant)
2. ✅ MUST use tokens via `var(--*)`, no hex literal trong component
3. ✅ MUST add archetype header comment cho HTML page mới (A-F + warm/dark)
4. ✅ MUST set `class="aesthetic-warm"` hoặc `"aesthetic-dark"` trên `<body>`
5. ✅ MUST run visual verify (Chrome headless screenshot) trước báo done UI task
6. ✅ MUST follow `INTERACTION-RULES.md` + `A11Y-RULES.md` + `USAGE-GUIDELINES.md`
7. ✅ MUST update CHANGELOG [Unreleased] nếu user-visible change
8. ✅ MUST regen `tokens.json` qua build script nếu touch `tokens/*.css`

**MUST NOT (❌) — never:**

9. ❌ MUST NOT create variant mới không define trong NAMING § 6 (variant taxonomy)
10. ❌ MUST NOT override token trực tiếp ở component (`color: #abc` thay vì `var(--text)`)
11. ❌ MUST NOT add color outside HSL math system (foundation HSL → semantic var → component)
12. ❌ MUST NOT skip `/kry-qc` trước commit prod
13. ❌ MUST NOT remove token / component / brand mà không deprecation cycle
14. ❌ MUST NOT mix archetype trong 1 file (vd dashboard + landing trong same HTML)
15. ❌ MUST NOT báo UI task done nếu chưa có screenshot proof (CLAUDE.md root rule)

**Enforcement (auto-triggered by user-level agents):**

| Violation | Agent | Action |
|---|---|---|
| HTML page thiếu archetype header | `ui-archetype-enforcer` | Reject Write, propose archetype |
| File ở vị trí sai taxonomy | `taxonomy-sentinel` | Reject Write, propose correct location |
| UI task done không có visual proof | `ui-visual-verifier` | Block "done" status, force Chrome headless |
| Hex literal trong component | `/kry-qc ui` checklist | Flag trong QC report |
| Variant ngoài taxonomy | `/kry-qc ui` checklist | Flag, propose register vào NAMING § 6 |

---

## 6. Breaking change protocol

Breaking change = bất cứ thứ gì khiến code consumer bị broken nếu upgrade lên version mới mà không sửa.

**Examples breaking:**
- Remove / rename token
- Remove / rename component
- Change component prop signature (rename prop, remove prop, change type)
- Change CSS class name public
- Change archetype convention (vd A-F → A-G remap)

**Protocol (mandatory pre-v1.0 + post-v1.0):**

1. **Deprecate first:**
   - Add deprecation notice trong code comment: `/** @deprecated v0.5 — use --elevation-4 */`
   - Console.warn nếu touched at runtime (cho component)
   - CSS: keep old var as alias pointing to new for 1 minor cycle

2. **CHANGELOG entry:** Move to `Deprecated` section với migration note

3. **Wait 1 minor version:** Giảm pain cho consumer adapt

4. **Remove in next MAJOR (or MINOR pre-v1.0):** Drop alias, drop deprecated symbol

5. **CHANGELOG entry:** Move to `Removed` section + reference migration guide

6. **Bump MAJOR** (sau v1.0) hoặc MINOR (pre-v1.0)

---

## 7. Migration guides

Per major version có breaking change, file `MIGRATION-v<N>.md` ở root ui-kit/.

**Template structure:**
- What changed (bullet list)
- Why (rationale ngắn)
- Codemod script if available (`tools/migrate-v0-to-v1.js`)
- Manual steps cho thứ codemod không handle được
- Rollback notes

**Pre-v1.0:** Optional, depend severity. Post-v1.0: Mandatory cho mọi MAJOR.

---

## 8. Review process (future, when team grows)

Hiện tại Dang là single contributor + AI agents nên skip formal review. Khi có team:

1. **Branch convention:**
   - `feat/<scope>-<short-desc>` — new feature
   - `fix/<bug>` — bug fix
   - `docs/<topic>` — docs only
   - `refactor/<area>` — code restructure no behavior change
   - `chore/<task>` — tooling, build, deps

2. **PR description checklist:**
   - Why (problem statement)
   - What (changes summary)
   - Visual proof (screenshot before/after nếu UI)
   - Affected layers (foundation/semantic/component/template/...)

3. **CI gates:**
   - Build pass (`node tokens/build-tokens.js`)
   - Visual diff vs baseline (future: Chromatic / Percy)
   - A11y audit (future: axe-core trên template render)

4. **Reviewer:** Dang approve, hoặc maintainer delegate

5. **Merge strategy:** Squash + Conventional Commits format

---

## 9. Issue tracking

**Bugs + feature requests:** `BACKLOG.md` ở root ui-kit/

**Format:**

```markdown
# Backlog

## 🔴 Critical (block production)
- [ ] (none)

## 🟠 High
- [ ] (id) Title — short desc — link plan/Outline doc

## 🟡 Medium
- [ ] ...

## 🟢 Nice-to-have
- [ ] ...

## ✅ Done (last 30 days)
- [x] ...
```

**Severity definitions:**
- 🔴 **Critical** — block production deploy, broken in live brand site
- 🟠 **High** — visible bug nhưng workaround có, blocking new feature
- 🟡 **Medium** — polish, refactor, tech debt visible
- 🟢 **Nice-to-have** — future ideation, no urgency

**AI scan weekly via `/kry-safe`** → flag stale items >60 ngày + suggest re-prioritize / close.

---

## 10. Release cadence

**Pre-v1.0 (hiện tại):**
- Continuous, ad-hoc per Dang request
- Tag version chỉ khi milestone đáng nhớ (vd hoàn thành mobile layer = v0.5)

**Post-v1.0 (target — khi kit stable + 7 brand all use production):**
- MAJOR: yearly hoặc as needed (rare)
- MINOR: monthly cycle (1st of month nếu có changes)
- PATCH: as needed, không lịch cố định

**Release process:**
1. Update CHANGELOG: move [Unreleased] → [x.y.z] với date
2. Update version trong `tokens/build-tokens.js`
3. Git tag: `git tag v0.5.0 -m "Mobile layer + governance docs"`
4. Push tag: `git push --tags`
5. Build static gallery → deploy `ui.dang.pm` (VPS 5)
6. Note trong Outline collection "AI & Tooling" nếu MINOR+

---

## 11. Backwards compatibility

**Pre-v1.0 (hiện tại):**
- Best effort, có thể break với notice
- Mọi break → MUST document trong CHANGELOG + 1 line note tại sao
- Avoid break nếu có thể, prefer additive

**Post-v1.0:**
- Tokens: never remove without deprecation cycle § 6
- Components: never remove public API without deprecation cycle
- Brand presets: never remove (mark legacy trong CHANGELOG, keep file for archive)
- Aesthetic (warm/dark): contract eternal — không add `aesthetic-cool` mà thay `aesthetic-warm`

**Compatibility window:** 1 MINOR version cho deprecation. Vd deprecate ở v1.5 → remove ở v1.6 hoặc v2.0.

---

## 12. Documentation requirements

Mọi change MUST có:

- [ ] Updated `<component>.md` doc nếu component thay đổi API / variant
- [ ] Updated `CHANGELOG.md` nếu user-visible (token / component / brand / archetype change)
- [ ] Updated `tokens.json` (auto qua `tokens/build-tokens.js`) nếu CSS var thay đổi
- [ ] Visual proof (screenshot folder `_previews/` hoặc commit reference) nếu UI change
- [ ] A11y notes trong A11Y-RULES.md nếu interaction / contrast thay đổi
- [ ] INDEX.md update nếu thêm component / pattern / block mới
- [ ] Cross-link related docs (vd thêm motion token → link tới INTERACTION-RULES § animation)

**AI agent enforce:** `/kry-qc docs` checklist scan các point trên.

---

## 13. License & attribution

**Hiện tại:** Internal Dang (Phan Dang). Không public open-source yet.

**Cho AI agent (Claude / Cursor / future):**
- Generate code based on Cowork kit cho project của Dang → free, không cần attribution
- Reuse cho project khác (client, third-party) → cần Dang explicit approval
- Mass-reuse pattern (vd build SaaS bán template based on kit) → respect Dang attribution trong README

**Future open-source:** Khả năng pivot sang MIT khi kit stable v1.0+, decision TBD.

---

## 14. Contact

- **Owner:** Dang — dangphan.work@gmail.com
- **Issues:** File trong `BACKLOG.md` (root ui-kit/) hoặc Outline collection "AI & Tooling" (`b8a5795f...`)
- **AI agents:** Chạy `/kry-help` để xem skills available. `/kry-ui` để generate UI. `/kry-qc ui` để QC trước ship.
- **Live preview:** https://ui.dang.pm/ (gallery 6 archetype × 7 brand)
- **Source:** `C:\Users\DANG\AI-Cowork\00-templates\ui-kit\`

---

## Appendix A — Quick decision tree

**"Tôi muốn add cái mới":**

```
Add token mới?
├── Foundation (HSL math layer)        → 4.A · auto-approve, regen tokens.json
├── Semantic (--bg, --text, --primary) → 4.A · Dang review
└── Brand-specific (--brand-h)         → 4.C · Dang chốt

Add component mới?
├── Atom (button, input, badge)        → 4.B · auto-approve nếu follow layer
├── Molecule (form-field, card-header) → 4.B · auto-approve
├── Organism (nav, hero, dashboard)    → 4.B · /kry-qc ui pass
└── Template (page layout)             → 4.B + archetype rule § 5.3-4

Add brand preset?                       → 4.C · Dang explicit only

Add doc / pattern / block?              → 4.D / 4.E · auto-approve nếu follow archetype
```

**"Tôi muốn change cái có sẵn":**

```
Modify token value?                     → 4.A · Dang review (visual regression risk)
Modify component prop?                  → 4.B · Dang chốt nếu breaking
Modify brand HSL?                       → 4.C · Dang explicit
Modify archetype convention?            → BREAKING · § 6 protocol + Dang chốt
```

**"Tôi muốn remove":**

```
Remove gì cũng phải đi qua § 6 deprecation cycle. No exception.
```

---

## Appendix B — Versioning rationale

Tại sao SemVer cho UI kit (không phải CalVer / date-based):

- **Tokens + components có public API contract** (`var(--*)`, `<Button variant="primary">`) → consumer code break nếu sai → SemVer signal breaking rất rõ
- **Brand preset là plug-in pattern** → add brand mới = MINOR additive
- **Archetype convention là contract cứng** → thay = MAJOR
- **CalVer phù hợp khi không có API contract** (vd Ubuntu releases) — không match case này

Pre-v1.0 cho phép lỏng vì kit còn churning. Sau v1.0 strict.

---

_Last updated: 2026-05-20 · Current version: v0.4.0 · Maintained by: Dang + AI agents_