# v1.0.0 Release Checklist

> **Last updated**: 2026-06-11 (现状重评 — 见下方 §🔄 2026-06-11 现状重评；原 2026-05-19 决策表与 ❌ OUTSTANDING 多项已被现状取代，保留作历史)
>
> ## 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.

---

## 🔄 2026-06-11 现状重评（这是当前 SoT；下方 ❌ OUTSTANDING 是 2026-05-19 快照）

> 逐 trigger 对照现状。结论：**v1.0 已不被任何 design-system 工程工作闸住，只差 2 个 owner 决策 + 1 轮 RC soak。**
>
> 🅿️ **owner 2026-06-11 拍板：维持 0.8.x 定位，1.0 stamp 待 owner 显式 "可以 1.0 了" 信号再议。** 1.0 是 **owner-gated，非工程闸，无时间压力**；下方两个"剩余决策"仅在 owner 启动 1.0 时才需回答，平时**无需用户介入**。其余实质工作（保真度 compliance pass / 三视图债务 / backlog）与 1.0 与否正交，照常推进。

| v1.0 trigger | 2026-05-19 快照 | 2026-06-11 现状 | 闸 / 已解 |
|---|---|---|---|
| (a) 5 能力交付 | 4/5；能力3 BLOCKED | 能力3 **旁路 shipped**（[`CAPABILITY_3_BYPASS.md`](./CAPABILITY_3_BYPASS.md)）+ decision 2b 宽松读 | ✅ 已解（旁路 ack） |
| (b) burn-in ≥3 月 | 最后破坏 = v0.6.0 (2026-05-18) | **stale**：最后破坏 = **v0.8.0 Notification breaking (2026-06-11)** → strict reading 重置到 ~2026-09-11 | decision 4a = **waive first 1.0**，仍可绕 |
| (c) Tier 1 全 L5 | 1-A L5；1-B/1-C L3-L4 | reference adoption 已实测（v0.6.1 MicroApps Console）→ 若 redefine L5="tooling ships + ≥1 consumer adopts" 则**已满足** | ⚠️ **闸：owner ruling 定 L5 口径** |
| (d) a11y CI | 103→43，全 contrast | **contrast 全线收口**（library 47 + non-text 20，accept 型 owner ruling，2026-06-10/11）；axe 原始数字未清零 → CI a11y job **维持非阻塞** | ✅ DoD "clean" 按 owner accept ack 判定（同能力3旁路范式）已满足 |
| (e) API lock + migration | ✅ done | ✅ `API_STABILITY.md` + `MIGRATION_TO_V1.md` | ✅ |

**真正剩余的 v1.0 闸（全是决策 / soak，不是工程量）**：

1. **Tier 1-B/1-C L5 口径** — owner 一句话裁定："tooling ships + ≥1 consumer adopts" 即 L5（MicroApps 已 adopt → 当即满足），还是死等更多 consumer rollout。
2. **RC product testing (5b)** — 等用户定哪些产品做 `v1.0.0-rc.1` 测，测后 ack OK 才 stamp。

**release naming 实际走向**：原计划 v0.7.0 → v1.0.0；实际 v0.7.0 → **v0.8.0**（Notification 双轴 breaking + G1-G4 enforcement，2026-06-11 published）。即 §Proposed release path 的 **Path 3**（0.x 累积、ready 才 stamp 1.0）已自然发生。

**已解的旧"待决"项**（原 §What user needs to decide 1-5 中）：#1 contrast route → 全线 accept 收口；#2 capability 3 → 旁路 shipped；#4 burn-in → decision 4a waive locked。剩 #3（L5 口径）+ #5（已落地为 Path 3）。

---

## RC Consumer 验收协议（v1.0 stamp 前置 — 2026-06-12 新增）

> 把上面 §闸 #2「RC product testing」从"等用户决定"升级为**可执行协议**。**量级校准**：单 owner，不强求多 consumer 招募 / 多人 sign-off——owner 自跑已 adopt 的产品即可。

| 维度 | 标准 |
|---|---|
| **Soak 对象** | 已 adopt 本包的 **MicroApps Console**（首选，已实测 reference adoption）；如有其它已接入产品可叠加，但**不强制等更多 consumer** |
| **Soak 时长** | ≥ **1 周**日常使用（对齐 §Proposed path 的 `rc.1 ~1 week`）；期间正常迭代该产品，不另造测试场景 |
| **必覆盖场景** | ① `pnpm add` 安装 + import 成功 ② 核心组件真渲染（token CSS 生效，组件非 unstyled — v0.9.0 修过的盲区）③ dark / light 切换 ④ 该产品主流程跑通不崩 |
| **合格线** | **0 critical / blocker**。非阻塞小问题 → 登 `backlog.md`，**不挡 stamp** |
| **Sign-off** | owner 单签即可。在本文件或 STATUS 记一行：`rc.1 soak <YYYY-MM-DD>→+7d, consumer=<名>, N issues, 0 critical → go` |
| **Stamp gate** | 闸 #3（L5 口径 ruling）已裁 + 本 soak 0 critical → 可 stamp `v1.0.0` |

**反模式**：① 没真装 RC 包、只在本仓库 dev server 看 → 不算 soak（必须 consumer 侧 `pnpm add` 真装）② 有 critical 但"觉得能忍"就 stamp → 禁止，critical 必须先修或降级到非 critical 才放行。

---

## ✅ 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)

> 🔄 **SUPERSEDED 2026-06-11**：contrast 全线收口（library 47 对 + non-text 20 对，accept 型 owner ruling，2026-06-10/11，零 Figma 改动）。下方 Path options A-D 已不适用 — 详见 §🔄 现状重评。

**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)

> 🔄 **SUPERSEDED 2026-06-11**：最后破坏性 change 已更新为 **v0.8.0 Notification `status`→`form`+`type`+`closable`（2026-06-11 ship）**，非下文的 v0.6.0。strict reading 重置到 ~2026-09-11。decision 4a 仍 waive first 1.0。

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.