# v1.0.0 Release Checklist

> **Last updated**: 2026-05-19 (user decisions locked; awaiting contrast cleanup + RC product testing)
>
> ## User decisions locked (2026-05-19)
>
> | # | Decision | Implication |
> |---|---|---|
> | **1a / 1b / 1c** | Code 严格 Figma 真源；不允许 code 端 token 偏离 | color-contrast cleanup 走 **路线 A**：我识别 → 设计师改 Figma → sync 回 code |
> | **2a** | Figma plan 不升级 | 能力 3 走旁路（硬规则 #6 + canonical SoT），文档化 |
> | **2b** | v1.0 "5 能力交付" 宽松读 | 旁路实现算交付 |
> | **3a / 3b** | audit 自动触发优先；ESLint plugin 是自动入口；手动需简短提示 | postinstall banner + templates 目录 + 修 README |
> | **4a** | Waive 首次 1.0 burn-in | 时间线只受 contrast cleanup + RC 测试约束 |
> | **5a** | 独立 release: v0.7.0 (contrast cleanup) → v1.0.0 | |
> | **5b** | 走 RC channel (1.0.0-rc.N) | 新产品测试；用户测后 ack OK 才 stamp v1.0.0 |
>
> v1.0.0 trigger conditions per [`PROJECT_GOAL.md`](./PROJECT_GOAL.md):
> (a) 5 能力全交付 · (b) ≥ 3 个月无破坏性 · (c) Tier 1-A/B/C 全 L5 · (d) a11y CI 跑通 · (e) API lock + migration guide
>
> **Pre-release version (v0.7.x / v0.8.x / v1.0.0-rc.1)**: ship-ready content here can land in a pre-release name first if condition (b) burn-in clock hasn't run; user signs off final tag.

---

## ✅ DONE (in master)

### Tier 1 / 2 自动化 + Infrastructure (能力 1 / 4 / 5)

- [x] **Tier 1-A** translation/* JSON + Schema + audit:translation-completeness (v0.3.0)
- [x] **Tier 1-B** mockup audit 三件套 (M-INTEGRITY + M-COLOR + M0/M1/M30 library-binding) — v0.6.0
- [x] **Tier 1-C foundation** audit-product-code.mjs CLI (R1/R2/R16) — v0.6.0
- [x] **Tier 1-C** ESLint plugin proper (subpath export, 4 rules, recommended config) — v0.6.0
- [x] **Tier 2-D** new-backlog CLI (v0.4.0)
- [x] **Tier 2-E** figma-url-to-canonical CLI (v0.5.0)
- [x] **Tier 2-F** lint-skills CLI (v0.5.0)
- [x] **Tier 2-G** audit-status-consistency (v0.6.0)
- [x] **INFRA-F32** figma-data/mockup/ sync mechanism (v0.5.0/v0.6.0)
- [x] **INFRA-F33** code-side figma name normalize (v0.6.0)
- [x] **INFRA-F34** scripts stdlib audit + CI Node 20/22 matrix (v0.6.0)

### Component canonical migration (能力 1 / 2)

- [x] **Phase 6.8** Button canonicalTheme 8-axis (v0.5.0)
- [x] **Button legacy props removal** — v0.6.0 (variant/size/disabled/loading 删)
- [x] **EXTRACT-006** figma Styles pipeline (Text/Effect/Fill/Grid) — v0.5.0
- [x] **CANONICAL-007** Pagination buttons → DS Button (v0.5.0)

### Release infrastructure

- [x] Changesets-based release flow
- [x] 13 strict audit gates in prepublishOnly
- [x] Tag-triggered CI with Node 20/22 matrix pre-flight
- [x] Visual regression baseline (Playwright)

### v1.0 prep documentation (this batch)

- [x] **API_STABILITY.md** — what becomes v1-stable; deprecation protocol
- [x] **MIGRATION_TO_V1.md** — consumer upgrade guide (0.x → 1.0)
- [x] **V1_RELEASE_CHECKLIST.md** — this file

### a11y infrastructure

- [x] axe-core + @axe-core/playwright integration
- [x] tests/a11y/docs-pages.spec.ts — 30 pages × 2 themes, blocks ALL severities
- [x] playwright.a11y.config.ts — separate from visual regression config
- [x] `pnpm test:a11y` script
- [x] scripts/a11y-survey.mjs — reconnaissance / triage report → docs/internal/a11y-survey.json
- [x] **Code-side a11y fixes** (Input/Switch/InputNumber/Select/Slider aria-label fallbacks; Chart canvas aria-hidden + wrapper role="img"; scrollable region tabindex hook in DocsShell; SKILL.md typo fix; ProgressPage range input label)

Result: violation count 103 → 43 (all 43 remaining are `color-contrast`).

---

## ❌ OUTSTANDING — blocks v1.0 "clean" release

### 1. **a11y color-contrast cleanup** — 1943 nodes across 43 pages × 2 themes (light theme heavier)

**Scope**: WCAG 2.1 AA color contrast violations. Distribution per `docs/internal/a11y-survey.json`:

- Light theme worst offenders: icon (232), button (147), steps (112), badge (77), select (73), datetime (67), notification (55), prompt-message (56), color (52), form-item (50)
- Dark theme cleaner but still has 200+ nodes across most pages

**Why this is real design system work, not just a code fix**:
- Failing pairs include tokens like `--text-tips` against `--bg-layer3` — used component-wide
- Fix requires bumping token values which may violate Figma 真源 alignment (硬规则 #1)
- Each fix changes visual baseline → all 58 playwright snapshots regenerate
- Designer aesthetic review needed: "darker --text-tips" might break visual hierarchy intent

**Path options**:

| Option | Effort | Trade-off |
|---|---|---|
| **A — designer-led token revision** | 1-2 weeks (designer + dev iteration) | Cleanest; Figma + code stay aligned; visual changes acknowledged |
| **B — code-side token override + divergence log** | ~3-5 days | Faster; documents intentional code/Figma divergence in `divergences.md` |
| **C — release v1.0 with documented a11y debt** (e.g. accept-list known findings) | ~1 day | Violates user's "clean v1.0" requirement; not recommended |
| **D — defer v1.0; ship interim v0.7 / v0.8 with non-contrast wins** | 0 (just version bump) | Allows other v1.0 work to ship; v1.0 awaits contrast |

**Recommendation**: Option **A or B**. User pick.

### 2. **3-month burn-in clock** (v1.0 condition b)

PROJECT_GOAL specifies "≥ 3 个月无破坏性 change" before v1.0. Last breaking change = Button legacy props deletion in **v0.6.0** (2026-05-18 ship). Earliest v1.0 by strict reading = **2026-08-18**.

**Path options**:

| Option | When can v1.0 ship? |
|---|---|
| **Strict 3 months from v0.6.0** | 2026-08-18 |
| **Reset clock when contrast cleanup ships** (likely v0.7.0 with `color-contrast` fixes — additive, not breaking, no reset) | Same as above (3 months from v0.6.0) |
| **Waive condition (b) for first 1.0** with explicit note | Whenever (a)/(c)/(d)/(e) all green |

**Recommendation**: Waive (b) if (a)+(c)+(d)+(e) green and user wants v1.0 sooner. Reasonable for first stable release; subsequent majors should respect burn-in.

### 3. **5 能力 ship verification** (v1.0 condition a)

| 能力 | 状态 | Note |
|---|---|---|
| 1 dev npm + docs site | ✅ shipped v0.1.x onwards; canonical complete v0.6.0 | |
| 2 AI Figma URL → code | ✅ Tier 2-E `figma-url-to-canonical.mjs` (v0.5.0) | |
| 3 AI code → Figma | ❌ **BLOCKED — Figma Pro plan limit** (`figma connect publish` unreachable on non-Org/Ent). v1.0 path: **旁路 / accept incomplete**, document as "deferred to v1.x once plan upgraded". |
| 4 AI multimodal → mockup | ✅ Tier 1-B mockup audit gates (M0/M1/M30/I1/I2/I3/C1/C2/C3) — first L3+ gate landed v0.6.0 | |
| 5 Figma↔code 溯源 schema | ✅ Tier 1-A translation/*.json + audit:translation-completeness L5 (v0.3.0) | |

**Recommendation**: Accept (3) as deferred with documentation, ship v1.0 with 4/5 capabilities + 旁路 note. Or wait for Figma plan upgrade (timeline = company decision).

### 4. **Tier 1 全 L5 verification** (v1.0 condition c)

| Tier | L5 status |
|---|---|
| Tier 1-A translation schema | ✅ L5 (audit:translation-completeness in prepublishOnly) |
| Tier 1-B mockup audit | ⚠️ **L3-L4** — scripts exist and run on demand (`pnpm audit:consumer-mockup`), but NOT yet wired as a CI gate that runs automatically on each consumer mockup change. Open question: is L5 = "consumer products' CI runs it"? If so, depends on consumer adoption (out of design-system repo scope). |
| Tier 1-C ESLint plugin | ⚠️ **L3-L4** — same situation. Plugin exists, depends on consumer flat-config adoption. |

**Recommendation**: Redefine L5 trigger as "tooling ships + at least 1 consumer (MicroApps Console) actually consumes the gate." This is realistic and verifiable.

### 5. **Misc cleanup / polish (small)**

- [ ] `docs/internal/_plans/next-session-pickup-*.md` cleanup — old pickups are stale
- [ ] Decide BRIDGE-MOCKUP-001/002/003/005 disposition (设计师 owner; v1.0 doesn't need them)
- [ ] Consider rev'ing Node action versions in `.github/workflows/publish.yml` to Node 24 (GitHub deprecation warning)

---

## Proposed release path

Given the above, three realistic paths for the user to choose from:

### Path 1 — Strict clean v1.0 (designer-led contrast cleanup)

```
v0.7.0 — color-contrast cleanup (token revisions + Figma sync) [~1-2 weeks design + dev]
  ↓ (additive only; 3 months elapse from v0.6.0)
v1.0.0-rc.1 — soak / smoke test, no new changes [~1 week]
  ↓
v1.0.0 — stable; clean a11y; API locked
```

Total: ~2-3 months calendar, mostly design + burn-in.

### Path 2 — Pragmatic v1.0 (defer contrast partially)

```
v0.7.0 — code-side contrast quick wins (~3-5 days dev) + remaining 'aa-fail' allowlist documented
v1.0.0 — ship with documented a11y debt + roadmap item "v1.x post-design-sprint"
```

Total: ~1-2 weeks. Violates "clean" requirement — user already declined this path earlier in session.

### Path 3 — Ship a v0.9.x as informal "1.0 except contrast"

```
v0.7.0/v0.8.0/v0.9.0 — accumulate non-contrast work; documented as "1.0 candidate, contrast pending"
v1.0.0 — final stamp once contrast clean
```

Behaviorally same as Path 1 but doesn't tie burn-in clock to a specific version. Useful psychologically — gives the project momentum without forcing the "1.0" stamp before it's ready.

**Recommendation**: **Path 1 or 3**, depending on whether user prefers ship now under "0.9" name or wait quietly.

---

## What user needs to decide

1. **Color-contrast cleanup route** — Option A (designer-led) / B (code + divergence log) / D (defer with v0.7-v0.9)
2. **Capability 3 (AI code → Figma)** — defer with note in v1.0, or hold v1.0 for Figma plan upgrade
3. **Tier 1-B / 1-C L5 definition** — redefine as "tooling ships + 1 consumer adopts", or hold for actual consumer rollout
4. **Burn-in clock** — strict 3 months, or waive for first 1.0
5. **Release naming** — v0.7/v0.8/v0.9 interim or jump straight v1.0.0-rc.1

Once 1–5 are answered, the actual v1.0 (or v0.9.0) tag can be cut.