Merge branch 'feat/docs-tone-pass-remove-defensive-wording'

- bin 表 `ull` 行：State 列补回「未随 v0.1.0 资产分发」/ "not in the v0.1.0 assets"，
  只看表格的人也读得到分发状态
- 平台基线末条：去掉「而非独立产物链」这半句对没人提的质疑的反驳，
  改为「每个平台跑各自的测试矩阵」/ "Each platform runs its own test matrix"

.github/workflows/ci.yml

@@ -90,3 +90,83 @@ jobs:
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
       - run: cargo build --workspace --release
+
+  # 运行时冒烟（M62）：Linux 上**真渲染一帧**，补上「能编译 ≠ 能跑」的空白。
+  # 上面四个 job 都只证明代码编得过、测得过，从不创建真实图形窗口；本 job 在 Xvfb 虚拟显示里
+  # 启动 GUI 进程，让 Slint 软件渲染器把当前场景渲进内存像素缓冲并编码成 PNG，再对**像素本身**
+  # 断言（不是只看退出码：窗口起来了但一帧空白同样是「退出码 0」）。
+  # 诚实边界：证明「Linux 上真能跑出非空白的一帧」，**不**证明视觉正确——视觉靠人眼看 artifact。
+  # 本 job 绑死 Slint Window::take_snapshot；迁 iced 后必须提供等价的离屏截图通道，否则本 job 静默退化成「能起进程」。
+  runtime-smoke:
+    name: runtime smoke (ubuntu x64, xvfb)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: 无头 X 与图形栈依赖（xvfb + 软渲染 + 字体）
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            xvfb xauth \
+            libxkbcommon-dev libxkbcommon-x11-0 libfontconfig1-dev \
+            libgl1-mesa-dev libegl1-mesa-dev libwayland-dev libxcb1-dev \
+            libx11-6 libxcursor1 libxrandr2 libxi6 \
+            fonts-dejavu-core fonts-liberation2
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # 用 debug 而不是 release：本 job 验的是「运行时渲染通路能通」，不是优化后二进制的行为；
+      # release 的 lto="fat" + codegen-units=1 会把这一步拖到十几分钟却不带来额外证据。
+      - run: cargo build --bin unlucky-launcher --locked
+      - name: 在 Xvfb 里跑一帧并截图（退出码非 0 即失败）
+        run: |
+          set -o pipefail  # 当前没有管道（死行），保留是为将来加管道时先有失败传播
+          mkdir -p "$RUNNER_TEMP/smoke/data"
+          xvfb-run -a --server-args="-screen 0 1280x1024x24" \
+            target/debug/unlucky-launcher --software-renderer \
+            --screenshot "$RUNNER_TEMP/smoke/runtime-smoke.png" \
+            --data-dir "$RUNNER_TEMP/smoke/data"
+      - name: 断言 PNG 存在且非空白（尺寸 / 唯一色数 / 亮度σ / 强边缘占比）
+        run: python3 packaging/check_screenshot.py "$RUNNER_TEMP/smoke/runtime-smoke.png" --json
+      - name: 上传截图与数据目录（失败也传，便于复盘）
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: runtime-smoke-screenshot
+          path: ${{ runner.temp }}/smoke/
+          if-no-files-found: warn
+
+  # macOS 槽位探针（M62）：**默认不在 PR 上跑**，只有手动 dispatch 才触发。
+  # 之所以是探针而不是常驻槽位：官方 macOS runner 处于 LaunchDaemon 上下文，没有登录的
+  # WindowServer 会话，Slint 的 winit backend 创建窗口大概率直接失败；而 worker 禁 push，
+  # 本机也没有 macOS，这条路径**尚无任何实测证据**——不拿未验证的 job 卡住主干门禁。
+  # 首跑结论决定去留：绿 → 去掉 if/continue-on-error 升为常驻槽位；红 → 按 D26 归入 iced
+  # 重写后再规划，并把错误原文贴进 progress 文档（不静默删 job、不吞失败原因）。
+  runtime-smoke-macos:
+    name: runtime smoke (macos arm64, probe)
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: macos-latest
+    timeout-minutes: 30
+    # 探针阶段保留证据但不算流水线结论：log/artifact 里失败原因照常可见，
+    # 解除条件 = 该槽位在真实 runner 上首跑通过并把本行与上面那条 if 一起删掉。
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo build --bin unlucky-launcher --locked
+      - name: 尝试截图（macOS 没有 X 服务器，直接跑；失败即为结论）
+        run: |
+          set -o pipefail  # 当前没有管道（死行），保留是为将来加管道时先有失败传播
+          mkdir -p "$RUNNER_TEMP/smoke/data"
+          target/debug/unlucky-launcher --software-renderer \
+            --screenshot "$RUNNER_TEMP/smoke/runtime-smoke.png" \
+            --data-dir "$RUNNER_TEMP/smoke/data"
+      - name: 断言 PNG 存在且非空白
+        run: python3 packaging/check_screenshot.py "$RUNNER_TEMP/smoke/runtime-smoke.png" --json
+      - name: 上传截图与数据目录（失败也传，便于复盘）
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: runtime-smoke-screenshot-macos
+          path: ${{ runner.temp }}/smoke/
+          if-no-files-found: warn

.github/workflows/guards.yml

@@ -63,7 +63,9 @@ jobs:
               echo "::error file=$f::$f 有 $n 行，超过 $LIMIT 行上限，请按模块拆分"
               failed=$((failed + 1))
             fi
-          done < <(git ls-files '*.rs' '*.md' '*.slint' '*.yml' '*.yaml' '*.toml' '*.json')
+          # 覆盖范围含脚本（*.py/*.sh）：packaging/ 下的构建辅助脚本同样受 400 行约束；
+          # Cargo.lock 等机器生成文件刻意不在列（否则一生成就超限）
+          done < <(git ls-files '*.rs' '*.md' '*.slint' '*.yml' '*.yaml' '*.toml' '*.json' '*.py' '*.sh')
           if [ "$failed" -ne 0 ]; then
             echo "共 $failed 个文件超限"
             exit 1

.github/workflows/release.yml

@@ -1,6 +1,6 @@
 name: Release
 
-# 发布流水线：tag `v*` → 三平台（四槽位）矩阵构建 → 单文件产物 + SHA256SUMS
+# 发布流水线：tag `v*` → 四平台（六槽位）矩阵构建 → 单文件产物 + SHA256SUMS
 # → 上传 artifact + 创建 GitHub Release（pre-release 默认开）。同一 tag 重跑幂等：
 # Release 已存在时覆盖资产与说明，不再 `gh release create`（见 release job 末步）；
 # 重跑**不碰** pre-release 标记，该标记只在 `inputs.prerelease` 显式给出时才被断言。
@@ -42,26 +42,56 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          # Windows：MSVC + 静态 CRT（+crt-static）→ exe 不依赖 VC++ 可再发行包，
+          # Windows x64：MSVC + 静态 CRT（+crt-static）→ exe 不依赖 VC++ 可再发行包，
           # 双击即用的单文件形态；UCRT 本身就是 Win10+ 的系统组件。
+          # 产物根 target/release；自检与打包都从 matrix.build_dir 取路径（不硬编码）。
           - slot: windows-x64
             os: windows-latest
+            build_dir: target/release
+            rustflags: -C target-feature=+crt-static
+          # Windows arm64：在 windows-latest（x64 宿主）上**交叉编译**到 aarch64-pc-windows-msvc。
+          # 为什么不用 windows-11-arm 原生 runner（GitHub 文档 2026 已把 `windows-11-arm` 与
+          # `windows-11-vs2026-arm` 列为公开仓库**免费**的标准 arm64 runner，原生路线可行）：
+          #   ① 双 Windows 槽位共用同一套已验证镜像/工具链，tag 重跑行为与既有槽位一致；
+          #   ② M50 的 dumpbin 定位链取的是 `Hostx64/x64/dumpbin.exe`，dumpbin 读 ARM64 PE 的
+          #      导入表没问题，而原生 ARM 宿主上那条链得再长一条 `Hostarm64/arm64` 分支——为一个
+          #      槽位放宽刚立的门禁不值得；
+          #   ③ 交叉编译产物路径变成 target/<triple>/release，已用 matrix.build_dir 参数化。
+          # 若将来改成原生：只需把 os 换成 windows-11-arm、删掉 target/rustflags 依赖并给 dumpbin
+          # 定位链补 Hostarm64 分支（届时再评估，不在这里预先放宽）。
+          - slot: windows-arm64
+            os: windows-latest
+            target: aarch64-pc-windows-msvc
+            build_dir: target/aarch64-pc-windows-msvc/release
             rustflags: -C target-feature=+crt-static
           # Linux：固定 ubuntu-22.04（glibc 2.35 地板）而不是 latest，
-          # 否则产物的 glibc 底线会跟着 runner 漂移（24.04 = 2.39）。
+          # 否则产物的 glibc 底线会跟着 runner 漂移（24.04 的 glibc 明显更高）。
           - slot: linux-x64
             os: ubuntu-22.04
+            build_dir: target/release
+          # Linux arm64：公开仓库免费的原生 ARM64 runner（原生构建，不做交叉）。
+          # 用 `ubuntu-22.04-arm` 而**不是** 24.04：与 x64 同 glibc 地板（2.35），
+          # 覆盖 Debian 12 / Ubuntu 22.04 arm64 / Raspberry Pi OS Bookworm（2.36）这类实际在跑的
+          # ARM 发行版；换 24.04 会把地板抬高、把上面前两个挡在门外。该家族标签有
+          # `ubuntu-22.04-arm` / `ubuntu-24.04-arm` / `ubuntu-26.04-arm`，均 4C/16GB、
+          # 公开仓库免费不限量（GitHub 文档 Standard runners for public repositories）。
+          - slot: linux-arm64
+            os: ubuntu-22.04-arm
+            build_dir: target/release
           # macOS：latest = arm64；Intel x64 用 macos-15-intel（macos-13 已下线）。
           - slot: macos-arm64
             os: macos-latest
+            build_dir: target/release
           - slot: macos-x64
             os: macos-15-intel
+            build_dir: target/release
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
 
       - name: Linux 图形栈构建依赖（winit / femtovg 编译期需要）
         if: runner.os == 'Linux'
+        shell: bash
         run: |
           sudo apt-get update
           sudo apt-get install -y --no-install-recommends \
@@ -71,14 +101,56 @@ jobs:
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
 
+      # 只有交叉编译槽位需要额外 target（原生槽位留空 → 本步整体跳过）。
+      # 不把 `${{ }}` 直接拼进 bash：与后面的打包步骤同一纪律，一律经 env 传入再展开。
+      - name: 追加交叉编译目标 ${{ matrix.target }}
+        if: matrix.target != ''
+        shell: bash
+        env:
+          TARGET: ${{ matrix.target }}
+        run: rustup target add "$TARGET"
+
+      # 交叉链接的前提是镜像里真有 ARM64 的 MSVC 库（VC `/lib/arm64/libcmt.lib`，+crt-static
+      # 就靠它）与 Windows SDK 的 ARM64 导入库（`um/arm64/kernel32.lib`）。缺了照样是失败，
+      # 但先给一句能照做的话，而不是让链接器吐一屏乱码才发现方向：门禁不降级，只把失败说清楚。
+      - name: Windows ARM64 交叉工具链体检
+        if: matrix.target == 'aarch64-pc-windows-msvc'
+        shell: bash
+        run: |
+          set -euo pipefail
+          roots=("C:/Program Files/Microsoft Visual Studio" "C:/Program Files (x86)/Microsoft Visual Studio")
+          vc_lib=$(find "${roots[@]}" -maxdepth 11 -type f -path '*/VC/Tools/MSVC/*/lib/arm64/libcmt.lib' 2>/dev/null | head -n1 || true)
+          sdk_version=$(ls -d "C:/Program Files (x86)/Windows Kits/10/Lib"/* 2>/dev/null | tail -n1 || true)
+          sdk_lib=""
+          if [ -n "$sdk_version" ]; then
+            sdk_lib=$(find "$sdk_version/um/arm64" -maxdepth 1 -name 'kernel32.lib' 2>/dev/null | head -n1 || true)
+          fi
+          echo "MSVC ARM64 静态 CRT:  ${vc_lib:-<缺失>}"
+          echo "SDK ARM64 导入库:     ${sdk_lib:-<缺失>}"
+          if [ -z "$vc_lib" ] || [ -z "$sdk_lib" ]; then
+            echo "::error::交叉链接缺 ARM64 库：给 VS 加上 Microsoft.VisualStudio.Component.VC.Tools.ARM64（含 ARM64 Windows SDK），或把该槽位改用原生 windows-11-arm runner"
+            exit 1
+          fi
+
       - name: cargo build --release --locked
+        shell: bash
         env:
           RUSTFLAGS: ${{ matrix.rustflags }}
-        run: cargo build --release --locked --bin unlucky-launcher --bin ull
+          TARGET: ${{ matrix.target }}
+        run: |
+          set -euo pipefail
+          target_args=()
+          if [ -n "$TARGET" ]; then
+            target_args+=(--target "$TARGET")
+          fi
+          cargo build --release --locked "${target_args[@]}" --bin unlucky-launcher --bin ull
 
       - name: Windows 单文件自检（导入表不得出现 VC++ 可再发行 DLL）
         if: runner.os == 'Windows'
         shell: bash
+        env:
+          # 跨槽位的关键点：产物在 target/<triple>/release 而不是 target/release。
+          EXE: ${{ matrix.build_dir }}/unlucky-launcher.exe
         run: |
           set -euo pipefail
           # +crt-static 是否真的生效，只看导入表：出现 VCRUNTIME/MSVCP/msvcr/ucrtbase 说明还得装
@@ -89,6 +161,7 @@ jobs:
           #   ② find 兜底：Program Files 与 Program Files (x86) 两个 VS 根都扫（Build Tools 落在 x86 根）；
           #   ③ PATH：镜像若已把工具链预置进 PATH 则直接可用。
           # PATH 排最后是刻意的：PATH 最不可控，官方定位器优先。
+          # Hostx64 的 dumpbin 读 ARM64 PE 的导入表没问题，所以 arm64 槽位共用同一条链。
           VSWHERE="C:/Program Files (x86)/Microsoft Visual Studio/Installer/vswhere.exe"
           DUMPBIN=""
           VIA=""
@@ -133,7 +206,8 @@ jobs:
             exit 1
           fi
           echo "dumpbin: $DUMPBIN（定位自 $VIA）"
-          "$DUMPBIN" -nologo -dependents target/release/unlucky-launcher.exe | tee dependents.txt
+          ls -l "$EXE"
+          "$DUMPBIN" -nologo -dependents "$EXE" | tee dependents.txt
           if grep -Eiq 'VCRUNTIME|MSVCP|MSVCR|ucrtbase\.dll' dependents.txt; then
             echo "::error::静态 CRT 未生效：exe 仍动态依赖 VC++ 可再发行包"
             exit 1
@@ -145,11 +219,15 @@ jobs:
           # 不把 `${{ }}` 直接拼进 bash 脚本：git ref 名允许 `$`/反引号/`"`，一律经 env 传入再展开。
           REF_TYPE: ${{ github.ref_type }}
           TAG: ${{ github.ref_name }}
+          SLOT: ${{ matrix.slot }}
+          BUILD_DIR: ${{ matrix.build_dir }}
         run: |
           set -euo pipefail
           # git-bash 与 Linux/macOS runner 的 python 入口名不一致，先探一遍。
           PY=$(command -v python3 || command -v python)
-          args=()
+          # 槽位与产物根都从矩阵来：交叉槽位的二进制不在 target/release，脚本据此定位
+          # 并回读可执行文件头校验架构（宿主 x64 ≠ 产物 arm64 时冒烟自动跳过，只等 CI 真机）。
+          args=(--slot "$SLOT" --build-dir "$BUILD_DIR")
           if [ "$REF_TYPE" = "tag" ]; then
             args+=(--version "$TAG")   # 与 Cargo.toml 版本交叉校验
           fi
@@ -202,7 +280,8 @@ jobs:
         run: |
           set -euo pipefail
           ls -l dist
-          for slot in windows-x64 linux-x64 macos-arm64 macos-x64; do
+          # 六槽位全齐才发版：缺任意一个就 fail（宁可不出 Release，也不出少一档的 Release）。
+          for slot in windows-x64 windows-arm64 linux-x64 linux-arm64 macos-arm64 macos-x64; do
             if ! compgen -G "dist/*-$slot*" >/dev/null; then
               echo "::error::矩阵缺产物：$slot"
               exit 1

Cargo.toml

@@ -1,6 +1,15 @@
 [workspace]
 resolver = "2"
-members = ["crates/core", "crates/agent", "crates/app", "crates/cli"]
+members = [
+    "crates/core",
+    "crates/agent",
+    "crates/app",
+    "crates/cli",
+    "crates/design",
+    # P4（D26 iced 重写）第一步：与 Slint 版 `crates/app` 并存的新 UI crate。
+    # bin 名 `unlucky-launcher-iced`，翻牌时才改名（见 DevDocs/SubAgentsTalk/app-iced-骨架与翻牌.md）。
+    "crates/app-iced",
+]
 
 [workspace.package]
 version = "0.1.0"

NOTICE

@@ -18,13 +18,38 @@ Copyright 2026 AskaEth (YeiJ)
 
    Slint 的其余许可分支（GPL-3.0-only / Slint Software License 3.0）本项目不适用。
 
-2. Rust crates 生态
+2. Google Material Color Utilities（https://github.com/material-foundation/material-color-utilities）
+
+   本产品的色彩令牌（crates/design 的 color 模块）是 Material 3 色彩算法（HCT 色彩空间 +
+   ColorSpec2021 调色板/角色映射）的 **Rust 重写移植**，依据 Apache License 2.0 使用，未把其任何语言的源码作为依赖
+   引入；除下面注明的那张生成常数表外，也没有复制其代码文件。
+
+   实际移植的部分（均为纯算法，逐函数对照后以 Rust 重写）：
+
+   - `hct/Cam16.java`、`hct/ViewingConditions.java`、`hct/Hct.java` → `crates/design/src/color/cam16.rs`、
+     `viewing_conditions.rs`、`hct.rs`（CAM16 色相/彩度 + CIELAB `L*` 亮度）
+   - `hct/HctSolver.java` → `crates/design/src/color/hct_solver.rs` + `critical_planes.rs`
+     （色域映射求解器；其中 255 项 `CRITICAL_PLANES` 常数表是原样搬运的生成数据）
+   - `utils/ColorUtils.java`、`utils/MathUtils.java` → `crates/design/src/color/space.rs`
+   - `palettes/TonalPalette.java`、`dynamiccolor/ColorSpec2021.java`、`dynamiccolor/DynamicScheme.java`
+     → `crates/design/src/color/tonal.rs`、`palettes.rs`、`scheme.rs`（Tonal Spot 变体的彩度常数与
+     49 个角色的 tone 映射）
+
+   对齐验证：`crates/design/tests/official_baseline.rs` 与 `tests/official_accent.rs` 的期望色值，
+   是把上述官方 Java 实现（Apache-2.0）在本机编译运行后输出的结果抄本——合计 290 项逐通道
+   比对（baseline 49 角色 × 2 模式 = 98 项；强调色 8 个种子 × 12 个强调族角色 × 2 模式 = 192 项），
+   误差上限 1（实测为 0）。两文件的表头各写着自己的分项口径。
+
+   Apache License 2.0 全文见 https://www.apache.org/licenses/LICENSE-2.0
+   上游版权声明：Copyright Google LLC。
+
+3. Rust crates 生态
 
    cargo-deny 白名单见 deny.toml：Apache-2.0 / MIT / BSD-2-Clause / BSD-3-Clause / Zlib / BSL-1.0 / ISC /
    CC0-1.0 / MIT-0 / Unlicense / Unicode-3.0 / CDLA-Permissive-2.0 / Apache-2.0 WITH LLVM-exception。
    GPL 系（含 AGPL、LGPL 静态链接、SSPL）依赖不得进入主干。
 
-3. 参考实现致谢
+4. 参考实现致谢
 
    本项目设计参考自 HMCL（https://github.com/HMCL-dev/HMCL）与 PCL2
    （https://github.com/Meloong-Git/PCL），两者均为 GPL-3.0，特此致谢。

README.md

@@ -2,57 +2,91 @@
 
 **English** · [简体中文](README.zh-CN.md)
 
-> **Official project home**: https://github.com/AskaEth/Unlucky-Launcher
+> **Official project home**: https://github.com/AskaEth/Unlucky-Launcher ｜ downloads, issues and
+> release notes all live there: <https://github.com/AskaEth/Unlucky-Launcher/releases>
 
 Unlucky Launcher (ULL) is a free, open-source Minecraft: Java Edition launcher written in Rust
-(Apache-2.0, non-commercial), with a Slint + Metro UI. It embeds an AI agent client (chat /
-configuration / crash diagnosis) and integrates with the broader agent tooling ecosystem via MCP.
-Minimum baseline: Windows 10.
+(Apache-2.0). It ships as one native binary per platform — no installer, no bundled runtime, no
+WebView. The launcher embeds an AI agent client (chat / configuration / crash diagnosis) and can be
+attached to other agent tooling as an MCP server.
 
-- Runtime: a single native Rust binary — no JVM, no WebView, no external runtime
-- UI: Slint (Royalty-Free 2.0; GL preferred, CPU software-rendering fallback so older machines
-  without a usable GPU still get the full UI)
-- License: Apache-2.0 © AskaEth (YeiJ)
+## Highlights
 
-## Compliance statement
-
-Authentication uses only official Microsoft/Mojang endpoints — Microsoft OAuth 2.0 device code
-flow, Xbox Live, XSTS, and api.minecraftservices.com — so players sign in with their own Microsoft
-account and launch the game they already own. Account tokens are stored only on the user's local
-machine and are never sent to any server operated by the project. ULL does not distribute, mirror,
-proxy or modify any Minecraft game files. Online play always requires a Microsoft account with
-valid entitlements. Local offline profiles never contact Microsoft or Mojang services and cannot
-join online-mode servers. Not affiliated with Mojang or Microsoft.
+- **Single-file native binary**: the launcher itself needs no JVM, no WebView and no sidecar
+  runtime. The JDK a game needs is downloaded and managed per instance, not as a launcher
+  dependency.
+- **Two UI stacks during the rewrite**: the released UI is Slint (Royalty-Free 2.0); the
+  next-generation UI is iced 0.14 + Material 3 Expressive and is still being written (see Status).
+- **CPU software-rendering fallback**: `--software-renderer` keeps the interface rendering
+  normally on machines with no usable GPU or with broken drivers.
+- **AI agent + MCP**: chat, setting edits and crash diagnosis inside the launcher; `ull agent
+  serve` exposes the same core as an MCP server (stdio or Streamable HTTP) to external agent tools.
+- **Mod loaders**: Fabric, Quilt, NeoForge, Forge, with modpack and CurseForge / Modrinth clients in
+  the core.
+- **Java management**: a Temurin → Oracle → Microsoft → Zulu fallback chain, region-aware.
+- **Accounts**: sign in with a Microsoft account over OAuth 2.0 device code flow → Xbox Live →
+  XSTS → `api.minecraftservices.com`; account tokens are kept on this machine only.
+- **Engine**: multi-source download (health scoring, mirrors, chunked transfers, hash while
+  downloading) and a YAML rule-based crash diagnosis engine.
+- **License**: Apache-2.0 © AskaEth (YeiJ).
 
 ## Status
 
-The core engine is complete (workspace: 983+ tests passing):
+Two tracks. They are not the same product yet, so read the headings before downloading anything.
 
-- **Microsoft sign-in**: OAuth 2.0 device code flow → Xbox Live → XSTS → Minecraft Services, with
-  entitlement verification
-- **Account credentials are stored only on the local machine** — never uploaded, and inaccessible
-  to the AI features
-- Mod loaders: Forge / NeoForge / Fabric / Quilt, verified on real machines
-- Java management: Temurin / Oracle / Microsoft / Zulu with a regional fallback chain
-- Multi-source download engine; YAML rule-based crash diagnosis
-- Usable as an MCP server for external agent tooling (`ull agent serve`)
-- Local offline profiles: for local / isolated-network testing only; they perform no Microsoft
-  authentication and cannot join servers with online-mode enabled
+### Track A — released: v0.1.0, Slint UI (this is what you can download today)
 
-**CLI (`ull`) is fully usable**: `install / launch / accounts / java / diagnose / agent`.
+- **GitHub Releases `v0.1.0`** (2026-11-01, flagged pre-release): single-file assets for Windows
+  x64 (a bare `.exe`), Linux x64 and macOS (arm64 and x64) `.tar.gz`. Every release also carries
+  `SHA256SUMS.txt` and the `LICENSE` / `NOTICE` / `README.md` texts as separate assets; on Windows
+  those texts sit next to the `.exe` because a bare exe cannot hold them, while the unix archives
+  already contain them.
+- **UI**: Slint + Metro. This is the shipped GUI — the instance, download, account, Java, log and
+  settings pages all run on the core engine (the in-app AI chat panel is a scripted placeholder).
+- **CLI `ull`** is built from the same tree at the same version — but the `v0.1.0` assets ship
+  only the GUI binary. If you want the CLI, build it yourself:
+  `cargo build --release --bin ull`. Commands: `instances`, `install`, `launch`, `accounts`,
+  `sessions`, `logs`, `diag`, `config`, `java`, `agent`.
+- Windows ARM64 and Linux ARM64 slots are wired into the release pipeline; the next tagged release
+  builds them. The `v0.1.0` assets predate those two slots.
 
-**GUI in development**: `crates/app` is currently a Slint + Metro skeleton; the theme system and
-the full interface ship with subsequent versions — use the CLI until then.
+### Track B — in progress on `dev`: next-generation UI (iced + Material 3 Expressive)
+
+**This track is not released yet — you can see it only by building from source.**
+
+- **Locked direction**: the look is Material 3 Expressive and the framework is iced 0.14; the UI
+  layer is written from scratch. Neither the style nor the framework will change again.
+- **Done**: the token crate `crates/design` (no UI framework, no third-party crates — real HCT
+  color, type scale, shape scale, spacing, elevation, motion, icon geometry, per-component
+  metrics) and the skeleton crate `crates/app-iced` (opens a window, self-drawn title bar and
+  window buttons, navigation rail, colors and type taken from tokens only, GPU→CPU backend probe
+  with automatic fallback, and the screenshot/diff channel the visual reviews use).
+- **Not done**: the component library (buttons, dialogs, lists, menus, search, and the rest of the
+  M3 set), page migration, and the i18n pass. Every page in the iced binary is a placeholder.
+- **Slint stays until the flip**: `crates/app` remains the reference implementation until the iced
+  build passes equivalence acceptance; only then is `unlucky-launcher-iced` renamed to
+  `unlucky-launcher` and the Slint crate retired.
+
+Binaries in the workspace, so you can tell them apart:
+
+| Binary | Crate | State |
+|--------|-------|-------|
+| `unlucky-launcher` | `crates/app` (Slint) | released in v0.1.0; still the usable GUI |
+| `unlucky-launcher-iced` | `crates/app-iced` (iced 0.14) | under construction; skeleton only, not shipped |
+| `ull` | `crates/cli` | built from the same tree at the same version; not in the v0.1.0 assets |
 
 ## Module map
 
 ```
 Unlucky-Launcher (cargo workspace)
-├── crates/core     # domain library, zero UI dependencies, eight modules
-├── crates/agent    # AI agent: ToolSpec registry + built-in client + MCP server (one shared core)
-├── crates/app      # Slint UI: the only crate allowed to depend on a UI framework
-├── crates/cli      # CLI (bin `ull`): headless, zero UI, depends on core + agent
-└── packaging       # single-file artifact matrix and packaging assets (planned)
+├── crates/core       # domain library: zero UI dependencies, eight modules
+├── crates/agent      # AI agent: ToolSpec registry + built-in client + MCP server (one core, two shapes)
+├── crates/design     # design tokens: real HCT color / type / shape / spacing / elevation / motion / icons
+│                     #   / component metrics — zero UI dependencies, no third-party crates
+├── crates/app        # Slint UI (bin `unlucky-launcher`): the released GUI, kept until equivalence acceptance
+├── crates/app-iced   # next-generation iced UI (bin `unlucky-launcher-iced`): under construction
+├── crates/cli        # CLI (bin `ull`): headless, zero UI
+└── packaging         # single-file artifact matrix and release scripts
 ```
 
 The eight modules of `crates/core`:
@@ -63,7 +97,7 @@ The eight modules of `crates/core`:
 | `download` | multi-source health scoring, mirrors, chunked downloads, hash-while-downloading |
 | `game` | version / instance repository, snapshots and inheritance resolution |
 | `launch` | 10-stage launch pipeline, processes, JSONL event stream |
-| `auth` | Microsoft sign-in / local offline profiles |
+| `auth` | Microsoft sign-in (OAuth 2.0 device code → Xbox Live → XSTS → Minecraft Services) |
 | `addon` | mod loader installation, modpacks, CurseForge / Modrinth |
 | `diagnose` | five signal collectors, YAML rule engine, hs_err parsing |
 | `platform` | OS abstraction: paths, processes, file locks, capability probing, runtime OS detection |
@@ -72,53 +106,87 @@ The eight modules of `crates/core`:
 
 Prerequisites:
 
-- Rust stable (`rust-toolchain.toml` selects the toolchain automatically; components `rustfmt` /
-  `clippy`)
-- Windows: MSVC toolchain (used by CI) or MinGW-w64 (`x86_64-pc-windows-gnu`)
-- Linux: `libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev libxcb1-dev`
-  (Slint winit backend + femtovg build dependencies)
+- Rust stable (`rust-toolchain.toml` selects the toolchain automatically; the gates also need the
+  `rustfmt` and `clippy` components)
+- Windows: MSVC toolchain (what CI uses) or MinGW-w64 (`x86_64-pc-windows-gnu`)
+- Linux: `libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev
+  libxcb1-dev` — needed by both UI stacks (Slint's winit + femtovg, iced's winit + wgpu/tiny-skia)
 
 ```bash
-cargo fmt --all --check                               # formatting
-cargo clippy --workspace --all-targets -- -D warnings # lints (zero-warning gate)
-cargo test --workspace                                # tests
-cargo build --release                                 # artifact: target/release/unlucky-launcher[.exe]
+cargo fmt --all --check                                # formatting
+cargo clippy --workspace --all-targets -- -D warnings  # lints (zero-warning gate)
+cargo test --workspace                                 # tests
+cargo build --release                                  # binaries land in target/release/
 ```
 
-Software-rendering switch (machines without a usable GPU / with broken drivers):
-`unlucky-launcher --software-renderer` (equivalent to `SLINT_BACKEND=winit-software`).
+What the build produces:
+
+- `unlucky-launcher` — the Slint UI (the released one)
+- `unlucky-launcher-iced` — the iced UI skeleton. The name is temporary: it can only become
+  `unlucky-launcher` at the flip, because two crates in one workspace cannot emit the same binary
+  name into the same target directory.
+- `ull` — the CLI
+
+Rendering switches:
+
+- `unlucky-launcher --software-renderer` (equivalent to `SLINT_BACKEND=winit-software`) forces the
+  CPU path on the Slint build
+- `unlucky-launcher-iced --software-renderer` forces tiny-skia (`ICED_BACKEND=tiny-skia`);
+  `--screenshot <png>` writes one frame and exits, which is the acceptance channel
+- Both stacks fall back to the CPU path when no usable adapter is there: the Slint build through its
+  own renderer fallback chain, the iced build through its explicit probe
 
 Dependency license check (optional locally, required in CI):
 `cargo deny check licenses bans sources`.
 
 ## CI gates
 
+Every push to `main` and every pull request runs fmt / clippy (warnings are errors) / the full test
+suite, and the Linux headless render smoke is a hard gate on the same footing: a red result blocks
+the merge. The macOS runtime probe is not there yet — it only runs on a manual `workflow_dispatch`
+and its result is recorded, not enforced (`continue-on-error`), until the slot passes a first run on
+a real runner.
+
 | Workflow | Content |
 |----------|---------|
-| `.github/workflows/ci.yml` | fmt + clippy + test + build, Windows / Linux matrix |
-| `.github/workflows/guards.yml` | zero-UI guard for core, 400-line-per-file guard, cargo-deny license guard |
+| `.github/workflows/ci.yml` | fmt + clippy + test + release build (Windows / Linux matrix); Linux runtime smoke (Xvfb: renders one real frame, then asserts the PNG is not blank); macOS runtime probe (manual dispatch only) |
+| `.github/workflows/guards.yml` | zero-UI guard for `crates/core` (manifest plus `cargo tree`), 400-lines-per-file guard, cargo-deny license and source guard |
+| `.github/workflows/release.yml` | tag `v*` → per-slot builds → single-file artifacts + `SHA256SUMS.txt` → GitHub Release |
 
 ## Platform baseline
 
-Minimum baseline: **Windows 10**. Windows 8.1 / 8 / 7 are not supported:
+Minimum baseline: **Windows 10**; Windows 8.1 / 8 / 7 are not supported.
 
-- Windows 10/11 builds use the **standard toolchain** (MSVC / GNU) — no custom target specs, no
-  `-Zbuild-std`, no import-table allowlists
-- Other platforms: macOS 12+ first class; Linux x64 with X11 preferred, Wayland as the long-term
-  direction; Android Termux experimental, not committed
-- UI fallback: Slint software rendering (fully usable on machines without a GPU or with broken
-  drivers)
-- Platform independence is expressed through **separate test matrices**, not separate artifact
-  pipelines; capability differences use feature gates with runtime probing
+- Windows 10/11 builds use the **standard toolchain** (MSVC / GNU), built the same way as
+  upstream cargo
+- macOS 12+ (Apple Silicon and Intel) and Linux x64 / arm64 are supported build slots; on Linux,
+  X11 is the preferred path today and Wayland is the long-term direction. macOS builds are unsigned,
+  so the first launch needs the Gatekeeper quarantine attribute cleared
+  (`xattr -d com.apple.quarantine`)
+- Android Termux is experimental and not promised: CLI only, GUI unverified
+- Each platform runs its own test matrix; capability differences use feature gates with runtime
+  probing.
 
 ## License and acknowledgements
 
-- This project: Apache License 2.0, see [LICENSE](LICENSE); third-party notices in [NOTICE](NOTICE)
-- The GUI uses [Slint](https://slint.dev) (Royalty-Free 2.0 track). Per the RF 2.0 obligations an
-  `AboutSlint` widget will be placed on the about page (P2); until then NOTICE and this section
-  serve the attribution duty.
+- **This project**: Apache License 2.0, see [LICENSE](LICENSE); third-party notices in
+  [NOTICE](NOTICE).
+- **Slint** (<https://slint.dev>), Royalty-Free 2.0: obligation for the Slint build that v0.1.0
+  ships — an `AboutSlint` widget on the about page (still outstanding) and, until it lands, the
+  NOTICE file, this section and a "Made with Slint" note on the release page. The obligation is
+  kept for as long as a Slint-linked binary ships.
+- **iced** (<https://github.com/iced-rs/iced>), MIT: the framework of the next-generation UI,
+  together with `winit` and, through it, `wgpu` / `tiny-skia` (Apache-2.0 / MIT).
+- **Google Material Color Utilities** (Apache-2.0): the color tokens in `crates/design` are a Rust
+  port of its HCT / ColorSpec2021 algorithms; details and the exact ported functions are listed in
+  [NOTICE](NOTICE).
+- **Other major dependencies**: `rmcp` and `axum` (Apache-2.0 / MIT) for the MCP server, `tokio`
+  (MIT), `reqwest` with rustls (MIT / Apache-2.0), `serde` / `serde_json` (MIT / Apache-2.0),
+  `zip` / `flate2` / `tar` (MIT / Apache-2.0). The allow-list cargo-deny enforces is in `deny.toml`;
+  GPL-family dependencies may not enter the main line.
 
-Thanks to [HMCL](https://github.com/HMCL-dev/HMCL) and
-[PCL2](https://github.com/Meloong-Git/PCL) (both GPL-3.0) — these two launchers have accompanied
-the vast majority of Minecraft players for many years. ULL learned a great deal about design and
-implementation from them, and this project is dedicated to those two pioneers.
+Thanks to [HMCL](https://github.com/HMCL-dev/HMCL) and [PCL2](https://github.com/Meloong-Git/PCL)
+(both GPL-3.0). They have been with the vast majority of Minecraft players for years, and this
+project has benefited a great deal from their design choices and implementation details.
+
+Not affiliated with Mojang or Microsoft.

README.zh-CN.md

@@ -2,41 +2,81 @@
 
 [English](README.md) · **简体中文**
 
-> **官方项目主页**：https://github.com/AskaEth/Unlucky-Launcher
+> **官方项目主页**：https://github.com/AskaEth/Unlucky-Launcher ｜ 下载、议题、发布说明都在这里：
+> <https://github.com/AskaEth/Unlucky-Launcher/releases>
 
-Rust 原生单文件 Minecraft 启动器：**Slint + Metro 视觉**，内置 **AI Agent 客户端**（对话 / 改配置 / 崩溃诊断），
-融合主流 Agent 工具（**MCP**），**最低基线 Win10+**。
+Unlucky Launcher（ULL）是一个用 Rust 写的免费开源 Minecraft: Java 版启动器（Apache-2.0）。
+每个平台就一个原生二进制——没有安装包、没有捆绑运行时、没有 WebView。启动器内置 AI Agent
+客户端（对话 / 改配置 / 崩溃诊断），也能作为 MCP server 接进别的 Agent 工具。
 
-- 运行时：纯 Rust 原生二进制——无 JVM、无 WebView、无外部运行时
-- UI：Slint（Royalty-Free 2.0；GL 优先，CPU 软渲染兜底，无可用 GPU 的老机也有完整 UI）
-- 许可：Apache-2.0 © AskaEth (YeiJ)
+## 特性
+
+- **单文件原生二进制**：启动器本体不需要 JVM、不需要 WebView、不带旁挂运行时。游戏要的 JDK 由
+  启动器按实例下载管理，不是启动器的依赖。
+- **重写期两套 UI 并存**：已发布版本是 Slint（Royalty-Free 2.0）；下一代 UI 是 iced 0.14 +
+  Material 3 Expressive，目前仍在写（见「当前状态」）。
+- **CPU 软渲染兜底**：`--software-renderer` 让没有可用 GPU 或驱动有问题的老机也能正常显示界面。
+- **AI Agent + MCP**：启动器内可对话、改设置、读崩溃诊断；`ull agent serve` 把同一个内核以 MCP
+  server 形态（stdio 或 Streamable HTTP）开放给外部 Agent 工具。
+- **加载器**：Fabric / Quilt / NeoForge / Forge；整合包与 CurseForge / Modrinth 客户端在 core 里。
+- **Java 管理**：Temurin → Oracle → Microsoft → Zulu 回退链，带地区判定。
+- **账户**：用 Microsoft 账户登录，认证走 OAuth 2.0 device code flow → Xbox Live → XSTS →
+  `api.minecraftservices.com`；账户令牌只保存在本机。
+- **引擎**：多源下载（健康度评分、镜像、分块传输、边下边算）与 YAML 规则引擎的崩溃诊断。
+- **许可**：Apache-2.0 © AskaEth (YeiJ)。
 
 ## 当前状态
 
-**核心引擎已完成**（workspace 983+ 测试全绿）：
+两条轨道，还不是同一个东西——看小标题再决定下载什么。
 
-- **正版登录**：Microsoft OAuth 2.0 device code flow → Xbox Live → XSTS → Minecraft Services，校验游戏拥有状态
-- **账户凭据仅保存在本机**，不上传任何服务器，AI 功能无法访问
-- 加载器：Forge / NeoForge / Fabric / Quilt 四家真机验证
-- Java 管理：Temurin / Oracle / Microsoft / Zulu 四发行版回退链
-- 多源下载引擎、崩溃诊断规则引擎
-- 可作为 MCP server 接入外部 Agent 工具（`ull agent serve`）
-- 本地离线档案：仅用于本地/隔离网络环境的测试，不经过 Microsoft 账户认证，无法连接启用正版验证的服务器
+### 轨道 A —— 已发布：v0.1.0，Slint 版（现在能下载的就是它）
 
-**CLI（`ull`）完整可用**：`install / launch / accounts / java / diagnose / agent` 等全量命令。
+- **GitHub Releases `v0.1.0`**（2026-11-01，标记为 pre-release）：单文件产物覆盖 Windows x64（裸
+  `.exe`）、Linux x64、macOS（arm64 与 x64）`.tar.gz`。每个 Release 另挂 `SHA256SUMS.txt` 与
+  `LICENSE` / `NOTICE` / `README.md` 三份文本——Windows 是「一个 exe 装不下文本」所以并列挂出，
+  unix 归档里本来就装着。
+- **UI**：Slint + Metro。这是已交付的图形界面——实例、下载、账户、Java、日志、设置
+  各页都由 core 引擎驱动（应用内 AI 对话面板仍是脚本化的占位）。
+- **CLI `ull`** 与 v0.1.0 同源同版本，但发布资产里只有 GUI 单文件——要用它请自己构建：
+  `cargo build --release --bin ull`。命令：`instances`、`install`、`launch`、`accounts`、`sessions`、
+  `logs`、`diag`、`config`、`java`、`agent`。
+- Windows ARM64 与 Linux ARM64 两个槽位已接进发布流水线，随下一个 tag 发布；`v0.1.0` 的资产早于
+  这两个槽位。
 
-**图形界面（GUI）开发中**：`crates/app` 当前为 Slint + Metro 风格骨架，主题系统与完整界面
-随后续版本交付——在此之前请使用 CLI。
+### 轨道 B —— dev 上的下一代 UI（iced + M3 Expressive，施工中）
+
+**这条轨道还没发布——要看只能自己从源码编。**
+
+- **方向已锁死**：视觉 = Material 3 Expressive，框架 = iced 0.14，UI 层从头写；风格与框架都不会再换。
+- **已完成**：令牌 crate `crates/design`（零 UI 框架依赖、零第三方 crate——真 HCT 色彩、排版档位、
+  形状刻度、间距、高程、动效、图标几何、组件度量）与骨架 crate `crates/app-iced`（能开窗、自绘标题栏
+  与窗口键、导航轨、颜色与字号只从令牌取、GPU→CPU 后端探测与自动降级、视觉验收用的截图与逐像素
+  对比通道）。
+- **没完成**：组件库（按钮、对话框、列表、菜单、搜索栏，以及 M3 其余组件）、页面搬迁、i18n 文案。
+  iced 版里现在每一个页面都是占位。
+- **Slint 版在翻牌前不退场**：`crates/app` 作为参考实现保留，直到 iced 版通过等价验收；那时才把
+  `unlucky-launcher-iced` 改名成 `unlucky-launcher`，并让 Slint 版退役。
+
+工作区里的三个 bin，先认清楚：
+
+| 二进制 | crate | 状态 |
+|--------|-------|------|
+| `unlucky-launcher` | `crates/app`（Slint） | v0.1.0 已发布，仍是当前能用的图形界面 |
+| `unlucky-launcher-iced` | `crates/app-iced`（iced 0.14） | 施工中，仅骨架，不随发布包分发 |
+| `ull` | `crates/cli` | 与发布版同源同版本构建；未随 v0.1.0 资产分发 |
 
 ## 模块地图
 
 ```
 Unlucky-Launcher (cargo workspace)
-├── crates/core     # 领域库：零 UI 依赖，八模块
-├── crates/agent    # AI Agent：ToolSpec 注册表 + 内置客户端 + MCP server（双形态共用一个内核）
-├── crates/app      # Slint UI：唯一允许依赖 UI 框架的 crate
-├── crates/cli      # CLI（bin `ull`）：headless，零 UI，只依赖 core + agent
-└── packaging       # 单文件产物矩阵与打包资源（规划中）
+├── crates/core       # 领域库：零 UI 依赖，八模块
+├── crates/agent      # AI Agent：ToolSpec 注册表 + 内置客户端 + MCP server（双形态共用一个内核）
+├── crates/design     # 设计令牌：真 HCT 色彩 / 排版 / 形状 / 间距 / 高程 / 动效 / 图标 / 组件度量
+│                     #   —— 零 UI 依赖、零第三方 crate
+├── crates/app        # Slint UI（bin `unlucky-launcher`）：已发布的图形界面，保留到等价验收通过
+├── crates/app-iced   # 下一代 iced UI（bin `unlucky-launcher-iced`）：施工中
+├── crates/cli        # CLI（bin `ull`）：headless，零 UI
+└── packaging         # 单文件产物矩阵与发布脚本
 ```
 
 `crates/core` 的八个模块：
@@ -47,7 +87,7 @@ Unlucky-Launcher (cargo workspace)
 | `download` | 多源健康度、镜像、分块下载、边下边算 |
 | `game` | 版本/实例仓库、快照与继承解析 |
 | `launch` | 10 阶段启动管线、进程、JSONL 事件流 |
-| `auth` | Microsoft 正版登录 / 本地离线档案 |
+| `auth` | Microsoft 账户登录（OAuth 2.0 device code → Xbox Live → XSTS → Minecraft Services） |
 | `addon` | 加载器安装、整合包、CurseForge / Modrinth |
 | `diagnose` | 五类信号采集、YAML 规则引擎、hs_err 解析 |
 | `platform` | OS 抽象：路径、进程、文件锁、能力探测、运行期 OS 检测 |
@@ -56,44 +96,73 @@ Unlucky-Launcher (cargo workspace)
 
 前置：
 
-- Rust stable（`rust-toolchain.toml` 会自动选择工具链；组件 `rustfmt` / `clippy`）
-- Windows：MSVC 工具链（CI 用）或 MinGW-w64（`x86_64-pc-windows-gnu`）
-- Linux：`libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev libxcb1-dev`
-  （Slint winit 后端 + femtovg 编译依赖）
+- Rust stable（`rust-toolchain.toml` 会自动选工具链；门禁还需要 `rustfmt` / `clippy` 组件）
+- Windows：MSVC 工具链（CI 用这套）或 MinGW-w64（`x86_64-pc-windows-gnu`）
+- Linux：`libxkbcommon-dev libfontconfig1-dev libgl1-mesa-dev libegl1-mesa-dev libwayland-dev
+  libxcb1-dev`——两套 UI 都要用（Slint 的 winit + femtovg，iced 的 winit + wgpu/tiny-skia）
 
 ```bash
-cargo fmt --all --check                              # 格式
-cargo clippy --workspace --all-targets -- -D warnings # 静态检查（零 warning 门禁）
-cargo test --workspace                               # 测试
-cargo build --release                                # 产物：target/release/unlucky-launcher[.exe]
+cargo fmt --all --check                                # 格式
+cargo clippy --workspace --all-targets -- -D warnings  # 静态检查（零 warning 门禁）
+cargo test --workspace                                 # 测试
+cargo build --release                                  # 三个 bin 都落在 target/release/
 ```
 
-软渲染开关（无可用 GPU / 烂驱动的老机）：`unlucky-launcher --software-renderer`
-（等价于 `SLINT_BACKEND=winit-software`）。
+编出来的三个 bin：
+
+- `unlucky-launcher`——Slint 版（已发布的那个）
+- `unlucky-launcher-iced`——iced 版骨架。名字是临时的：只有翻牌时才能改成 `unlucky-launcher`，
+  因为同一个工作区里两个 crate 不能往同一个 target 目录里产出同名 bin。
+- `ull`——CLI
+
+渲染开关：
+
+- `unlucky-launcher --software-renderer`（等价于 `SLINT_BACKEND=winit-software`）强制 Slint 版走 CPU
+- `unlucky-launcher-iced --software-renderer` 强制 tiny-skia（`ICED_BACKEND=tiny-skia`）；
+  `--screenshot <png>` 出一帧图后退出，这是验收通道
+- 两套栈在没有可用适配器时都会退到 CPU：Slint 版走它自己的渲染器回退链，iced 版走显式探测
 
 依赖许可检查（本地可选，CI 必跑）：`cargo deny check licenses bans sources`。
 
 ## CI 门禁
 
+每次推送到 `main` 与每个 PR 都跑 fmt / clippy（warnings 视为错误）/ 全量测试，Linux 无头渲染冒烟
+与它们同级、是硬门禁：红了就不许合。macOS 运行期探针还不算——它只在手动 `workflow_dispatch` 时跑，
+结果留证据但不作为流水线结论（`continue-on-error`），直到该槽位在真实 runner 上首跑通过。
+
 | Workflow | 内容 |
 |----------|------|
-| `.github/workflows/ci.yml` | fmt + clippy + test + build，Windows / Linux 矩阵 |
-| `.github/workflows/guards.yml` | core 零 UI 守门、单文件 ≤400 行守门、cargo-deny 许可守门 |
+| `.github/workflows/ci.yml` | fmt + clippy + test + release build（Windows / Linux 矩阵）；Linux runtime smoke（Xvfb 里真渲染一帧，再断言 PNG 非空白）；macOS 运行期探针（仅手动 dispatch） |
+| `.github/workflows/guards.yml` | `crates/core` 零 UI 守门（依赖表 + `cargo tree`）、单文件 ≤400 行守门、cargo-deny 许可与来源守门 |
+| `.github/workflows/release.yml` | tag `v*` → 分槽位构建 → 单文件产物 + `SHA256SUMS.txt` → GitHub Release |
 
 ## 平台基线
 
-最低基线 **Windows 10**。Windows 8.1 / 8 / 7 不在支持范围内：
+最低基线 **Windows 10**；Windows 8.1 / 8 / 7 不在支持范围内。
 
-- Windows 10/11 走**标准工具链**产物（MSVC / GNU），无自定义 target spec、无 `-Zbuild-std`、无导入表白名单
-- 其他平台：macOS 12+ 一等；Linux x64 X11 优先、Wayland 为**大方向**；Android Termux 试验级不承诺
-- UI 兜底：Slint 软渲染（无 GPU / 烂驱动的老机可完整使用）
-- 平台独立性体现在**独立测试矩阵**，而非独立产物链；能力差异用 feature gate + 运行期探测表达
+- Windows 10/11 的产物由**标准工具链**（MSVC / GNU）构建，构建方式与上游 cargo 一致
+- macOS 12+（Apple Silicon 与 Intel）与 Linux x64 / arm64 都是支持槽位；Linux 上 X11 是当前首选路径，
+  Wayland 是大方向。macOS 产物未签名，首次启动要自己清掉 Gatekeeper 隔离标记
+  （`xattr -d com.apple.quarantine`）
+- Android Termux 试验级、不承诺：只保证 CLI，GUI 未验证
+- 每个平台跑各自的测试矩阵；能力差异用 feature gate + 运行期探测表达。
 
 ## 许可证与致谢
 
-- 本项目：Apache License 2.0，见 [LICENSE](LICENSE)；第三方声明见 [NOTICE](NOTICE)
-- GUI 使用 [Slint](https://slint.dev)（Royalty-Free 2.0 轨道）。按 RF 2.0 义务，关于页将放置
-  `AboutSlint` 部件（P2），在此之前由 NOTICE 与本节承担告知义务
+- **本项目**：Apache License 2.0，见 [LICENSE](LICENSE)；第三方声明见 [NOTICE](NOTICE)。
+- **Slint**（<https://slint.dev>），Royalty-Free 2.0：v0.1.0 发布的正是 Slint 版，这项义务继续有效
+  ——关于页放 `AboutSlint` 部件（尚未落地），在此之前由 NOTICE、本节与发布页的「Made with Slint」
+  说明承担告知义务。只要还有链接 Slint 的产物在发，这条义务就保留。
+- **iced**（<https://github.com/iced-rs/iced>），MIT：下一代 UI 的框架；与它同栈的 `winit`、以及经它
+  引入的 `wgpu` / `tiny-skia`（Apache-2.0 / MIT）。
+- **Google Material Color Utilities**（Apache-2.0）：`crates/design` 的色彩令牌是它 HCT /
+  ColorSpec2021 算法的 Rust 重写移植，移植清单与逐函数对照写在 [NOTICE](NOTICE)。
+- **其余主要依赖**：MCP server 的 `rmcp` 与 `axum`（Apache-2.0 / MIT）、`tokio`（MIT）、`reqwest`
+  与 rustls（MIT / Apache-2.0）、`serde` / `serde_json`（MIT / Apache-2.0）、`zip` / `flate2` / `tar`
+  （MIT / Apache-2.0）。cargo-deny 强制执行的白名单在 `deny.toml`；GPL 系依赖不得进主干。
 
-感谢 [HMCL](https://github.com/HMCL-dev/HMCL) 和 [PCL2](https://github.com/Meloong-Git/PCL)（均 GPL-3.0）这两个启动器陪伴了绝大多数 MC 玩家好多年。
-ULL 的设计与实现从它们身上学到了太多，谨以此项目向两位前辈致敬。
+感谢 [HMCL](https://github.com/HMCL-dev/HMCL) 和 [PCL2](https://github.com/Meloong-Git/PCL)
+（均 GPL-3.0）。这两款启动器陪着绝大多数 MC 玩家走了很多年，
+本项目在设计取舍与实现细节上都从中受益良多。
+
+与 Mojang、Microsoft 无关联。

crates/app-iced/Cargo.toml

@@ -0,0 +1,51 @@
+[package]
+name = "unlucky-app-iced"
+description = "Unlucky-Launcher 桌面壳（iced 0.14 重写版）：M3 Expressive 骨架 / 令牌适配 / 截图通道"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+# 并存期（D26）：Slint 版仍是 `crates/app` 的 `unlucky-launcher`，本 crate 出
+# `unlucky-launcher-iced`。两个 package 在同一 target 目录产出同名 bin 会冲突，
+# 所以**翻牌前不许改回 `unlucky-launcher`**（步骤见 SubAgentsTalk/app-iced-骨架与翻牌.md）。
+[[bin]]
+name = "unlucky-launcher-iced"
+path = "src/main.rs"
+
+[lib]
+name = "unlucky_app_iced"
+path = "src/lib.rs"
+
+[dependencies]
+# 令牌唯一真源（M61）：颜色/排版/形状/间距/图标几何全部只从这里取。
+unlucky-design = { path = "../design", version = "0.1" }
+
+# UI 框架（D26 锁定 iced 0.14）。**不得依赖 slint**。
+# 关掉默认 features 后必须显式给执行器（M60 踩坑 Q2：否则 `No futures executor has been enabled`），
+# 这里给 `thread-pool`（iced 自己的默认执行器，不额外引 tokio 运行时）。
+# `wgpu` 由本 crate 的 `gpu` feature 打开，于是「仅 CPU」体积基线用 `--no-default-features` 就能量到。
+iced = { version = "=0.14.0", default-features = false, features = [
+    "tiny-skia",
+    "crisp",
+    "advanced",
+    "svg",
+    "thread-pool",
+    "x11",
+    "wayland",
+    "linux-theme-detection",
+] }
+
+# 截图落 PNG。只开 png 编码器，不要默认全套 codec（体积）。
+image = { version = "0.25", default-features = false, features = ["png"] }
+
+[features]
+default = ["gpu"]
+# 硬件渲染后端（wgpu→Vulkan/DX12）。关闭后只剩 tiny-skia（CPU），用于体积基线与无 GPU 机器。
+gpu = ["iced/wgpu"]
+
+[lints]
+workspace = true

crates/app-iced/src/app.rs

@@ -0,0 +1,400 @@
+//! Elm 三件套：`State` / `Message` / `update` + `view` 接线。
+//!
+//! ## 启动序列（顺序有讲究）
+//!
+//! 1. **探测渲染后端** → 写 `ICED_BACKEND`（必须在 `run()` 之前，M60 Q1）；
+//! 2. **求值字体栈**（D28 前半）→ 一行启动日志；
+//! 3. `iced::application(..).run()`：窗口 1180×760、无边框（自绘标题栏）；
+//! 4. 首个 `view()` 打「到首帧」耗时；截图模式下第 3 帧 `window::screenshot` 落盘后退出。
+//!
+//! ## 为什么截图要等 3 帧
+//!
+//! 无边框窗口启动时会先收到一次「显示器工作区尺寸」的 `Resized`，再回到设定尺寸（M60 坑 #5），
+//! 第一帧可能是旧尺寸；再叠上字体系统首次上屏的排版抖动，留 2 帧余量最稳。
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::OnceLock;
+use std::time::Instant;
+
+use iced::{window, window::Direction, Element, Subscription, Task};
+
+use unlucky_design::color::SchemeFlavor;
+
+use crate::cli::Options;
+use crate::fonts;
+use crate::probe;
+use crate::shell::{self, NavItem};
+use crate::shot;
+use crate::theme::{Families, Ui};
+
+/// 验收窗口尺寸（1180×760，100% DPI —— D30 的硬要求）。
+pub const WINDOW_SIZE: iced::Size = iced::Size {
+    width: 1180.0,
+    height: 760.0,
+};
+
+/// 产品名（自绘标题栏的标题；也是 `'static`，好让 view 借用）。
+pub const APP_TITLE: &str = "Unlucky Launcher";
+
+/// 窗口最小尺寸（低于这个值骨架会挤坏：88 导航 + 页面留白 + 卡片）。
+const MIN_SIZE: iced::Size = iced::Size {
+    width: 880.0,
+    height: 560.0,
+};
+
+/// 截图落盘的帧号（见模块文档）。
+const CAPTURE_AT_FRAME: u32 = 3;
+
+/// 进程内「run() 开始」的时刻（首帧耗时基线）。
+static STARTED: OnceLock<Instant> = OnceLock::new();
+/// 首帧日志只打一次。
+static FIRST_FRAME_LOGGED: AtomicBool = AtomicBool::new(false);
+
+/// 应用状态（**只有 UI 状态**；业务状态等页面 mission 接 `host`/`state` 时再进）。
+pub struct App {
+    options: Options,
+    families: Families,
+    ui: Ui,
+    nav: NavItem,
+    window: Option<window::Id>,
+    frames: u32,
+    /// 截图模式的「主题已定」闸门：`system::theme()` 是异步的，早拍会拍到错的深浅色。
+    theme_resolved: bool,
+}
+
+/// 消息（单一大枚举；页面接进来时按页拆子枚举）。
+#[derive(Debug, Clone)]
+pub enum Message {
+    /// 启动即发一次（`iced::application` 的 boot 闭包）。
+    Boot,
+    /// `window::latest()` 的结果。
+    WindowReady(Option<window::Id>),
+    /// 系统主题探测结果。
+    SystemTheme(iced::theme::Mode),
+    /// 一帧画完（只有截图模式才订阅）。
+    Frame,
+    /// 导航项切换。
+    Select(NavItem),
+    /// 按下标题栏 → 拖窗。
+    DragWindow,
+    /// 按下边缘热区 → 缩放窗口。
+    ResizeStart(Direction),
+    /// 最小化。
+    Minimize,
+    /// 最大化/还原。
+    ToggleMaximize,
+    /// 关闭。
+    Close,
+    /// 截图回来了。
+    Captured(window::Screenshot),
+}
+
+impl App {
+    fn new(options: Options, families: Families, flavor: SchemeFlavor) -> Self {
+        let options_theme_given = options.shot_flavor().is_some();
+        Self {
+            ui: Ui::new(flavor, families),
+            families,
+            options,
+            nav: NavItem::Instances,
+            window: None,
+            frames: 0,
+            // 显式给了主题就算已定；否则等 `SystemTheme` 到达
+            theme_resolved: options_theme_given,
+        }
+    }
+
+    fn has_screenshot(&self) -> bool {
+        self.options.screenshot.is_some()
+    }
+
+    fn update(&mut self, message: Message) -> Task<Message> {
+        match message {
+            Message::Boot => {
+                let mut tasks = vec![window::latest().map(Message::WindowReady)];
+
+                // 主题：参数里没指定就探系统（深浅两套都要能出图）
+                if self.options.shot_flavor().is_none() {
+                    tasks.push(iced::system::theme().map(Message::SystemTheme));
+                }
+
+                Task::batch(tasks)
+            }
+            Message::WindowReady(id) => {
+                self.window = id;
+                Task::none()
+            }
+            Message::SystemTheme(mode) => {
+                let flavor = match mode {
+                    iced::theme::Mode::Dark => SchemeFlavor::Dark,
+                    iced::theme::Mode::None | iced::theme::Mode::Light => SchemeFlavor::Light,
+                };
+                eprintln!("[theme] 系统主题 = {mode:?} -> {}", slug(flavor));
+                self.set_flavor(flavor);
+                self.theme_resolved = true;
+                Task::none()
+            }
+            Message::Frame => self.on_frame(),
+            Message::Select(nav) => {
+                self.nav = nav;
+                Task::none()
+            }
+            Message::DragWindow => match self.window {
+                Some(id) => window::drag(id),
+                None => Task::none(),
+            },
+            Message::ResizeStart(direction) => match self.window {
+                Some(id) => window::drag_resize(id, direction),
+                None => Task::none(),
+            },
+            Message::Minimize => match self.window {
+                Some(id) => window::minimize(id, true),
+                None => Task::none(),
+            },
+            Message::ToggleMaximize => match self.window {
+                Some(id) => window::toggle_maximize(id),
+                None => Task::none(),
+            },
+            Message::Close => iced::exit(),
+            Message::Captured(screenshot) => self.on_captured(&screenshot),
+        }
+    }
+
+    /// 切主题：只重建 [`Ui`]（= 重建 Style），**不动任何 UI 状态**。
+    fn set_flavor(&mut self, flavor: SchemeFlavor) {
+        if self.ui.flavor() == flavor {
+            return;
+        }
+
+        let next = Ui::new(flavor, self.families);
+        eprintln!(
+            "[theme] {} -> {} (Theme::name 变化触发缓存重算)",
+            self.ui.name(),
+            next.name()
+        );
+        self.ui = next;
+    }
+    fn on_frame(&mut self) -> Task<Message> {
+        self.frames += 1;
+
+        // 主题没定就不出图：等 `SystemTheme`（否则暗色系统上会拍到浅色图）
+        if !self.has_screenshot() || !self.theme_resolved || self.frames < CAPTURE_AT_FRAME {
+            return Task::none();
+        }
+
+        match self.window {
+            Some(id) => window::screenshot(id).map(Message::Captured),
+            None => Task::none(),
+        }
+    }
+
+    fn on_captured(&mut self, screenshot: &window::Screenshot) -> Task<Message> {
+        let Some(path) = self.options.screenshot.clone() else {
+            return Task::none();
+        };
+
+        match shot::save(screenshot, &path) {
+            Ok(summary) => {
+                eprintln!("{}", summary.describe());
+                eprintln!(
+                    "[shot] theme={} renderer={}",
+                    shot::flavor_slug(&self.ui),
+                    renderer_note(self.options.backend)
+                );
+            }
+            Err(error) => eprintln!("[shot] 失败：{error}"),
+        }
+
+        iced::exit()
+    }
+
+    fn subscription(&self) -> Subscription<Message> {
+        // 只有截图模式才订阅帧事件：否则「每帧一条消息 → 每帧重绘」会白烧 CPU。
+        if self.wants_frames() {
+            window::frames().map(|_| Message::Frame)
+        } else {
+            Subscription::none()
+        }
+    }
+
+    /// 是否订阅帧事件（= 截图模式）。
+    fn wants_frames(&self) -> bool {
+        self.has_screenshot()
+    }
+
+    fn theme(&self) -> iced::Theme {
+        self.ui.theme()
+    }
+
+    fn title(&self) -> String {
+        APP_TITLE.to_owned()
+    }
+
+    fn view(&self) -> Element<'_, Message> {
+        if !FIRST_FRAME_LOGGED.swap(true, Ordering::Relaxed) {
+            if let Some(started) = STARTED.get() {
+                eprintln!(
+                    "[boot] first frame in {:.0} ms（run() 开始 → 首次 view，含后端探测与字体扫描）",
+                    started.elapsed().as_secs_f64() * 1000.0
+                );
+            }
+        }
+
+        shell::view(
+            &self.ui,
+            self.nav,
+            APP_TITLE,
+            self.nav.label(),
+            "Skeleton only: titlebar, navigation rail and one card. \
+             Business pages, the component library and the glass shader are follow-up missions.",
+            self.options.force_state,
+        )
+    }
+}
+
+fn renderer_note(backend: crate::Backend) -> &'static str {
+    if cfg!(feature = "gpu") {
+        match backend {
+            crate::Backend::Cpu => "cpu(forced)",
+            crate::Backend::Gpu => "gpu(preferred)",
+            crate::Backend::Auto => "auto",
+        }
+    } else {
+        "cpu(build without wgpu)"
+    }
+}
+
+/// 主题名（日志用，和 `Ui::name()` 同一口径）。
+fn slug(flavor: SchemeFlavor) -> &'static str {
+    if flavor.is_dark() {
+        "ull-m3-dark"
+    } else {
+        "ull-m3-light"
+    }
+}
+
+/// 启动 iced（阻塞到退出）。`--diff` 不走这里，见 `main.rs`。
+pub(crate) fn run(options: Options) -> iced::Result {
+    let _ = STARTED.set(Instant::now());
+
+    let probe_started = Instant::now();
+    // 只有 `auto` 需要探测：`cpu` 与 `gpu` 的决策与「有没有硬件 GPU」无关，
+    // 而枚举 13 个适配器在本机要 0.65~1.2 s（实测），纯属白花。
+    let needs_probe = options.backend == crate::Backend::Auto;
+    let probe = if needs_probe {
+        probe::Probe::run()
+    } else {
+        probe::Probe::default()
+    };
+    let probe_ms = probe_started.elapsed().as_secs_f64() * 1000.0;
+    probe::apply(options.backend, &probe);
+    if cfg!(feature = "gpu") {
+        if needs_probe {
+            eprintln!("[probe] 探测耗时 {probe_ms:.0} ms（wgpu 实例 + 全后端适配器枚举）");
+        } else {
+            eprintln!(
+                "[probe] 探测耗时 {probe_ms:.0} ms（--renderer={} 与硬件无关，跳过枚举）",
+                options.backend.name()
+            );
+        }
+    }
+
+    let font_started = Instant::now();
+    let resolved = fonts::resolve();
+    eprintln!(
+        "[font] 求值耗时 {:.0} ms",
+        font_started.elapsed().as_secs_f64() * 1000.0
+    );
+    eprintln!("{}", resolved.describe());
+    if resolved.has_synthetic() {
+        eprintln!(
+            "[font] 警告：有字重落在「合成加粗」档（观感降级），D28 后半（CDN 字体/按档换族）要处理"
+        );
+    }
+    let families = resolved.families();
+
+    // 截图模式：`--screenshot-theme` > `--theme` > 浅色（后续系统探测会覆盖）
+    let flavor = options.shot_flavor().unwrap_or(SchemeFlavor::Light);
+    let boot_options = options.clone();
+
+    let application = iced::application(
+        move || {
+            (
+                App::new(boot_options.clone(), families, flavor),
+                Task::done(Message::Boot),
+            )
+        },
+        App::update,
+        App::view,
+    )
+    .title(App::title)
+    .theme(App::theme)
+    .subscription(App::subscription)
+    .default_font(iced::Font {
+        family: iced::font::Family::Name(families.text),
+        ..iced::Font::DEFAULT
+    })
+    .window(window::Settings {
+        size: WINDOW_SIZE,
+        min_size: Some(MIN_SIZE),
+        decorations: false,
+        resizable: true,
+        ..window::Settings::default()
+    });
+
+    match options.scale_factor {
+        Some(scale) => application.scale_factor(move |_| scale).run(),
+        None => application.run(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const FAMILIES: Families = Families {
+        text: "Segoe UI",
+        display: "Segoe UI",
+        mono: "Consolas",
+    };
+
+    #[test]
+    fn switching_flavor_rebuilds_styles_but_keeps_ui_state() {
+        let mut app = App::new(Options::default(), FAMILIES, SchemeFlavor::Light);
+        app.nav = NavItem::Logs;
+        assert_eq!(app.ui.name(), "ull-m3-light");
+
+        app.set_flavor(SchemeFlavor::Dark);
+
+        assert_eq!(app.ui.name(), "ull-m3-dark", "切主题要换主题名");
+        assert_eq!(app.nav, NavItem::Logs, "切主题不许重置 UI 状态");
+        assert!(app.options.screenshot.is_none(), "切主题不许改启动参数");
+    }
+
+    #[test]
+    fn window_size_is_the_acceptance_size() {
+        assert_eq!((WINDOW_SIZE.width, WINDOW_SIZE.height), (1180.0, 760.0));
+        const {
+            assert!(MIN_SIZE.width < WINDOW_SIZE.width);
+            assert!(MIN_SIZE.height < WINDOW_SIZE.height);
+        }
+    }
+
+    #[test]
+    fn slug_matches_the_theme_name() {
+        assert_eq!(slug(SchemeFlavor::Light), "ull-m3-light");
+        assert_eq!(slug(SchemeFlavor::Dark), "ull-m3-dark");
+    }
+
+    #[test]
+    fn frames_are_only_requested_in_screenshot_mode() {
+        let mut app = App::new(Options::default(), FAMILIES, SchemeFlavor::Light);
+        assert!(!app.wants_frames(), "普通运行不订阅帧，避免每帧重绘");
+
+        app.options.screenshot = Some(std::path::PathBuf::from("x.png"));
+        assert!(
+            app.wants_frames(),
+            "截图模式必须订阅帧事件才能在第 3 帧出图"
+        );
+    }
+}

crates/app-iced/src/cli.rs

@@ -0,0 +1,298 @@
+//! 命令行参数（只做骨架期需要的那些；业务开关等页面 mission 再加）。
+//!
+//! 取值语法与现役 Slint 版一致：`--key value` 与 `--key=value` 两种都认
+//! （`crates/app/src/screenshot.rs` 的 `value_of` 是同一口径），这样将来 CI 换 bin 不用改脚本。
+
+use std::path::PathBuf;
+
+use unlucky_design::color::SchemeFlavor;
+
+/// 渲染后端请求（D27）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Backend {
+    /// 探测后决定：有硬件 GPU 就让 iced 自己走 wgpu→tiny-skia 回退；没有就强制 CPU 起步。
+    #[default]
+    Auto,
+    /// 优先 GPU（写 `ICED_BACKEND=wgpu,tiny-skia`：拿不到适配器仍会降级，不硬失败）。
+    Gpu,
+    /// 强制 CPU（`--software-renderer` 的等价物，写 `ICED_BACKEND=tiny-skia`）。
+    Cpu,
+}
+
+impl Backend {
+    /// 稳定名字（日志用）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Backend::Auto => "auto",
+            Backend::Gpu => "gpu",
+            Backend::Cpu => "cpu",
+        }
+    }
+}
+
+/// 解析后的启动参数。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Options {
+    /// 渲染后端请求。
+    pub backend: Backend,
+    /// 主题：`None` = 探测系统主题。
+    pub theme: Option<SchemeFlavor>,
+    /// 截图通道：给了路径就出图后退出。
+    pub screenshot: Option<PathBuf>,
+    /// 截图时用的主题（`--screenshot-theme`，优先级高于 `--theme`）。
+    pub screenshot_theme: Option<SchemeFlavor>,
+    /// 强制窗口缩放因子（截图验收要 100% DPI；`None` = 用系统 DPI）。
+    pub scale_factor: Option<f32>,
+    /// `--diff <left> <right>`：只做两图逐像素对比，不开窗。
+    pub diff: Option<(PathBuf, PathBuf)>,
+    /// `--diff-scan <n>`：对比时额外做 ±n px 的平移扫描（找最佳对齐，默认 0 = 不扫）。
+    pub diff_scan: u32,
+    /// `--force-state=hover|pressed`：把按钮强制成某个状态便于截图取证（D30 的状态图）。
+    pub force_state: Option<ForcedState>,
+    /// `--data-dir <dir>`：当前**接受并忽略**。
+    ///
+    /// 现役 Slint 版的 CI 冒烟用 `--software-renderer --screenshot <png> --data-dir <dir>`，
+    /// 翻牌后同一套脚本要能直接跑 iced 版；真正的数据目录消费由后续页面 mission 接 `host`/`state` 时做。
+    pub data_dir: Option<PathBuf>,
+}
+
+/// 截图取证用的强制交互状态（只影响观感，不改变任何状态机）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ForcedState {
+    /// 所有可交互控件按 hover 画。
+    Hover,
+    /// 所有可交互控件按 pressed 画。
+    Pressed,
+}
+
+impl ForcedState {
+    /// 稳定名字（日志用）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            ForcedState::Hover => "hover",
+            ForcedState::Pressed => "pressed",
+        }
+    }
+}
+
+impl Default for Options {
+    fn default() -> Self {
+        Self {
+            backend: Backend::Auto,
+            theme: None,
+            screenshot: None,
+            screenshot_theme: None,
+            scale_factor: None,
+            diff: None,
+            diff_scan: 0,
+            force_state: None,
+            data_dir: None,
+        }
+    }
+}
+
+impl Options {
+    /// 从进程参数解析。
+    ///
+    /// # Errors
+    /// 参数值不合法（未知的 `--renderer` / `--theme` / 非法 `--scale-factor`）时返回人话。
+    pub fn from_env() -> Result<Self, String> {
+        Self::parse(std::env::args().skip(1))
+    }
+
+    /// 从任意参数序列解析（`argv[1..]`，测试直接喂数组）。
+    ///
+    /// # Errors
+    /// 同 [`Options::from_env`]。
+    pub fn parse(args: impl IntoIterator<Item = String>) -> Result<Self, String> {
+        let mut options = Self::default();
+        let mut args = args.into_iter();
+
+        while let Some(arg) = args.next() {
+            let (key, inline) = match arg.split_once('=') {
+                Some((key, value)) => (key.to_owned(), Some(value.to_owned())),
+                None => (arg.clone(), None),
+            };
+
+            match key.as_str() {
+                "--software-renderer" => options.backend = Backend::Cpu,
+                "--renderer" => {
+                    let value = take(&mut args, inline, "--renderer")?;
+                    options.backend = match value.as_str() {
+                        "auto" => Backend::Auto,
+                        "gpu" => Backend::Gpu,
+                        "cpu" => Backend::Cpu,
+                        other => {
+                            return Err(format!("--renderer 只认 auto|gpu|cpu，收到 {other:?}"));
+                        }
+                    };
+                }
+                "--theme" => {
+                    options.theme = Some(flavor(&take(&mut args, inline, "--theme")?)?);
+                }
+                "--screenshot-theme" => {
+                    options.screenshot_theme =
+                        Some(flavor(&take(&mut args, inline, "--screenshot-theme")?)?);
+                }
+                "--screenshot" => {
+                    options.screenshot =
+                        Some(PathBuf::from(take(&mut args, inline, "--screenshot")?));
+                }
+                "--scale-factor" => {
+                    let raw = take(&mut args, inline, "--scale-factor")?;
+                    let value: f32 = raw
+                        .parse()
+                        .map_err(|_| format!("--scale-factor 需要数字，收到 {raw:?}"))?;
+                    if !(value.is_finite() && value > 0.0) {
+                        return Err(format!("--scale-factor 必须 > 0，收到 {raw:?}"));
+                    }
+                    options.scale_factor = Some(value);
+                }
+                "--diff" => {
+                    let left = take(&mut args, inline, "--diff")?;
+                    let right = args
+                        .next()
+                        .ok_or_else(|| "--diff 需要两张图的路径".to_owned())?;
+                    options.diff = Some((PathBuf::from(left), PathBuf::from(right)));
+                }
+                "--diff-scan" => {
+                    let raw = take(&mut args, inline, "--diff-scan")?;
+                    options.diff_scan = raw
+                        .parse()
+                        .map_err(|_| format!("--diff-scan 需要非负整数，收到 {raw:?}"))?;
+                }
+                "--force-state" => {
+                    let raw = take(&mut args, inline, "--force-state")?;
+                    options.force_state = Some(match raw.as_str() {
+                        "hover" => ForcedState::Hover,
+                        "pressed" => ForcedState::Pressed,
+                        other => {
+                            return Err(format!(
+                                "--force-state 只认 hover|pressed，收到 {other:?}"
+                            ));
+                        }
+                    });
+                }
+                // 翻牌前的兼容参数：接受并忽略（见字段文档）
+                "--data-dir" => {
+                    options.data_dir = Some(PathBuf::from(take(&mut args, inline, "--data-dir")?));
+                }
+                other => return Err(format!("未知参数 {other:?}")),
+            }
+        }
+
+        Ok(options)
+    }
+
+    /// 截图时实际使用的主题（截图专用参数优先）。
+    pub fn shot_flavor(&self) -> Option<SchemeFlavor> {
+        self.screenshot_theme.or(self.theme)
+    }
+}
+
+fn take(
+    args: &mut impl Iterator<Item = String>,
+    inline: Option<String>,
+    flag: &str,
+) -> Result<String, String> {
+    inline
+        .or_else(|| args.next())
+        .ok_or_else(|| format!("{flag} 需要一个值"))
+}
+
+fn flavor(raw: &str) -> Result<SchemeFlavor, String> {
+    match raw {
+        "light" => Ok(SchemeFlavor::Light),
+        "dark" => Ok(SchemeFlavor::Dark),
+        other => Err(format!("--theme 只认 light|dark，收到 {other:?}")),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn parse(args: &[&str]) -> Result<Options, String> {
+        Options::parse(args.iter().map(|arg| (*arg).to_owned()))
+    }
+
+    #[test]
+    fn defaults_are_auto_and_system_theme() {
+        let options = parse(&[]).expect("空参数要能解析");
+        assert_eq!(options.backend, Backend::Auto);
+        assert_eq!(options.theme, None);
+        assert_eq!(options.screenshot, None);
+    }
+
+    #[test]
+    fn software_renderer_is_an_alias_of_cpu() {
+        assert_eq!(
+            parse(&["--software-renderer"]).unwrap().backend,
+            Backend::Cpu
+        );
+        assert_eq!(parse(&["--renderer=cpu"]).unwrap().backend, Backend::Cpu);
+        assert_eq!(parse(&["--renderer", "gpu"]).unwrap().backend, Backend::Gpu);
+    }
+
+    #[test]
+    fn screenshot_accepts_both_argv_forms() {
+        let spaced = parse(&["--screenshot", "out.png"]).unwrap();
+        let inline = parse(&["--screenshot=out.png"]).unwrap();
+        assert_eq!(spaced.screenshot, Some(PathBuf::from("out.png")));
+        assert_eq!(spaced.screenshot, inline.screenshot);
+    }
+
+    #[test]
+    fn screenshot_theme_wins_over_theme() {
+        let options = parse(&["--theme=dark", "--screenshot-theme=light"]).unwrap();
+        assert_eq!(options.theme, Some(SchemeFlavor::Dark));
+        assert_eq!(options.shot_flavor(), Some(SchemeFlavor::Light));
+    }
+
+    #[test]
+    fn bad_values_are_reported_not_panicked() {
+        assert!(parse(&["--renderer=metal"]).is_err());
+        assert!(parse(&["--theme=blue"]).is_err());
+        assert!(parse(&["--scale-factor=0"]).is_err());
+        assert!(parse(&["--scale-factor=abc"]).is_err());
+        assert!(parse(&["--screenshot"]).is_err());
+        assert!(parse(&["--diff", "only-one.png"]).is_err());
+        assert!(parse(&["--nope"]).is_err());
+    }
+
+    #[test]
+    fn data_dir_is_accepted_and_ignored_for_the_flip() {
+        // 现役 CI 冒烟：--software-renderer --screenshot <png> --data-dir <dir>
+        let options = parse(&[
+            "--software-renderer",
+            "--screenshot",
+            "shot.png",
+            "--data-dir",
+            "/d/tmp/x",
+        ])
+        .expect("翻牌前必须兼容 --data-dir");
+        assert_eq!(options.backend, Backend::Cpu);
+        assert_eq!(options.screenshot, Some(PathBuf::from("shot.png")));
+        assert_eq!(options.data_dir, Some(PathBuf::from("/d/tmp/x")));
+    }
+
+    #[test]
+    fn diff_scan_and_force_state_parse() {
+        assert_eq!(parse(&["--diff-scan=2"]).unwrap().diff_scan, 2);
+        assert_eq!(
+            parse(&["--force-state", "hover"]).unwrap().force_state,
+            Some(ForcedState::Hover)
+        );
+        assert!(parse(&["--force-state=focus"]).is_err());
+        assert!(parse(&["--diff-scan=-1"]).is_err());
+    }
+
+    #[test]
+    fn diff_takes_two_paths() {
+        let options = parse(&["--diff", "a.png", "b.png"]).unwrap();
+        assert_eq!(
+            options.diff,
+            Some((PathBuf::from("a.png"), PathBuf::from("b.png")))
+        );
+    }
+}

crates/app-iced/src/fonts.rs

@@ -0,0 +1,263 @@
+//! 字体基座（D28 前半）：把令牌的字体栈求值成「本机真的有的族名」，并打一行启动日志。
+//!
+//! ## 做什么
+//!
+//! 1. 取 `Platform::current()` 的三条栈（Display / Text / Mono，见 `unlucky_design::typography`）；
+//! 2. 用 iced 的**全局字体系统**（`iced_graphics::text::font_system()`，即 cosmic-text 的
+//!    `FontSystem`，首次调用会扫系统字体）核对每个族名是否装机 → 取栈里第一个装机可用的族；
+//! 3. 给出 400/500/700 三档字重的落点（原生 / 最近档 / 合成加粗）：
+//!    **先查系统里这个族真实提供的字面（fontdb 的 `FaceInfo.weight`）**，查不到才回落到令牌的
+//!    纯函数 `Platform::resolve_weight`。缺档按降级记录。
+//!
+//! ## 为什么要真查系统
+//!
+//! 令牌栈写的是「Win11 有 Segoe UI Variable Text」，但 Win10 / Server 只有 `Segoe UI`（静态
+//! 300/400/600/700，**没有 500**），干净安装的 Linux 可能一个都没有。只按栈头写死族名会把
+//! 「实际使用哪个族、哪一档字重」变成猜测——本 mission 的开发机就是 Windows Server 2025，
+//! 实测就回退到了经典 `Segoe UI`（见交接文档的启动日志）。
+
+//! ## 不做什么
+//!
+//! **中文字体 CDN 下载不在这里**（后续 mission）。本模块只做「系统字体优先」这一半，
+//! 也没有能力判断 CJK 字形覆盖（那是 `ttf-parser` 查 cmap 的活，M60 Q3 的 spike 做过）。
+
+use unlucky_design::typography::{FontFamily, Platform, Weight, WeightMatch};
+
+use crate::theme::Families;
+
+/// 一条栈的求值结果。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct FamilyReport {
+    /// 栈的用途（`text` / `display` / `mono`）。
+    pub stack: &'static str,
+    /// 实际选中的族名（栈里第一个装机可用的；都没装就是栈头）。
+    pub family: &'static str,
+    /// 选中的族是否真的在系统字体库里。
+    pub installed: bool,
+}
+
+/// 一档字重的求值结果。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct WeightReport {
+    /// 请求的字重（400/500/700）。
+    pub requested: u16,
+    /// 实际可用的字重（降级后）。
+    pub available: u16,
+    /// 匹配质量（原生 / 最近档 / 合成加粗）。
+    pub quality: WeightMatch,
+}
+
+/// 字体求值的全部结论（启动日志与测试都用它）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Resolved {
+    /// 平台（决定栈与字重覆盖表）。
+    pub platform: Platform,
+    /// 三条栈的落点。
+    pub families: [FamilyReport; 3],
+    /// 三档字重的落点（对**正文**栈求值）。
+    pub weights: [WeightReport; 3],
+}
+
+impl Resolved {
+    /// 把结论塞回主题适配层要的形状。
+    pub fn families(&self) -> Families {
+        Families {
+            text: self.families[0].family,
+            display: self.families[1].family,
+            mono: self.families[2].family,
+        }
+    }
+
+    /// 是否有任何一档走了「合成加粗」（= 观感降级，要记日志）。
+    pub fn has_synthetic(&self) -> bool {
+        self.weights
+            .iter()
+            .any(|weight| weight.quality == WeightMatch::Synthetic)
+    }
+
+    /// 启动日志（两行：一行族，一行字重）。
+    pub fn describe(&self) -> String {
+        let families = self
+            .families
+            .iter()
+            .map(|report| {
+                format!(
+                    "{}={:?}{}",
+                    report.stack,
+                    report.family,
+                    if report.installed {
+                        ""
+                    } else {
+                        "(未装机→回落)"
+                    }
+                )
+            })
+            .collect::<Vec<_>>()
+            .join(" ");
+
+        let weights = self
+            .weights
+            .iter()
+            .map(|report| {
+                let quality = match report.quality {
+                    WeightMatch::Native => "native",
+                    WeightMatch::Nearest => "nearest",
+                    WeightMatch::Synthetic => "synthetic",
+                };
+                format!("w{}={}({quality})", report.requested, report.available)
+            })
+            .collect::<Vec<_>>()
+            .join(" ");
+
+        format!(
+            "[font] platform={} {families} | weights {weights}",
+            self.platform.name()
+        )
+    }
+}
+
+/// 求值本机字体（会触发 iced 全局字体系统的首次初始化，约 0.1~0.8s）。
+pub fn resolve() -> Resolved {
+    let platform = Platform::current();
+    let faces = system_faces();
+
+    let is_installed = |family: &str| -> bool {
+        faces
+            .as_ref()
+            .is_none_or(|faces: &Vec<Face>| faces.iter().any(|face| face.family == family))
+    };
+
+    let families = [
+        FamilyReport {
+            stack: "text",
+            family: pick(platform, FontFamily::Text, &is_installed),
+            installed: is_installed(pick(platform, FontFamily::Text, &is_installed)),
+        },
+        FamilyReport {
+            stack: "display",
+            family: pick(platform, FontFamily::Display, &is_installed),
+            installed: is_installed(pick(platform, FontFamily::Display, &is_installed)),
+        },
+        FamilyReport {
+            stack: "mono",
+            family: pick(platform, FontFamily::Mono, &is_installed),
+            installed: is_installed(pick(platform, FontFamily::Mono, &is_installed)),
+        },
+    ];
+
+    // 字重：**优先用系统里这个族真实提供的档位**（令牌表的 `WeightCoverage` 是「这个族通常有哪几档」，
+    // 装机版可能是静态子集：Win Server / 精简版只有经典 Segoe UI，没有 500）。查不到才回落到令牌纯函数。
+    let weights = [Weight::Regular, Weight::Medium, Weight::Bold]
+        .map(|weight| weight_report(platform, families[0].family, weight, faces.as_deref()));
+
+    Resolved {
+        platform,
+        families,
+        weights,
+    }
+}
+
+/// 一条系统字面（族名 + 字重）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Face {
+    family: String,
+    weight: u16,
+}
+
+/// 某档字重的落点：先问系统，再问令牌。
+fn weight_report(
+    platform: Platform,
+    family: &str,
+    weight: Weight,
+    faces: Option<&[Face]>,
+) -> WeightReport {
+    let requested = weight.value();
+
+    let available = faces.and_then(|faces| {
+        let mut weights = faces
+            .iter()
+            .filter(|face| face.family == family)
+            .map(|face| face.weight)
+            .collect::<Vec<_>>();
+        weights.sort_unstable();
+        weights.dedup();
+        if weights.is_empty() {
+            return None;
+        }
+
+        Some(
+            weights
+                .iter()
+                .copied()
+                .min_by_key(|candidate| candidate.abs_diff(requested))
+                .unwrap_or(requested),
+        )
+    });
+
+    match available {
+        Some(available) => WeightReport {
+            requested,
+            available,
+            quality: quality_of(requested, available),
+        },
+        None => {
+            let choice = platform.resolve_weight(FontFamily::Text, weight);
+            WeightReport {
+                requested: choice.requested,
+                available: choice.available,
+                quality: choice.quality,
+            }
+        }
+    }
+}
+
+/// 与令牌层同一判据：原生 / 最近档（差 <200）/ 合成加粗（差 ≥200）。
+fn quality_of(requested: u16, available: u16) -> WeightMatch {
+    match available.abs_diff(requested) {
+        0 => WeightMatch::Native,
+        delta if delta >= 200 => WeightMatch::Synthetic,
+        _ => WeightMatch::Nearest,
+    }
+}
+
+/// 在栈里选第一个**装机可用**的族（跳过 `sans-serif` 这类通用族名）。
+///
+/// 一个都没装上时返回栈头：让 cosmic-text 自己去回退，比我们猜一个更靠谱。
+pub fn pick(
+    platform: Platform,
+    stack: FontFamily,
+    is_installed: &dyn Fn(&str) -> bool,
+) -> &'static str {
+    let faces = platform.font_stack(stack);
+
+    faces
+        .iter()
+        .find(|face| !is_generic(face.family) && is_installed(face.family))
+        .map_or(faces[0].family, |face| face.family)
+}
+
+/// 通用族名（CSS 关键字，不是真族名）。
+fn is_generic(family: &str) -> bool {
+    matches!(family, "sans-serif" | "serif" | "monospace" | "cursive")
+}
+
+/// 系统字体库里的全部字面（`None` = 拿不到，视为「不知道」，全部当装机）。
+fn system_faces() -> Option<Vec<Face>> {
+    let lock = iced::advanced::graphics::text::font_system();
+    let mut font_system = lock.write().ok()?;
+
+    let mut faces = Vec::new();
+    for face in font_system.raw().db().faces() {
+        for (family, _) in &face.families {
+            faces.push(Face {
+                family: family.clone(),
+                weight: face.weight.0,
+            });
+        }
+    }
+
+    Some(faces)
+}
+
+#[cfg(test)]
+mod tests;

crates/app-iced/src/fonts/tests.rs

@@ -0,0 +1,163 @@
+//! `fonts` 的单元测试（拆出来只为「src 文件 ≤400 行」的门禁）。
+
+use super::*;
+use unlucky_design::typography::WeightCoverage;
+
+fn only(installed: &'static [&'static str]) -> impl Fn(&str) -> bool {
+    move |family| installed.contains(&family)
+}
+
+#[test]
+fn windows_stack_falls_back_to_classic_segoe_when_variable_is_absent() {
+    // Win10 没有 Segoe UI Variable Text
+    let family = pick(
+        Platform::Windows,
+        FontFamily::Text,
+        &only(&["Segoe UI", "Microsoft YaHei UI"]),
+    );
+    assert_eq!(family, "Segoe UI");
+}
+
+#[test]
+fn windows_stack_prefers_the_variable_face_on_win11() {
+    let family = pick(
+        Platform::Windows,
+        FontFamily::Text,
+        &only(&["Segoe UI Variable Text", "Segoe UI"]),
+    );
+    assert_eq!(family, "Segoe UI Variable Text");
+}
+
+#[test]
+fn generic_family_names_are_never_reported_as_the_resolved_family() {
+    // 一个都没装：返回栈头，且栈头不是通用族名
+    let family = pick(Platform::Linux, FontFamily::Text, &only(&[]));
+    assert_eq!(family, "Roboto");
+    assert!(!is_generic(family));
+}
+
+#[test]
+fn missing_cjk_fonts_do_not_change_the_latin_pick() {
+    // 装了苹方但没装 SF：macOS 栈应该选 Helvetica Neue 而不是中文族
+    let family = pick(
+        Platform::MacOs,
+        FontFamily::Text,
+        &only(&["PingFang SC", "Helvetica Neue"]),
+    );
+    assert_eq!(family, "Helvetica Neue");
+}
+
+#[test]
+fn weight_reports_use_the_token_degradation_path() {
+    // 没有系统字面表时回落到令牌纯函数：Windows 栈里 Segoe UI Variable Text 是可变 300..700
+    let medium = weight_report(
+        Platform::Windows,
+        "Segoe UI Variable Text",
+        Weight::Medium,
+        None,
+    );
+    assert_eq!(medium.requested, 500);
+    assert_eq!(medium.quality, WeightMatch::Native);
+
+    // 手工构造一个「只有 400/700」的族（= 经典 Segoe UI），500 应该落到最近档
+    let faces = [
+        Face {
+            family: "Segoe UI".to_owned(),
+            weight: 400,
+        },
+        Face {
+            family: "Segoe UI".to_owned(),
+            weight: 700,
+        },
+    ];
+    let medium = weight_report(Platform::Windows, "Segoe UI", Weight::Medium, Some(&faces));
+    assert_eq!(medium.available, 400, "400 比 700 更近");
+    assert_eq!(medium.quality, WeightMatch::Nearest);
+
+    // 只有 400 却要 700 → 合成加粗
+    let only_regular = [Face {
+        family: "Narrow".to_owned(),
+        weight: 400,
+    }];
+    let bold = weight_report(
+        Platform::Windows,
+        "Narrow",
+        Weight::Bold,
+        Some(&only_regular),
+    );
+    assert_eq!(bold.quality, WeightMatch::Synthetic);
+
+    // 原生有 500 就用 500
+    let has_medium = [Face {
+        family: "Noto".to_owned(),
+        weight: 500,
+    }];
+    assert_eq!(
+        weight_report(Platform::Linux, "Noto", Weight::Medium, Some(&has_medium)).quality,
+        WeightMatch::Native
+    );
+
+    let narrow = WeightCoverage::Static(&[400]);
+    assert_eq!(narrow.nearest(700), 400);
+}
+
+#[test]
+fn describe_is_one_line_and_mentions_all_three_stacks() {
+    let resolved = Resolved {
+        platform: Platform::Windows,
+        families: [
+            FamilyReport {
+                stack: "text",
+                family: "Segoe UI",
+                installed: true,
+            },
+            FamilyReport {
+                stack: "display",
+                family: "Segoe UI Variable Display",
+                installed: false,
+            },
+            FamilyReport {
+                stack: "mono",
+                family: "Cascadia Mono",
+                installed: true,
+            },
+        ],
+        weights: [
+            WeightReport {
+                requested: 400,
+                available: 400,
+                quality: WeightMatch::Native,
+            },
+            WeightReport {
+                requested: 500,
+                available: 400,
+                quality: WeightMatch::Nearest,
+            },
+            WeightReport {
+                requested: 700,
+                available: 400,
+                quality: WeightMatch::Synthetic,
+            },
+        ],
+    };
+
+    let line = resolved.describe();
+    assert_eq!(line.lines().count(), 1);
+    assert!(line.contains("text=\"Segoe UI\""), "{line}");
+    assert!(line.contains("未装机"), "{line}");
+    assert!(line.contains("w700=400(synthetic)"), "{line}");
+    assert!(resolved.has_synthetic());
+    assert_eq!(resolved.families().text, "Segoe UI");
+}
+
+#[test]
+fn type_roles_pick_the_display_stack_for_big_text() {
+    use unlucky_design::typography::TypeRole;
+
+    assert_eq!(
+        TypeRole::TitleLarge.style().family,
+        FontFamily::Display,
+        "22px 标题走 Display 栈"
+    );
+    assert_eq!(TypeRole::BodyMedium.style().family, FontFamily::Text);
+}

crates/app-iced/src/icons.rs

@@ -0,0 +1,126 @@
+//! 令牌图标（`unlucky_design::icons` 的 24 网格 SVG path）→ iced `svg` 控件。
+//!
+//! ## 为什么走 SVG 而不是自绘 canvas
+//!
+//! 令牌里存的是 **SVG path 字符串**（含 `A` 弧线命令），自绘要自己写 path parser + 弧线细分，
+//! 那是一份将来只有自己在维护的代码；iced 的 `svg` 控件已经带 usvg 解析与按 id 缓存的位图。
+//! 代价是二进制多一份 resvg/usvg（体积基线里会单列出来）。
+//!
+//! ## 描边语义（`design-令牌约定.md` §4）
+//!
+//! 令牌的 `Icon::stroke_width(render_px)` 已经把「视觉 1.5px」折算成 **viewBox 单位**
+//! （`1.5 × 24 / render_px`），本模块**不重算也不手抄常数**。
+//! 本骨架所有图标都按 24px 渲染（12b 2.2 标题栏 / 5.5 导航），所以每个图标只有一份位图缓存。
+
+use std::sync::OnceLock;
+
+use iced::widget::svg;
+use iced::Color;
+
+use unlucky_design::icons::{IconKind, IconPaint, IconSize};
+
+/// 骨架期图标的统一渲染尺寸（12b：标题栏与导航轨都是 24）。
+pub const RENDER_PX: f32 = IconSize::Toolbar.px();
+
+/// 生成一个图标的 SVG 源码（`viewBox` 24×24，颜色用 `currentColor` 交给 iced 的色滤镜）。
+///
+/// 之所以用 `currentColor` 而不是把令牌色写进 SVG：色滤镜（`svg::Style::color`）会按
+/// **alpha 蒙版**重涂 RGB，这样一份 SVG 位图能被浅/深两套主题复用，缓存不会翻倍。
+pub fn source(kind: IconKind) -> String {
+    let icon = kind.icon();
+    let paint = match icon.paint {
+        IconPaint::Stroke => format!(
+            "fill=\"none\" stroke=\"currentColor\" stroke-width=\"{}\" \
+             stroke-linecap=\"round\" stroke-linejoin=\"round\"",
+            icon.stroke_width(RENDER_PX)
+        ),
+        IconPaint::Fill => "fill=\"currentColor\" stroke=\"none\"".to_owned(),
+    };
+
+    format!(
+        "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"{0}\" height=\"{0}\" \
+         viewBox=\"0 0 24 24\"><path d=\"{1}\" {paint}/></svg>",
+        RENDER_PX, icon.path
+    )
+}
+
+/// 图标的 SVG 句柄（按 `IconKind` 缓存；句柄 id 是内容哈希，所以 iced 侧也能命中缓存）。
+fn handle(kind: IconKind) -> svg::Handle {
+    static HANDLES: OnceLock<Vec<svg::Handle>> = OnceLock::new();
+
+    let handles = HANDLES.get_or_init(|| {
+        IconKind::ALL
+            .iter()
+            .map(|kind| svg::Handle::from_memory(source(*kind).into_bytes()))
+            .collect()
+    });
+
+    // 依赖「枚举下标 == IconKind::ALL 下标」（令牌层用 `GLYPHS[self as usize]` 同一约定）。
+    // 这条断言把约定钉在测试与 debug 构建里，`IconKind` 一旦乱序插入就会立刻炸。
+    debug_assert_eq!(
+        IconKind::ALL[kind as usize],
+        kind,
+        "IconKind::ALL 必须与枚举声明顺序一致"
+    );
+
+    handles[kind as usize].clone()
+}
+
+/// 一个图标控件（尺寸走令牌，颜色走令牌角色）。
+pub fn view<'a, Message: 'a>(kind: IconKind, color: Color) -> iced::Element<'a, Message> {
+    svg(handle(kind))
+        .width(RENDER_PX)
+        .height(RENDER_PX)
+        .style(move |_theme, _status| svg::Style { color: Some(color) })
+        .into()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn every_icon_produces_wellformed_svg() {
+        for kind in IconKind::ALL {
+            let source = source(kind);
+            assert!(source.starts_with("<svg"), "{} 的 SVG 头不对", kind.name());
+            assert!(source.ends_with("</svg>"), "{} 的 SVG 尾不对", kind.name());
+            assert!(source.contains("viewBox=\"0 0 24 24\""), "{}", kind.name());
+            assert!(
+                source.contains(kind.icon().path),
+                "{} 的 path 没写进去",
+                kind.name()
+            );
+            assert!(!source.contains('#'), "{} 里出现了色值字面量", kind.name());
+        }
+    }
+
+    #[test]
+    fn stroke_icons_carry_the_token_stroke_width() {
+        let stroke = source(IconKind::Settings);
+        let expected = IconKind::Settings.icon().stroke_width(RENDER_PX);
+        assert!(
+            stroke.contains(&format!("stroke-width=\"{expected}\"")),
+            "{stroke}"
+        );
+        assert!(stroke.contains("stroke-linecap=\"round\""));
+        // 24px 渲染时的视觉线宽必须是 1.5（M54 结论）
+        assert!((expected - 1.5).abs() < f32::EPSILON);
+    }
+
+    #[test]
+    fn filled_icons_do_not_get_a_stroke() {
+        // `more` 是三个填充圆点
+        let filled = source(IconKind::More);
+        assert!(filled.contains("fill=\"currentColor\""));
+        assert!(filled.contains("stroke=\"none\""));
+    }
+
+    #[test]
+    fn handles_are_cached_per_kind() {
+        let first = handle(IconKind::Close);
+        let second = handle(IconKind::Close);
+        assert_eq!(first.id(), second.id());
+        assert_ne!(first.id(), handle(IconKind::Minimize).id());
+    }
+}

crates/app-iced/src/lib.rs

@@ -0,0 +1,55 @@
+//! # unlucky-app-iced · iced 版桌面壳（P4 / D26）
+//!
+//! 本 crate 是「UI 从头写」的第一步：**只做骨架**（能开窗、颜色/字体对、层级在），
+//! 业务页面、组件库、i18n 全文案、玻璃 shader 都是后续 mission。
+//!
+//! | 模块 | 职责 | 不负责 |
+//! |---|---|---|
+//! | [`theme`] | 令牌（`unlucky-design`）→ iced 类型：`Color` / `Font` / `Radius` / `Theme` | 发明令牌值 |
+//! | `cli` | `--renderer` / `--software-renderer` / `--theme` / `--screenshot*` 参数 | 业务开关 |
+//! | `probe` | 渲染后端探测（D27）+ 写 `ICED_BACKEND`，失败自动降级 CPU | 绘制 |
+//! | `fonts` | 字体栈求值（D28 前半）：平台族名 → 系统字体库校验 → 启动日志 | 中文字体下载 |
+//! | `app` / `shell` | Elm 三件套 + 自绘标题栏 / 导航轨 / 内容骨架 | 业务逻辑 |
+//! | `shot` | `window::screenshot` → PNG（验收通道） | 图像比对 |
+//! | `icons` | 令牌里的 SVG path → iced `svg` 控件 | 画新图标 |
+//!
+//! ## 消费纪律
+//!
+//! **组件层零硬编码色值/字号/半径/间距**：一律走 [`theme::Ui`]。守门测试在
+//! `tests/no_hardcoded_tokens.rs`（扫 `src/**`，出现 `#RRGGBB` / `Color::from_rgb(` 即红）。
+//!
+//! ## 与 Slint 版的关系
+//!
+//! 并存期：`crates/app` 仍出 `unlucky-launcher`，本 crate 出 `unlucky-launcher-iced`。
+//! 等价验收后翻牌（bin 改名 + 旧 crate 降级），步骤写在
+//! `DevDocs/SubAgentsTalk/app-iced-骨架与翻牌.md`。
+
+pub mod shot;
+pub mod theme;
+
+mod app;
+mod cli;
+mod fonts;
+mod icons;
+mod probe;
+mod shell;
+
+pub use cli::{Backend, Options};
+pub use probe::Probe;
+
+/// 启动 UI（阻塞到窗口关闭）。渲染后端由 `probe` 在 `run()` 之前写进 `ICED_BACKEND`。
+pub fn run(options: Options) -> iced::Result {
+    app::run(options)
+}
+
+/// 与 [`run`] 同义，但把命令行做成最终结论：`Options::from_env()` + 启动日志。
+///
+/// 二进制入口用 [`Options::from_env`] + [`run`] 自己拼（要额外处理 `--diff`），这个函数留给
+/// 集成测试与将来的 CLI 复用。
+///
+/// # Errors
+/// 参数不合法时返回人话（不 panic、不 `exit`）。
+pub fn run_from_env() -> Result<iced::Result, String> {
+    let options = Options::from_env()?;
+    Ok(run(options))
+}

crates/app-iced/src/main.rs

@@ -0,0 +1,52 @@
+//! 入口。所有实际逻辑在 lib（`unlucky_app_iced`）里：
+//!
+//! - `--diff <a> <b>`：只读两张 PNG 做逐像素对比（D30 的 GPU/CPU 几何一致性检查），不开窗；
+//! - 其余参数：开窗跑骨架，`--screenshot` 出图后退出。
+//!
+//! 退出码：`0` 成功 / `1` 截图有差异（diff 模式）/ `2` 参数或运行错误。
+
+use std::process::ExitCode;
+
+use unlucky_app_iced::shot;
+use unlucky_app_iced::Options;
+
+fn main() -> ExitCode {
+    let options = match Options::from_env() {
+        Ok(options) => options,
+        Err(message) => {
+            eprintln!("[cli] {message}");
+            eprintln!(
+                "用法：unlucky-launcher-iced [--renderer=auto|gpu|cpu] [--software-renderer] \
+                 [--theme=light|dark] [--screenshot <png>] [--screenshot-theme=light|dark] \
+                 [--scale-factor <f32>] [--diff <a.png> <b.png>]"
+            );
+            return ExitCode::from(2);
+        }
+    };
+
+    if let Some((left, right)) = options.diff.clone() {
+        let scan = i32::try_from(options.diff_scan).unwrap_or(i32::MAX);
+        return match shot::diff_files_with_scan(&left, &right, scan) {
+            Ok(diff) => {
+                eprintln!("{}", diff.describe());
+                if diff.is_identical() {
+                    ExitCode::SUCCESS
+                } else {
+                    ExitCode::from(1)
+                }
+            }
+            Err(message) => {
+                eprintln!("[diff] {message}");
+                ExitCode::from(2)
+            }
+        };
+    }
+
+    match unlucky_app_iced::run(options) {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(error) => {
+            eprintln!("[run] {error}");
+            ExitCode::FAILURE
+        }
+    }
+}

crates/app-iced/src/probe.rs

@@ -0,0 +1,238 @@
+//! 渲染后端探测 + 自动降级（D27）。
+//!
+//! ## 为什么需要探测
+//!
+//! iced 0.14 的 `Renderer` 本身就是「wgpu → tiny-skia」的运行时回退枚举（M60 Q1）：
+//! **不设** `ICED_BACKEND` 时，拿不到 GPU 适配器会自动降级到 CPU，零代码。
+//! 需要自研的只有**判据**：
+//!
+//! - 本机会枚举出 `Microsoft Basic Render Driver [Cpu]`（= WARP 软光栅），
+//!   所以「有没有适配器」不能当「有没有 GPU」（M60 实测），必须看 `device_type`。
+//! - 没有硬件 GPU 时要**主动**把 CPU 放到候选首位（`tiny-skia,wgpu`），
+//!   否则 wgpu 会先花时间尝试 WARP，观感与行为都难料。
+//!
+//! ## 语义订正（与 M60 备忘录的差异，以源码 + 实测为准）
+//!
+//! M60 记「`ICED_BACKEND=wgpu` 会**关闭**回退」。读 `iced_renderer-0.14.0/src/fallback.rs`
+//! 得到的是：**候选列表**语义——列表里没有 `tiny-skia` 时才真的关闭回退。
+//! 所以本 crate 的「优先 GPU」写 `wgpu,tiny-skia`（首选 GPU，拿不到仍降级，**绝不硬失败**），
+//! 而不是 `wgpu`。
+
+use crate::Backend;
+
+/// 单个适配器的摘要（只留日志要用的字段）。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AdapterSummary {
+    /// 适配器名（如 `AMD Radeon RX 6600 XT`）。
+    pub name: String,
+    /// `device_type` 的字符串形式（`DiscreteGpu` / `IntegratedGpu` / `Cpu` / …）。
+    pub device_type: &'static str,
+}
+
+/// 探测结论。
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Probe {
+    /// 枚举到的全部适配器（含 WARP 这类软光栅）。
+    pub adapters: Vec<AdapterSummary>,
+    /// 是否存在**真**硬件适配器（`device_type` 既不是 `Cpu` 也不是 `Other`）。
+    pub hardware: bool,
+}
+
+impl Probe {
+    /// 探测本机渲染能力（编入 `wgpu` 时真的枚举适配器）。
+    #[cfg(feature = "gpu")]
+    pub fn run() -> Self {
+        run_wgpu()
+    }
+
+    /// 探测本机渲染能力（`--no-default-features` 的纯 CPU 构建：没有 wgpu，直接判定无硬件）。
+    #[cfg(not(feature = "gpu"))]
+    pub fn run() -> Self {
+        Self::default()
+    }
+
+    /// 一行日志：适配器清单 + 判定。
+    pub fn describe(&self) -> String {
+        if self.adapters.is_empty() {
+            return format!("adapters=0 hardware={}", self.hardware);
+        }
+
+        let list = self
+            .adapters
+            .iter()
+            .map(|adapter| format!("{} [{}]", adapter.name, adapter.device_type))
+            .collect::<Vec<_>>()
+            .join(" | ");
+
+        format!(
+            "adapters={} [{list}] hardware={}",
+            self.adapters.len(),
+            self.hardware
+        )
+    }
+}
+
+/// 按请求与探测结果决定 `ICED_BACKEND` 的值（`None` = 不干预，交给 iced 自己回退）。
+///
+/// 纯函数，好让「降级矩阵」被测试钉死。
+pub fn backend_env(request: Backend, probe: &Probe, gpu_compiled: bool) -> Option<&'static str> {
+    match (request, gpu_compiled) {
+        // 命令行 --software-renderer / --renderer=cpu：只留 CPU 候选。
+        (Backend::Cpu, _) => Some("tiny-skia"),
+        // 用户点名要 GPU，但没编进 wgpu：只能 CPU，日志里说明。
+        (Backend::Gpu, false) => Some("tiny-skia"),
+        // 优先 GPU，但保留 tiny-skia 兜底（候选列表语义：不会硬失败）。
+        (Backend::Gpu, true) => Some("wgpu,tiny-skia"),
+        // 自动：有硬件就让 iced 走默认顺序（wgpu 优先，自动回退）。
+        (Backend::Auto, true) if probe.hardware => None,
+        // 自动 + 没编进 wgpu：只有 CPU 候选，别把 wgpu 写进列表（会与「未编入 wgpu」的日志自相矛盾）。
+        (Backend::Auto, false) => Some("tiny-skia"),
+        // 自动 + 有 wgpu 但没硬件（含只有 WARP 的机器）：CPU 起步，wgpu 留作兜底。
+        (Backend::Auto, true) => Some("tiny-skia,wgpu"),
+    }
+}
+
+/// 把决策落到进程环境变量，并把探测结果 + 生效值打进日志。
+///
+/// 返回**实际生效**的后端描述（`"auto (iced: wgpu -> tiny-skia)"` 之类）。
+pub fn apply(request: Backend, probe: &Probe) -> String {
+    let gpu_compiled = cfg!(feature = "gpu");
+    let env = backend_env(request, probe, gpu_compiled);
+
+    // ICED_BACKEND 是进程级环境变量，必须在 `iced::application(..).run()` 之前写。
+    // 仓库是 edition 2021 → `set_var` 仍是安全 API（升 2024 后要改成子进程 exec 自身）。
+    if let Some(value) = env {
+        std::env::set_var("ICED_BACKEND", value);
+    }
+
+    let effective = if gpu_compiled {
+        match (request, env) {
+            (Backend::Cpu, _) => "tiny-skia (CPU，强制)".to_owned(),
+            (_, None) => "auto (wgpu -> tiny-skia)".to_owned(),
+            (_, Some("wgpu,tiny-skia")) => "wgpu.then(tiny-skia) (优先 GPU)".to_owned(),
+            (_, Some(value)) => format!("{value} (CPU 起步)"),
+        }
+    } else {
+        "tiny-skia (本构建未编入 wgpu，只有 CPU)".to_owned()
+    };
+
+    let note = if !gpu_compiled && request != Backend::Cpu {
+        "；本构建未编入 wgpu（--no-default-features），只能 CPU"
+    } else {
+        ""
+    };
+
+    eprintln!(
+        "[probe] {} :: request={} -> ICED_BACKEND={}{note}",
+        probe.describe(),
+        request.name(),
+        env.unwrap_or("<unset>")
+    );
+    eprintln!("[probe] renderer = {effective}");
+
+    effective
+}
+
+#[cfg(feature = "gpu")]
+fn run_wgpu() -> Probe {
+    // `iced::wgpu` 就是 wgpu crate 本身（`pub use iced_renderer::wgpu::wgpu` 再导出），
+    // 所以不需要单独依赖 wgpu，版本也不会和 iced 打架。
+    use iced::wgpu::{Backends, DeviceType, Instance, InstanceDescriptor};
+
+    let instance = Instance::new(&InstanceDescriptor {
+        backends: Backends::all(),
+        ..Default::default()
+    });
+
+    let adapters = instance
+        .enumerate_adapters(Backends::all())
+        .into_iter()
+        .map(|adapter| {
+            let info = adapter.get_info();
+            let device_type = match info.device_type {
+                DeviceType::DiscreteGpu => "DiscreteGpu",
+                DeviceType::IntegratedGpu => "IntegratedGpu",
+                DeviceType::VirtualGpu => "VirtualGpu",
+                DeviceType::Cpu => "Cpu",
+                DeviceType::Other => "Other",
+            };
+            AdapterSummary {
+                name: info.name,
+                device_type,
+            }
+        })
+        .collect::<Vec<_>>();
+
+    let hardware = adapters
+        .iter()
+        .any(|adapter| !matches!(adapter.device_type, "Cpu" | "Other"));
+
+    Probe { adapters, hardware }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn probe(types: &[&'static str]) -> Probe {
+        let adapters = types
+            .iter()
+            .map(|device_type| AdapterSummary {
+                name: "adapter".to_owned(),
+                device_type,
+            })
+            .collect::<Vec<_>>();
+        Probe {
+            adapters,
+            hardware: types
+                .iter()
+                .any(|device_type| !matches!(*device_type, "Cpu" | "Other")),
+        }
+    }
+
+    #[test]
+    fn warp_only_machine_counts_as_no_gpu() {
+        // 本机实测会枚举出 WARP：`Microsoft Basic Render Driver [Cpu]`
+        let warp = probe(&["Cpu"]);
+        assert!(!warp.hardware, "只有 WARP 不能当「有 GPU」");
+        assert_eq!(
+            backend_env(Backend::Auto, &warp, true),
+            Some("tiny-skia,wgpu")
+        );
+    }
+
+    #[test]
+    fn auto_with_real_gpu_leaves_iced_alone() {
+        let gpu = probe(&["DiscreteGpu", "Cpu"]);
+        assert!(gpu.hardware);
+        assert_eq!(backend_env(Backend::Auto, &gpu, true), None);
+    }
+
+    #[test]
+    fn explicit_choices_always_keep_a_fallback() {
+        let gpu = probe(&["DiscreteGpu"]);
+        let none = probe(&[]);
+        // 优先 GPU 但候选列表里留 tiny-skia：拿不到适配器时降级而不是报错
+        assert_eq!(
+            backend_env(Backend::Gpu, &gpu, true),
+            Some("wgpu,tiny-skia")
+        );
+        assert_eq!(
+            backend_env(Backend::Gpu, &none, true),
+            Some("wgpu,tiny-skia")
+        );
+        assert_eq!(backend_env(Backend::Cpu, &gpu, true), Some("tiny-skia"));
+        // 没编进 wgpu 的构建绝不写 wgpu（连候选列表也不许出现，reviewer P3-4）
+        assert_eq!(backend_env(Backend::Gpu, &gpu, false), Some("tiny-skia"));
+        assert_eq!(backend_env(Backend::Auto, &gpu, false), Some("tiny-skia"));
+        assert_eq!(backend_env(Backend::Auto, &none, false), Some("tiny-skia"));
+    }
+
+    #[test]
+    fn describe_lists_every_adapter() {
+        let text = probe(&["DiscreteGpu", "Cpu"]).describe();
+        assert!(text.contains("DiscreteGpu"), "{text}");
+        assert!(text.contains("Cpu"), "{text}");
+        assert!(text.contains("hardware=true"), "{text}");
+    }
+}

crates/app-iced/src/shell/mod.rs

@@ -0,0 +1,349 @@
+//! 首屏骨架（**不做业务**）：自绘标题栏 + 左侧导航轨 + 内容区（页头 + 一张卡片）。
+//!
+//! ## 与参考判据的对应（`research/12b-component-fidelity.md`）
+//!
+//! | 部件 | 参考 | 令牌落点 |
+//! |---|---|---|
+//! | 标题栏高度 | 16.2 桌面标题栏 **40**（登记偏离） | `LM.titlebar_height = 48`（M63 §1.4/R13 桌面档，令牌优先） |
+//! | 标题栏按钮 | 16.5 图标 **24** | `IconSize::Toolbar` + `LM.titlebar_button_width = 46` |
+//! | 页头 | 16.1 官方 AppBar **64**；本项目 **56** | `LM.page_header_height = 56`（已有偏离登记） |
+//! | 卡片 | 3.x Outlined：**Medium(12)**、L0、`OutlineVariant` 1px、`SurfaceContainerLow` | `Component::OutlinedCard.spec()` + `STROKE_PX` |
+//! | 字级 | 16.4 标题 `TitleLarge`；卡片 `TitleMedium` / `BodySmall` | `Ui::style` / `Ui::emphasized` |
+//!
+//! 导航轨在 [`nav`] 子模块里（12b §5 的判据表也在那边）。
+//!
+//! 一屏只出现 4 档字号（22 / 16 / 14 / 12），且**没有实心 accent**（rubric K2：一屏最多一个实心
+//! Primary，骨架期一个都不要）。阴影只给浮层，骨架里没有浮层，所以**全屏零阴影**（rubric K3）。
+
+mod nav;
+
+pub use nav::NavItem;
+
+use iced::widget::text::LineHeight;
+use iced::widget::{button, column, container, mouse_area, row, space, stack, text};
+use iced::{mouse, Alignment, Background, Border, Color, Element, Length, Padding, Pixels, Shadow};
+use iced::{window::Direction, Theme as IcedTheme};
+
+use unlucky_design::color::{Role, StateLayer};
+use unlucky_design::component_map::Component;
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::IconKind;
+use unlucky_design::spacing::Space;
+use unlucky_design::typography::TypeRole;
+
+use crate::app::Message;
+use crate::cli::ForcedState;
+use crate::icons;
+use crate::theme::Ui;
+
+/// 整棵树。
+pub fn view<'a>(
+    ui: &'a Ui,
+    selected: NavItem,
+    app_title: &'a str,
+    page_title: &'a str,
+    body: &'a str,
+    forced: Option<ForcedState>,
+) -> Element<'a, Message> {
+    let work_area = column![
+        titlebar(ui, app_title, forced),
+        row![
+            nav::rail(ui, selected, forced),
+            content(ui, page_title, body)
+        ]
+        .width(Length::Fill)
+        .height(Length::Fill),
+    ]
+    .width(Length::Fill)
+    .height(Length::Fill);
+
+    // 无边框窗口没有系统缩放边框 → 自己给两条热区（东/南）。
+    // **必须叠层而不是兄弟列**：当兄弟列会吃掉 4px 布局宽（右留白变 28、caption 按钮离窗角 4px，
+    // 视觉复审 P3-1）。叠层容器自己铺满，再用 align 把 4px 热区贴到边上，布局宽保持 1180。
+    // 东侧热区从标题栏下方开始，避免吃掉三个 caption 按钮最右 4px 的点击区。
+    let thickness = ui.space(Space::X1);
+
+    let east = container(
+        column![
+            space::vertical().height(ui.metrics().titlebar_height),
+            resize_edge(
+                Direction::East,
+                (Length::Fixed(thickness), Length::Fill),
+                mouse::Interaction::ResizingHorizontally,
+            ),
+        ]
+        .height(Length::Fill),
+    )
+    .width(Length::Fill)
+    .height(Length::Fill)
+    .align_x(Alignment::End);
+
+    let south = container(resize_edge(
+        Direction::South,
+        (Length::Fill, Length::Fixed(thickness)),
+        mouse::Interaction::ResizingVertically,
+    ))
+    .width(Length::Fill)
+    .height(Length::Fill)
+    .align_y(Alignment::End);
+
+    let shell = stack![work_area, east, south];
+
+    container(shell)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .style(|_theme| filled(ui.layer(MaterialLayer::Canvas)))
+        .into()
+}
+
+/// 窗口缩放热区（透明；玻璃/底色由根容器提供）。
+///
+/// 拖动时调 `window::drag_resize(id, direction)`——Windows/X11 走 winit 原生实现，
+/// **macOS 返回 `NotSupported`**（M60 Q4），如实登记在交接文档里。
+fn resize_edge<'a>(
+    direction: Direction,
+    size: (Length, Length),
+    interaction: mouse::Interaction,
+) -> Element<'a, Message> {
+    let (width, height) = size;
+
+    mouse_area(container(space::horizontal()).width(width).height(height))
+        .interaction(interaction)
+        .on_press(Message::ResizeStart(direction))
+        .into()
+}
+
+// ---------------------------------------------------------------- 标题栏
+
+fn titlebar<'a>(ui: &'a Ui, title: &'a str, forced: Option<ForcedState>) -> Element<'a, Message> {
+    let metrics = ui.metrics();
+
+    // 拖动热区：从窗口左缘到第一个按钮（按钮自己不能被拖区吞掉，所以只包左侧一段）
+    let drag_area = mouse_area(
+        container(label(
+            ui,
+            TypeRole::LabelLarge,
+            true,
+            title,
+            ui.color(Role::OnSurface),
+        ))
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .align_y(Alignment::Center)
+        .padding(Padding::from([0.0, ui.space(Space::X4)])),
+    )
+    .on_press(Message::DragWindow);
+
+    let bar = row![
+        drag_area,
+        caption(ui, IconKind::Minimize, Message::Minimize, forced),
+        caption(ui, IconKind::Maximize, Message::ToggleMaximize, forced),
+        caption(ui, IconKind::Close, Message::Close, forced),
+    ]
+    .width(Length::Fill)
+    .height(metrics.titlebar_height)
+    .align_y(Alignment::Center);
+
+    container(bar)
+        .width(Length::Fill)
+        .height(metrics.titlebar_height)
+        .style(|_theme| filled(ui.layer(MaterialLayer::Canvas)))
+        .into()
+}
+
+/// 标题栏按钮（自绘最小化/最大化/关闭）。
+///
+/// 图标必须**再包一层固定 24×24 的容器**：iced 的 `button` 在 layout 里给内容 Fill 约束，
+/// 直接把 `svg(...).width(24)` 塞进 button，usvg 会按 Contain 撑满内区（实测渲染盒 46 → 视觉线宽
+/// 从 1.5 变 2.9，视觉复审 P2-2）。Container 尊重子元素的 Length，所以这层是「锁尺寸」用的。
+fn caption<'a>(
+    ui: &'a Ui,
+    kind: IconKind,
+    message: Message,
+    forced: Option<ForcedState>,
+) -> Element<'a, Message> {
+    let metrics = ui.metrics();
+    // 用 `center(Length::Fill)` 而不是只设 `width(24).height(24)`：后者会让容器缩到 24×24 并贴到
+    // button 内容的左上角（button 不居中「收缩后」的内容，r1 实测图标跑到 cell 左上 (left+11.5, 11.5)）；
+    // `center(Fill)` = 撑满按钮内容区 + 内容居中，字形仍是 24 盒、命中区仍是 46×48。
+    let icon = container(icons::view::<Message>(
+        kind,
+        ui.color(Role::OnSurfaceVariant),
+    ))
+    .width(icons::RENDER_PX)
+    .height(icons::RENDER_PX)
+    .center(Length::Fill);
+
+    button(icon)
+        .width(metrics.titlebar_button_width)
+        .height(metrics.titlebar_height)
+        .padding(0)
+        .style(move |_theme: &IcedTheme, status| {
+            let background = match overridden(forced, status) {
+                button::Status::Hovered => Some(Background::Color(ui.state_over(
+                    StateLayer::Hover,
+                    Role::OnSurface,
+                    Role::Surface,
+                ))),
+                button::Status::Pressed => Some(Background::Color(ui.state_over(
+                    StateLayer::Pressed,
+                    Role::OnSurface,
+                    Role::Surface,
+                ))),
+                button::Status::Active | button::Status::Disabled => None,
+            };
+
+            button::Style {
+                background,
+                text_color: ui.color(Role::OnSurfaceVariant),
+                border: Border::default(),
+                shadow: Shadow::default(),
+                snap: true,
+            }
+        })
+        .on_press(message)
+        .into()
+}
+
+// ---------------------------------------------------------------- 内容区
+
+fn content<'a>(ui: &'a Ui, title: &'a str, body: &'a str) -> Element<'a, Message> {
+    let metrics = ui.metrics();
+    // 卡片档位由组件表决定（圆角/字级），组件层不自己挑
+    let card_spec = Component::OutlinedCard.spec();
+    let body_role = card_spec.support.unwrap_or(card_spec.text);
+
+    let header = container(label(
+        ui,
+        TypeRole::TitleLarge,
+        true,
+        title,
+        ui.color(Role::OnSurface),
+    ))
+    .width(Length::Fill)
+    .height(metrics.page_header_height)
+    .align_y(Alignment::Center)
+    .padding(Padding::from([0.0, ui.space(Space::X6)]));
+
+    let card = container(
+        column![
+            label(
+                ui,
+                card_spec.text,
+                true,
+                "Shell ready",
+                ui.color(Role::OnSurface),
+            ),
+            label(ui, body_role, false, body, ui.color(Role::OnSurfaceVariant)),
+        ]
+        .spacing(ui.space(Space::X2)),
+    )
+    .width(Length::Fill)
+    .padding(metrics.card_padding)
+    .style(move |_theme| container::Style {
+        background: Some(Background::Color(ui.layer(MaterialLayer::Card))),
+        border: ui.outlined(card_spec.shape),
+        ..container::Style::default()
+    });
+
+    let body_area = container(card)
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .padding(ui.space(Space::X6))
+        .align_y(Alignment::Start);
+
+    column![header, body_area]
+        .width(Length::Fill)
+        .height(Length::Fill)
+        .into()
+}
+
+// ---------------------------------------------------------------- 小工具
+
+/// 一个文字元素：字号/行高/字重全部来自令牌排版档。
+pub(super) fn label<'a>(
+    ui: &'a Ui,
+    role: TypeRole,
+    emphasized: bool,
+    content: &'a str,
+    color: Color,
+) -> Element<'a, Message> {
+    let style = if emphasized {
+        ui.emphasized(role)
+    } else {
+        ui.style(role)
+    };
+
+    text(content)
+        .size(style.size_px)
+        .line_height(LineHeight::Absolute(Pixels(style.line_height_px)))
+        .font(ui.font_of(style))
+        .color(color)
+        .into()
+}
+
+/// 取证用的状态覆盖（`--force-state`）：只改画出来的状态，不动任何状态机。
+pub(super) fn overridden(forced: Option<ForcedState>, status: button::Status) -> button::Status {
+    match forced {
+        Some(ForcedState::Hover) => button::Status::Hovered,
+        Some(ForcedState::Pressed) => button::Status::Pressed,
+        None => status,
+    }
+}
+
+pub(super) fn filled(color: Color) -> container::Style {
+    container::Style {
+        background: Some(Background::Color(color)),
+        ..container::Style::default()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use unlucky_design::color::SchemeFlavor;
+    use unlucky_design::typography::Platform;
+
+    use crate::theme::Families;
+
+    fn ui(flavor: SchemeFlavor) -> Ui {
+        Ui::with_platform(
+            flavor,
+            Platform::Windows,
+            Families {
+                text: "Segoe UI",
+                display: "Segoe UI",
+                mono: "Consolas",
+            },
+        )
+    }
+
+    #[test]
+    fn a_screen_only_uses_four_text_sizes_at_most() {
+        let ui = ui(SchemeFlavor::Dark);
+        let card = Component::OutlinedCard.spec();
+        let sizes = [
+            ui.emphasized(TypeRole::TitleLarge).size_px,
+            ui.emphasized(TypeRole::LabelLarge).size_px,
+            ui.emphasized(card.text).size_px,
+            ui.style(card.support.unwrap_or(card.text)).size_px,
+            ui.style(TypeRole::LabelMedium).size_px,
+        ];
+        let mut unique = sizes.to_vec();
+        unique.sort_by(f32::total_cmp);
+        unique.dedup();
+        assert!(
+            unique.len() <= 4,
+            "rubric D4：一屏字号档 ≤4（实际 {} 档 {unique:?}）",
+            unique.len()
+        );
+        assert!(unique[0] >= 12.0, "最小档不下 12px（caption ≥11）");
+        assert!(unique[unique.len() - 1] <= 28.0, "列表页标题不得 >28px");
+    }
+
+    #[test]
+    fn flavor_slug_is_stable_for_filenames() {
+        assert_eq!(crate::shot::flavor_slug(&ui(SchemeFlavor::Light)), "light");
+        assert_eq!(crate::shot::flavor_slug(&ui(SchemeFlavor::Dark)), "dark");
+    }
+}

crates/app-iced/src/shell/nav.rs

@@ -0,0 +1,258 @@
+//! 左侧导航轨（M3 `NavigationRail`）。
+//!
+//! 判据来源 `research/12b-component-fidelity.md` §5：
+//!
+//! | 项 | 参考值 | 令牌落点 |
+//! |---|---|---|
+//! | 轨宽 | 5.1 官方 96（narrow 80）；本项目 **88** | [`nav_rail_width`]（`LayoutMetrics` 骨架值，详见该函数文档的 M69 迁移说明） |
+//! | 轨容器 | 5.3 形状 None / L0 / `Surface` | `MaterialLayer::Canvas` |
+//! | 选中指示器 | 5.4 **56×32**、圆角 full、`SecondaryContainer` | [`indicator_size`]（令牌推导） |
+//! | 图标 | 5.5 24px | `IconSize::Toolbar` |
+//! | 标签 | 5.5 `LabelMedium 12/16` | `TypeRole::LabelMedium` |
+//! | 颜色 | 5.6 选中图标 `OnSecondaryContainer` / 选中标签 `Secondary` / 未选中 `OnSurfaceVariant` | `Ui::color` |
+//! | 项间距 | 5.7 **4** | `LayoutMetrics::nav_item_gap` |
+
+use iced::widget::{button, column, container};
+use iced::{Alignment, Background, Border, Element, Length, Padding, Shadow, Theme as IcedTheme};
+
+use unlucky_design::color::{Role, StateLayer};
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::icons::IconKind;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::{LayoutMetrics, Space};
+use unlucky_design::typography::TypeRole;
+
+use crate::app::Message;
+use crate::cli::ForcedState;
+use crate::icons;
+use crate::shell::{filled, label, overridden};
+use crate::theme::Ui;
+
+/// 导航占位项（任务要求 4~6 个；真正的页面由后续 mission 接管）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum NavItem {
+    /// 实例列表。
+    Instances,
+    /// 下载/版本。
+    Download,
+    /// 日志。
+    Logs,
+    /// 设置。
+    Settings,
+    /// AI 助手。
+    Ai,
+}
+
+impl NavItem {
+    /// 全部占位项（顺序 = 导航栏自上而下）。
+    pub const ALL: [NavItem; 5] = [
+        NavItem::Instances,
+        NavItem::Download,
+        NavItem::Logs,
+        NavItem::Settings,
+        NavItem::Ai,
+    ];
+
+    /// 显示名（i18n 是后续 mission；本 mission 用英文基线文案，避免干净 CI 上缺中文变豆腐块）。
+    pub const fn label(self) -> &'static str {
+        match self {
+            NavItem::Instances => "Instances",
+            NavItem::Download => "Download",
+            NavItem::Logs => "Logs",
+            NavItem::Settings => "Settings",
+            NavItem::Ai => "Assistant",
+        }
+    }
+
+    /// 令牌图标。
+    pub const fn icon(self) -> IconKind {
+        match self {
+            NavItem::Instances => IconKind::Instances,
+            NavItem::Download => IconKind::Download,
+            NavItem::Logs => IconKind::Logs,
+            NavItem::Settings => IconKind::Settings,
+            NavItem::Ai => IconKind::Ai,
+        }
+    }
+}
+
+/// 整条导航轨。
+pub(super) fn rail<'a>(
+    ui: &'a Ui,
+    selected: NavItem,
+    forced: Option<ForcedState>,
+) -> Element<'a, Message> {
+    let metrics = ui.metrics();
+    let indicator = indicator_size(metrics);
+
+    let items = NavItem::ALL
+        .iter()
+        .map(|item| rail_item(ui, *item, *item == selected, indicator, forced))
+        .collect::<Vec<_>>();
+
+    // 轨顶留白走 container padding，而不是「先塞一个 spacer 元素」：后者会被 column 的
+    // spacing（4）再加一档，实测变 28（视觉复审 P3-5）。
+    container(column(items).spacing(metrics.nav_item_gap))
+        .width(nav_rail_width(metrics))
+        .height(Length::Fill)
+        .padding(Padding::from([ui.space(Space::X6), 0.0]))
+        .style(|_theme| filled(ui.layer(MaterialLayer::Canvas)))
+        .into()
+}
+
+fn rail_item<'a>(
+    ui: &'a Ui,
+    item: NavItem,
+    selected: bool,
+    indicator: (f32, f32),
+    forced: Option<ForcedState>,
+) -> Element<'a, Message> {
+    let (indicator_width, indicator_height) = indicator;
+
+    let icon_color = if selected {
+        ui.color(Role::OnSecondaryContainer)
+    } else {
+        ui.color(Role::OnSurfaceVariant)
+    };
+    // 12b 5.6：选中标签用 `Secondary`，未选中 `OnSurfaceVariant`
+    let label_color = if selected {
+        ui.color(Role::Secondary)
+    } else {
+        ui.color(Role::OnSurfaceVariant)
+    };
+
+    // **不要用 `center_x/center_y(Fill)`**：那会把容器自己的 width/height 改成 Fill，
+    // 于是 56 被父级（button 宽 88）覆盖成 88、32 靠布局凑巧（视觉复审 P2-1）。
+    // 尺寸只认令牌推导值，居中交给父 column 的 `align_x`。
+    let pill = container(icons::view::<Message>(item.icon(), icon_color))
+        .width(indicator_width)
+        .height(indicator_height)
+        .align_x(Alignment::Center)
+        .align_y(Alignment::Center)
+        .style(move |_theme| container::Style {
+            background: selected.then(|| Background::Color(ui.color(Role::SecondaryContainer))),
+            border: Border {
+                radius: ui.radius(ShapeScale::Full, indicator_height),
+                ..Border::default()
+            },
+            ..container::Style::default()
+        });
+
+    let item_height = nav_item_height(ui, indicator_height);
+    // 列必须显式占满轨宽，否则它会 shrink 到 56，`align_x(Center)` 就变成空操作，
+    // 药丸会贴左缘（x=0..55 而不是 16..71）——r1 实测踩到的第二个坑。
+    let stack = column![
+        pill,
+        label(ui, TypeRole::LabelMedium, false, item.label(), label_color),
+    ]
+    .spacing(ui.space(Space::X1))
+    .width(nav_rail_width(ui.metrics()))
+    .align_x(Alignment::Center)
+    .height(item_height);
+
+    button(stack)
+        .width(nav_rail_width(ui.metrics()))
+        .height(item_height)
+        .padding(0)
+        .style(move |_theme: &IcedTheme, status| {
+            let background = match overridden(forced, status) {
+                button::Status::Hovered if !selected => Some(Background::Color(ui.state_over(
+                    StateLayer::Hover,
+                    Role::OnSurface,
+                    Role::Surface,
+                ))),
+                button::Status::Pressed if !selected => Some(Background::Color(ui.state_over(
+                    StateLayer::Pressed,
+                    Role::OnSurface,
+                    Role::Surface,
+                ))),
+                _ => None,
+            };
+
+            button::Style {
+                background,
+                text_color: label_color,
+                border: Border::default(),
+                shadow: Shadow::default(),
+                snap: true,
+            }
+        })
+        .on_press(Message::Select(item))
+        .into()
+}
+
+/// 导航轨宽度（M69 起是令牌层的 `nav_rail_width`）。
+///
+/// M69（`141e9b1`）把 `LayoutMetrics` 的 nav 字段做了语义纠正：
+///
+/// | 旧 | 新 |
+/// |---|---|
+/// | `nav_expanded_width = 88` | **`nav_rail_width = 88`**（值不变，名字从「展开」改成「轨」） |
+/// | `nav_collapsed_width = 48` | 删除（48 连 56 宽的选中指示器都放不下） |
+/// | —（缺） | `nav_drawer_width = 240`（D33 的展开态抽屉，本 crate 未用） |
+///
+/// 三处调用点都走这里：将来令牌再改名，仍然只改这一行。
+fn nav_rail_width(metrics: LayoutMetrics) -> f32 {
+    metrics.nav_rail_width
+}
+
+/// 选中指示器尺寸（12b 5.4 参考 56×32），全部由令牌推导、不写死：
+///
+/// - 宽 = [`nav_rail_width`] − 2 × `Space::X4` = 88 − 32 = **56**（轨的左右内边距 16）
+/// - 高 = `control_height − Space::X2` = 40 − 8 = **32**（可见高度上下各让 4）
+pub fn indicator_size(metrics: LayoutMetrics) -> (f32, f32) {
+    (
+        nav_rail_width(metrics) - Space::X4.dp() * 2.0,
+        metrics.control_height - Space::X2.dp(),
+    )
+}
+
+/// 导航项高度 = 指示器 + 4 + 标签行高 = 32 + 4 + 16 = 52（`LM.nav_item_height` 是列表行节奏，
+/// 药丸 + 标签的轨项放不进 44，偏差登记在交接文档里）。
+pub fn nav_item_height(ui: &Ui, indicator_height: f32) -> f32 {
+    indicator_height + ui.space(Space::X1) + ui.style(TypeRole::LabelMedium).line_height_px
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use unlucky_design::color::SchemeFlavor;
+    use unlucky_design::typography::Platform;
+
+    use crate::theme::Families;
+
+    fn ui() -> Ui {
+        Ui::with_platform(
+            SchemeFlavor::Light,
+            Platform::Windows,
+            Families {
+                text: "Segoe UI",
+                display: "Segoe UI",
+                mono: "Consolas",
+            },
+        )
+    }
+
+    #[test]
+    fn indicator_matches_the_reference_56x32() {
+        let (width, height) = indicator_size(LayoutMetrics::DESKTOP);
+        assert_eq!((width, height), (56.0, 32.0), "12b 5.4 的参考值");
+    }
+
+    #[test]
+    fn nav_item_height_is_indicator_plus_gap_plus_label() {
+        let ui = ui();
+        let (_, indicator_height) = indicator_size(ui.metrics());
+        // 32 + 4 + 16
+        assert_eq!(nav_item_height(&ui, indicator_height), 52.0);
+    }
+
+    #[test]
+    fn every_nav_item_has_a_label_and_an_icon() {
+        assert!((4..=6).contains(&NavItem::ALL.len()));
+        for item in NavItem::ALL {
+            assert!(!item.label().is_empty(), "{item:?} 没有文案");
+            assert!(!item.icon().icon().path.is_empty(), "{item:?} 没有图标");
+        }
+    }
+}

crates/app-iced/src/shot/diff.rs

@@ -0,0 +1,352 @@
+//! 两图逐像素对比（GPU/CPU 几何一致性）与 ±N px 平移扫描。
+//!
+//! 拆成子模块只为「src 文件 ≤400 行」的门禁；对外通过 `shot::{compare, diff_files, Diff, Image}`
+//! 使用，调用方不用感知这层。
+
+use std::path::Path;
+
+/// 一张已解码的 RGBA 图。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Image {
+    /// RGBA8 字节（逐像素 4 字节）。
+    pub rgba: Vec<u8>,
+    /// 宽（px）。
+    pub width: u32,
+    /// 高（px）。
+    pub height: u32,
+}
+
+impl Image {
+    /// 读 PNG（只支持 PNG：本 crate 的 `image` 只开了 png 编码/解码）。
+    ///
+    /// # Errors
+    /// 读文件失败或解码失败时返回人话。
+    pub fn load(path: &Path) -> Result<Self, String> {
+        let reader = image::ImageReader::open(path)
+            .map_err(|error| format!("读图 {} 失败：{error}", path.display()))?
+            .with_guessed_format()
+            .map_err(|error| format!("判定 {} 的格式失败：{error}", path.display()))?;
+
+        let decoded = reader
+            .decode()
+            .map_err(|error| format!("解码 {} 失败：{error}", path.display()))?
+            .to_rgba8();
+
+        Ok(Self {
+            width: decoded.width(),
+            height: decoded.height(),
+            rgba: decoded.into_raw(),
+        })
+    }
+}
+
+/// 两图对比结果（GPU/CPU 一致性靠它给数字，不靠肉眼）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Diff {
+    /// 宽（px）。
+    pub width: u32,
+    /// 高（px）。
+    pub height: u32,
+    /// 有差异的像素数。
+    pub differing_pixels: usize,
+    /// 单通道最大差（0~255）。
+    pub max_channel_delta: u8,
+    /// 单通道平均差（0~255）。
+    pub mean_channel_delta: f64,
+    /// 平移扫描的最佳对齐（dx, dy）；不扫描时为 (0, 0)。
+    pub best_shift: (i32, i32),
+    /// 最佳对齐下的差异像素数（不扫描时等于 `differing_pixels`）。
+    pub best_differing_pixels: usize,
+}
+
+/// 逐像素对比两张尺寸相同的图。
+///
+/// # Errors
+/// 尺寸不同直接报错——**几何不一致不许静默通过**。
+pub fn compare(left: &Image, right: &Image) -> Result<Diff, String> {
+    if (left.width, left.height) != (right.width, right.height) {
+        return Err(format!(
+            "尺寸不同：{}x{} vs {}x{}",
+            left.width, left.height, right.width, right.height
+        ));
+    }
+
+    let pixel_count = left.rgba.len() / 4;
+    let mut differing = 0_usize;
+    let mut max_delta = 0_u8;
+    let mut sum_delta = 0_u64;
+
+    for index in 0..pixel_count {
+        let offset = index * 4;
+        let mut pixel_differs = false;
+
+        for channel in 0..4 {
+            let delta = left.rgba[offset + channel].abs_diff(right.rgba[offset + channel]);
+            if delta > 0 {
+                pixel_differs = true;
+                max_delta = max_delta.max(delta);
+                sum_delta += u64::from(delta);
+            }
+        }
+
+        if pixel_differs {
+            differing += 1;
+        }
+    }
+
+    Ok(Diff {
+        width: left.width,
+        height: left.height,
+        differing_pixels: differing,
+        max_channel_delta: max_delta,
+        mean_channel_delta: if pixel_count == 0 {
+            0.0
+        } else {
+            sum_delta as f64 / (pixel_count * 4) as f64
+        },
+        best_shift: (0, 0),
+        best_differing_pixels: differing,
+    })
+}
+
+/// ±`max_shift` px 的平移扫描：把 `right` 平移后再比，返回差异像素数最小的那一档。
+///
+/// 用途：D30 的「几何逐像素一致」除了看差异占比，还要证明**没有整体错位**——
+/// 如果 (0,0) 就是最优，说明差异只来自抗锯齿而不是位移/缩放。CI 不必再依赖 numpy。
+///
+/// 平移后越界的像素按「无法比较」处理，不计入差异（否则边缘会造成假阳性）。
+pub fn shift_scan(left: &Image, right: &Image, max_shift: i32) -> Result<Diff, String> {
+    let mut best = compare(left, right)?;
+    let max_shift = max_shift.unsigned_abs();
+
+    if (left.width, left.height) != (right.width, right.height) {
+        return Err("尺寸不同，无法做平移扫描".to_owned());
+    }
+
+    for dy in -(max_shift as i32)..=(max_shift as i32) {
+        for dx in -(max_shift as i32)..=(max_shift as i32) {
+            if (dx, dy) == (0, 0) {
+                continue;
+            }
+
+            let count = shifted_differing_pixels(left, right, dx, dy);
+            if count < best.best_differing_pixels {
+                best.best_differing_pixels = count;
+                best.best_shift = (dx, dy);
+            }
+        }
+    }
+
+    Ok(best)
+}
+
+/// 把 `right` 平移 `(dx, dy)` 后与 `left` 比较，返回差异像素数（越界不算）。
+fn shifted_differing_pixels(left: &Image, right: &Image, dx: i32, dy: i32) -> usize {
+    let width = left.width as i32;
+    let height = left.height as i32;
+    let mut differing = 0;
+
+    for y in 0..height {
+        let source_y = y - dy;
+        if !(0..height).contains(&source_y) {
+            continue;
+        }
+
+        for x in 0..width {
+            let source_x = x - dx;
+            if !(0..width).contains(&source_x) {
+                continue;
+            }
+
+            let left_offset = ((y * width + x) * 4) as usize;
+            let right_offset = ((source_y * width + source_x) * 4) as usize;
+
+            if left.rgba[left_offset..left_offset + 4] != right.rgba[right_offset..right_offset + 4]
+            {
+                differing += 1;
+            }
+        }
+    }
+
+    differing
+}
+
+impl Diff {
+    /// 完全一致（几何 + 颜色都一致）。
+    pub fn is_identical(&self) -> bool {
+        self.differing_pixels == 0
+    }
+
+    /// 一行日志。
+    pub fn describe(&self) -> String {
+        let total = (self.width as usize) * (self.height as usize);
+        let percent = if total == 0 {
+            0.0
+        } else {
+            self.differing_pixels as f64 * 100.0 / total as f64
+        };
+
+        format!(
+            "[diff] {}x{} differing={}/{} ({percent:.2}%) max_delta={} mean_delta={:.4} best_shift=({},{}) best_differing={}",
+            self.width,
+            self.height,
+            self.differing_pixels,
+            total,
+            self.max_channel_delta,
+            self.mean_channel_delta,
+            self.best_shift.0,
+            self.best_shift.1,
+            self.best_differing_pixels,
+        )
+    }
+}
+
+/// `--diff <left> <right>` 的实现：读两张 PNG、对比、打日志。
+///
+/// # Errors
+/// 任一图读不出来，或尺寸不同。
+pub fn diff_files(left: &Path, right: &Path) -> Result<Diff, String> {
+    diff_files_with_scan(left, right, 0)
+}
+
+/// 同 [`diff_files`]，但额外做 ±`max_shift` px 的平移扫描（`--diff-scan`）。
+///
+/// # Errors
+/// 任一图读不出来，或尺寸不同。
+pub fn diff_files_with_scan(left: &Path, right: &Path, max_shift: i32) -> Result<Diff, String> {
+    let left = Image::load(left)?;
+    let right = Image::load(right)?;
+
+    if max_shift == 0 {
+        compare(&left, &right)
+    } else {
+        shift_scan(&left, &right, max_shift)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::PathBuf;
+
+    use iced::window;
+
+    use super::*;
+    use crate::shot::{save, write_rgba};
+
+    fn temp_dir() -> PathBuf {
+        let dir = std::env::temp_dir().join("ull-app-iced-shot-tests");
+        std::fs::create_dir_all(&dir).expect("建临时目录");
+        dir
+    }
+
+    #[test]
+    fn identical_images_have_zero_diff() {
+        let image = Image {
+            rgba: vec![7_u8; 4 * 4],
+            width: 2,
+            height: 2,
+        };
+        let diff = compare(&image, &image).unwrap();
+        assert!(diff.is_identical());
+        assert_eq!(diff.max_channel_delta, 0);
+    }
+
+    #[test]
+    fn geometry_mismatch_is_an_error_not_a_silent_pass() {
+        let square = Image {
+            rgba: vec![0; 16],
+            width: 2,
+            height: 2,
+        };
+        let strip = Image {
+            rgba: vec![0; 16],
+            width: 4,
+            height: 1,
+        };
+        assert!(compare(&square, &strip).is_err());
+    }
+
+    #[test]
+    fn color_only_differences_are_counted_per_pixel() {
+        let left = Image {
+            rgba: vec![0, 0, 0, 255, 0, 0, 0, 255],
+            width: 2,
+            height: 1,
+        };
+        let right = Image {
+            rgba: vec![10, 0, 0, 255, 0, 0, 0, 255],
+            width: 2,
+            height: 1,
+        };
+        let diff = compare(&left, &right).unwrap();
+        assert_eq!(diff.differing_pixels, 1);
+        assert_eq!(diff.max_channel_delta, 10);
+        assert!(diff.describe().contains("differing=1/2"));
+    }
+
+    #[test]
+    fn png_roundtrip_through_disk() {
+        let path = temp_dir().join("roundtrip.png");
+        let bytes = vec![200_u8; 4 * 3 * 2];
+        write_rgba(&bytes, 3, 2, &path).unwrap();
+
+        let loaded = Image::load(&path).unwrap();
+        assert_eq!((loaded.width, loaded.height), (3, 2));
+        assert_eq!(loaded.rgba, bytes);
+
+        let diff = diff_files(&path, &path).unwrap();
+        assert!(diff.is_identical());
+    }
+
+    #[test]
+    fn shift_scan_finds_the_best_alignment() {
+        // 5x5 图，R 通道存唯一值；构造 right[y][x] = left[y+1][x+1]（即把左图向左上挪 1px），
+        // 于是「left 与 right 在 dy=1,dx=1 时逐像素相等」——扫描应该把 (1,1) 找出来。
+        let side = 5_i32;
+        let mut rgba = Vec::new();
+        for y in 0..side {
+            for x in 0..side {
+                rgba.extend([(y * side + x) as u8, 0, 0, 255]);
+            }
+        }
+        let left = Image {
+            rgba,
+            width: side as u32,
+            height: side as u32,
+        };
+
+        let mut moved = vec![255_u8; (side * side * 4) as usize];
+        for y in 0..side - 1 {
+            for x in 0..side - 1 {
+                let source = ((y + 1) * side + (x + 1)) as usize * 4;
+                let target = (y * side + x) as usize * 4;
+                moved[target..target + 4].copy_from_slice(&left.rgba[source..source + 4]);
+            }
+        }
+        let right = Image {
+            rgba: moved,
+            width: side as u32,
+            height: side as u32,
+        };
+
+        let diff = shift_scan(&left, &right, 2).unwrap();
+        assert_eq!(diff.best_shift, (1, 1), "应扫出 1px 的位移");
+        assert_eq!(diff.best_differing_pixels, 0, "对齐后应逐像素相等");
+        assert!(
+            diff.differing_pixels > 0,
+            "不对齐时应该有差异（否则这条测试没有信息量）"
+        );
+
+        // 同一张图：最佳对齐就是 (0,0)
+        let same = shift_scan(&left, &left, 2).unwrap();
+        assert_eq!(same.best_shift, (0, 0));
+        assert_eq!(same.best_differing_pixels, 0);
+    }
+
+    #[test]
+    fn wrong_byte_count_is_reported() {
+        let screenshot = window::Screenshot::new(vec![0_u8; 3], iced::Size::new(1, 1), 1.0);
+        let error = save(&screenshot, &temp_dir().join("unused.png")).unwrap_err();
+        assert!(error.contains("字节数对不上"), "{error}");
+    }
+}

crates/app-iced/src/shot/mod.rs

@@ -0,0 +1,100 @@
+//! 截图通道（D30 验收用）：`iced::window::screenshot` 的真窗口出图 → PNG，以及两图逐像素对比。
+//!
+//! ## 为什么用真窗口而不是 `iced_test::Emulator`
+//!
+//! 任务书首选路径①：真开窗截图覆盖了标题栏/DPI/窗口管理的真实行为，离屏通道不覆盖
+//! （M60 §Q6 的边界说明）。本机与 Windows CI 都有交互会话，所以走路径①。
+//!
+//! ## 关键事实（M60 踩坑 Q3）
+//!
+//! `Screenshot` 的字节字段在 0.14 叫 **`rgba`**（0.13 是 `bytes`），`size` 是**物理像素**，
+//! 另带 `scale_factor`（换算逻辑坐标用）。落盘用 `image::save_buffer` + `ExtendedColorType::Rgba8`。
+//!
+//! ## 为什么自己带一个 diff
+//!
+//! D30 的硬项是「GPU 档与 CPU 档**几何逐像素一致**，只有颜色/材质不同」。CI 里不该假设有
+//! Python/PIL/ImageMagick，所以把「读两张 PNG → 数差异像素 → 给最大/平均通道差」做进本程序
+//! （`--diff a.png b.png`），复用同一个二进制。
+
+use std::path::{Path, PathBuf};
+
+use iced::window;
+
+use crate::theme;
+
+/// 把一帧截图写到 `path`（自动建父目录）。
+///
+/// # Errors
+/// 目录建不出来、PNG 编码失败、字节数与尺寸对不上时返回人话（截图通道要能一眼看出哪一步断）。
+pub fn save(screenshot: &window::Screenshot, path: &Path) -> Result<Summary, String> {
+    let width = screenshot.size.width;
+    let height = screenshot.size.height;
+    let bytes = screenshot.rgba.as_ref();
+
+    let expected = width as usize * height as usize * 4;
+    if bytes.len() != expected {
+        return Err(format!(
+            "截图字节数对不上：{width}x{height} 应该 {expected} B，实际 {} B",
+            bytes.len()
+        ));
+    }
+
+    write_rgba(bytes, width, height, path)?;
+
+    Ok(Summary {
+        width,
+        height,
+        scale_factor: screenshot.scale_factor,
+        path: path.to_path_buf(),
+    })
+}
+
+fn write_rgba(bytes: &[u8], width: u32, height: u32, path: &Path) -> Result<(), String> {
+    if let Some(parent) = path.parent() {
+        if !parent.as_os_str().is_empty() {
+            std::fs::create_dir_all(parent)
+                .map_err(|error| format!("建目录 {} 失败：{error}", parent.display()))?;
+        }
+    }
+
+    image::save_buffer(path, bytes, width, height, image::ExtendedColorType::Rgba8)
+        .map_err(|error| format!("写 PNG {} 失败：{error}", path.display()))
+}
+
+/// 一次截图的结果摘要（打日志与报告用）。
+#[derive(Debug, Clone, PartialEq)]
+pub struct Summary {
+    /// 物理宽（px）。
+    pub width: u32,
+    /// 物理高（px）。
+    pub height: u32,
+    /// 窗口缩放因子（100% DPI = 1.0）。
+    pub scale_factor: f32,
+    /// 落盘路径。
+    pub path: PathBuf,
+}
+
+impl Summary {
+    /// 一行日志。
+    pub fn describe(&self) -> String {
+        format!(
+            "[shot] {}x{} scale={} -> {}",
+            self.width,
+            self.height,
+            self.scale_factor,
+            self.path.display()
+        )
+    }
+}
+
+mod diff;
+
+pub use diff::{compare, diff_files, diff_files_with_scan, shift_scan, Diff, Image};
+
+/// 主题名 → 归档文件名片段（`visual-acceptance-protocol.md` §7 的命名）。
+pub fn flavor_slug(ui: &theme::Ui) -> &'static str {
+    match ui.flavor() {
+        unlucky_design::color::SchemeFlavor::Light => "light",
+        unlucky_design::color::SchemeFlavor::Dark => "dark",
+    }
+}

crates/app-iced/src/theme.rs

@@ -0,0 +1,334 @@
+//! 令牌 → iced 类型（`Color` / `Font` / `Border` / `Radius` / `Theme`）。
+//!
+//! ## 边界（M61 `design-令牌约定.md` §0 的落地）
+//!
+//! 本模块是**唯一**允许把 `unlucky-design` 的值翻成 iced 类型的地方。组件层（`shell`）
+//! 只调 [`Ui`] 的方法，绝不出现色值 / 字号 / 半径 / 间距字面量——`tests/no_hardcoded_tokens.rs`
+//! 会扫 `src/**` 做守门。
+//!
+//! ## 为什么不用 `iced::theme::Base` 自定义主题承载 49 个角色
+//!
+//! `iced` 的 `Palette` 只有 6 个颜色（`background/text/primary/success/warning/danger`），
+//! M3 有 49 个角色，塞不进去（M60 Q5 + M61 §9-0 的同一结论）。所以：
+//!
+//! - **真源**是本模块持有的 [`Scheme`]（49 角色）；
+//! - iced 的 `Theme` 只用来「换名字」——`Theme::name()` 变了 iced 才会重算受主题影响的缓存
+//!   （M61 §9 的最后一条）。`palette()` 只给 devtools 看，控件外观一律由各自的 `Style` 注入。
+//!
+//! `success` / `warning` 在 M3 里**没有对应角色**（`design-令牌约定.md` §2 明写），
+//! 这里按「语义最近的现成角色」映射：`success → Secondary`（不是「成功」的承诺）、
+//! `warning → Tertiary`（M3 把「提醒」放 Tertiary）。任何控件都不要去读这两个槽位。
+
+use iced::border::Radius;
+use iced::theme::Palette;
+use iced::{Border, Color, Font, Theme};
+
+use unlucky_design::color::{Role, Scheme, SchemeFlavor, StateLayer};
+use unlucky_design::elevation::MaterialLayer;
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::{LayoutMetrics, Space};
+use unlucky_design::typography::{FontFamily, Platform, TypeRole, TypeStyle, Weight};
+
+/// 全站描边宽度（逻辑 px @100% DPI）。rubric G7 要求全站 1px —— 令牌层的「一像素线单一真源」。
+///
+/// M69 起令牌层提供 `unlucky_design::stroke::HAIRLINE`（容器描边/分隔线/聚焦环共用），
+/// 这里**再导出**而不是自己写 `1.0`：全仓只有令牌层一个定义点。
+pub use unlucky_design::stroke::HAIRLINE as STROKE_PX;
+
+/// 已经解析到系统的字体族名（`&'static str` 才能塞进 `iced::Font`）。
+///
+/// 由 `fonts` 模块按令牌栈 + 系统字体库求值，本模块只消费。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Families {
+    /// 正文族（`FontFamily::Text` 栈里第一个装机可用的）。
+    pub text: &'static str,
+    /// 展示族（`FontFamily::Display`）。
+    pub display: &'static str,
+    /// 等宽族（`FontFamily::Mono`，日志/版本号用）。
+    pub mono: &'static str,
+}
+
+/// 令牌求值器：一个 `Ui` 对应一套主题（浅或深）。
+///
+/// 深浅热切 = 重新 `Ui::new(flavor, families)` 并整树重绘；控件里不要缓存颜色。
+#[derive(Debug, Clone)]
+pub struct Ui {
+    scheme: Scheme,
+    platform: Platform,
+    metrics: LayoutMetrics,
+    families: Families,
+}
+
+impl Ui {
+    /// 按平台（由 `cfg!` 决定）与令牌基线方案求值。
+    pub fn new(flavor: SchemeFlavor, families: Families) -> Self {
+        Self::with_platform(flavor, Platform::current(), families)
+    }
+
+    /// 显式指定平台（跨平台核对与测试用）。
+    pub fn with_platform(flavor: SchemeFlavor, platform: Platform, families: Families) -> Self {
+        Self {
+            scheme: Scheme::baseline(flavor),
+            platform,
+            metrics: LayoutMetrics::DESKTOP,
+            families,
+        }
+    }
+
+    /// 当前深浅模式。
+    pub fn flavor(&self) -> SchemeFlavor {
+        self.scheme.flavor()
+    }
+
+    /// 当前平台（决定字体族与字重降级）。
+    pub fn platform(&self) -> Platform {
+        self.platform
+    }
+
+    /// 骨架尺寸（标题栏/导航/行高…）。
+    pub fn metrics(&self) -> LayoutMetrics {
+        self.metrics
+    }
+
+    /// 已解析的字体族名。
+    pub fn families(&self) -> Families {
+        self.families
+    }
+
+    /// 间距档位（4px 栅格）。
+    pub fn space(&self, space: Space) -> f32 {
+        space.dp()
+    }
+
+    /// M3 角色 → iced 颜色。
+    pub fn color(&self, role: Role) -> Color {
+        to_iced(self.scheme.get(role))
+    }
+
+    /// 材质层（Canvas/Card/Overlay）→ 容器色。
+    pub fn layer(&self, layer: MaterialLayer) -> Color {
+        self.color(layer.surface_role())
+    }
+
+    /// 状态层叠在容器色上，返回**不透明**结果。
+    ///
+    /// 为什么不用带 alpha 的叠加：D27 要求 CPU 档不出现半透明，而「不透明结果」让 GPU/CPU
+    /// 两档的颜色也逐像素一致（只有材质/玻璃才允许两档不同）。
+    pub fn state_over(&self, state: StateLayer, content: Role, container: Role) -> Color {
+        to_iced(state.over(self.scheme.get(content), self.scheme.get(container)))
+    }
+
+    /// 圆角（令牌刻度）；`side` 是控件在该轴上的边长（`ShapeScale::Full` 要按边长折算）。
+    pub fn radius(&self, shape: ShapeScale, side: f32) -> Radius {
+        Radius::new(shape.radius_px(side))
+    }
+
+    /// 固定档圆角（不需要边长）。`ShapeScale::Full` 必须走 [`Ui::radius`]（它没有绝对值）。
+    pub fn radius_dp(&self, shape: ShapeScale) -> Radius {
+        debug_assert!(
+            !matches!(shape, ShapeScale::Full),
+            "Full 需要边长，请用 Ui::radius(shape, side)"
+        );
+        Radius::new(if matches!(shape, ShapeScale::Full) {
+            0.0
+        } else {
+            shape.dp()
+        })
+    }
+
+    /// 描边：`OutlineVariant` + [`STROKE_PX`]，圆角走刻度（固定档）。
+    pub fn outlined(&self, shape: ShapeScale) -> Border {
+        Border {
+            color: self.color(Role::OutlineVariant),
+            width: STROKE_PX,
+            radius: self.radius_dp(shape),
+        }
+    }
+
+    /// baseline 排版档。
+    pub fn style(&self, role: TypeRole) -> TypeStyle {
+        role.style()
+    }
+
+    /// Expressive 强调档（官方值：字重升到 500/700）。
+    pub fn emphasized(&self, role: TypeRole) -> TypeStyle {
+        role.emphasized()
+    }
+
+    /// 某个排版档对应的 iced 字体（族 + 字重）。
+    pub fn font_of(&self, style: TypeStyle) -> Font {
+        let family = match style.family {
+            FontFamily::Display => self.families.display,
+            FontFamily::Text => self.families.text,
+            FontFamily::Mono => self.families.mono,
+        };
+
+        Font {
+            family: iced::font::Family::Name(family),
+            weight: weight_of(style.weight),
+            ..Font::DEFAULT
+        }
+    }
+
+    /// baseline 档的字体。
+    pub fn font(&self, role: TypeRole) -> Font {
+        self.font_of(self.style(role))
+    }
+
+    /// 强调档的字体。
+    pub fn emphasized_font(&self, role: TypeRole) -> Font {
+        self.font_of(self.emphasized(role))
+    }
+
+    /// iced 的 6 色 `Palette`（只给 devtools / 兜底控件用；M3 的 49 角色在 [`Ui::color`]）。
+    pub fn palette(&self) -> Palette {
+        Palette {
+            background: self.color(Role::Surface),
+            text: self.color(Role::OnSurface),
+            primary: self.color(Role::Primary),
+            success: self.color(Role::Secondary),
+            warning: self.color(Role::Tertiary),
+            danger: self.color(Role::Error),
+        }
+    }
+
+    /// iced 主题对象：**名字带深浅**，切主题时 `Theme::name()` 变化会触发重算。
+    pub fn theme(&self) -> Theme {
+        Theme::custom(self.name(), self.palette())
+    }
+
+    /// `Theme::name()` 的取值（稳定字符串，改名要先在协作文档登记）。
+    pub fn name(&self) -> &'static str {
+        match self.flavor() {
+            SchemeFlavor::Light => "ull-m3-light",
+            SchemeFlavor::Dark => "ull-m3-dark",
+        }
+    }
+}
+
+/// 令牌色（8 bit sRGB）→ iced 的 sRGB 分量。
+pub fn to_iced(color: unlucky_design::color::Color) -> Color {
+    Color::from_rgba8(
+        color.r,
+        color.g,
+        color.b,
+        f32::from(color.a) / f32::from(u8::MAX),
+    )
+}
+
+/// 令牌字重 → iced 字重。
+pub fn weight_of(weight: Weight) -> iced::font::Weight {
+    match weight {
+        Weight::Regular => iced::font::Weight::Normal,
+        Weight::Medium => iced::font::Weight::Medium,
+        Weight::SemiBold => iced::font::Weight::Semibold,
+        Weight::Bold => iced::font::Weight::Bold,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const FAMILIES: Families = Families {
+        text: "Segoe UI Variable Text",
+        display: "Segoe UI Variable Display",
+        mono: "Cascadia Mono",
+    };
+
+    fn ui(flavor: SchemeFlavor) -> Ui {
+        Ui::with_platform(flavor, Platform::Windows, FAMILIES)
+    }
+
+    #[test]
+    fn theme_name_tracks_the_flavor() {
+        assert_eq!(ui(SchemeFlavor::Light).name(), "ull-m3-light");
+        assert_eq!(ui(SchemeFlavor::Dark).name(), "ull-m3-dark");
+        assert_ne!(
+            ui(SchemeFlavor::Light).theme().to_string(),
+            ui(SchemeFlavor::Dark).theme().to_string()
+        );
+    }
+
+    #[test]
+    fn canvas_card_overlay_follow_surface_containers() {
+        let ui = ui(SchemeFlavor::Light);
+        assert_eq!(ui.layer(MaterialLayer::Canvas), ui.color(Role::Surface));
+        assert_eq!(
+            ui.layer(MaterialLayer::Card),
+            ui.color(Role::SurfaceContainerLow)
+        );
+        assert_eq!(
+            ui.layer(MaterialLayer::Overlay),
+            ui.color(Role::SurfaceContainerHigh)
+        );
+    }
+
+    #[test]
+    fn radii_only_come_from_the_scale() {
+        let ui = ui(SchemeFlavor::Light);
+        // 卡片 Medium(12)：边长够大时就是 12
+        assert_eq!(ui.radius_dp(ShapeScale::Medium).top_left, 12.0);
+        assert_eq!(ui.radius_dp(ShapeScale::ExtraSmall).top_left, 4.0);
+        // 药丸 Full：按边长一半折算
+        assert_eq!(ui.radius(ShapeScale::Full, 32.0).top_left, 16.0);
+        // 不许超过边长一半
+        assert_eq!(ui.radius(ShapeScale::ExtraLarge, 20.0).top_left, 10.0);
+    }
+
+    #[test]
+    fn outlines_are_one_pixel_and_use_outline_variant() {
+        let ui = ui(SchemeFlavor::Light);
+        let border = ui.outlined(ShapeScale::Medium);
+        assert_eq!(border.width, STROKE_PX);
+        assert_eq!(border.width, 1.0, "rubric G7：全站 1px");
+        assert_eq!(border.color, ui.color(Role::OutlineVariant));
+        assert_eq!(border.radius.top_left, 12.0);
+    }
+
+    #[test]
+    fn emphasized_weights_are_the_official_ones() {
+        let ui = ui(SchemeFlavor::Light);
+        // title-small 的强调档是 700（官方 Emphasized）
+        assert_eq!(
+            ui.emphasized_font(TypeRole::TitleSmall).weight,
+            iced::font::Weight::Bold
+        );
+        // baseline 正文是 400
+        assert_eq!(
+            ui.font(TypeRole::BodyMedium).weight,
+            iced::font::Weight::Normal
+        );
+    }
+
+    #[test]
+    fn body_text_keeps_wcag_contrast_in_both_flavors() {
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let scheme = Scheme::baseline(flavor);
+            assert!(
+                scheme.contrast(Role::OnSurface, Role::Surface) >= 4.5,
+                "{flavor:?} 的正文对比度不够"
+            );
+            assert!(
+                scheme.contrast(Role::OnSecondaryContainer, Role::SecondaryContainer) >= 4.5,
+                "{flavor:?} 的选中态药丸对比度不够"
+            );
+        }
+    }
+
+    #[test]
+    fn every_role_maps_to_an_iced_color() {
+        for role in Role::ALL {
+            let color = ui(SchemeFlavor::Dark).color(role);
+            assert!((0.0..=1.0).contains(&color.a), "{role:?} 的 alpha 越界");
+        }
+    }
+
+    #[test]
+    fn state_layers_are_opaque_so_cpu_and_gpu_match() {
+        let ui = ui(SchemeFlavor::Light);
+        let hovered = ui.state_over(StateLayer::Hover, Role::OnSurface, Role::Surface);
+        assert_eq!(hovered.a, 1.0, "状态层必须给出不透明结果");
+        assert_ne!(hovered, ui.color(Role::Surface));
+    }
+}

crates/app-iced/tests/no_hardcoded_tokens.rs

@@ -0,0 +1,351 @@
+//! 门禁：**组件层零硬编码**（色值 / 尺寸）与「不依赖 slint」。
+//!
+//! 这三条测试会扫本 crate 的 `src/**` 与 `Cargo.toml`，故意写得「宁可错杀」：
+//! 将来 reviewer 复跑 `cargo test -p unlucky-app-iced` 就能挡住「顺手写个 #RRGGBB」的提交。
+//!
+//! 判定口径（与 `component-fidelity-rubric.md` T1/T2、`visual-acceptance-protocol.md` §1 对齐）：
+//!
+//! - **色值字面量**：`#` + 6 位十六进制（且**至少含一个数字**，这样文档里的 `#RRGGBB` 占位不会被误杀）
+//!   或 `Color::from_rgb(0.1, …)` / `color!(0x…)` 这类带数值参数的构造。
+//! - **令牌优先**：唯一允许的是 `theme.rs`（适配层），且它也只做 `token → iced` 的搬运。
+//! - **尺寸字面量**：`shell.rs` 里 `.width(12.0)` / `.height(34)` / `.size(22)` 一律不许出现
+//!   （必须走 `LayoutMetrics` / `TypeStyle` / `Space`）。
+
+use std::path::{Path, PathBuf};
+
+/// 本 crate 根目录（编译期注入，换机器也成立）。
+fn manifest_dir() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+}
+
+/// 递归收集 `dir` 下的 `.rs` 文件。
+fn rust_files(dir: &Path, collected: &mut Vec<PathBuf>) {
+    let entries =
+        std::fs::read_dir(dir).unwrap_or_else(|error| panic!("读不动 {}：{error}", dir.display()));
+
+    for entry in entries {
+        let path = entry.expect("目录项读失败").path();
+        if path.is_dir() {
+            rust_files(&path, collected);
+        } else if path.extension().is_some_and(|ext| ext == "rs") {
+            collected.push(path);
+        }
+    }
+}
+
+fn sources() -> Vec<(PathBuf, String)> {
+    let mut files = Vec::new();
+    rust_files(&manifest_dir().join("src"), &mut files);
+
+    assert!(
+        files.len() >= 8,
+        "只扫到 {} 个源文件：扫描逻辑坏了，这条门禁等于没跑",
+        files.len()
+    );
+
+    files
+        .into_iter()
+        .map(|path| {
+            let text = std::fs::read_to_string(&path)
+                .unwrap_or_else(|error| panic!("读不动 {}：{error}", path.display()));
+            (path, text)
+        })
+        .collect()
+}
+
+/// `#RRGGBB` / `#AARRGGBB` 形式的色值字面量（至少含一个数字，避开 `#RRGGBB` 这种占位写法）。
+fn hex_color_at(bytes: &[u8], start: usize) -> Option<&str> {
+    let digits = bytes.get(start + 1..start + 7)?;
+    let all_hex = digits
+        .iter()
+        .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_whitespace());
+    let has_number = digits.iter().any(u8::is_ascii_digit);
+
+    if all_hex && has_number {
+        // 后面不能再跟着十六进制字符（否则是更长的 token，不是 6 位色值）
+        let next = bytes.get(start + 7).copied();
+        if next.is_none_or(|byte| !byte.is_ascii_hexdigit()) {
+            return Some("hex 色值字面量（#RRGGBB）");
+        }
+    }
+
+    None
+}
+
+/// 带数值参数的取色构造（`Color::from_rgb(0.1, …)`、`Color::from_rgb8(103, 80, 164)`、`color!(0x12, …)`）。
+///
+/// **子串匹配要注意前后缀**：`from_rgb(` 匹配不到 `from_rgb8(`，所以 8 bit 那个必须单独列出来
+/// （reviewer 造样就是这么绕过去的）。
+const NUMERIC_COLOR_CALLS: [&str; 8] = [
+    "Color::from_rgb(",
+    "Color::from_rgb8(",
+    "Color::from_rgba(",
+    "Color::from_rgba8(",
+    "Color::from_hex(",
+    "Color::rgba(",
+    "Color::rgb8(",
+    "color!(",
+];
+
+/// 取色构造后面是不是跟着数值字面量（允许 `Color::from_rgba8(color.r, …)` 这类搬运）。
+fn numeric_color_call(text: &str) -> Option<&'static str> {
+    for pattern in NUMERIC_COLOR_CALLS {
+        let mut from = 0;
+        while let Some(found) = text[from..].find(pattern) {
+            let after = from + found + pattern.len();
+            let next = text[after..].trim_start().chars().next();
+
+            // 参数以数字或 `0x`/`#` 开头才算字面量；`Color::from_rgba8(color.r, …)` 是搬运，放行。
+            if next.is_some_and(|ch| ch.is_ascii_digit() || ch == '#') {
+                return Some(pattern);
+            }
+
+            from = after;
+        }
+    }
+
+    None
+}
+
+/// 结构体字面量取色：`Color { r: 0.4, g: 0.3, b: 0.6, a: 1.0 }`。
+///
+/// 判据：`Color {` 之后 64 个字符内同时出现 `r:` 与 `g:` 且有数字（`Color { a: 0.0, .. }` 这种
+/// 只改 alpha 的写法不会命中，因为它没有 `r:`）。
+fn color_struct_literal(text: &str) -> bool {
+    let mut from = 0;
+    while let Some(found) = text[from..].find("Color {") {
+        let after = from + found + "Color {".len();
+        let window: String = text[after..].chars().take(64).collect();
+        let has_channels = window.contains("r:") && window.contains("g:");
+        let has_number = window.chars().any(|ch| ch.is_ascii_digit());
+
+        if has_channels && has_number {
+            return true;
+        }
+
+        from = after;
+    }
+
+    false
+}
+
+#[test]
+fn no_hardcoded_colors_in_sources() {
+    let mut offenders = Vec::new();
+
+    for (path, text) in sources() {
+        for (index, line) in text.lines().enumerate() {
+            let bytes = line.as_bytes();
+            let mut position = 0;
+
+            while let Some(found) = line[position..].find('#') {
+                let at = position + found;
+                if let Some(kind) = hex_color_at(bytes, at) {
+                    offenders.push(format!(
+                        "{}:{} {line:?} -> {kind}",
+                        path.display(),
+                        index + 1
+                    ));
+                }
+                position = at + 1;
+            }
+
+            if let Some(pattern) = numeric_color_call(line) {
+                offenders.push(format!(
+                    "{}:{} {line:?} -> {pattern}",
+                    path.display(),
+                    index + 1
+                ));
+            }
+
+            if color_struct_literal(line) {
+                offenders.push(format!(
+                    "{}:{} {line:?} -> Color {{ r: … }} 结构体字面量",
+                    path.display(),
+                    index + 1
+                ));
+            }
+        }
+    }
+
+    assert!(
+        offenders.is_empty(),
+        "组件层不许出现色值字面量（一律走 unlucky_design 的 Role）：\n{}",
+        offenders.join("\n")
+    );
+}
+
+/// 判断某个布局调用后面是不是直接跟了尺寸字面量；`0`（= 无内边距）放行。
+///
+/// iced 里尺寸经常被包一层：`.width(Length::Fixed(123.0))`、`.padding(Padding::from([12.0, 8.0]))`、
+/// `.size(Size::new(10.0, 10.0))` —— 所以遇到这些包装要**往里剥一层**再判。
+fn size_literal(argument: &str) -> Option<String> {
+    let mut rest = argument.trim_start();
+
+    for wrapper in ["Length::Fixed(", "Padding::from(", "Size::new("] {
+        if let Some(after) = rest.strip_prefix(wrapper) {
+            rest = after.trim_start().trim_start_matches(['[', '(']);
+            break;
+        }
+    }
+
+    let number: String = rest
+        .trim_start()
+        .chars()
+        .take_while(|ch| ch.is_ascii_digit() || *ch == '.')
+        .collect();
+
+    if number.is_empty() || number.trim_end_matches('.').parse::<f64>() == Ok(0.0) {
+        return None;
+    }
+
+    Some(number)
+}
+
+#[test]
+fn shell_takes_every_size_from_tokens() {
+    let mut files = Vec::new();
+    rust_files(&manifest_dir().join("src").join("shell"), &mut files);
+    assert!(
+        files.len() >= 2,
+        "shell 模块至少有两个文件（mod.rs + nav.rs），实际扫到 {}",
+        files.len()
+    );
+
+    let mut offenders = Vec::new();
+
+    for path in files {
+        let text = std::fs::read_to_string(&path).expect("读 shell 源文件");
+
+        for (index, line) in text.lines().enumerate() {
+            // 文档注释是散文不是代码：里面写 `.width(24)` 是在解释坑，不该判违规
+            if line.trim_start().starts_with("//") {
+                continue;
+            }
+
+            for pattern in [".width(", ".height(", ".size(", ".spacing(", ".padding("] {
+                let mut from = 0;
+                while let Some(found) = line[from..].find(pattern) {
+                    let after = from + found + pattern.len();
+                    if let Some(number) = size_literal(&line[after..]) {
+                        offenders.push(format!(
+                            "{}:{} {line:?} -> {pattern} 后面直接写了数字 {number}",
+                            path.display(),
+                            index + 1
+                        ));
+                    }
+                    from = after;
+                }
+            }
+        }
+    }
+
+    assert!(
+        offenders.is_empty(),
+        "骨架尺寸必须来自 LayoutMetrics / TypeStyle / Space：\n{}",
+        offenders.join("\n")
+    );
+}
+
+/// 依赖行里出现 `slint` 就算违规（注释行放过：说明并存期要提到 slint）。
+fn manifest_has_slint_dependency(manifest: &str) -> Vec<String> {
+    manifest
+        .lines()
+        .enumerate()
+        .filter(|(_, line)| {
+            let trimmed = line.trim_start();
+            !trimmed.starts_with('#') && trimmed.contains("slint")
+        })
+        .map(|(index, line)| format!("Cargo.toml:{} {line}", index + 1))
+        .collect()
+}
+
+#[test]
+fn this_crate_never_depends_on_slint() {
+    let manifest =
+        std::fs::read_to_string(manifest_dir().join("Cargo.toml")).expect("读 Cargo.toml");
+
+    let offenders = manifest_has_slint_dependency(&manifest);
+    assert!(
+        offenders.is_empty(),
+        "P4 的 iced 版 crate 不许依赖 slint（D26）：\n{}",
+        offenders.join("\n")
+    );
+
+    for (path, text) in sources() {
+        for (index, line) in text.lines().enumerate() {
+            // 只查真代码里的 use/路径，文档里提 slint 是允许的（要解释并存期）
+            let code = line.trim_start();
+            let is_import = code.starts_with("use ") || code.starts_with("extern crate");
+            if is_import && code.contains("slint") {
+                panic!("{}:{} 引入了 slint：{line}", path.display(), index + 1);
+            }
+        }
+    }
+}
+
+#[test]
+fn the_gate_itself_catches_a_planted_violation() {
+    // 自检：把违规样本喂给同一套判定，必须被抓住（否则门禁是空转）。
+    // **reviewer r1 造样验证过的 5 个漏网样本逐条钉在这里**，退化成「放行」立刻红。
+
+    // 1. `Color::from_rgb8(103, 80, 164)` —— 8bit 版曾因 `from_rgb(` 匹配不到而漏
+    assert!(numeric_color_call("Color::from_rgb8(103, 80, 164)").is_some());
+    // 2. `iced::Color::from_rgb8(...)` —— 带路径前缀的写法同样要拦
+    assert!(numeric_color_call("iced::Color::from_rgb8(103, 80, 164)").is_some());
+    // 3. `Color { r: 0.4, g: 0.3, b: 0.6, a: 1.0 }` —— 结构体字面量
+    assert!(color_struct_literal(
+        "Color { r: 0.4, g: 0.3, b: 0.6, a: 1.0 }"
+    ));
+    // 4. `.width(Length::Fixed(123.0))` —— 尺寸被 iced 包装一层
+    assert_eq!(
+        size_literal("Length::Fixed(123.0))").as_deref(),
+        Some("123.0")
+    );
+    // 5. `.padding(Padding::from([12.0, 8.0]))` —— 数组字面量
+    assert_eq!(
+        size_literal("Padding::from([12.0, 8.0]))").as_deref(),
+        Some("12.0")
+    );
+
+    // 原有规则不能退化
+    assert!(hex_color_at(b"    color: #6750A4,", 11).is_some());
+    assert!(hex_color_at(b"// placeholder #RRGGBB here", 15).is_none());
+    assert!(numeric_color_call("Color::from_rgb(0.1, 0.2, 0.3)").is_some());
+    assert!(numeric_color_call("Color::from_rgba8(color.r, color.g, color.b, color.a)").is_none());
+    assert!(numeric_color_call("color!(0x5865F2)").is_some());
+    assert!(size_literal("40.0)").is_some());
+    assert!(size_literal("0)").is_none());
+    assert!(size_literal("metrics.titlebar_height)").is_none());
+    assert!(size_literal("Length::Fixed(thickness))").is_none());
+    assert!(size_literal("Padding::from([0.0, ui.space(Space::X4)]))").is_none());
+    assert!(!color_struct_literal(
+        "Color::from_rgba8(color.r, color.g, color.b, 1.0)"
+    ));
+    assert!(!color_struct_literal("let color = Color { a: 0.5 };"));
+    assert!(!manifest_has_slint_dependency("slint = \"1.18\"").is_empty());
+    assert!(manifest_has_slint_dependency("# 不得依赖 slint").is_empty());
+}
+
+/// 渲染层回归守门（视觉复审 P2-1 的教训）：`indicator_matches_the_reference_56x32` 只测纯函数，
+/// 门禁全绿但图上的药丸实际是 88×32 —— 因为 `.center_x(Length::Fill)` 会把容器 width 覆盖成 Fill。
+/// 这里直接扫 `nav.rs`：药丸容器**不许**出现 `center_x(` / `center_y(`。
+#[test]
+fn pill_never_overrides_its_size_with_fill() {
+    let nav = manifest_dir().join("src").join("shell").join("nav.rs");
+    let text = std::fs::read_to_string(&nav).expect("读 nav.rs");
+
+    for (index, line) in text.lines().enumerate() {
+        let code = line.trim_start();
+        if code.starts_with("//") {
+            continue;
+        }
+        for pattern in ["center_x(", "center_y("] {
+            assert!(
+                !code.contains(pattern),
+                "nav.rs:{} 用了 {pattern}——`center_*(Length::Fill)` 会把容器尺寸改成 Fill，                 药丸会被父级宽度覆盖（视觉复审 P2-1）。居中请用父级 `align_x`：{line}",
+                index + 1
+            );
+        }
+    }
+}

crates/design/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "unlucky-design"
+description = "Unlucky-Launcher 设计令牌：M3 Expressive 色彩/排版/形状/高程/动效/图标，纯数据 + 纯函数，零 UI 依赖"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+# 零 UI 依赖是硬约束（D3 纪律 + M61）：本 crate 是渲染无关的**数据与纯函数**，
+# 不得出现 iced / slint / winit / wgpu / gtk / egui / tauri 等 UI 或渲染框架，
+# 也不引入任何第三方 crate（连 serde 都不加——序列化由消费方适配层自己做）。
+# 证据命令：cargo tree -p unlucky-design --edges normal
+[dependencies]
+
+[lints]
+workspace = true

crates/design/src/color/cam16.rs

@@ -0,0 +1,120 @@
+//! CAM16 正向换算：sRGB 色值 → CAM16 的 **hue**（色相角）与 **chroma**（彩度）。
+//!
+//! HCT = **H**ue / **C**hroma from CAM16 + **T**one from `L*`。这里只实现 M3 用到的方向
+//! （色值 → hue/chroma）；反向（hue/chroma/tone → 色值）在 [`super::hct_solver`] 里按官方
+//! 求解器内联实现——两边如果各写一份，数值会对不上。
+//!
+//! 照搬 `java/hct/Cam16.java`（Apache-2.0，见 `NOTICE`），逐行对应，包括 `Math.signum` 的
+//! 「零返回 0」这种 Java 语义差别（见 [`space::signum`]）。
+
+use super::space::{self, signum};
+use super::viewing_conditions::{default_conditions, ViewingConditions};
+use super::Color;
+
+/// XYZ → CAM16 的「锥体响应」矩阵。
+pub(crate) const XYZ_TO_CAM16_RGB: [[f64; 3]; 3] = [
+    [0.401_288, 0.650_173, -0.051_461],
+    [-0.250_268, 1.204_414, 0.045_854],
+    [-0.002_079, 0.048_952, 0.953_127],
+];
+
+/// CAM16 里 M3 真正用到的两个坐标（`J` 明度不参与 HCT，HCT 的 tone 走 `L*`）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub(crate) struct Cam16 {
+    /// 色相角（度，`0..360`）。
+    pub(crate) hue: f64,
+    /// 彩度（无上限；sRGB 立方体内最大值约 130）。
+    pub(crate) chroma: f64,
+}
+
+impl Cam16 {
+    /// 从色值取 CAM16 色相/彩度（默认 sRGB 观察条件）。
+    pub(crate) fn from_color(color: Color) -> Self {
+        Self::from_xyz(space::xyz_from_color(color), default_conditions())
+    }
+
+    /// 从 XYZ 取 CAM16 色相/彩度。
+    pub(crate) fn from_xyz(xyz: [f64; 3], vc: &ViewingConditions) -> Self {
+        let [r_t, g_t, b_t] = space::matrix_multiply(xyz, XYZ_TO_CAM16_RGB);
+
+        // 折扣光源（色适应）
+        let r_d = vc.rgb_d[0] * r_t;
+        let g_d = vc.rgb_d[1] * g_t;
+        let b_d = vc.rgb_d[2] * b_t;
+
+        // 非线性压缩（视觉响应）
+        let r_af = (vc.fl * r_d.abs() / 100.0).powf(0.42);
+        let g_af = (vc.fl * g_d.abs() / 100.0).powf(0.42);
+        let b_af = (vc.fl * b_d.abs() / 100.0).powf(0.42);
+        let r_a = signum(r_d) * 400.0 * r_af / (r_af + 27.13);
+        let g_a = signum(g_d) * 400.0 * g_af / (g_af + 27.13);
+        let b_a = signum(b_d) * 400.0 * b_af / (b_af + 27.13);
+
+        // 红绿 / 黄蓝对立通道
+        let a = (11.0 * r_a - 12.0 * g_a + b_a) / 11.0;
+        let b = (r_a + g_a - 2.0 * b_a) / 9.0;
+
+        // 辅助量
+        let u = (20.0 * r_a + 20.0 * g_a + 21.0 * b_a) / 20.0;
+        let p2 = (40.0 * r_a + 20.0 * g_a + b_a) / 20.0;
+
+        let hue = space::sanitize_degrees(b.atan2(a).to_degrees());
+        let ac = p2 * vc.nbb;
+        let j = 100.0 * (ac / vc.aw).powf(vc.c * vc.z);
+
+        // 彩度：eHue 的 20.14° 断点是官方原样（把橙红段挪到 0 附近做插值）
+        let hue_prime = if hue < 20.14 { hue + 360.0 } else { hue };
+        let e_hue = 0.25 * ((hue_prime.to_radians() + 2.0).cos() + 3.8);
+        let p1 = 50_000.0 / 13.0 * e_hue * vc.nc * vc.ncb;
+        let t = p1 * a.hypot(b) / (u + 0.305);
+        let alpha = (1.64 - 0.29_f64.powf(vc.n)).powf(0.73) * t.powf(0.9);
+        let chroma = alpha * (j / 100.0).sqrt();
+
+        Self { hue, chroma }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn primaries_have_the_official_hue_angles() {
+        // 官方 material-color-utilities 对纯红/绿/蓝解出的 CAM16 色相（Java 实测）。
+        let cases = [
+            (Color::rgb(255, 0, 0), 27.408_225, 113.357_887),
+            (Color::rgb(0, 255, 0), 142.139_894, 108.410_061),
+            (Color::rgb(0, 0, 255), 282.788_18, 87.230_694),
+        ];
+        for (color, hue, chroma) in cases {
+            let cam = Cam16::from_color(color);
+            assert!(
+                (cam.hue - hue).abs() < 1.0e-4,
+                "{} 的 hue 是 {}，官方 {hue}",
+                color.to_hex(),
+                cam.hue
+            );
+            assert!(
+                (cam.chroma - chroma).abs() < 1.0e-4,
+                "{} 的 chroma 是 {}，官方 {chroma}",
+                color.to_hex(),
+                cam.chroma
+            );
+        }
+    }
+
+    #[test]
+    fn gray_has_near_zero_chroma() {
+        for value in [16_u8, 64, 128, 200] {
+            let cam = Cam16::from_color(Color::rgb(value, value, value));
+            assert!(cam.chroma < 2.5, "灰 {value} 的彩度 {}", cam.chroma);
+        }
+    }
+
+    #[test]
+    fn black_is_finite() {
+        let cam = Cam16::from_color(Color::BLACK);
+        assert!(cam.hue.is_finite() && cam.chroma.is_finite());
+        assert_eq!(cam.chroma, 0.0);
+    }
+}

crates/design/src/color/critical_planes.rs

@@ -0,0 +1,77 @@
+//! 官方 `HctSolver.CRITICAL_PLANES` 表（255 项，**原样搬运**）。
+//!
+//! 这不是可以推导的常数集：它是 HCT 求解器在 sRGB 立方体上按 `Y` 找边界、再做色相二分时的
+//! 「关键平面」索引表，由 Google 的脚本一次性生成后冻结。逐值复制是唯一忠实的做法——
+//! 表错了，极端 tone（深色/浅色端）的颜色会偏一两个通道。
+//!
+//! 来源：`material-color-utilities/java/hct/HctSolver.java`（Apache-2.0），见仓库根 `NOTICE`。
+
+/// sRGB 立方体上按 `Y` 递增排序的关键平面（线性 RGB 0..=100 标度）。
+///
+/// 手写密度由 `#[rustfmt::skip]` 保住：这张表是数据，不是代码，一列一个数会撑到 266 行。
+#[rustfmt::skip]
+pub(crate) const CRITICAL_PLANES: [f64; 255] = [
+    0.015176349177441876, 0.045529047532325624, 0.07588174588720938, 0.10623444424209313,
+    0.13658714259697685, 0.16693984095186062, 0.19729253930674434, 0.2276452376616281,
+    0.2579979360165119, 0.28835063437139563, 0.3188300904430532, 0.350925934958123,
+    0.3848314933096426, 0.42057480301049466, 0.458183274052838, 0.4976837250274023,
+    0.5391024159806381, 0.5824650784040898, 0.6277969426914107, 0.6751227633498623,
+    0.7244668422128921, 0.775853049866786, 0.829304845476233, 0.8848452951698498,
+    0.942497089126609, 1.0022825574869039, 1.0642236851973577, 1.1283421258858297,
+    1.1946592148522128, 1.2631959812511864, 1.3339731595349034, 1.407011200216447,
+    1.4823302800086415, 1.5599503113873272, 1.6398909516233677, 1.7221716113234105,
+    1.8068114625156377, 1.8938294463134073, 1.9832442801866852, 2.075074464868551,
+    2.1693382909216234, 2.2660538449872063, 2.36523901573795, 2.4669114995532007,
+    2.5710888059345764, 2.6777882626779785, 2.7870270208169257, 2.898822059350997,
+    3.0131901897720907, 3.1301480604002863, 3.2497121605402226, 3.3718988244681087,
+    3.4967242352587946, 3.624204428461639, 3.754355295633311, 3.887192587735158,
+    4.022731918402185, 4.160988767090289, 4.301978482107941, 4.445716283538092,
+    4.592217266055746, 4.741496401646282, 4.893568542229298, 5.048448422192488,
+    5.20615066083972, 5.3666897647573375, 5.5300801301023865, 5.696336044816294,
+    5.865471690767354, 6.037501145825082, 6.212438385869475, 6.390297286737924,
+    6.571091626112461, 6.7548350853498045, 6.941541251256611, 7.131223617812143,
+    7.323895587840543, 7.5195704746346665, 7.7182615035334345, 7.919981813454504,
+    8.124744458384042, 8.332562408825165, 8.543448553206703, 8.757415699253682,
+    8.974476575321063, 9.194643831691977, 9.417930041841839, 9.644347703669503,
+    9.873909240696694, 10.106627003236781, 10.342513269534024, 10.58158024687427,
+    10.8238400726681, 11.069304815507364, 11.317986476196008, 11.569896988756009,
+    11.825048221409341, 12.083451977536606, 12.345119996613247, 12.610063955123938,
+    12.878295467455942, 13.149826086772048, 13.42466730586372, 13.702830557985108,
+    13.984327217668513, 14.269168601521828, 14.55736596900856, 14.848930523210871,
+    15.143873411576273, 15.44220572664832, 15.743938506781891, 16.04908273684337,
+    16.35764934889634, 16.66964922287304, 16.985093187232053, 17.30399201960269,
+    17.62635644741625, 17.95219714852476, 18.281524751807332, 18.614349837764564,
+    18.95068293910138, 19.290534541298456, 19.633915083172692, 19.98083495742689,
+    20.331304511189067, 20.685334046541502, 21.042933821039977, 21.404114048223256,
+    21.76888489811322, 22.137256497705877, 22.50923893145328, 22.884842241736916,
+    23.264076429332462, 23.6469514538663, 24.033477234264016, 24.42366364919083,
+    24.817520537484558, 25.21505769858089, 25.61628489293138, 26.021211842414342,
+    26.429848230738664, 26.842203703840827, 27.258287870275353, 27.678110301598522,
+    28.10168053274597, 28.529008062403893, 28.96010235337422, 29.39497283293396,
+    29.83362889318845, 30.276079891419332, 30.722335150426627, 31.172403958865512,
+    31.62629557157785, 32.08401920991837, 32.54558406207592, 33.010999283389665,
+    33.4802739966603, 33.953417292456834, 34.430438229418264, 34.911345834551085,
+    35.39614910352207, 35.88485700094671, 36.37747846067349, 36.87402238606382,
+    37.37449765026789, 37.87891309649659, 38.38727753828926, 38.89959975977785,
+    39.41588851594697, 39.93615253289054, 40.460400508064545, 40.98864111053629,
+    41.520882981230194, 42.05713473317016, 42.597404951718396, 43.141702194811224,
+    43.6900349931913, 44.24241185063697, 44.798841244188324, 45.35933162437017,
+    45.92389141541209, 46.49252901546552, 47.065252796817916, 47.64207110610409,
+    48.22299226451468, 48.808024568002054, 49.3971762874833, 49.9904556690408,
+    50.587870934119984, 51.189430279724725, 51.79514187861014, 52.40501387947288,
+    53.0190544071392, 53.637271562750364, 54.259673423945976, 54.88626804504493,
+    55.517063457223934, 56.15206766869424, 56.79128866487574, 57.43473440856916,
+    58.08241284012621, 58.734331877617365, 59.39049941699807, 60.05092333227251,
+    60.715611475655585, 61.38457167773311, 62.057811747619894, 62.7353394731159,
+    63.417162620860914, 64.10328893648692, 64.79372614476921, 65.48848194977529,
+    66.18756403501224, 66.89098006357258, 67.59873767827808, 68.31084450182222,
+    69.02730813691093, 69.74813616640164, 70.47333615344107, 71.20291564160104,
+    71.93688215501312, 72.67524319850172, 73.41800625771542, 74.16517879925733,
+    74.9167682708136, 75.67278210128072, 76.43322770089146, 77.1981124613393, 77.96744375590167,
+    78.74122893956174, 79.51947534912904, 80.30219030335869, 81.08938110306934,
+    81.88105503125999, 82.67721935322541, 83.4778813166706, 84.28304815182372,
+    85.09272707154808, 85.90692527145302, 86.72564993000343, 87.54890820862819,
+    88.3767072518277, 89.2090541872801, 90.04595612594655, 90.88742016217518, 91.73345337380438,
+    92.58406282226491, 93.43925555268066, 94.29903859396902, 95.16341895893969,
+    96.03240364439274, 96.9059996312159, 97.78421388448044, 98.6670533535366, 99.55452497210776,
+];

crates/design/src/color/hct.rs

@@ -0,0 +1,160 @@
+//! **HCT** 色彩空间：色相/彩度取自 CAM16，亮度取自 CIELAB 的 `L*`（即 M3 的 tone）。
+//!
+//! 为什么不是 OKLab/HSL：`L*` 与人眼感知线性的**对比度**直接挂钩（`Y` 是它的单调函数），
+//! 所以「tone 差 40 ⇒ 对比度 ≥ 3:1」「tone 差 50 ⇒ ≥ 4.5:1」这类性质在 HCT 里是恒等式，
+//! 换任何种子色都成立。CAM16 的色相/彩度则保证「同一条调色板只有一种色相」在感知上也是真的。
+//!
+//! 语义与官方 `java/hct/Hct.java` 一致：`Hct` 的真身是那个 **8 bit 色值**，`hue/chroma/tone`
+//! 是它的测量值。所以 [`Hct::from_components`] 解出来的 `tone` 可能比请求值差一点点
+//! （例如请求 tone 40、实测 40.08），官方也是这样——请求值只是求解目标。
+//!
+//! 来源：`material-color-utilities`（Apache-2.0），见仓库根 `NOTICE`。
+
+use super::space;
+use super::{cam16::Cam16, hct_solver, Color};
+
+/// 一个色值的 HCT 坐标。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Hct {
+    /// CAM16 色相角（度，`0..360`）。
+    pub hue: f64,
+    /// CAM16 彩度（无上限；sRGB 立方体内约 0..=130）。
+    pub chroma: f64,
+    /// CIELAB `L*`（0 = 黑 / 100 = 白）——M3 里叫 **tone**。
+    pub tone: f64,
+    /// 这个坐标对应的 8 bit 色值（HCT 的真身）。
+    color: Color,
+}
+
+impl Hct {
+    /// 量一个色值的 HCT 坐标。
+    pub fn from_color(color: Color) -> Self {
+        let cam = Cam16::from_color(color);
+        Self {
+            hue: cam.hue,
+            chroma: cam.chroma,
+            tone: space::lstar_from_color(color),
+            color,
+        }
+    }
+
+    /// 解 HCT 方程：给定色相/彩度/tone，求最接近的 sRGB 色值。
+    ///
+    /// 彩度装不下时**只压彩度**（色相与 tone 保住），这就是 M3 的 gamut 映射；
+    /// 返回值的 `tone` 是实测值，可能与 `tone` 参数相差千分之几。
+    pub fn from_components(hue: f64, chroma: f64, tone: f64) -> Self {
+        Self::from_color(hct_solver::solve_to_color(hue, chroma, tone))
+    }
+
+    /// 该坐标对应的色值。
+    pub fn to_color(self) -> Color {
+        self.color
+    }
+
+    /// 色相是否落在「黄」段（官方 `TonalPalette` 的 tone 99 特例用它）。
+    pub fn is_yellow(hue: f64) -> bool {
+        (105.0..125.0).contains(&hue)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// 官方 Java 实测的种子色 HCT 坐标（`hct.Count` 打印，APCA/CAM16 D65 默认条件）。
+    const SEED_HCT: [(&str, f64, f64, f64); 6] = [
+        ("#6750A4", 298.980_997, 47.856_526, 40.083_244),
+        ("#FF0000", 27.408_225, 113.357_887, 53.232_882),
+        ("#00FF00", 142.139_894, 108.410_061, 87.737_033),
+        ("#0000FF", 282.788_18, 87.230_694, 32.302_587),
+        ("#6E7C8A", 245.036_867, 14.675_86, 51.342_101),
+        ("#D000FF", 324.929_26, 99.544_477, 52.542_037),
+    ];
+
+    #[test]
+    fn seed_coordinates_match_official() {
+        for (hex, hue, chroma, tone) in SEED_HCT {
+            let hct = Hct::from_color(Color::from_hex(hex).expect("合法 hex"));
+            assert!((hct.hue - hue).abs() < 1.0e-4, "{hex} hue {}", hct.hue);
+            assert!(
+                (hct.chroma - chroma).abs() < 1.0e-4,
+                "{hex} chroma {}",
+                hct.chroma
+            );
+            assert!((hct.tone - tone).abs() < 1.0e-4, "{hex} tone {}", hct.tone);
+        }
+    }
+
+    #[test]
+    fn solver_reproduces_official_hexes() {
+        // 官方 Java 实测（`hct.Probe`）：同一组 (h, c, t) 必须解出同一个 hex。
+        let cases = [
+            (95.0, 36.0, 40.0, "#705D0D"),
+            (298.98, 36.0, 90.0, "#E9DDFF"),
+            (25.0, 84.0, 80.0, "#FFB4AB"),
+            (245.0, 16.0, 80.0, "#B8C8D9"),
+            (245.0, 42.0, 30.0, "#004B72"),
+            (10.0, 120.0, 5.0, "#2C000A"),
+            (245.0, 4.0, 30.0, "#45474A"),
+        ];
+        for (hue, chroma, tone, hex) in cases {
+            assert_eq!(
+                hct_solver::solve_to_color(hue, chroma, tone).to_hex(),
+                hex,
+                "HCT({hue}, {chroma}, {tone}) 与官方不一致"
+            );
+        }
+    }
+
+    #[test]
+    fn solver_keeps_hue_and_tone_when_chroma_is_available() {
+        for (hue, chroma, tone) in [
+            (95.0, 36.0, 40.0),
+            (298.98, 36.0, 90.0),
+            (245.0, 42.0, 30.0),
+            (25.0, 84.0, 80.0),
+            (245.0, 16.0, 80.0),
+        ] {
+            let solved = Hct::from_components(hue, chroma, tone);
+            assert_eq!(
+                solved.to_color(),
+                hct_solver::solve_to_color(hue, chroma, tone)
+            );
+            assert!(
+                (solved.tone - tone).abs() < 1.0,
+                "tone {} vs {tone}",
+                solved.tone
+            );
+            let delta = (solved.hue - hue)
+                .abs()
+                .min(360.0 - (solved.hue - hue).abs());
+            assert!(delta < 1.0, "色相 {} vs {hue}", solved.hue);
+            assert!(
+                solved.chroma <= chroma + 1.0,
+                "彩度反被拉高：{}",
+                solved.chroma
+            );
+        }
+    }
+
+    #[test]
+    fn low_chroma_hue_is_ill_conditioned_even_officially() {
+        // 彩度 8 在 tone 30 上，8 bit 量化会让 CAM16 色相跳 6°——官方同样如此
+        // （Java 实测 HCT(245,8,30) → #42474E / hue 251.5965）。这条钉的是「别去修它」。
+        let solved = Hct::from_components(245.0, 8.0, 30.0);
+        assert_eq!(solved.to_color().to_hex(), "#42474E");
+        assert!(
+            (solved.hue - 251.596_498).abs() < 1.0e-4,
+            "hue {}",
+            solved.hue
+        );
+    }
+
+    #[test]
+    fn yellow_band_matches_official_definition() {
+        assert!(Hct::is_yellow(105.0));
+        assert!(Hct::is_yellow(124.9));
+        assert!(!Hct::is_yellow(125.0));
+        assert!(!Hct::is_yellow(104.9));
+    }
+}

crates/design/src/color/hct_solver.rs

@@ -0,0 +1,311 @@
+//! HCT 求解器：给定 `(hue, chroma, tone)` 求 sRGB 色值——**这就是 M3 的 gamut 映射**。
+//!
+//! M3 不做「越界就硬裁」：它先假设色域足够，用 Newton 迭代解出线性 RGB；只有当解落进 sRGB
+//! 立方体之外时，才退到「在色调平面（`Y` 恒定）上沿色相二分」，把彩度压到该色相能取到的最大值，
+//! **色相与 tone 都保持不变**。所以深色/浅色端的颜色是「变灰」而不是「变色」。
+//!
+//! 照搬 `java/hct/HctSolver.java`（Apache-2.0，见 `NOTICE`）：两段（Newton + 二分）、
+//! 迭代次数、`100.01` 这类边界容差都一致。关键平面表见 [`super::critical_planes`]。
+
+use super::space::{self, signum};
+use super::viewing_conditions::default_conditions;
+use super::Color;
+
+/// 线性 RGB → 「折扣光源」标度的矩阵（求解器内联版，与 [`super::cam16`] 等价但省一次除法）。
+const SCALED_DISCOUNT_FROM_LINRGB: [[f64; 3]; 3] = [
+    [
+        0.001_200_833_568_784_504,
+        0.002_389_694_492_170_889,
+        0.000_279_574_288_586_112_4,
+    ],
+    [
+        0.000_589_108_665_137_599_9,
+        0.002_978_550_257_343_875_8,
+        0.000_327_066_610_400_839_8,
+    ],
+    [
+        0.000_101_466_924_916_405_72,
+        0.000_536_421_435_918_669_4,
+        0.003_297_940_177_071_207_6,
+    ],
+];
+
+/// 「折扣光源」标度 → 线性 RGB（[`SCALED_DISCOUNT_FROM_LINRGB`] 的逆）。
+const LINRGB_FROM_SCALED_DISCOUNT: [[f64; 3]; 3] = [
+    [
+        1_373.219_870_959_423_1,
+        -1_100.425_119_075_482_1,
+        -7.278_681_089_101_213,
+    ],
+    [
+        -271.815_969_077_903,
+        559.658_046_594_073_3,
+        -32.460_474_827_911_94,
+    ],
+    [
+        1.962_289_959_966_566_6,
+        -57.173_814_538_844_006,
+        308.723_319_781_238_5,
+    ],
+];
+
+/// 线性 RGB 的 `Y` 权重（Rec.709 亮度系数）。
+const Y_FROM_LINRGB: [f64; 3] = [0.2126, 0.7152, 0.0722];
+
+/// `(hue, chroma, tone)` → 色值。彩度取不到时压到该色相/色调下的最大值（色相与 tone 不变）。
+pub(crate) fn solve_to_color(hue_degrees: f64, chroma: f64, lstar: f64) -> Color {
+    // 端点与极低彩度直接走灰：官方用同一断点，保证 tone 0/100 是纯黑/纯白。
+    if chroma < 0.0001 || lstar < 0.0001 || lstar > 99.9999 {
+        return space::color_from_lstar(lstar);
+    }
+    let hue_radians = space::sanitize_degrees(hue_degrees).to_radians();
+    let y = space::y_from_lstar(lstar);
+    if let Some(exact) = find_result_by_j(hue_radians, chroma, y) {
+        return exact;
+    }
+    space::color_from_linrgb(bisect_to_limit(y, hue_radians))
+}
+
+/// 牛顿迭代直接解（色域内能解出来时，这条路径是精确解）。
+fn find_result_by_j(hue_radians: f64, chroma: f64, y: f64) -> Option<Color> {
+    let vc = default_conditions();
+    let mut j = y.sqrt() * 11.0;
+    let t_inner_coeff = 1.0 / (1.64 - 0.29_f64.powf(vc.n)).powf(0.73);
+    let e_hue = 0.25 * ((hue_radians + 2.0).cos() + 3.8);
+    let p1 = e_hue * (50_000.0 / 13.0) * vc.nc * vc.ncb;
+    let h_sin = hue_radians.sin();
+    let h_cos = hue_radians.cos();
+    for round in 0..5 {
+        let j_normalized = j / 100.0;
+        let alpha = if chroma == 0.0 || j == 0.0 {
+            0.0
+        } else {
+            chroma / j_normalized.sqrt()
+        };
+        let t = (alpha * t_inner_coeff).powf(1.0 / 0.9);
+        let ac = vc.aw * j_normalized.powf(1.0 / vc.c / vc.z);
+        let p2 = ac / vc.nbb;
+        let gamma = 23.0 * (p2 + 0.305) * t / (23.0 * p1 + 11.0 * t * h_cos + 108.0 * t * h_sin);
+        let a = gamma * h_cos;
+        let b = gamma * h_sin;
+        let r_a = (460.0 * p2 + 451.0 * a + 288.0 * b) / 1403.0;
+        let g_a = (460.0 * p2 - 891.0 * a - 261.0 * b) / 1403.0;
+        let b_a = (460.0 * p2 - 220.0 * a - 6300.0 * b) / 1403.0;
+        let linrgb = space::matrix_multiply(
+            [
+                inverse_chromatic_adaptation(r_a),
+                inverse_chromatic_adaptation(g_a),
+                inverse_chromatic_adaptation(b_a),
+            ],
+            LINRGB_FROM_SCALED_DISCOUNT,
+        );
+        if linrgb[0] < 0.0 || linrgb[1] < 0.0 || linrgb[2] < 0.0 {
+            return None;
+        }
+        let f_nj = Y_FROM_LINRGB[0] * linrgb[0]
+            + Y_FROM_LINRGB[1] * linrgb[1]
+            + Y_FROM_LINRGB[2] * linrgb[2];
+        if f_nj <= 0.0 {
+            return None;
+        }
+        if round == 4 || (f_nj - y).abs() < 0.002 {
+            if linrgb[0] > 100.01 || linrgb[1] > 100.01 || linrgb[2] > 100.01 {
+                return None;
+            }
+            return Some(space::color_from_linrgb(linrgb));
+        }
+        // Newton：用 2 * fn(j) / j 近似 fn'(j)
+        j -= (f_nj - y) * j / (2.0 * f_nj);
+    }
+    None
+}
+
+/// 色域外时的兜底：在 `Y` 恒定的平面上按色相二分，取边界上的颜色。
+fn bisect_to_limit(y: f64, target_hue: f64) -> [f64; 3] {
+    let (mut left, mut right) = bisect_to_segment(y, target_hue);
+    let mut left_hue = hue_of(left);
+    for axis in 0..3 {
+        if left[axis] == right[axis] {
+            continue;
+        }
+        let (mut l_plane, mut r_plane) = if left[axis] < right[axis] {
+            (
+                critical_plane_below(space::true_delinearized(left[axis])),
+                critical_plane_above(space::true_delinearized(right[axis])),
+            )
+        } else {
+            (
+                critical_plane_above(space::true_delinearized(left[axis])),
+                critical_plane_below(space::true_delinearized(right[axis])),
+            )
+        };
+        for _ in 0..8 {
+            if (r_plane - l_plane).abs() <= 1 {
+                break;
+            }
+            let m_plane = ((f64::from(l_plane) + f64::from(r_plane)) / 2.0).floor() as i32;
+            let coordinate = super::critical_planes::CRITICAL_PLANES[m_plane as usize];
+            let mid = set_coordinate(left, coordinate, right, axis);
+            let mid_hue = hue_of(mid);
+            if are_in_cyclic_order(left_hue, target_hue, mid_hue) {
+                right = mid;
+                r_plane = m_plane;
+            } else {
+                left = mid;
+                left_hue = mid_hue;
+                l_plane = m_plane;
+            }
+        }
+    }
+    midpoint(left, right)
+}
+
+/// 找到包含目标色相的边界线段（sRGB 立方体与 `Y` 平面的交是多边形）。
+fn bisect_to_segment(y: f64, target_hue: f64) -> ([f64; 3], [f64; 3]) {
+    let mut left = [-1.0_f64; 3];
+    let mut right = left;
+    let mut left_hue = 0.0;
+    let mut initialized = false;
+    let mut uncut = true;
+    for n in 0..12 {
+        let Some(mid) = nth_vertex(y, n) else {
+            continue;
+        };
+        let mid_hue = hue_of(mid);
+        if !initialized {
+            initialized = true;
+            left = mid;
+            right = mid;
+            left_hue = mid_hue;
+            continue;
+        }
+        if uncut || are_in_cyclic_order(left_hue, mid_hue, hue_of(right)) {
+            uncut = false;
+            if are_in_cyclic_order(left_hue, target_hue, mid_hue) {
+                right = mid;
+            } else {
+                left = mid;
+                left_hue = mid_hue;
+            }
+        }
+    }
+    (left, right)
+}
+
+/// `Y` 平面与立方体的第 `n` 个顶点（不在立方体内返回 `None`）。
+fn nth_vertex(y: f64, n: usize) -> Option<[f64; 3]> {
+    let [k_r, k_g, k_b] = Y_FROM_LINRGB;
+    let coord_a = if n % 4 <= 1 { 0.0 } else { 100.0 };
+    let coord_b = if n.is_multiple_of(2) { 0.0 } else { 100.0 };
+    let vertex = if n < 4 {
+        let (g, b) = (coord_a, coord_b);
+        [((y - g * k_g - b * k_b) / k_r), g, b]
+    } else if n < 8 {
+        let (b, r) = (coord_a, coord_b);
+        [r, ((y - r * k_r - b * k_b) / k_g), b]
+    } else {
+        let (r, g) = (coord_a, coord_b);
+        [r, g, ((y - r * k_r - g * k_g) / k_b)]
+    };
+    if vertex.iter().all(|c| (0.0..=100.0).contains(c)) {
+        Some(vertex)
+    } else {
+        None
+    }
+}
+
+/// 线性 RGB 的色相（弧度，未归一）。
+fn hue_of(linrgb: [f64; 3]) -> f64 {
+    let scaled = space::matrix_multiply(linrgb, SCALED_DISCOUNT_FROM_LINRGB);
+    let r_a = chromatic_adaptation(scaled[0]);
+    let g_a = chromatic_adaptation(scaled[1]);
+    let b_a = chromatic_adaptation(scaled[2]);
+    let a = (11.0 * r_a - 12.0 * g_a + b_a) / 11.0;
+    let b = (r_a + g_a - 2.0 * b_a) / 9.0;
+    b.atan2(a)
+}
+
+/// 角度上 `b` 是否落在 `a → c` 的前进区间内。
+fn are_in_cyclic_order(a: f64, b: f64, c: f64) -> bool {
+    space::sanitize_radians(b - a) < space::sanitize_radians(c - a)
+}
+
+/// 把线段 `source → target` 在 `axis` 上截到 `coordinate`。
+fn set_coordinate(source: [f64; 3], coordinate: f64, target: [f64; 3], axis: usize) -> [f64; 3] {
+    let t = (coordinate - source[axis]) / (target[axis] - source[axis]);
+    [
+        source[0] + (target[0] - source[0]) * t,
+        source[1] + (target[1] - source[1]) * t,
+        source[2] + (target[2] - source[2]) * t,
+    ]
+}
+
+/// 线段中点。
+fn midpoint(a: [f64; 3], b: [f64; 3]) -> [f64; 3] {
+    [
+        (a[0] + b[0]) / 2.0,
+        (a[1] + b[1]) / 2.0,
+        (a[2] + b[2]) / 2.0,
+    ]
+}
+
+/// 非线性压缩的正向（与 CAM16 里那段同公式）。
+fn chromatic_adaptation(component: f64) -> f64 {
+    let af = component.abs().powf(0.42);
+    signum(component) * 400.0 * af / (af + 27.13)
+}
+
+/// 非线性压缩的逆。
+fn inverse_chromatic_adaptation(adapted: f64) -> f64 {
+    let adapted_abs = adapted.abs();
+    let base = (27.13 * adapted_abs / (400.0 - adapted_abs)).max(0.0);
+    signum(adapted) * base.powf(1.0 / 0.42)
+}
+
+/// 关键平面索引：向下取（官方 `(int) Math.floor(x - 0.5)`）。
+fn critical_plane_below(x: f64) -> i32 {
+    (x - 0.5).floor() as i32
+}
+
+/// 关键平面索引：向上取（官方 `(int) Math.ceil(x - 0.5)`）。
+fn critical_plane_above(x: f64) -> i32 {
+    (x - 0.5).ceil() as i32
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn in_gamut_requests_are_met_exactly() {
+        // 官方 Java 实测：HCT(95, 36, 40) → #705D0D。
+        assert_eq!(solve_to_color(95.0, 36.0, 40.0).to_hex(), "#705D0D");
+        assert_eq!(solve_to_color(25.0, 84.0, 40.0).to_hex(), "#BA1A1A");
+        assert_eq!(solve_to_color(95.0, 36.0, 90.0).to_hex(), "#FCE186");
+    }
+
+    #[test]
+    fn out_of_gamut_requests_keep_hue_and_tone() {
+        // 请求 chroma 200（sRGB 装不下）：官方只在彩度上退让，色相与 tone 必须保住。
+        let color = solve_to_color(200.0, 200.0, 70.0);
+        assert_eq!(color.to_hex(), "#00BEC3");
+        let hct = super::super::Hct::from_color(color);
+        assert!((hct.tone - 70.0).abs() < 1.0, "tone 掉了：{}", hct.tone);
+        assert!(
+            (hct.hue - 200.0).abs() < 1.0,
+            "色相偏了：{}（应 ≈200）",
+            hct.hue
+        );
+        assert!(hct.chroma < 200.0);
+    }
+
+    #[test]
+    fn neutral_requests_return_exact_grays() {
+        for lstar in [0.0_f64, 4.0, 10.0, 50.0, 87.0, 98.0, 100.0] {
+            let color = solve_to_color(120.0, 0.0, lstar);
+            assert!(color.r == color.g && color.g == color.b, "{:?}", color);
+        }
+        assert_eq!(solve_to_color(0.0, 0.0, 0.0), Color::BLACK);
+        assert_eq!(solve_to_color(0.0, 0.0, 100.0), Color::WHITE);
+    }
+}

crates/design/src/color/mod.rs

@@ -0,0 +1,331 @@
+//! # 色彩令牌（M3 color roles）
+//!
+//! 49 个 M3 语义色角色 × light/dark 两套，全部由**一个种子色**派生（[`Palettes`]），
+//! 再按官方 tone 映射表解析成具体色值（[`Scheme`]）。
+//!
+//! ```no_run
+//! use unlucky_design::color::{Color, Role, Scheme, SchemeFlavor};
+//!
+//! let light = Scheme::baseline(SchemeFlavor::Light);
+//! let surface = light.get(Role::Surface);
+//! let on_surface = light.get(Role::OnSurface);
+//! assert!(on_surface.contrast_ratio(surface) > 4.5);
+//!
+//! // 用户自定义强调色：表面中性色不动，只换强调族。
+//! let custom = Scheme::from_accent(SchemeFlavor::Light, Color::from_hex("#006A5C").unwrap());
+//! assert_eq!(custom.get(Role::Surface), surface);
+//! ```
+//!
+//! ## 口径声明：真 HCT，不是近似
+//!
+//! 标准 M3 的调色板建在 **HCT**（CAM16 色相/彩度 + CIELAB 的 `L*`）上。本模块**就是**那套算法：
+//! CAM16 正换算（`cam16` 模块）取色相/彩度，`L*` 取 tone，色域外走官方的 `HctSolver`
+//! （`hct_solver` 模块：Newton 迭代 + 色调平面上的色相二分，**只压彩度、不硬裁**）。
+//!
+//! | 轴 | 标准 M3 | 本实现 | 一致性 |
+//! |---|---|---|---|
+//! | tone | CIELAB `L*` | CIELAB `L*`（同一个 `Y` 轴） | 逐值一致 |
+//! | 色相 / 彩度 | CAM16 | CAM16（D65 默认观察条件） | 逐值一致（误差 < 1e-4） |
+//! | gamut 映射 | `HctSolver` | 同一套两段求解器，关键平面表原样搬运 | 逐通道一致 |
+//! | 调色板彩度 | Tonal Spot 变体：36 / 16 / 24 / 6 / 8，error 25°/84 | 同（primary/secondary/tertiary/neutral-variant/error 逐值一致） | 逐值一致 |
+//! | 中性彩度 | 6（几乎无色） | 官方口径 6；**产品默认用 12**（有意偏离，见下节「出厂默认色」） | 仅此处偏离 |
+//! | 角色 tone 表 | ColorSpec2021 | 同（49 角色 × light/dark） | 逐值一致 |
+//!
+//! 对齐证据在 `tests/official_baseline.rs` 与 `tests/official_accent.rs`：期望值全部由
+//! `material-color-utilities`（官方 Java 实现，Apache-2.0）跑出来，**每通道误差 ≤1** 才通过。
+//! 所以本 crate 可以对外说「M3 动态取色（Tonal Spot 变体 / standard 对比度）」。
+//!
+//! ## 未实现的部分（gap 登记，别以为已经有）
+//!
+//! | 能力 | 官方叫什么 | 状态 |
+//! |---|---|---|
+//! | 对比度三档（default/medium/high） | `ContrastCurve` + `contrastLevel` | **未实现**：只做 `contrastLevel = 0`。在 0 档下官方那层「tone 差对 + 对比度修正」机制的输入全是常数，等价于本模块的静态 tone 表（已由对齐测试反证） |
+//! | 其他配色变体 | `Vibrant` / `Expressive` / `Fidelity` / `Content` / `Monochrome` / `Neutral` / `Rainbow` / `FruitSalad` / `CMF` | **未实现**：只有 `TonalSpot`（M3 默认、也是 Material Theme Builder 默认） |
+//! | 壁纸多色取色 | `QuantizerCelebi` / `Score` / 多 source 色 | **未实现**：桌面启动器用不到（安卓端特性），也避免引入图像依赖 |
+//! | 换观察条件 | `Hct.inViewingConditions` | **未实现**：只有 sRGB 屏的默认条件（D65 / 200 lux / 背景 `L* 50`） |
+//!
+//! ## 「自定义强调色」与官方 `from_seed` 的关系
+//!
+//! 官方 `SchemeTonalSpot(accent)` 会把**中性表面也染上**种子的色相；本项目的产品语义是
+//! 「换强调色不该让整个窗口底色变脏」，所以 [`Scheme::from_accent`] 只换 primary/secondary/
+//! tertiary 三族，中性色与 error 保持基线。强调族的色值与官方 `from_seed(accent)` 逐个对得上
+//! （`tests/official_accent.rs`，8 个种子 × 12 个强调族角色 × 2 模式 = 192 项）。
+//!
+//! ## 出厂默认色（M70：浅冷天蓝）——含**两处**有意偏离（同一处偏离的两半）
+//!
+//! 产品默认不走官方紫，而是「浅冷天蓝」。默认值收在两个常量里，**换默认只改这两行**
+//! （用户 2026-11-01 拍板采用候选 **④ 天蓝**；③ 浅冷天蓝 `#87CEEB` 留作备选，值仍 pin 在
+//! `tests/skyseed_candidates.rs`）：
+//!
+//! | 项 | 当前值 | 官方值 | 说明 |
+//! |---|---|---|---|
+//! | [`palettes::DEFAULT_SEED`] | `#3C8DBC`（CAM16 hue ≈ 240°） | `#6750A4`（[`palettes::BASELINE_SEED`]） | 种子只贡献**色相**（CAM16 240°）；种子彩度会被 Tonal Spot 丢掉 |
+//! | [`palettes::DEFAULT_NEUTRAL_CHROMA`]（neutral） | `12` | `6` | 让 surface / surface-container-* 带淡蓝调 |
+//! | 联动的 neutral-variant | `14` | `8`（**绝对值**；官方不是「neutral + 2」） | `outline` / `outline-variant` / `surface-variant` 一起偏蓝（light `outline` = `#6A7985` 就是 14 彩度的口径） |
+//!
+//! **定位（D38）**：这套默认只是「**莫奈关闭时的出厂预选色卡**」（首次启动、用户还没选过色卡时
+//! 用的那一套），**不是唯一的配色来源**。用户的配色来源有三级优先：① 启动器背景图取色（Monet）
+//! → ② 桌面壁纸取色 → ③ 莫奈关闭（默认）时从内置多套色卡里选。取色与「内置色卡库」都不在本 crate，
+//! 也还没实现；本模块只负责「给定一个种子 + 中性彩度，派生出 49 个角色」。
+//!
+//! > ⚠️ **有意偏离登记（两处，同一处偏离的两半）**：
+//! >
+//! > 1. **neutral 彩度 `6 → 12`**。理由＝产品要「浅冷」的冷调表面：官方 6 的表面几乎无色，单靠换
+//! >    种子做不到「浅」——primary 的 tone 被官方钉在 40，种子再浅主色也还是中蓝，所以「浅」只能
+//! >    落在中性色上。
+//! > 2. **neutral-variant 彩度 `8 → 14`**。这是第 1 条的连带结果：官方
+//! >    `getNeutralVariantPalette` 写死的是**绝对值 8**（不是「neutral + 2」这种相对式），
+//! >    本实现为了让层次不倒挂，让它跟着 neutral 联动（`nv = neutral + 2`）。若把 nv 钉回 8，
+//! >    表面（12）会比中性变体（8）更「有色」，破坏官方的「neutral < neutral-variant」层次。
+//! >    影响面不只表面：`outline` / `outline-variant` / `surface-variant` 三个角色一起偏蓝。
+//! >
+//! > 除这两处外全部走官方常数（primary 36 / secondary 16 / tertiary 24 且色相 +60° /
+//! > error 25°·84），tone 表与 gamut 映射一行未动；[`Scheme::official_baseline`] 仍是官方的
+//! > 6（neutral）/ 8（neutral-variant）口径。
+//!
+//! 官方口径的锚点仍然完整保留：[`Scheme::official_baseline`]（种子 `#6750A4` + 中性 6）
+//! 是 `tests/official_baseline.rs` 的对账入口，98 项仍是每通道 ≤1；
+//! `tests/skyseed_candidates.rs` 把四档候选（保守蓝 / 冷调蓝 / 浅冷蓝 / 天蓝）的色值逐个 pin 住，
+//! 换默认时它会指着要改的行。
+//!
+//! ✅ 默认色已由用户 2026-11-01 拍板：**④ 天蓝 `#3C8DBC`**。备选 ③ 浅冷蓝 `#87CEEB`
+//! （主色偏青 `#0C6780`）仍在候选表里，换回去只需改 [`palettes::DEFAULT_SEED`] 一行。
+//!
+//! ## 对比度纪律（WCAG AA）
+//!
+//! - 所有 `on-*` 与其承载色（`*-container`、`primary`、`surface`）都满足 **≥ 4.5:1**；
+//!   这一条由 `tests/contrast_aa.rs` 全表验证，且因为 tone 轴固定，**换任何种子色都成立**
+//!   （WCAG 对比度只取决于相对亮度，而 tone 直接钉住 `L*`；中性彩度同理，
+//!   `sky_seed_candidates_meet_wcag_aa` 逐档验证了 M70 的四档候选：4 档 × 2 模式 × 26 对 = 208 项）。
+//! - 例外（显式登记，非缺陷）：
+//!   - [`Role::Outline`] 对 [`Role::Surface`]：M3 定义的**非文字**元素（输入框描边），
+//!     目标 3:1，实测 light 4.26:1 / dark 5.89:1；
+//!   - [`Role::OutlineVariant`] 对 [`Role::Surface`]：纯装饰分隔线，M3 不要求对比度下限；
+//!   - [`Role::SurfaceVariant`]：它是**容器**色（不是前景），不参与对比度门禁。
+//! - 禁用态按 M3 的 alpha 叠加（[`state::DISABLED_CONTENT_ALPHA`]），刻意低于 AA。
+
+pub mod hct;
+pub mod palettes;
+pub mod roles;
+pub mod scheme;
+pub mod state;
+pub mod tonal;
+
+mod cam16;
+mod critical_planes;
+mod hct_solver;
+mod space;
+mod viewing_conditions;
+
+pub use hct::Hct;
+pub use palettes::{PaletteSlot, Palettes, BASELINE_SEED, DEFAULT_NEUTRAL_CHROMA, DEFAULT_SEED};
+pub use roles::Role;
+pub use scheme::{Scheme, SchemeFlavor, SCRIM_ALPHA, SHADOW_ALPHA};
+pub use state::StateLayer;
+pub use tonal::TonalPalette;
+
+/// sRGB 颜色（8 bit/通道 + alpha），刻意不用第三方颜色类型：本 crate 零依赖。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct Color {
+    /// 红通道。
+    pub r: u8,
+    /// 绿通道。
+    pub g: u8,
+    /// 蓝通道。
+    pub b: u8,
+    /// alpha（0 = 全透明，255 = 不透明）。
+    pub a: u8,
+}
+
+impl Color {
+    /// 不透明颜色。
+    pub const fn rgb(r: u8, g: u8, b: u8) -> Self {
+        Self { r, g, b, a: 255 }
+    }
+
+    /// 带 alpha 的颜色（`a` 为 0..=255）。
+    pub const fn rgba(r: u8, g: u8, b: u8, a: u8) -> Self {
+        Self { r, g, b, a }
+    }
+
+    /// 纯黑。
+    pub const BLACK: Color = Color::rgb(0, 0, 0);
+    /// 纯白。
+    pub const WHITE: Color = Color::rgb(255, 255, 255);
+
+    /// 从 `#RRGGBB` / `#RGB` / `#AARRGGBB` 解析（不合法返回 `None`）。
+    ///
+    /// 只给配置读取与测试用——UI 代码里**不许出现色字面量**，一律走 [`Role`]。
+    pub fn from_hex(text: &str) -> Option<Self> {
+        let hex = text.trim().trim_start_matches('#');
+        let parse = |s: &str| u8::from_str_radix(s, 16).ok();
+        match hex.len() {
+            3 => {
+                let d = |i: usize| {
+                    let v = parse(&hex[i..i + 1])?;
+                    Some(v * 17)
+                };
+                Some(Self::rgb(d(0)?, d(1)?, d(2)?))
+            }
+            6 => Some(Self::rgb(
+                parse(&hex[0..2])?,
+                parse(&hex[2..4])?,
+                parse(&hex[4..6])?,
+            )),
+            8 => Some(Self::rgba(
+                parse(&hex[2..4])?,
+                parse(&hex[4..6])?,
+                parse(&hex[6..8])?,
+                parse(&hex[0..2])?,
+            )),
+            _ => None,
+        }
+    }
+
+    /// 不透明部分转 `#RRGGBB`（alpha < 255 时附 `#AARRGGBB` 形式）。
+    pub fn to_hex(self) -> String {
+        if self.a == 255 {
+            format!("#{:02X}{:02X}{:02X}", self.r, self.g, self.b)
+        } else {
+            format!("#{:02X}{:02X}{:02X}{:02X}", self.a, self.r, self.g, self.b)
+        }
+    }
+
+    /// 改 alpha（`alpha` 0..1，越界夹取）。
+    pub fn with_alpha(self, alpha: f32) -> Self {
+        Self {
+            a: (alpha.clamp(0.0, 1.0) * 255.0).round() as u8,
+            ..self
+        }
+    }
+
+    /// alpha 归一化到 0..1。
+    pub fn alpha(self) -> f32 {
+        f32::from(self.a) / 255.0
+    }
+
+    /// 是否完全不透明。
+    pub fn is_opaque(self) -> bool {
+        self.a == 255
+    }
+
+    /// WCAG 相对亮度（0..1，即 XYZ 的 `Y` 除以 100）。
+    ///
+    /// 与 WCAG 2.x 的定义同一条 `Y` 轴（Rec.709 系数 0.2126/0.7152/0.0722），
+    /// 所以 [`Color::contrast_ratio`] 就是标准对比度公式。
+    pub fn relative_luminance(self) -> f32 {
+        (space::xyz_from_color(self)[1] / 100.0) as f32
+    }
+
+    /// CIELAB `L*`（0..100）——这就是 M3 的 **tone**。
+    ///
+    /// 调色板按这条轴生成，验收也按这条轴断言；想知道某个色值「是几号 tone」就用它。
+    pub fn lstar(self) -> f32 {
+        space::lstar_from_color(self) as f32
+    }
+
+    /// WCAG 对比度（1..21）。`self` 与 `other` 都不透明时才严格；带 alpha 时先算「不计 alpha」的值。
+    pub fn contrast_ratio(self, other: Self) -> f32 {
+        let a = self.relative_luminance();
+        let b = other.relative_luminance();
+        let (hi, lo) = if a > b { (a, b) } else { (b, a) };
+        (hi + 0.05) / (lo + 0.05)
+    }
+
+    /// alpha 合成：`self` 叠在 `bg` 之上，返回不透明结果。
+    ///
+    /// 这是 M3 状态层/禁用态/遮罩的唯一合成口径（非预乘 alpha）。
+    pub fn over(self, bg: Self) -> Self {
+        let sa = self.alpha();
+        if sa >= 1.0 {
+            return self;
+        }
+        let blend = |fg: u8, b: u8| {
+            let v = f32::from(fg) * sa + f32::from(b) * (1.0 - sa);
+            v.round().clamp(0.0, 255.0) as u8
+        };
+        let a = sa + bg.alpha() * (1.0 - sa);
+        Self {
+            r: blend(self.r, bg.r),
+            g: blend(self.g, bg.g),
+            b: blend(self.b, bg.b),
+            a: (a * 255.0).round().clamp(0.0, 255.0) as u8,
+        }
+    }
+
+    /// 两色线性插值（`t` 0..1），用于动画中间帧（GPU 路径的 shape morph 用得上）。
+    pub fn lerp(self, other: Self, t: f32) -> Self {
+        let t = t.clamp(0.0, 1.0);
+        let mix = |a: u8, b: u8| {
+            (f32::from(a) + (f32::from(b) - f32::from(a)) * t)
+                .round()
+                .clamp(0.0, 255.0) as u8
+        };
+        Self {
+            r: mix(self.r, other.r),
+            g: mix(self.g, other.g),
+            b: mix(self.b, other.b),
+            a: mix(self.a, other.a),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn hex_roundtrip() {
+        let c = Color::from_hex("#6750A4").expect("合法 hex");
+        assert_eq!(c, Color::rgb(0x67, 0x50, 0xA4));
+        assert_eq!(c.to_hex(), "#6750A4");
+        assert_eq!(Color::from_hex("6750a4"), Some(c));
+        assert_eq!(Color::from_hex("#FFF"), Some(Color::WHITE));
+        assert_eq!(Color::from_hex("#80FF0000").map(|c| c.a), Some(0x80));
+        assert_eq!(Color::from_hex("#12345"), None);
+        assert_eq!(Color::from_hex("zzzzzz"), None);
+    }
+
+    #[test]
+    fn contrast_extremes() {
+        assert!((Color::BLACK.contrast_ratio(Color::WHITE) - 21.0).abs() < 0.01);
+        assert!((Color::WHITE.contrast_ratio(Color::WHITE) - 1.0).abs() < 0.001);
+    }
+
+    #[test]
+    fn over_composites_correctly() {
+        let black_50 = Color::BLACK.with_alpha(0.5);
+        let got = black_50.over(Color::WHITE);
+        // with_alpha 量化到 128/255 = 0.50196，所以结果落在 127（不是 128）。
+        assert_eq!((got.r, got.a), (127, 255));
+    }
+
+    #[test]
+    fn lerp_hits_endpoints() {
+        let a = Color::rgb(0, 0, 0);
+        let b = Color::rgb(255, 255, 255);
+        assert_eq!(a.lerp(b, 0.0), a);
+        assert_eq!(a.lerp(b, 1.0), b);
+        assert_eq!(a.lerp(b, 0.5).r, 128);
+    }
+
+    #[test]
+    fn lstar_anchors_at_the_ends() {
+        assert!(Color::BLACK.lstar().abs() < 1.0e-3);
+        assert!((Color::WHITE.lstar() - 100.0).abs() < 1.0e-3);
+        // 中灰（sRGB 128）的 L* 是 53.6 左右，不是 50——这正是「L* 不是 sRGB 编码值」的证据。
+        let mid = Color::rgb(128, 128, 128).lstar();
+        assert!((mid - 53.585).abs() < 0.01, "中灰 L* = {mid}");
+    }
+
+    #[test]
+    fn tone_delta_implies_contrast_floor() {
+        // M3 的招牌性质：tone 差 50 ⇒ 对比度 ≥ 4.5:1（与色相/彩度无关）。
+        for (low, high) in [(10.0_f64, 60.0), (30.0, 80.0), (40.0, 90.0), (20.0, 70.0)] {
+            let a = space::color_from_lstar(low);
+            let b = space::color_from_lstar(high);
+            let ratio = a.contrast_ratio(b);
+            assert!(ratio >= 4.5, "tone {low}→{high} 只有 {ratio:.2}");
+        }
+    }
+}

crates/design/src/color/palettes.rs

@@ -0,0 +1,300 @@
+//! 六条 tone 调色板的集合（M3 scheme 的原料）。
+//!
+//! 角色 → 调色板槽位 → tone 的三段映射在 [`super::scheme`]；这里只负责「种子 → 六条调色板」，
+//! 以及**官方 Tonal Spot 变体**的彩度常数。
+//!
+//! 彩度值来自 `material-color-utilities` 的 `ColorSpec2021.get*Palette(Variant.TONAL_SPOT)`
+//! （Apache-2.0，见 `NOTICE`）：primary 恒定 **36**、secondary **16**、tertiary **24**
+//! （色相 +60°）、neutral **6**、neutral-variant **8**、error 固定色相 **25** 彩度 **84**。
+//! 注意 primary 的 36 与种子自身的彩度无关——这是官方口径：Tonal Spot 是「镇静」变体，
+//! 再鲜艳的种子也会被收到 36，再灰的种子也会被提到 36。
+//!
+//! ## 两个入口：官方口径 vs 产品默认（M70）
+//!
+//! | 入口 | 种子 | 中性彩度 | 用途 |
+//! |---|---|---|---|
+//! | [`Palettes::official_baseline`] / [`super::Scheme::official_baseline`] | [`BASELINE_SEED`]（`#6750A4`） | 6（官方） | 与官方 Java 实现逐角色对齐的**锚点**，`tests/official_baseline.rs` 用它 |
+//! | [`Palettes::baseline`] / [`super::Scheme::baseline`] | [`DEFAULT_SEED`] | [`DEFAULT_NEUTRAL_CHROMA`] | **产品出厂默认**（消费方拿到的就是它） |
+//!
+//! 换默认色只改 [`DEFAULT_SEED`] 与 [`DEFAULT_NEUTRAL_CHROMA`] 两行常量（中性彩度不动就只改一行），
+//! 然后重跑 `tests/skyseed_candidates.rs` 的 pin（它会打印新值并指出哪几行要同步）。
+//! 官方锚点不受影响——**算法没动，动的只是入参**。
+//!
+//! ⚠️ 中性彩度 6 → 12 是**有意偏离**官方 Tonal Spot（理由：产品要「浅冷」的冷调表面），
+//! 偏离登记见 [`super`] 模块文档的「出厂默认色」小节。
+
+use super::tonal::TonalPalette;
+use super::Color;
+
+/// M3 baseline 种子色（与 material-color-utilities 的默认基线同值）。
+///
+/// **不是**产品默认色——产品默认见 [`DEFAULT_SEED`]。
+pub const BASELINE_SEED: Color = Color::rgb(0x67, 0x50, 0xA4);
+
+/// 产品出厂默认种子色 —— M70 候选④「天蓝」，**用户 2026-11-01 拍板采用**。
+///
+/// `#3C8DBC`（CAM16 hue ≈ 239.5°，主色 `#236488`）。注意种子的彩度（42.6）会被 Tonal Spot
+/// 丢掉——主色板的彩度恒为 36，种子只贡献**色相**。
+///
+/// ## 定位（D38）：这是「莫奈关闭时的出厂预选色卡」，不是唯一的配色来源
+///
+/// 用户定了三级优先的配色来源：① 启动器背景图取色（Monet）→ ② 桌面壁纸取色 → ③ 莫奈关闭
+/// （默认）时用户从内置多套色卡里选。本常量 + [`DEFAULT_NEUTRAL_CHROMA`] 只定义**第三级里
+/// 出厂预选的那一套**（首次启动、用户没选过色卡时的那一套）。取色（Monet / 壁纸 /
+/// `QuantizerCelebi`）与「内置多色卡库」都不在本 crate，也还没实现。
+pub const DEFAULT_SEED: Color = Color::rgb(0x3C, 0x8D, 0xBC);
+
+/// 产品出厂默认的中性调色板彩度（官方 Tonal Spot 是 6，这里 12 = **有意偏离**）。
+///
+/// 官方 6 让表面几乎无色；12 让 surface / surface-container-* 带一层淡蓝调，
+/// 这是「浅冷天蓝」唯一能落在表面上的手段（primary 的 tone 被官方钉在 40，
+/// 种子再浅也变不成浅蓝）。
+///
+/// **数值安全区间 `6..=13`，产品取 12**：neutral-variant 跟 neutral 联动（`nv = neutral + 2`），
+/// 13 时 nv = 15 仍低于 secondary 的 16；**14 才会撞上**（nv = 16 = secondary），届时要一并改
+/// `NEUTRAL_VARIANT_OFFSET`（私有常量）的规则。nv 的那一半偏离见 `color` 模块文档的偏离登记。
+///
+/// 同样只服务于「出厂预选色卡」（D38 第三级），不约束将来的取色结果。将来若做「内置多套色卡」，
+/// 每套色卡各带自己的中性彩度更合适——本常量到时候会退化成「默认那套的取值」。
+pub const DEFAULT_NEUTRAL_CHROMA: f64 = 12.0;
+
+/// 调色板槽位（M3 的六条 tonal palette）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PaletteSlot {
+    /// 主调色板（种子色相，彩度 36）。
+    Primary,
+    /// 次调色板（同色相，彩度 16）。
+    Secondary,
+    /// 第三调色板（种子色相 +60°，彩度 24）。
+    Tertiary,
+    /// 中性调色板（同色相；官方彩度 6，产品默认 12——见 [`DEFAULT_NEUTRAL_CHROMA`]）。
+    Neutral,
+    /// 中性变体调色板（同色相，彩度 = neutral + 2；官方 8）。
+    NeutralVariant,
+    /// 错误调色板（固定红相 25°，彩度 84）。
+    Error,
+}
+
+/// Tonal Spot 的 primary 彩度（官方常数，与种子彩度无关）。
+const PRIMARY_CHROMA: f64 = 36.0;
+/// secondary 彩度。
+const SECONDARY_CHROMA: f64 = 16.0;
+/// tertiary 彩度。
+const TERTIARY_CHROMA: f64 = 24.0;
+/// 官方 Tonal Spot 的 neutral 彩度（几乎是灰）。产品默认用 [`DEFAULT_NEUTRAL_CHROMA`]。
+const TONAL_SPOT_NEUTRAL_CHROMA: f64 = 6.0;
+/// neutral-variant 相对 neutral 的彩度偏移。
+///
+/// ⚠️ 官方 `getNeutralVariantPalette` 写死的是**绝对值 8**，**不是**「neutral + 2」这种相对式；
+/// 本实现选择让 neutral-variant 随 neutral 联动，于是产品默认（neutral 12）取到 **14**。
+/// 这是**有意偏离**的另一半（见 `color` 模块文档的偏离登记），不是官方口径——
+/// 官方的 6 / 8 由 [`Palettes::official_baseline`] 原样保留。
+const NEUTRAL_VARIANT_OFFSET: f64 = 2.0;
+/// error 的色相（HCT 红相）。
+const ERROR_HUE_DEG: f64 = 25.0;
+/// error 的彩度。
+const ERROR_CHROMA: f64 = 84.0;
+/// tertiary 相对种子的色相偏移。
+const TERTIARY_HUE_SHIFT_DEG: f64 = 60.0;
+
+/// 一套完整的六条调色板。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Palettes {
+    /// 主要调色板。
+    pub primary: TonalPalette,
+    /// 次要调色板。
+    pub secondary: TonalPalette,
+    /// 第三调色板。
+    pub tertiary: TonalPalette,
+    /// 中性调色板。
+    pub neutral: TonalPalette,
+    /// 中性变体调色板。
+    pub neutral_variant: TonalPalette,
+    /// 错误调色板。
+    pub error: TonalPalette,
+}
+
+impl Palettes {
+    /// **产品出厂默认**：种子 [`DEFAULT_SEED`] + 中性彩度 [`DEFAULT_NEUTRAL_CHROMA`]。
+    ///
+    /// 消费方（`DesignTokens::baseline`、iced 适配层）拿到的就是这套，所以产品默认色
+    /// 只需要改那两个常量。
+    pub fn baseline() -> Self {
+        Self::from_seed_with_neutral_chroma(DEFAULT_SEED, DEFAULT_NEUTRAL_CHROMA)
+    }
+
+    /// **官方基线的锚点**：种子 [`BASELINE_SEED`] + 官方中性彩度 6（等价官方
+    /// `SchemeTonalSpot(0xFF6750A4)`）。只给对齐测试与文档表格用。
+    pub fn official_baseline() -> Self {
+        Self::from_seed(BASELINE_SEED)
+    }
+
+    /// 从一个种子色派生全套调色板（官方 Tonal Spot 变体，中性彩度取官方 6）。
+    pub fn from_seed(seed: Color) -> Self {
+        Self::from_seed_with_neutral_chroma(seed, TONAL_SPOT_NEUTRAL_CHROMA)
+    }
+
+    /// 从一个种子色派生，并显式指定中性调色板彩度（`6.0` 即官方 Tonal Spot）。
+    ///
+    /// ⚠️ **调用方负责传 `6.0..=13.0`（产品取 12）**。本函数**不做范围校验**，越界的表现是
+    /// 静默退化而不是 panic：
+    /// - `neutral_chroma < 0` 或 `NaN` → 彩度被夹到 0（`TonalPalette::new` 里 `.max(0.0)`），
+    ///   得到一套纯灰的表面（surface ≈ `#F9F9F9`），**不报错**；
+    /// - `neutral_chroma >= 14` → neutral-variant（= neutral + 2）够到甚至超过 secondary 的 16，
+    ///   「中性 < 中性变体 < 次色」的层次被破坏（描边会明显发蓝）。
+    ///
+    /// 除 neutral / neutral-variant 外**全部走官方常数**：primary 恒定 36、secondary 16、
+    /// tertiary 24（色相 +60°）、error 固定 25°/84。所以这条入口不绕算法，只是把「官方写死在
+    /// `getNeutralPalette` / `getNeutralVariantPalette` 里的那两个数」变成可调入参
+    /// （neutral-variant 这里取相对式 `neutral + 2`，属**有意偏离**，见 `NEUTRAL_VARIANT_OFFSET`）。
+    pub fn from_seed_with_neutral_chroma(seed: Color, neutral_chroma: f64) -> Self {
+        let hue = super::Hct::from_color(seed).hue;
+        Self::tonal_spot(hue, neutral_chroma)
+    }
+
+    /// 只换强调色：primary/secondary/tertiary 跟着新强调色的色相走，
+    /// **表面中性色与错误色保持不变**。
+    ///
+    /// 这是本项目的产品语义（换强调色不该让整个窗口底色变脏，见 `DesignTokens::with_accent`）：
+    /// 强调族的色值与官方 `from_seed(accent)` 逐个对得上，中性表面则仍走基线——
+    /// 官方 `from_seed` 会把中性色也染上种子的色相，那是「整窗染色」，不是我们要的。
+    pub fn with_accent(self, accent: Color) -> Self {
+        let hue = super::Hct::from_color(accent).hue;
+        Self {
+            primary: TonalPalette::new(hue, PRIMARY_CHROMA),
+            secondary: TonalPalette::new(hue, SECONDARY_CHROMA),
+            tertiary: TonalPalette::new(hue + TERTIARY_HUE_SHIFT_DEG, TERTIARY_CHROMA),
+            ..self
+        }
+    }
+
+    /// 官方 Tonal Spot 的六条调色板（色相来自种子，彩度取官方常数，neutral 可调）。
+    fn tonal_spot(hue: f64, neutral_chroma: f64) -> Self {
+        Self {
+            primary: TonalPalette::new(hue, PRIMARY_CHROMA),
+            secondary: TonalPalette::new(hue, SECONDARY_CHROMA),
+            tertiary: TonalPalette::new(hue + TERTIARY_HUE_SHIFT_DEG, TERTIARY_CHROMA),
+            neutral: TonalPalette::new(hue, neutral_chroma),
+            neutral_variant: TonalPalette::new(hue, neutral_chroma + NEUTRAL_VARIANT_OFFSET),
+            error: TonalPalette::new(ERROR_HUE_DEG, ERROR_CHROMA),
+        }
+    }
+
+    /// 按槽位取调色板。
+    pub fn slot(&self, slot: PaletteSlot) -> TonalPalette {
+        match slot {
+            PaletteSlot::Primary => self.primary,
+            PaletteSlot::Secondary => self.secondary,
+            PaletteSlot::Tertiary => self.tertiary,
+            PaletteSlot::Neutral => self.neutral,
+            PaletteSlot::NeutralVariant => self.neutral_variant,
+            PaletteSlot::Error => self.error,
+        }
+    }
+
+    /// 方案级取色：槽位 + tone → 色值。
+    pub fn tone(&self, slot: PaletteSlot, tone: f64) -> Color {
+        self.slot(slot).tone(tone)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn official_baseline_uses_the_official_tonal_spot_chromas() {
+        let palettes = Palettes::official_baseline();
+        assert_eq!(palettes.primary.chroma(), 36.0);
+        assert_eq!(palettes.secondary.chroma(), 16.0);
+        assert_eq!(palettes.tertiary.chroma(), 24.0);
+        assert_eq!(palettes.neutral.chroma(), 6.0);
+        assert_eq!(palettes.neutral_variant.chroma(), 8.0);
+        assert_eq!(palettes.error.hue_deg(), 25.0);
+        assert_eq!(palettes.error.chroma(), 84.0);
+    }
+
+    #[test]
+    fn product_default_only_moves_the_named_knobs() {
+        // 产品默认与官方锚点的差别必须**只**在种子色相与中性彩度两处：
+        // primary/secondary/tertiary/error 的取法一模一样（算法没动）。
+        let official = Palettes::official_baseline();
+        let product = Palettes::baseline();
+        assert_eq!(product.primary.chroma(), official.primary.chroma());
+        assert_eq!(product.secondary.chroma(), official.secondary.chroma());
+        assert_eq!(product.tertiary.chroma(), official.tertiary.chroma());
+        assert_eq!(product.error, official.error);
+        assert_eq!(product.neutral.chroma(), DEFAULT_NEUTRAL_CHROMA);
+        assert_eq!(
+            product.neutral_variant.chroma(),
+            DEFAULT_NEUTRAL_CHROMA + NEUTRAL_VARIANT_OFFSET
+        );
+        let seed = super::super::Hct::from_color(DEFAULT_SEED);
+        assert!((product.primary.hue_deg() - seed.hue).abs() < 1.0e-9);
+    }
+
+    #[test]
+    fn neutral_chroma_knob_keeps_the_official_ordering() {
+        // 官方关系 neutral(6) < neutral-variant(8) < secondary(16) 在安全区间里必须一直成立，
+        // 否则「表面比次色还艳」或两族撞色。
+        for neutral in [6.0, 8.0, 10.0, 12.0] {
+            let p = Palettes::from_seed_with_neutral_chroma(DEFAULT_SEED, neutral);
+            assert!(p.neutral.chroma() < p.neutral_variant.chroma());
+            assert!(p.neutral_variant.chroma() < p.secondary.chroma());
+            // 中性彩度不影响 tone 轴：tone 98 的 surface 仍是最亮的那个。
+            let surface = p.tone(PaletteSlot::Neutral, 98.0);
+            assert!(surface.relative_luminance() > 0.9);
+        }
+    }
+
+    #[test]
+    fn product_default_neutral_chroma_is_a_registered_deviation() {
+        // 官方 neutral / neutral-variant 是 6 / 8；产品默认是 12 / 14。
+        // 这**不是官方口径**，是「有意偏离」（见 `color` 模块文档的偏离登记）。
+        // 想把 nv 拉回官方绝对值 8 的人，请先改登记再改这里：直接钉成 8 会让表面（12）
+        // 比中性变体（8）更「有色」，破坏官方的 neutral < neutral-variant 层次。
+        let product = Palettes::baseline();
+        assert_eq!(product.neutral.chroma(), 12.0, "产品默认 neutral 彩度");
+        assert_eq!(
+            product.neutral_variant.chroma(),
+            14.0,
+            "产品默认的 neutral-variant 彩度 14 是**有意偏离**（官方绝对值 8），改前先更新偏离登记"
+        );
+        let official = Palettes::official_baseline();
+        assert_eq!(official.neutral.chroma(), 6.0, "官方锚点仍是 6");
+        assert_eq!(
+            official.neutral_variant.chroma(),
+            8.0,
+            "官方锚点仍是绝对值 8（不是 neutral + 2 的相对式）"
+        );
+    }
+
+    #[test]
+    fn baseline_hue_comes_from_the_seed() {
+        let palettes = Palettes::official_baseline();
+        let seed = super::super::Hct::from_color(BASELINE_SEED);
+        assert!((palettes.primary.hue_deg() - seed.hue).abs() < 1.0e-9);
+        assert!((palettes.neutral.hue_deg() - seed.hue).abs() < 1.0e-9);
+        assert!((palettes.tertiary.hue_deg() - (seed.hue + 60.0)).abs() < 1.0e-9);
+    }
+
+    #[test]
+    fn seed_chroma_never_leaks_into_the_primary_ramp() {
+        // 官方口径：Tonal Spot 的彩度是常数，纯灰种子也会得到彩度 36 的主色板。
+        let gray = Palettes::from_seed(Color::rgb(0x6E, 0x6E, 0x6E));
+        assert_eq!(gray.primary.chroma(), 36.0);
+        let hot = Palettes::from_seed(Color::rgb(0xFF, 0x00, 0x00));
+        assert_eq!(hot.primary.chroma(), 36.0);
+    }
+
+    #[test]
+    fn accent_override_keeps_surfaces_and_error() {
+        let base = Palettes::baseline();
+        let swapped = base.with_accent(Color::rgb(0x00, 0x6A, 0x5C));
+        assert_eq!(swapped.neutral, base.neutral);
+        assert_eq!(swapped.neutral_variant, base.neutral_variant);
+        assert_eq!(swapped.error, base.error);
+        assert_ne!(swapped.primary.hue_deg(), base.primary.hue_deg());
+        assert_eq!(swapped.primary.chroma(), 36.0);
+    }
+}

crates/design/src/color/roles.rs

@@ -0,0 +1,276 @@
+//! M3 语义色角色：`Role` 枚举是**唯一的名字清单**（49 个，M3 基础集全覆盖）。
+//!
+//! 后续 iced 页面不许另起名字（如 `bg-card` / `fg-primary`）——Fluent 时代的旧名到此为止，
+//! 要表达「卡片底」就用 [`Role::SurfaceContainerLow`]，要表达「次要文字」就用
+//! [`Role::OnSurfaceVariant`]（对应关系见 `DevDocs/SubAgentsTalk/design-令牌约定.md`）。
+
+/// M3 语义色角色（49 个）。
+///
+/// 顺序即 [`Role::ALL`] 的顺序，也是 [`super::Scheme`] 内部数组的下标：
+/// **只允许在末尾追加**，插到中间会静默改变已存盘的颜色映射。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum Role {
+    /// 主色：主操作填充、选中指示。
+    Primary,
+    /// 主色之上的前景（文字/图标）。
+    OnPrimary,
+    /// 主色容器：次级强调块、选中片。
+    PrimaryContainer,
+    /// 主色容器之上的前景。
+    OnPrimaryContainer,
+    /// 次色：低频强调、图表。
+    Secondary,
+    /// 次色之上的前景。
+    OnSecondary,
+    /// 次色容器。
+    SecondaryContainer,
+    /// 次色容器之上的前景。
+    OnSecondaryContainer,
+    /// 第三色：与主/次形成对比的装饰强调。
+    Tertiary,
+    /// 第三色之上的前景。
+    OnTertiary,
+    /// 第三色容器。
+    TertiaryContainer,
+    /// 第三色容器之上的前景。
+    OnTertiaryContainer,
+    /// 错误色：错误文字、危险操作填充。
+    Error,
+    /// 错误色之上的前景。
+    OnError,
+    /// 错误容器：错误提示底。
+    ErrorContainer,
+    /// 错误容器之上的前景。
+    OnErrorContainer,
+    /// 表面：窗口/内容底色（M3 最新口径里取代 background）。
+    Surface,
+    /// 表面之上的主体文字。
+    OnSurface,
+    /// 表面变体：中性分隔/次级容器（**不是**文字色）。
+    SurfaceVariant,
+    /// 表面变体之上的次级文字/图标。
+    OnSurfaceVariant,
+    /// 背景（M3 已并入 surface，保留以兼容旧值）。
+    Background,
+    /// 背景之上的文本（同上，保留兼容）。
+    OnBackground,
+    /// 变暗的表面（模态背后的压暗层）。
+    SurfaceDim,
+    /// 变亮的表面（深色下的抬高底）。
+    SurfaceBright,
+    /// 最低层容器（比 surface 更低）。
+    SurfaceContainerLowest,
+    /// 低层容器：卡片。
+    SurfaceContainerLow,
+    /// 标准容器：卡片/面板。
+    SurfaceContainer,
+    /// 高层容器：浮层。
+    SurfaceContainerHigh,
+    /// 最高层容器：对话框/菜单。
+    SurfaceContainerHighest,
+    /// 描边：输入框边框等（非文字，3:1 即可）。
+    Outline,
+    /// 弱描边：分隔线（纯装饰）。
+    OutlineVariant,
+    /// 反相表面：Snackbar / Tooltip 底。
+    InverseSurface,
+    /// 反相表面之上的文字。
+    InverseOnSurface,
+    /// 反相表面之上的强调。
+    InversePrimary,
+    /// 阴影色（通常带 alpha，见 [`super::Scheme::shadow`]）。
+    Shadow,
+    /// 遮罩色（模态背景，通常带 alpha）。
+    Scrim,
+    /// 表面着色（M3 旧规范的 elevation tint，现已被 surface container 取代）。
+    SurfaceTint,
+    /// 固定主色（深浅模式同值，用于需要跨模式稳定的块）。
+    PrimaryFixed,
+    /// 固定主色的暗档。
+    PrimaryFixedDim,
+    /// 固定主色之上的前景。
+    OnPrimaryFixed,
+    /// 固定主色暗档之上的前景。
+    OnPrimaryFixedVariant,
+    /// 固定次色。
+    SecondaryFixed,
+    /// 固定次色的暗档。
+    SecondaryFixedDim,
+    /// 固定次色之上的前景。
+    OnSecondaryFixed,
+    /// 固定次色暗档之上的前景。
+    OnSecondaryFixedVariant,
+    /// 固定第三色。
+    TertiaryFixed,
+    /// 固定第三色的暗档。
+    TertiaryFixedDim,
+    /// 固定第三色之上的前景。
+    OnTertiaryFixed,
+    /// 固定第三色暗档之上的前景。
+    OnTertiaryFixedVariant,
+}
+
+impl Role {
+    /// 全部 49 个角色，按 `Role as usize` 顺序排列。
+    pub const ALL: [Role; 49] = [
+        Role::Primary,
+        Role::OnPrimary,
+        Role::PrimaryContainer,
+        Role::OnPrimaryContainer,
+        Role::Secondary,
+        Role::OnSecondary,
+        Role::SecondaryContainer,
+        Role::OnSecondaryContainer,
+        Role::Tertiary,
+        Role::OnTertiary,
+        Role::TertiaryContainer,
+        Role::OnTertiaryContainer,
+        Role::Error,
+        Role::OnError,
+        Role::ErrorContainer,
+        Role::OnErrorContainer,
+        Role::Surface,
+        Role::OnSurface,
+        Role::SurfaceVariant,
+        Role::OnSurfaceVariant,
+        Role::Background,
+        Role::OnBackground,
+        Role::SurfaceDim,
+        Role::SurfaceBright,
+        Role::SurfaceContainerLowest,
+        Role::SurfaceContainerLow,
+        Role::SurfaceContainer,
+        Role::SurfaceContainerHigh,
+        Role::SurfaceContainerHighest,
+        Role::Outline,
+        Role::OutlineVariant,
+        Role::InverseSurface,
+        Role::InverseOnSurface,
+        Role::InversePrimary,
+        Role::Shadow,
+        Role::Scrim,
+        Role::SurfaceTint,
+        Role::PrimaryFixed,
+        Role::PrimaryFixedDim,
+        Role::OnPrimaryFixed,
+        Role::OnPrimaryFixedVariant,
+        Role::SecondaryFixed,
+        Role::SecondaryFixedDim,
+        Role::OnSecondaryFixed,
+        Role::OnSecondaryFixedVariant,
+        Role::TertiaryFixed,
+        Role::TertiaryFixedDim,
+        Role::OnTertiaryFixed,
+        Role::OnTertiaryFixedVariant,
+    ];
+
+    /// 稳定字符串名（kebab-case），用于日志、配置、快照对拍与文档表格。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Role::Primary => "primary",
+            Role::OnPrimary => "on-primary",
+            Role::PrimaryContainer => "primary-container",
+            Role::OnPrimaryContainer => "on-primary-container",
+            Role::Secondary => "secondary",
+            Role::OnSecondary => "on-secondary",
+            Role::SecondaryContainer => "secondary-container",
+            Role::OnSecondaryContainer => "on-secondary-container",
+            Role::Tertiary => "tertiary",
+            Role::OnTertiary => "on-tertiary",
+            Role::TertiaryContainer => "tertiary-container",
+            Role::OnTertiaryContainer => "on-tertiary-container",
+            Role::Error => "error",
+            Role::OnError => "on-error",
+            Role::ErrorContainer => "error-container",
+            Role::OnErrorContainer => "on-error-container",
+            Role::Surface => "surface",
+            Role::OnSurface => "on-surface",
+            Role::SurfaceVariant => "surface-variant",
+            Role::OnSurfaceVariant => "on-surface-variant",
+            Role::Background => "background",
+            Role::OnBackground => "on-background",
+            Role::SurfaceDim => "surface-dim",
+            Role::SurfaceBright => "surface-bright",
+            Role::SurfaceContainerLowest => "surface-container-lowest",
+            Role::SurfaceContainerLow => "surface-container-low",
+            Role::SurfaceContainer => "surface-container",
+            Role::SurfaceContainerHigh => "surface-container-high",
+            Role::SurfaceContainerHighest => "surface-container-highest",
+            Role::Outline => "outline",
+            Role::OutlineVariant => "outline-variant",
+            Role::InverseSurface => "inverse-surface",
+            Role::InverseOnSurface => "inverse-on-surface",
+            Role::InversePrimary => "inverse-primary",
+            Role::Shadow => "shadow",
+            Role::Scrim => "scrim",
+            Role::SurfaceTint => "surface-tint",
+            Role::PrimaryFixed => "primary-fixed",
+            Role::PrimaryFixedDim => "primary-fixed-dim",
+            Role::OnPrimaryFixed => "on-primary-fixed",
+            Role::OnPrimaryFixedVariant => "on-primary-fixed-variant",
+            Role::SecondaryFixed => "secondary-fixed",
+            Role::SecondaryFixedDim => "secondary-fixed-dim",
+            Role::OnSecondaryFixed => "on-secondary-fixed",
+            Role::OnSecondaryFixedVariant => "on-secondary-fixed-variant",
+            Role::TertiaryFixed => "tertiary-fixed",
+            Role::TertiaryFixedDim => "tertiary-fixed-dim",
+            Role::OnTertiaryFixed => "on-tertiary-fixed",
+            Role::OnTertiaryFixedVariant => "on-tertiary-fixed-variant",
+        }
+    }
+
+    /// 该角色是否是「文字/图标前景色」（`on-*` 与 `inverse-on-surface` 一类）。
+    ///
+    /// 用于对比度门禁区分两类要求：前景对容器 ≥ 4.5:1（WCAG AA 正文），
+    /// 非文字元素 ≥ 3:1。
+    pub const fn is_foreground(self) -> bool {
+        matches!(
+            self,
+            Role::OnPrimary
+                | Role::OnPrimaryContainer
+                | Role::OnSecondary
+                | Role::OnSecondaryContainer
+                | Role::OnTertiary
+                | Role::OnTertiaryContainer
+                | Role::OnError
+                | Role::OnErrorContainer
+                | Role::OnSurface
+                | Role::OnSurfaceVariant
+                | Role::OnBackground
+                | Role::InverseOnSurface
+                | Role::InversePrimary
+                | Role::OnPrimaryFixed
+                | Role::OnPrimaryFixedVariant
+                | Role::OnSecondaryFixed
+                | Role::OnSecondaryFixedVariant
+                | Role::OnTertiaryFixed
+                | Role::OnTertiaryFixedVariant
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn all_is_in_enum_order() {
+        for (i, role) in Role::ALL.iter().enumerate() {
+            assert_eq!(*role as usize, i, "Role::ALL 顺序必须等于枚举声明顺序");
+        }
+    }
+
+    #[test]
+    fn names_are_unique_and_kebab() {
+        let mut seen = std::collections::BTreeSet::new();
+        for role in Role::ALL {
+            let name = role.name();
+            assert!(seen.insert(name), "角色名重复：{name}");
+            assert!(
+                name.chars()
+                    .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-'),
+                "角色名必须是 kebab-case：{name}"
+            );
+        }
+    }
+}

crates/design/src/color/scheme.rs

@@ -0,0 +1,330 @@
+//! 一套完整的 M3 语义色方案（`Scheme`）：角色 → 调色板槽位 → tone 的三段映射。
+//!
+//! tone 表取自 **ColorSpec2021** 的官方映射（`MaterialDynamicColors` 的 light/dark 两列，
+//! 见 `NOTICE`）。固定角色（`*-fixed*`）深浅同值，因为它们的用途就是「跨模式稳定」。
+//!
+//! ## 只实现了 contrast level = 0（standard）
+//!
+//! 官方的 `ColorSpec2021.getTone()` 还有一层机制：`toneDeltaPair`（成对角色保持 tone 差）
+//! 与 `ContrastCurve`（按对比度等级修正 tone）。在 **contrastLevel = 0** 下这层机制的输入
+//! 全部是常数：`ContrastCurve.get(0)` 恒等于 normal 档的 tone，而「背景 tone」也都是本表里的
+//! 常数，所以它对 49 个角色的调整结果**就是这张表本身**。测试
+//! `tests/official_baseline.rs` 用官方 Java 实现的逐角色输出反证了这一点（每通道误差 ≤1）：
+//! 表错一格，对齐测试就会红。三档对比度（medium/high）不在本 crate 范围内，见
+//! [`super`] 的 gap 登记。
+
+use super::palettes::{PaletteSlot, Palettes};
+use super::roles::Role;
+use super::Color;
+
+/// 深浅模式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SchemeFlavor {
+    /// 浅色（亮底暗字）。
+    Light,
+    /// 深色（暗底亮字）。
+    Dark,
+}
+
+impl SchemeFlavor {
+    /// 是否深色模式。
+    pub const fn is_dark(self) -> bool {
+        matches!(self, SchemeFlavor::Dark)
+    }
+
+    /// 反过来那一个。
+    pub const fn toggled(self) -> Self {
+        match self {
+            SchemeFlavor::Light => SchemeFlavor::Dark,
+            SchemeFlavor::Dark => SchemeFlavor::Light,
+        }
+    }
+
+    /// 稳定字符串名（`light` / `dark`），写配置与日志用。
+    pub const fn name(self) -> &'static str {
+        match self {
+            SchemeFlavor::Light => "light",
+            SchemeFlavor::Dark => "dark",
+        }
+    }
+}
+
+/// 阴影色透明度（M3 阴影 = 纯黑 + 这个 alpha；绘制阴影时叠在背景上）。
+pub const SHADOW_ALPHA: f32 = 0.20;
+/// 遮罩色透明度（模态背景压暗层）。
+pub const SCRIM_ALPHA: f32 = 0.32;
+
+/// 一条「角色 → 槽位 + tone」映射。
+struct ToneRow {
+    role: Role,
+    slot: PaletteSlot,
+    light: f64,
+    dark: f64,
+}
+
+/// 49 个角色的 tone 映射表（ColorSpec2021），**下标必须等于 `Role as usize`**（由测试钉死）。
+const TONE_TABLE: [ToneRow; 49] = [
+    row(Role::Primary, PaletteSlot::Primary, 40.0, 80.0),
+    row(Role::OnPrimary, PaletteSlot::Primary, 100.0, 20.0),
+    row(Role::PrimaryContainer, PaletteSlot::Primary, 90.0, 30.0),
+    row(Role::OnPrimaryContainer, PaletteSlot::Primary, 30.0, 90.0),
+    row(Role::Secondary, PaletteSlot::Secondary, 40.0, 80.0),
+    row(Role::OnSecondary, PaletteSlot::Secondary, 100.0, 20.0),
+    row(Role::SecondaryContainer, PaletteSlot::Secondary, 90.0, 30.0),
+    row(
+        Role::OnSecondaryContainer,
+        PaletteSlot::Secondary,
+        30.0,
+        90.0,
+    ),
+    row(Role::Tertiary, PaletteSlot::Tertiary, 40.0, 80.0),
+    row(Role::OnTertiary, PaletteSlot::Tertiary, 100.0, 20.0),
+    row(Role::TertiaryContainer, PaletteSlot::Tertiary, 90.0, 30.0),
+    row(Role::OnTertiaryContainer, PaletteSlot::Tertiary, 30.0, 90.0),
+    row(Role::Error, PaletteSlot::Error, 40.0, 80.0),
+    row(Role::OnError, PaletteSlot::Error, 100.0, 20.0),
+    row(Role::ErrorContainer, PaletteSlot::Error, 90.0, 30.0),
+    row(Role::OnErrorContainer, PaletteSlot::Error, 30.0, 90.0),
+    row(Role::Surface, PaletteSlot::Neutral, 98.0, 6.0),
+    row(Role::OnSurface, PaletteSlot::Neutral, 10.0, 90.0),
+    row(
+        Role::SurfaceVariant,
+        PaletteSlot::NeutralVariant,
+        90.0,
+        30.0,
+    ),
+    row(
+        Role::OnSurfaceVariant,
+        PaletteSlot::NeutralVariant,
+        30.0,
+        80.0,
+    ),
+    row(Role::Background, PaletteSlot::Neutral, 98.0, 6.0),
+    row(Role::OnBackground, PaletteSlot::Neutral, 10.0, 90.0),
+    row(Role::SurfaceDim, PaletteSlot::Neutral, 87.0, 6.0),
+    row(Role::SurfaceBright, PaletteSlot::Neutral, 98.0, 24.0),
+    row(
+        Role::SurfaceContainerLowest,
+        PaletteSlot::Neutral,
+        100.0,
+        4.0,
+    ),
+    row(Role::SurfaceContainerLow, PaletteSlot::Neutral, 96.0, 10.0),
+    row(Role::SurfaceContainer, PaletteSlot::Neutral, 94.0, 12.0),
+    row(Role::SurfaceContainerHigh, PaletteSlot::Neutral, 92.0, 17.0),
+    row(
+        Role::SurfaceContainerHighest,
+        PaletteSlot::Neutral,
+        90.0,
+        22.0,
+    ),
+    row(Role::Outline, PaletteSlot::NeutralVariant, 50.0, 60.0),
+    row(
+        Role::OutlineVariant,
+        PaletteSlot::NeutralVariant,
+        80.0,
+        30.0,
+    ),
+    row(Role::InverseSurface, PaletteSlot::Neutral, 20.0, 90.0),
+    row(Role::InverseOnSurface, PaletteSlot::Neutral, 95.0, 20.0),
+    row(Role::InversePrimary, PaletteSlot::Primary, 80.0, 40.0),
+    row(Role::Shadow, PaletteSlot::Neutral, 0.0, 0.0),
+    row(Role::Scrim, PaletteSlot::Neutral, 0.0, 0.0),
+    row(Role::SurfaceTint, PaletteSlot::Primary, 40.0, 80.0),
+    row(Role::PrimaryFixed, PaletteSlot::Primary, 90.0, 90.0),
+    row(Role::PrimaryFixedDim, PaletteSlot::Primary, 80.0, 80.0),
+    row(Role::OnPrimaryFixed, PaletteSlot::Primary, 10.0, 10.0),
+    row(
+        Role::OnPrimaryFixedVariant,
+        PaletteSlot::Primary,
+        30.0,
+        30.0,
+    ),
+    row(Role::SecondaryFixed, PaletteSlot::Secondary, 90.0, 90.0),
+    row(Role::SecondaryFixedDim, PaletteSlot::Secondary, 80.0, 80.0),
+    row(Role::OnSecondaryFixed, PaletteSlot::Secondary, 10.0, 10.0),
+    row(
+        Role::OnSecondaryFixedVariant,
+        PaletteSlot::Secondary,
+        30.0,
+        30.0,
+    ),
+    row(Role::TertiaryFixed, PaletteSlot::Tertiary, 90.0, 90.0),
+    row(Role::TertiaryFixedDim, PaletteSlot::Tertiary, 80.0, 80.0),
+    row(Role::OnTertiaryFixed, PaletteSlot::Tertiary, 10.0, 10.0),
+    row(
+        Role::OnTertiaryFixedVariant,
+        PaletteSlot::Tertiary,
+        30.0,
+        30.0,
+    ),
+];
+
+/// `const` 友好的行构造器（数组初始化里不能调用非 const fn 之外的东西）。
+const fn row(role: Role, slot: PaletteSlot, light: f64, dark: f64) -> ToneRow {
+    ToneRow {
+        role,
+        slot,
+        light,
+        dark,
+    }
+}
+
+/// 一套语义色（49 个角色，全部已解析成具体颜色）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Scheme {
+    flavor: SchemeFlavor,
+    colors: [Color; 49],
+}
+
+impl Scheme {
+    /// **产品出厂默认方案**（种子 [`super::palettes::DEFAULT_SEED`] + 中性彩度
+    /// [`super::palettes::DEFAULT_NEUTRAL_CHROMA`]，见 [`Palettes::baseline`]）。
+    pub fn baseline(flavor: SchemeFlavor) -> Self {
+        Self::from_palettes(&Palettes::baseline(), flavor)
+    }
+
+    /// **官方基线锚点**（种子 `#6750A4` + 官方中性彩度 6，等价官方
+    /// `SchemeTonalSpot(0xFF6750A4)`）。
+    ///
+    /// 与 [`Scheme::baseline`] 的区别只有入参：算法、tone 表、gamut 映射完全同一条路径，
+    /// 所以 `tests/official_baseline.rs` 拿它跟官方 Java 输出逐角色对账。
+    pub fn official_baseline(flavor: SchemeFlavor) -> Self {
+        Self::from_palettes(&Palettes::official_baseline(), flavor)
+    }
+
+    /// 指定种子色的方案（表面色与强调色同源，等价官方 `SchemeTonalSpot`）。
+    pub fn from_seed(flavor: SchemeFlavor, seed: Color) -> Self {
+        Self::from_palettes(&Palettes::from_seed(seed), flavor)
+    }
+
+    /// 只覆盖强调色（表面中性色仍走基线，见 [`Palettes::with_accent`]）。
+    pub fn from_accent(flavor: SchemeFlavor, accent: Color) -> Self {
+        Self::from_palettes(&Palettes::baseline().with_accent(accent), flavor)
+    }
+
+    /// 直接从调色板集合构建（高级入口：整仓测试与自定义 scheme 用）。
+    pub fn from_palettes(palettes: &Palettes, flavor: SchemeFlavor) -> Self {
+        let colors = std::array::from_fn(|i| {
+            let entry = &TONE_TABLE[i];
+            palettes.tone(entry.slot, Scheme::tone_of(entry.role, flavor))
+        });
+        Self { flavor, colors }
+    }
+
+    /// 该角色在指定模式下的 tone 值（M3 语义；文档表格、调试与测试用）。
+    pub fn tone_of(role: Role, flavor: SchemeFlavor) -> f64 {
+        let entry = &TONE_TABLE[role as usize];
+        debug_assert_eq!(entry.role, role, "TONE_TABLE 下标必须等于角色序号");
+        match flavor {
+            SchemeFlavor::Light => entry.light,
+            SchemeFlavor::Dark => entry.dark,
+        }
+    }
+
+    /// 取角色色值。
+    pub fn get(&self, role: Role) -> Color {
+        self.colors[role as usize]
+    }
+
+    /// 当前模式。
+    pub fn flavor(&self) -> SchemeFlavor {
+        self.flavor
+    }
+
+    /// 按角色顺序遍历（`for (role, color) in scheme.iter()`）。
+    pub fn iter(&self) -> impl Iterator<Item = (Role, Color)> + '_ {
+        Role::ALL.iter().copied().map(|role| (role, self.get(role)))
+    }
+
+    /// 阴影色（纯黑 + [`SHADOW_ALPHA`]）。
+    pub fn shadow(&self) -> Color {
+        self.get(Role::Shadow).with_alpha(SHADOW_ALPHA)
+    }
+
+    /// 遮罩色（纯黑 + [`SCRIM_ALPHA`]）。
+    pub fn scrim(&self) -> Color {
+        self.get(Role::Scrim).with_alpha(SCRIM_ALPHA)
+    }
+
+    /// 两个角色的 WCAG 对比度（1..21）。
+    pub fn contrast(&self, fg: Role, bg: Role) -> f32 {
+        self.get(fg).contrast_ratio(self.get(bg))
+    }
+}
+
+impl std::ops::Index<Role> for Scheme {
+    type Output = Color;
+
+    fn index(&self, role: Role) -> &Color {
+        &self.colors[role as usize]
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn tone_table_matches_role_order() {
+        for (i, entry) in TONE_TABLE.iter().enumerate() {
+            assert_eq!(
+                entry.role as usize,
+                i,
+                "TONE_TABLE 第 {i} 行是 {}，顺序与 Role 枚举不一致",
+                entry.role.name()
+            );
+        }
+    }
+
+    #[test]
+    fn fixed_roles_are_identical_across_flavors() {
+        let light = Scheme::baseline(SchemeFlavor::Light);
+        let dark = Scheme::baseline(SchemeFlavor::Dark);
+        for role in [
+            Role::PrimaryFixed,
+            Role::PrimaryFixedDim,
+            Role::OnPrimaryFixed,
+            Role::OnPrimaryFixedVariant,
+            Role::SecondaryFixed,
+            Role::TertiaryFixedDim,
+        ] {
+            assert_eq!(
+                light.get(role),
+                dark.get(role),
+                "{} 应跨模式同值",
+                role.name()
+            );
+        }
+    }
+
+    #[test]
+    fn light_and_dark_differ_on_text_pairs() {
+        let light = Scheme::baseline(SchemeFlavor::Light);
+        let dark = Scheme::baseline(SchemeFlavor::Dark);
+        assert_ne!(light.get(Role::OnSurface), dark.get(Role::OnSurface));
+        assert!(light.get(Role::Surface).relative_luminance() > 0.8);
+        assert!(dark.get(Role::Surface).relative_luminance() < 0.05);
+    }
+
+    #[test]
+    fn shadow_and_scrim_carry_alpha() {
+        let scheme = Scheme::baseline(SchemeFlavor::Light);
+        assert_eq!(scheme.shadow().a, (SHADOW_ALPHA * 255.0).round() as u8);
+        assert_eq!(scheme.scrim().a, (SCRIM_ALPHA * 255.0).round() as u8);
+    }
+
+    #[test]
+    fn accent_override_changes_primary_only() {
+        let base = Scheme::baseline(SchemeFlavor::Light);
+        let teal = Scheme::from_accent(SchemeFlavor::Light, Color::rgb(0x00, 0x6A, 0x5C));
+        assert_ne!(base.get(Role::Primary), teal.get(Role::Primary));
+        assert_eq!(base.get(Role::Surface), teal.get(Role::Surface));
+        assert_eq!(
+            base.get(Role::Outline),
+            teal.get(Role::Outline),
+            "强调色覆盖不该动中性描边"
+        );
+        assert_eq!(base.get(Role::Error), teal.get(Role::Error));
+    }
+}

crates/design/src/color/space.rs

@@ -0,0 +1,203 @@
+//! 色彩空间底层换算：sRGB ↔ 线性 RGB ↔ CIE XYZ ↔ `L*`（tone 轴）。
+//!
+//! 只放**纯数学**，不认识任何语义色角色。数值口径逐函数照搬 Google
+//! `material-color-utilities` 的 `java/utils/ColorUtils.java`（Apache-2.0，见 `NOTICE`）：
+//! 矩阵、阈值、取整方式都一致——差一位小数，HCT 求解器就会与官方差一个通道。
+//!
+//! 内部一律用 `f64`（官方实现是 Java `double`）。公开 API 仍以 `u8` 通道与 `f32` 标量对外，
+//! 因为令牌消费方（绘制层）不需要比 8 bit 更高的精度。
+
+use super::Color;
+
+/// sRGB → XYZ（D65）。官方用的是 IEC 6-1 的舍入值，不是更精确的 sRGB 矩阵。
+const SRGB_TO_XYZ: [[f64; 3]; 3] = [
+    [0.412_338_95, 0.357_620_64, 0.180_510_42],
+    [0.2126, 0.7152, 0.0722],
+    [0.019_321_41, 0.119_163_82, 0.950_344_78],
+];
+
+/// D65 白点（XYZ，Y 归一化到 100）。
+pub(crate) const WHITE_POINT_D65: [f64; 3] = [95.047, 100.0, 108.883];
+
+/// 行向量 × 3×3 矩阵。
+pub(crate) fn matrix_multiply(row: [f64; 3], matrix: [[f64; 3]; 3]) -> [f64; 3] {
+    let mul = |m: [f64; 3]| row[0] * m[0] + row[1] * m[1] + row[2] * m[2];
+    [mul(matrix[0]), mul(matrix[1]), mul(matrix[2])]
+}
+
+/// sRGB 编码值（8 bit 通道）→ 线性光强（0..=100，官方标度）。
+pub(crate) fn linearized(component: u8) -> f64 {
+    let normalized = f64::from(component) / 255.0;
+    if normalized <= 0.040_449_936 {
+        normalized / 12.92 * 100.0
+    } else {
+        ((normalized + 0.055) / 1.055).powf(2.4) * 100.0
+    }
+}
+
+/// 线性光强（0..=100）→ sRGB 编码值，四舍五入并夹取到 0..=255。
+pub(crate) fn delinearized(component: f64) -> u8 {
+    let value = true_delinearized(component).round().clamp(0.0, 255.0);
+    value as u8
+}
+
+/// 同 [`delinearized`]，但不取整也不夹取（求解器二分时需要连续值）。
+pub(crate) fn true_delinearized(component: f64) -> f64 {
+    let normalized = component / 100.0;
+    let encoded = if normalized <= 0.003_130_8 {
+        normalized * 12.92
+    } else {
+        1.055 * normalized.powf(1.0 / 2.4) - 0.055
+    };
+    encoded * 255.0
+}
+
+/// 线性 RGB（0..=100）→ 不透明颜色。
+pub(crate) fn color_from_linrgb(linrgb: [f64; 3]) -> Color {
+    Color::rgb(
+        delinearized(linrgb[0]),
+        delinearized(linrgb[1]),
+        delinearized(linrgb[2]),
+    )
+}
+
+/// 色值 → XYZ（Y 在 0..=100 标度）。
+pub(crate) fn xyz_from_color(color: Color) -> [f64; 3] {
+    let linear = [
+        linearized(color.r),
+        linearized(color.g),
+        linearized(color.b),
+    ];
+    matrix_multiply(linear, SRGB_TO_XYZ)
+}
+
+/// `L*` 的比较函数（CIE 分段线性/立方根）。
+fn lab_f(t: f64) -> f64 {
+    const EPSILON: f64 = 216.0 / 24389.0;
+    const KAPPA: f64 = 24389.0 / 27.0;
+    if t > EPSILON {
+        t.powf(1.0 / 3.0)
+    } else {
+        (KAPPA * t + 16.0) / 116.0
+    }
+}
+
+/// [`lab_f`] 的逆。
+fn lab_invf(ft: f64) -> f64 {
+    const EPSILON: f64 = 216.0 / 24389.0;
+    const KAPPA: f64 = 24389.0 / 27.0;
+    let cubed = ft * ft * ft;
+    if cubed > EPSILON {
+        cubed
+    } else {
+        (116.0 * ft - 16.0) / KAPPA
+    }
+}
+
+/// `L*` → 相对亮度 Y（0..=100）。
+pub(crate) fn y_from_lstar(lstar: f64) -> f64 {
+    100.0 * lab_invf((lstar + 16.0) / 116.0)
+}
+
+/// 相对亮度 Y（0..=100）→ `L*`。
+pub(crate) fn lstar_from_y(y: f64) -> f64 {
+    lab_f(y / 100.0) * 116.0 - 16.0
+}
+
+/// 色值 → `L*`（即 M3 的 **tone**）。
+pub(crate) fn lstar_from_color(color: Color) -> f64 {
+    lstar_from_y(xyz_from_color(color)[1])
+}
+
+/// `L*` → 中性灰色值（`L*` 与彩度无关，纯灰）。
+pub(crate) fn color_from_lstar(lstar: f64) -> Color {
+    let component = delinearized(y_from_lstar(lstar));
+    Color::rgb(component, component, component)
+}
+
+/// Java `Math.signum` 的口径：负数 −1、零 0、正数 1（**Rust 的 `f64::signum(0.0)` 是 1**，
+/// 直接换会改变中性色的求解结果）。
+pub(crate) fn signum(value: f64) -> f64 {
+    if value < 0.0 {
+        -1.0
+    } else if value == 0.0 {
+        0.0
+    } else {
+        1.0
+    }
+}
+
+/// 角度归一到 `0.0..360.0`。
+pub(crate) fn sanitize_degrees(degrees: f64) -> f64 {
+    let wrapped = degrees % 360.0;
+    if wrapped < 0.0 {
+        wrapped + 360.0
+    } else {
+        wrapped
+    }
+}
+
+/// 弧度归一到 `0.0..2π`（官方 `sanitizeRadians`，多加了 8π 保证非负）。
+pub(crate) fn sanitize_radians(angle: f64) -> f64 {
+    (angle + std::f64::consts::PI * 8.0) % (std::f64::consts::PI * 2.0)
+}
+
+/// 线性插值（官方 `lerp`）。
+pub(crate) fn lerp(start: f64, stop: f64, amount: f64) -> f64 {
+    (1.0 - amount) * start + amount * stop
+}
+
+/// 夹取到 `min..=max`。
+pub(crate) fn clamp(min: f64, max: f64, input: f64) -> f64 {
+    input.clamp(min, max)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn lstar_and_luminance_are_inverse() {
+        for lstar in [0.0_f64, 8.0, 20.0, 50.0, 87.0, 98.0, 100.0] {
+            let back = lstar_from_y(y_from_lstar(lstar));
+            assert!((back - lstar).abs() < 1.0e-9, "L* {lstar} 往返成 {back}");
+        }
+    }
+
+    #[test]
+    fn white_and_black_anchor_the_scale() {
+        assert_eq!(delinearized(100.0), 255);
+        assert_eq!(delinearized(0.0), 0);
+        assert_eq!(color_from_lstar(100.0), Color::WHITE);
+        assert_eq!(color_from_lstar(0.0), Color::BLACK);
+        assert!((lstar_from_color(Color::WHITE) - 100.0).abs() < 1.0e-6);
+        assert!(lstar_from_color(Color::BLACK).abs() < 1.0e-6);
+    }
+
+    #[test]
+    fn white_point_matches_d65() {
+        // 用官方那组舍入矩阵，纯白必须落在 D65 白点上（容差 1e-3 对应矩阵末位舍入）。
+        let xyz = xyz_from_color(Color::WHITE);
+        for (got, want) in xyz.iter().zip(WHITE_POINT_D65) {
+            assert!(
+                (got - want).abs() < 1.0e-3,
+                "{xyz:?} vs D65 {WHITE_POINT_D65:?}"
+            );
+        }
+        assert!(xyz_from_color(Color::BLACK).iter().all(|v| *v == 0.0));
+    }
+
+    #[test]
+    fn signum_matches_java_semantics() {
+        assert_eq!(signum(-1.5), -1.0);
+        assert_eq!(signum(0.0), 0.0);
+        assert_eq!(signum(-0.0), 0.0);
+        assert_eq!(signum(2.5), 1.0);
+    }
+
+    #[test]
+    fn degrees_sanitize_wraps_negatives() {
+        assert!((sanitize_degrees(-30.0) - 330.0).abs() < 1.0e-9);
+        assert!(sanitize_degrees(360.0).abs() < 1.0e-9);
+    }
+}

crates/design/src/color/state.rs

@@ -0,0 +1,96 @@
+//! M3 状态层（state layer）与禁用态透明度。
+//!
+//! M3 的 hover/pressed 不是「另一种灰」，而是**内容色自身 + 固定 alpha** 叠在容器上——
+//! 所以同一套令牌在任何底色上都成立，不必为每种底色各配一套（这条从 Fluent 时代沿用，
+//! 见 `DevDocs/SubAgentsTalk/ui-integration-contract.md` §2 的三态叠加层思路）。
+
+use super::Color;
+
+/// 状态层的四种状态与对应 alpha（M3 规范值）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum StateLayer {
+    /// 悬停：内容色 8%。
+    Hover,
+    /// 键盘焦点：内容色 10%。
+    Focus,
+    /// 按下：内容色 10%。
+    Pressed,
+    /// 拖拽中：内容色 16%。
+    Dragged,
+}
+
+impl StateLayer {
+    /// 叠加透明度（0..1）。
+    pub const fn alpha(self) -> f32 {
+        match self {
+            StateLayer::Hover => 0.08,
+            StateLayer::Focus | StateLayer::Pressed => 0.10,
+            StateLayer::Dragged => 0.16,
+        }
+    }
+
+    /// 把状态层叠到容器色上，得到**最终不透明色**。
+    ///
+    /// `content` 一般是容器上的前景角色（例如 FilledButton 用 `on-primary`，
+    /// 中性表面上的按钮用 `on-surface`）。
+    pub fn over(self, content: Color, container: Color) -> Color {
+        content.with_alpha(self.alpha()).over(container)
+    }
+}
+
+/// 禁用态的透明度（M3）：容器 12%、内容 38%。
+///
+/// 别用「灰化」近似——深色模式下灰化会降低对比度，alpha 叠加两种模式都成立。
+pub const DISABLED_CONTAINER_ALPHA: f32 = 0.12;
+/// 禁用态内容（文字/图标）透明度。
+pub const DISABLED_CONTENT_ALPHA: f32 = 0.38;
+
+/// 禁用态容器色：`on_surface` 12% 叠在 `surface` 上。
+pub fn disabled_container(scheme: &super::Scheme) -> Color {
+    scheme
+        .get(super::Role::OnSurface)
+        .with_alpha(DISABLED_CONTAINER_ALPHA)
+        .over(scheme.get(super::Role::Surface))
+}
+
+/// 禁用态内容色：`on_surface` 38% 叠在容器上。
+pub fn disabled_content(scheme: &super::Scheme, container: Color) -> Color {
+    scheme
+        .get(super::Role::OnSurface)
+        .with_alpha(DISABLED_CONTENT_ALPHA)
+        .over(container)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::color::{Role, Scheme, SchemeFlavor};
+
+    #[test]
+    fn hover_is_lighter_than_pressed_on_dark_container() {
+        let scheme = Scheme::baseline(SchemeFlavor::Dark);
+        let container = scheme.get(Role::SurfaceContainer);
+        let content = scheme.get(Role::OnSurface);
+        let hover = StateLayer::Hover.over(content, container);
+        let pressed = StateLayer::Pressed.over(content, container);
+        assert_eq!(hover.a, 255);
+        assert!(pressed.relative_luminance() > hover.relative_luminance());
+    }
+
+    #[test]
+    fn state_layer_alpha_matches_m3() {
+        assert!((StateLayer::Hover.alpha() - 0.08).abs() < f32::EPSILON);
+        assert!((StateLayer::Dragged.alpha() - 0.16).abs() < f32::EPSILON);
+    }
+
+    #[test]
+    fn disabled_content_stays_visible() {
+        let scheme = Scheme::baseline(SchemeFlavor::Light);
+        let container = disabled_container(&scheme);
+        let content = disabled_content(&scheme, container);
+        // 禁用态不追求 AA（规范就是这么定的），但必须仍可辨（> 1.5:1）。
+        let ratio = content.contrast_ratio(container);
+        assert!(ratio > 1.5, "禁用态对比度过低：{ratio}");
+        assert!(ratio < 4.5, "禁用态不该和正文一样醒目：{ratio}");
+    }
+}

crates/design/src/color/tonal.rs

@@ -0,0 +1,150 @@
+//! tone 调色板：**固定 HCT 色相 + 固定 HCT 彩度**，沿 tone 轴取色。
+//!
+//! 这就是 M3 的 `TonalPalette`：一条调色板只回答一个问题——「我的第 N 号 tone 是什么色」。
+//! 因为 HCT 的 tone 轴是 `L*`，同一条调色板上「tone 差 40 ⇒ 对比度 ≥ 3:1」天然成立；
+//! 又因为 hue 固定，整条调色板在感知上是同一个色相（这正是 OKLCh 近似做不到的那一点）。
+//!
+//! 语义对齐 `java/palettes/TonalPalette.java`（Apache-2.0，见 `NOTICE`）。
+
+use super::{Color, Hct};
+
+/// 一条 tone 调色板（HCT 色相 + 彩度上限）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct TonalPalette {
+    hue_deg: f64,
+    chroma: f64,
+}
+
+impl TonalPalette {
+    /// 直接给 HCT 色相（度）与 HCT 彩度建调色板（彩度 0 = 中性灰）。
+    pub fn new(hue_deg: f64, chroma: f64) -> Self {
+        Self {
+            hue_deg: hue_deg.rem_euclid(360.0),
+            chroma: chroma.max(0.0),
+        }
+    }
+
+    /// 从种子色取 HCT 色相与彩度（等价官方 `TonalPalette.fromInt`）。
+    pub fn from_color(seed: Color) -> Self {
+        let hct = Hct::from_color(seed);
+        Self::new(hct.hue, hct.chroma)
+    }
+
+    /// 固定色相，换彩度（M3 用它把种子的彩度压到 secondary/neutral 档）。
+    pub fn with_chroma(self, chroma: f64) -> Self {
+        Self::new(self.hue_deg, chroma)
+    }
+
+    /// 旋转色相（derived hue，例如 tertiary = 种子色相 +60°）。
+    pub fn rotated(self, deg: f64) -> Self {
+        Self::new(self.hue_deg + deg, self.chroma)
+    }
+
+    /// 该调色板的 HCT 色相（度）。
+    pub fn hue_deg(self) -> f64 {
+        self.hue_deg
+    }
+
+    /// 该调色板的 HCT 彩度。
+    pub fn chroma(self) -> f64 {
+        self.chroma
+    }
+
+    /// 取某个 tone 的颜色（tone 超出 0..=100 时自然夹到纯黑/纯白）。
+    ///
+    /// 彩度装不下时按官方的 gamut 映射**只压彩度**，色相与 tone 不变。
+    pub fn tone(self, tone: f64) -> Color {
+        self.hct(tone).to_color()
+    }
+
+    /// 取某个 tone 的 HCT 坐标（`TonalPalette.hct` / 官方 `getHct`）。
+    ///
+    /// 黄相（105°..125°）的 tone 99 是官方的特例：那里 `L*` 与 sRGB 平面不平滑，
+    /// 直接横向取自 tone 98 与 tone 100 的中点，避免出一格色带。
+    pub fn hct(self, tone: f64) -> Hct {
+        if tone == 99.0 && Hct::is_yellow(self.hue_deg) {
+            let low = self.hct(98.0).to_color();
+            let high = self.hct(100.0).to_color();
+            return Hct::from_color(average(low, high));
+        }
+        Hct::from_components(self.hue_deg, self.chroma, tone)
+    }
+}
+
+/// 两色的通道中点（官方 `averageArgb`，四舍五入）。
+fn average(a: Color, b: Color) -> Color {
+    let mid = |x: u8, y: u8| {
+        let sum = u16::from(x) + u16::from(y);
+        u8::try_from(sum.div_ceil(2)).unwrap_or(u8::MAX)
+    };
+    Color::rgb(mid(a.r, b.r), mid(a.g, b.g), mid(a.b, b.b))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const SEED: Color = Color::rgb(0x67, 0x50, 0xA4);
+
+    #[test]
+    fn tone_is_hit_within_quantisation_error() {
+        let palette = TonalPalette::from_color(SEED).with_chroma(36.0);
+        for tone in [
+            4.0_f64, 6.0, 10.0, 12.0, 17.0, 20.0, 30.0, 40.0, 50.0, 80.0, 87.0, 90.0, 92.0, 94.0,
+            95.0, 96.0, 98.0,
+        ] {
+            let got = Hct::from_color(palette.tone(tone)).tone;
+            assert!(
+                (got - tone).abs() <= 1.0,
+                "tone {tone} 的 L* 是 {got}，偏差超过 1（8 bit 量化上限）"
+            );
+        }
+    }
+
+    #[test]
+    fn extremes_are_pure_black_and_white() {
+        let palette = TonalPalette::from_color(SEED);
+        assert_eq!(palette.tone(0.0), Color::rgb(0, 0, 0));
+        assert_eq!(palette.tone(100.0), Color::rgb(255, 255, 255));
+        assert_eq!(palette.tone(-5.0), Color::rgb(0, 0, 0));
+        assert_eq!(palette.tone(120.0), Color::rgb(255, 255, 255));
+    }
+
+    #[test]
+    fn hue_is_preserved_across_the_whole_ramp() {
+        let palette = TonalPalette::new(298.980_997, 36.0);
+        for tone in [10.0_f64, 30.0, 50.0, 70.0, 90.0] {
+            let hct = palette.hct(tone);
+            let delta = (hct.hue - palette.hue_deg()).abs();
+            let delta = delta.min(360.0 - delta);
+            assert!(delta < 1.0, "tone {tone} 色相偏移 {delta}°");
+        }
+    }
+
+    #[test]
+    fn chroma_zero_is_neutral_gray() {
+        let neutral = TonalPalette::new(120.0, 0.0);
+        for tone in [6.0_f64, 30.0, 50.0, 90.0, 98.0] {
+            let color = neutral.tone(tone);
+            assert!(color.r == color.g && color.g == color.b, "{color:?}");
+        }
+    }
+
+    #[test]
+    fn yellow_tone_99_uses_the_official_average() {
+        let palette = TonalPalette::new(110.0, 40.0);
+        let expected = average(palette.tone(98.0), palette.tone(100.0));
+        assert_eq!(palette.tone(99.0), expected);
+        // 非黄相不触发特例：tone 99 走正常求解。
+        let normal = TonalPalette::new(300.0, 40.0);
+        assert_eq!(normal.tone(99.0), normal.hct(99.0).to_color());
+    }
+
+    #[test]
+    fn requested_chroma_is_respected_when_the_gamut_allows() {
+        // tone 50 是最「宽」的色调面，彩度 36 一定装得下。
+        let palette = TonalPalette::new(298.980_997, 36.0);
+        let hct = palette.hct(50.0);
+        assert!((hct.chroma - 36.0).abs() < 0.5, "彩度 {}", hct.chroma);
+    }
+}

crates/design/src/color/viewing_conditions.rs

@@ -0,0 +1,165 @@
+//! CAM16 的**观察条件**（viewing conditions）。
+//!
+//! HCT 的色相/彩度来自 CAM16，而 CAM16 是「在外界光环境下看起来如何」的模型——同一个 hex，
+//! 换观察条件就是不同的 hue/chroma。M3 固定用 sRGB 默认条件：D65 白点、200 lux（适应亮度）、
+//! 背景 `L* = 50`、surround = 2.0、**不做**光源折扣（自发光屏幕）。
+//!
+//! 照搬 `java/hct/ViewingConditions.java`（Apache-2.0，见 `NOTICE`）。
+
+use super::space;
+
+/// CAM16 观察条件里与颜色无关的那堆中间量（只为避免重复计算）。
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct ViewingConditions {
+    /// 白点响应（achromatic response to the white point）。
+    pub(crate) aw: f64,
+    /// 背景亮度因子。
+    pub(crate) n: f64,
+    /// 亮度指数。
+    pub(crate) nbb: f64,
+    /// 彩度指数。
+    pub(crate) ncb: f64,
+    /// 环绕度决定的对比度系数。
+    pub(crate) c: f64,
+    /// 环绕度。
+    pub(crate) nc: f64,
+    /// 三通道的色适应折扣系数。
+    pub(crate) rgb_d: [f64; 3],
+    /// 亮度适应因子。
+    pub(crate) fl: f64,
+    /// 基函数。
+    pub(crate) z: f64,
+}
+
+// 与 XYZ 有关的常量矩阵在 CAM16 里也要用，从 space 引一次保持单一来源。
+use super::cam16::XYZ_TO_CAM16_RGB;
+
+impl ViewingConditions {
+    /// 按官方参数构造（`white_point` 是 XYZ，`adapting_luminance` 由 lux 换算）。
+    pub(crate) fn make(
+        white_point: [f64; 3],
+        adapting_luminance: f64,
+        background_lstar: f64,
+        surround: f64,
+        discounting_illuminant: bool,
+    ) -> Self {
+        // 纯黑背景是非物理的，会让「任何颜色都看不见」这类无穷大出现，官方取下限 0.1。
+        let background_lstar = background_lstar.max(0.1);
+        let [r_w, g_w, b_w] = space::matrix_multiply(white_point, XYZ_TO_CAM16_RGB);
+        let f = 0.8 + surround / 10.0;
+        let c = if f >= 0.9 {
+            space::lerp(0.59, 0.69, (f - 0.9) * 10.0)
+        } else {
+            space::lerp(0.525, 0.59, (f - 0.8) * 10.0)
+        };
+        let d = if discounting_illuminant {
+            1.0
+        } else {
+            let raw = f * (1.0 - (1.0 / 3.6) * ((-adapting_luminance - 42.0) / 92.0).exp());
+            space::clamp(0.0, 1.0, raw)
+        };
+        let nc = f;
+        let rgb_d = [
+            d * (100.0 / r_w) + 1.0 - d,
+            d * (100.0 / g_w) + 1.0 - d,
+            d * (100.0 / b_w) + 1.0 - d,
+        ];
+        let k = 1.0 / (5.0 * adapting_luminance + 1.0);
+        let k4 = k * k * k * k;
+        let k4_f = 1.0 - k4;
+        let fl = k4 * adapting_luminance + 0.1 * k4_f * k4_f * (5.0 * adapting_luminance).cbrt();
+        let n = space::y_from_lstar(background_lstar) / white_point[1];
+        let z = 1.48 + n.sqrt();
+        let nbb = 0.725 / n.powf(0.2);
+        let ncb = nbb;
+        let rgb_a_factors = [
+            (fl * rgb_d[0] * r_w / 100.0).powf(0.42),
+            (fl * rgb_d[1] * g_w / 100.0).powf(0.42),
+            (fl * rgb_d[2] * b_w / 100.0).powf(0.42),
+        ];
+        let rgb_a = [
+            400.0 * rgb_a_factors[0] / (rgb_a_factors[0] + 27.13),
+            400.0 * rgb_a_factors[1] / (rgb_a_factors[1] + 27.13),
+            400.0 * rgb_a_factors[2] / (rgb_a_factors[2] + 27.13),
+        ];
+        let aw = (2.0 * rgb_a[0] + rgb_a[1] + 0.05 * rgb_a[2]) * nbb;
+        Self {
+            aw,
+            n,
+            nbb,
+            ncb,
+            c,
+            nc,
+            rgb_d,
+            fl,
+            z,
+        }
+    }
+
+    /// 指定背景 `L*` 的 sRGB 默认条件。
+    pub(crate) fn default_with_background_lstar(background_lstar: f64) -> Self {
+        Self::make(
+            space::WHITE_POINT_D65,
+            200.0 / std::f64::consts::PI * space::y_from_lstar(50.0) / 100.0,
+            background_lstar,
+            2.0,
+            false,
+        )
+    }
+}
+
+/// 全仓共用的默认观察条件（sRGB 屏，背景 `L* = 50`）。
+pub(crate) fn default_conditions() -> &'static ViewingConditions {
+    static DEFAULT: std::sync::OnceLock<ViewingConditions> = std::sync::OnceLock::new();
+    DEFAULT.get_or_init(|| ViewingConditions::default_with_background_lstar(50.0))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default_conditions_match_the_official_constants() {
+        // 官方 material-color-utilities 的 ViewingConditions.DEFAULT 解出来的值（Java 实测，
+        // `hct.Count` 打印）。
+        let vc = default_conditions();
+        assert!(
+            (vc.n - 0.184_186_518_512_444_16).abs() < 1.0e-12,
+            "n = {}",
+            vc.n
+        );
+        assert!(
+            (vc.aw - 29.980_997_194_447_333).abs() < 1.0e-12,
+            "aw = {}",
+            vc.aw
+        );
+        assert!(
+            (vc.nbb - 1.016_919_180_445_875_5).abs() < 1.0e-12,
+            "nbb = {}",
+            vc.nbb
+        );
+        assert!((vc.c - 0.69).abs() < 1.0e-12);
+        assert!((vc.nc - 1.0).abs() < 1.0e-12);
+        assert!(
+            (vc.fl - 0.388_481_453_780_035_3).abs() < 1.0e-12,
+            "fl = {}",
+            vc.fl
+        );
+        assert!(
+            (vc.z - 1.909_169_568_483_652).abs() < 1.0e-12,
+            "z = {}",
+            vc.z
+        );
+        assert!((vc.rgb_d[0] - 1.021_177_702_757_52).abs() < 1.0e-12);
+        assert!((vc.rgb_d[1] - 0.986_307_729_428_012_4).abs() < 1.0e-12);
+        assert!((vc.rgb_d[2] - 0.933_960_508_280_229_9).abs() < 1.0e-12);
+    }
+
+    #[test]
+    fn white_point_has_zero_chroma_in_cam16() {
+        // CAM16 的白点在默认条件下应当接近中性（这才是「色适应」的意义）。
+        use super::super::cam16::Cam16;
+        let white = Cam16::from_color(super::super::Color::WHITE);
+        assert!(white.chroma < 5.0, "白点彩度 {}", white.chroma);
+    }
+}

crates/design/src/component_map/metrics.rs

@@ -0,0 +1,179 @@
+//! 组件级微度量（`ComponentMetrics`）：**单个控件内部的几何**，不是窗口骨架。
+//!
+//! 为什么要有这个结构（M69 / G10）：Checkbox 的 20×20、圆角 2、描边 2、状态层 Ø40 这类值，
+//! `ShapeScale`（刻度）装不了、`LayoutMetrics`（骨架）也不该装——M66 对账时它们只能写在组件
+//! 实现里，而 D30 禁止组件层自定义数值。这里给它们一个**唯一落点**。
+//!
+//! ## 与 `LayoutMetrics` 的分工（两把尺子，量不同的东西）
+//!
+//! | | [`crate::spacing::LayoutMetrics`] | `ComponentMetrics`（本模块） |
+//! |---|---|---|
+//! | 管什么 | 窗口骨架与布局节奏：标题栏/页头/行高、dock 宽度、命中区 | 单个控件方框内的几何：外框、微圆角、描边/环线宽、状态层、内点、图标偏移 |
+//! | 随什么变 | 窗口尺寸、列宽、用户折叠导航 | 只随组件自身规格变 |
+//! | 例子 | `nav_drawer_width = 240`、`search_bar_height = 56` | checkbox 20×20、描边 2、状态层 Ø40 |
+//! | 判据 | 决定「一块面板/一行占多宽多高」 | 决定「画进这个方框里的那几个像素」 |
+//!
+//! 冲突时的规则是**同一个量只许有一份**：搜索条高 56 属骨架级，所以
+//! [`ComponentMetrics::SEARCH_BAR`] 的 `height` 留 `0.0` 并在文档里指回 LM；drawer 宽同理。
+//! 测试 `component_metrics_never_duplicate_layout_metrics` 把这条钉死。
+//!
+//! 数值来源：`androidx.compose.material3:material3-android:1.4.0` 源码（A 级，M66 逐行核对，
+//! 见 `research/15` §18~§23）。逐字段的出处写在下面各组件的关联常量上；**团队口径**（官方没有
+//! token 的）单独注明。
+
+use super::Component;
+use crate::icons::IconSize;
+use crate::shape::ComponentRadius;
+use crate::spacing::Space;
+
+/// 单个控件的内部几何。
+///
+/// `0.0` 表示**该控件没有这一项**（不是「默认值 0」）——拿 `0.0` 反推数值一定错。
+/// 骨架级尺寸（条高、面板宽）不在这里，去 [`crate::spacing::LayoutMetrics`] 拿。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct ComponentMetrics {
+    /// 可见外框宽（dp；`0.0` = 由内容或骨架决定）。
+    pub width: f32,
+    /// 可见外框高（dp；`0.0` = 由内容或骨架决定）。
+    pub height: f32,
+    /// 微控件圆角（D32 第二层）。`None` = 该控件的圆角走 `ShapeScale`（见 `ComponentSpec::shape`）。
+    pub radius: Option<ComponentRadius>,
+    /// 描边 / 环线宽度（dp）。**禁用态也不许变细**——官方 disabled 只改透明度。
+    pub stroke: f32,
+    /// 状态层（hover / focus / pressed）圆的直径（dp；`0.0` = 不画状态层）。
+    pub state_layer: f32,
+    /// 内点直径（dp）：radio 选中时的实心点，其余控件 `0.0`。
+    pub inner_dot: f32,
+    /// 控件相对容器的外距（dp）：drawer 项 = 12，决定选中指示器左右各内缩 12。
+    pub inset: f32,
+    /// 内容起始侧内边距（dp）。**图标不算在内**：图标可视边 = `pad_start + icon_offset`。
+    pub pad_start: f32,
+    /// 内容结束侧内边距（dp）。同起始侧，图标可视边 = `pad_end + icon_offset`。
+    pub pad_end: f32,
+    /// 图标边长（dp；`0.0` = 无图标）。
+    pub icon: f32,
+    /// 图标相对内边距的**额外**偏移（dp）。图标可视边 = 内边距 + 本值（search bar：12 + 4 = 16），
+    /// **不要**把内边距本身当图标边用，也不要再手抄那个 12 / 16。
+    pub icon_offset: f32,
+    /// 图标与文字（或相邻元素）的间距（dp）。
+    pub gap: f32,
+}
+
+impl ComponentMetrics {
+    /// Checkbox（`research/15` §18 / §23）。
+    ///
+    /// A 级出处：`Checkbox.kt:737 CheckboxSize = 20.dp`、`:738 RadiusSize = 2.dp`（圆角走 D32 的
+    /// [`ComponentRadius::Micro`]）、`CheckboxTokens.UnselectedOutlineWidth = 2`、
+    /// `StateLayerSize = 40` + `StateLayerShape = CornerFull`。
+    /// 注意 `CheckboxTokens.ContainerWidth/Height = 18` 是**死值**（全仓 0 引用），Compose 实际画
+    /// 20（§26.2 矛盾 ①）——判据取 20。
+    /// 勾选控件 ↔ 标签间距 8 是**团队口径**：官方没有「框 + 标签」组合的 token（§18.9，估）。
+    pub const CHECKBOX: Self = Self {
+        width: 20.0,
+        height: 20.0,
+        radius: Some(ComponentRadius::Micro),
+        stroke: 2.0,
+        state_layer: 40.0,
+        inner_dot: 0.0,
+        inset: 0.0,
+        pad_start: 0.0,
+        pad_end: 0.0,
+        icon: 0.0,
+        icon_offset: 0.0,
+        gap: Space::X2.dp(),
+    };
+
+    /// Radio（`research/15` §19 / §23）。
+    ///
+    /// A 级出处：`RadioButtonTokens.IconSize = 20`、`RadioStrokeWidth = 2.dp`；内点名义
+    /// `RadioButtonDotSize = 12`，但绘制半径 = 12/2 − stroke/2 = 5 → **实际内点直径 10**
+    /// （§19.2：抄 12 会明显偏大）。圆角走 `ShapeScale::Full`（真圆），不是微半径。
+    /// 标签间距 8 同 Checkbox（团队口径）。
+    pub const RADIO: Self = Self {
+        width: 20.0,
+        height: 20.0,
+        radius: None,
+        stroke: 2.0,
+        state_layer: 40.0,
+        inner_dot: 10.0,
+        inset: 0.0,
+        pad_start: 0.0,
+        pad_end: 0.0,
+        icon: 0.0,
+        icon_offset: 0.0,
+        gap: Space::X2.dp(),
+    };
+
+    /// Search bar（`research/15` §20A / §23）。
+    ///
+    /// 高度与宽度**不在这里**：条高 56 是骨架级（`LayoutMetrics::search_bar_height`），
+    /// 最小宽 360 同样属骨架级（尚未进 LM，M69 报告里登记为待办）。这里只装画进 bar 里的几何：
+    /// 图标 24（`IconSize::Toolbar`）、**图标可视边 = `pad_start + icon_offset`** = 12 + 4 = **16**
+    /// （右侧同式为 16，§20.4）、圆角走 `ShapeScale::Full`（56 → 28 = 官方 `SearchBarCornerRadius`），
+    /// 所以 `radius` 是 `None`。
+    ///
+    /// 为什么要拆成 12 + 4 而不是直接写 16：官方 = 文本框内容内边距 **12**（`TextFieldImpl` 默认）
+    /// 加上 `SearchBarIconOffsetX = 4`。拆开才能让「文本从 12 起、图标从 16 起」都被消费方拿到；
+    /// 只写 16 的话文本内边距没有落点，消费方只能自己写 `12.0`——正是 G10 要消灭的字面量。
+    /// 图标位置一律按 `pad + icon_offset` 求和，不要单独把 `pad` 当图标边用。
+    pub const SEARCH_BAR: Self = Self {
+        width: 0.0,
+        height: 0.0,
+        radius: None,
+        stroke: 0.0,
+        state_layer: 0.0,
+        inner_dot: 0.0,
+        inset: 0.0,
+        pad_start: Space::X3.dp(),
+        pad_end: Space::X3.dp(),
+        icon: IconSize::Toolbar.px(),
+        icon_offset: 4.0,
+        // 图标 ↔ 文本 8 是**团队口径 [估]**：`research/15` §20.4 只给了图标尺寸/位置与 48 命中框，
+        // 没有「图标 ↔ 文字」的 token（Compose 由 `TextFieldImpl` 内部排版决定）。
+        gap: Space::X2.dp(),
+    };
+
+    /// Navigation drawer（`research/15` §21 / §23）。
+    ///
+    /// 宽度与项高**不在这里**：drawer 240 / rail 88 在 `LayoutMetrics`，项高 44 =
+    /// `LayoutMetrics::nav_item_height`。这里装项内几何（§21.6，A 级：
+    /// `NavigationDrawerItemDefaults.ItemPadding = 12`、项内 start 16 / end 24、
+    /// `IconSize = 24`、图标 ↔ label 12）。
+    /// 容器形状 `CornerLargeEnd`（只有靠内容那一侧两角 16）由 `ComponentSpec::shape` 的
+    /// `Large` + 组件实现按侧位决定哪两个角，度量层不表达「部分角」。
+    pub const NAVIGATION_DRAWER: Self = Self {
+        width: 0.0,
+        height: 0.0,
+        radius: None,
+        stroke: 0.0,
+        state_layer: 0.0,
+        inner_dot: 0.0,
+        inset: 12.0,
+        pad_start: Space::X4.dp(),
+        pad_end: Space::X6.dp(),
+        icon: IconSize::Toolbar.px(),
+        icon_offset: 0.0,
+        gap: Space::X3.dp(),
+    };
+
+    /// drawer 选中指示器宽度：容器宽 − 2 × [`ComponentMetrics::inset`]。
+    ///
+    /// 240 − 24 = **216**；官方 360 − 24 = 336 是同一个公式（§21.5）——写死 336 就是忘了推导。
+    pub fn indicator_width(&self, container_width: f32) -> f32 {
+        (container_width - self.inset * 2.0).max(0.0)
+    }
+}
+
+/// 组件 → 组件级微度量。`None` = 该组件没有控件内部几何（只有骨架值，去 LM 拿）。
+///
+/// Divider 是 `None` 的显式例子：它的唯一几何量是厚度，而厚度是**一像素线**
+/// （`LayoutMetrics::divider_thickness` = `stroke::HAIRLINE`），不是「控件内部」的东西。
+pub(super) const fn metrics_of(component: Component) -> Option<ComponentMetrics> {
+    match component {
+        Component::Checkbox => Some(ComponentMetrics::CHECKBOX),
+        Component::Radio => Some(ComponentMetrics::RADIO),
+        Component::Search => Some(ComponentMetrics::SEARCH_BAR),
+        Component::NavigationDrawer => Some(ComponentMetrics::NAVIGATION_DRAWER),
+        _ => None,
+    }
+}

crates/design/src/component_map/mod.rs

@@ -0,0 +1,212 @@
+//! 组件 → 档位映射表：哪个组件用哪档形状 / 高程 / 字体 / 动效。
+//!
+//! 目的不是「规定 M3 官方长什么样」（官方只给组件规格，不给启动器里的档位表），而是
+//! **给 iced 页面线一个不需要再谈判的默认值**：同一个组件在五个页面里长得一样，
+//! 才有用户要的「UI 整体性」。
+//!
+//! 口径：
+//! - 形状档位见 [`crate::shape::ShapeScale`]，高程见 [`crate::elevation::Elevation`]；
+//! - `text` 是主要文字角色，`support` 是辅助文字（没有就 `None`）；
+//! - `motion` + `duration` 是状态过渡（hover/press/展开），不是页面切换；
+//! - `morph` 是按下/选中时的形状形变（Expressive 特征），不需要就 `None`；
+//! - 圆角分两层（D32）：容器级查 [`crate::shape::ShapeScale`]，≤24dp 的微控件查
+//!   [`crate::shape::ComponentRadius`]（落在 [`ComponentSpec::micro_radius`]）。
+//!
+//! 档位（形状/高程/字级/动效）之外，**控件内部的微几何**（20×20、描边 2、状态层 Ø40 …）在
+//! [`ComponentMetrics`] 里，入口是 [`Component::metrics`]——两者分工见该项的文档
+//! （`component_map::metrics` 模块）。
+//!
+//! **改这里的值 = 改全站观感**，必须同步 `DevDocs/SubAgentsTalk/design-令牌约定.md`；
+//! 页面线不许在页面里覆盖这些档位。
+
+mod metrics;
+mod table;
+
+pub use metrics::ComponentMetrics;
+
+use crate::elevation::Elevation;
+use crate::motion::{DurationToken, Easing};
+use crate::shape::{ComponentRadius, ShapeMorph, ShapeScale};
+use crate::typography::TypeRole;
+
+/// 组件的排版 + 形状 + 动效档位。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct ComponentSpec {
+    /// 该档位属于哪个组件（表自描述，便于测试与文档生成）。
+    pub component: Component,
+    /// 圆角档位（容器级，[`ShapeScale`] 的严格刻度）。
+    pub shape: ShapeScale,
+    /// 微控件圆角（D32 第二层）。
+    ///
+    /// `Some` 时**本字段才是半径真源**，此时 [`ComponentSpec::shape`] 必须是
+    /// [`ShapeScale::None`]（占位、不参与渲染）——因为 2dp 不在 `ShapeScale` 刻度里，
+    /// 硬塞进 `shape` 会破坏「圆角只取刻度值」。这层配对由测试钉死。
+    pub micro_radius: Option<ComponentRadius>,
+    /// 高程级别（决定 surface container 角色与是否画阴影）。
+    pub elevation: Elevation,
+    /// 主要文字角色。**无文字的组件（如 `Divider`）这里是占位值**，消费方不得据此排版。
+    pub text: TypeRole,
+    /// 辅助文字角色。
+    pub support: Option<TypeRole>,
+    /// 状态过渡缓动。
+    ///
+    /// 该字段不是 `Option`，所以**没有动效语义的组件（如 `Divider`）这里是占位值**——
+    /// 读之前先确认组件本身有状态过渡，无过渡的组件不得据此排动效。
+    pub motion: Easing,
+    /// 状态过渡时长。
+    pub duration: DurationToken,
+    /// 按下/选中时的形状形变。
+    pub morph: Option<ShapeMorph>,
+}
+
+/// 需要固定档位的组件清单（M53 页面骨架 + M69 组件线补的 5 个）。
+///
+/// **冻结为只可末尾追加**：判别值当索引用（`table::SPECS[self as usize]`），改名/换位等于
+/// 让整张表错行。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Component {
+    /// 顶部标题栏（第一层 chrome）。
+    TopAppBar,
+    /// 导航项（侧栏一行）。
+    NavigationItem,
+    /// 主操作按钮（实心强调色，每屏最多一个）。
+    PrimaryButton,
+    /// 次操作按钮（tonal）。
+    SecondaryButton,
+    /// 文本按钮（低权重）。
+    TextButton,
+    /// 图标按钮。
+    IconButton,
+    /// 描边卡片。
+    OutlinedCard,
+    /// 填充卡片（层级高于描边卡）。
+    FilledCard,
+    /// 列表行。
+    ListItem,
+    /// 文本输入框。
+    TextField,
+    /// 分段按钮（磁贴/列表切换、小中大三档）。
+    SegmentedButton,
+    /// 贴片/徽标。
+    Chip,
+    /// 开关。
+    Switch,
+    /// 滑块。
+    Slider,
+    /// 进度条。
+    ProgressIndicator,
+    /// 对话框。
+    Dialog,
+    /// 下拉菜单。
+    Menu,
+    /// 底部提示条。
+    Snackbar,
+    /// 悬浮提示。
+    Tooltip,
+    /// 空态（图标 + 标题 + 说明 + 标准按钮）。
+    EmptyState,
+    /// 复选框（安装选项 / mod 启用 / 日志过滤 / Java 管理勾选）。
+    ///
+    /// 圆角 **2dp** 不在 `ShapeScale` 刻度里 → 走 [`ComponentSpec::micro_radius`]（D32 第二层）；
+    /// 20×20 / 描边 2 / 状态层 Ø40 见 [`ComponentMetrics::CHECKBOX`]。
+    Checkbox,
+    /// 单选框（Java 版本单选 / 安装模式选择）。
+    ///
+    /// 真圆（`ShapeScale::Full`）；20 / 环线 2 / 内点 10 / 状态层 Ø40 见 [`ComponentMetrics::RADIO`]。
+    Radio,
+    /// 搜索条（实例 / 版本 / mod 搜索，页级入口）。
+    ///
+    /// 高 56 是骨架级（`LayoutMetrics::search_bar_height`），圆角 `Full`（56 → 28）；
+    /// 图标 24 + 偏移 4 见 [`ComponentMetrics::SEARCH_BAR`]。高程取 **L0**（源码矛盾已登记）。
+    Search,
+    /// 导航抽屉（左侧常驻导航的展开形态，D33）。
+    ///
+    /// 形状 `CornerLargeEnd`（只有靠内容那侧两角 16），宽 240 = `LayoutMetrics::nav_drawer_width`；
+    /// 项内几何见 [`ComponentMetrics::NAVIGATION_DRAWER`]。
+    NavigationDrawer,
+    /// 分隔线（列表行分隔 / 区块分隔）。
+    ///
+    /// **无高程、无圆角**；厚度是一像素线（`LayoutMetrics::divider_thickness` = `stroke::HAIRLINE`），
+    /// 颜色 `OutlineVariant`（列表内）或 `Outline`（search view 头部分隔，见 §20.8）。
+    Divider,
+}
+
+impl Component {
+    /// 全部组件。
+    pub const ALL: [Component; 25] = [
+        Component::TopAppBar,
+        Component::NavigationItem,
+        Component::PrimaryButton,
+        Component::SecondaryButton,
+        Component::TextButton,
+        Component::IconButton,
+        Component::OutlinedCard,
+        Component::FilledCard,
+        Component::ListItem,
+        Component::TextField,
+        Component::SegmentedButton,
+        Component::Chip,
+        Component::Switch,
+        Component::Slider,
+        Component::ProgressIndicator,
+        Component::Dialog,
+        Component::Menu,
+        Component::Snackbar,
+        Component::Tooltip,
+        Component::EmptyState,
+        // M69 G9：末尾追加的 5 个（前 20 个次序不许动）。
+        Component::Checkbox,
+        Component::Radio,
+        Component::Search,
+        Component::NavigationDrawer,
+        Component::Divider,
+    ];
+
+    /// 该组件的档位。
+    pub fn spec(self) -> ComponentSpec {
+        table::SPECS[self as usize]
+    }
+
+    /// 该组件的**控件内部**微度量；`None` = 只有骨架值（去 `LayoutMetrics` 拿）。
+    ///
+    /// 这一条是 G10 的消费入口：组件线拿到 `Component::Checkbox.metrics()` 就有 20×20 / 圆角 2 /
+    /// 描边 2 / 状态层 Ø40，**不许再在实现里写这些字面量**。
+    pub fn metrics(self) -> Option<ComponentMetrics> {
+        metrics::metrics_of(self)
+    }
+
+    /// 稳定字符串名（kebab-case）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Component::TopAppBar => "top-app-bar",
+            Component::NavigationItem => "navigation-item",
+            Component::PrimaryButton => "primary-button",
+            Component::SecondaryButton => "secondary-button",
+            Component::TextButton => "text-button",
+            Component::IconButton => "icon-button",
+            Component::OutlinedCard => "outlined-card",
+            Component::FilledCard => "filled-card",
+            Component::ListItem => "list-item",
+            Component::TextField => "text-field",
+            Component::SegmentedButton => "segmented-button",
+            Component::Chip => "chip",
+            Component::Switch => "switch",
+            Component::Slider => "slider",
+            Component::ProgressIndicator => "progress-indicator",
+            Component::Dialog => "dialog",
+            Component::Menu => "menu",
+            Component::Snackbar => "snackbar",
+            Component::Tooltip => "tooltip",
+            Component::EmptyState => "empty-state",
+            // M69 G9：末尾追加（`name()` 是持久化字符串 id，同样只许末尾追加）。
+            Component::Checkbox => "checkbox",
+            Component::Radio => "radio",
+            Component::Search => "search",
+            Component::NavigationDrawer => "navigation-drawer",
+            Component::Divider => "divider",
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests;

crates/design/src/component_map/table.rs

@@ -0,0 +1,371 @@
+//! 组件档位数据表（**下标必须等于 `Component as usize`**，由测试钉死）。
+//!
+//! 一行一个组件。改值就是在改全站观感——同步协作文档再改。
+//!
+//! **末尾 5 行（M69 G9）** 的来源是 `research/15` §18~§23（同一套 `material3-android:1.4.0` 源码）：
+//! Checkbox / Radio / Search / NavigationDrawer / Divider。其中 Checkbox 的 **2dp** 圆角走
+//! [`ComponentRadius`]（D32 第二层，不塞进 `ShapeScale`），Divider 的厚度是一像素线（G12）而不在这张表里。
+//!
+//! **高程/形状取值来源（A 级）**：`androidx.compose.material3.tokens` 的各组件 `<X>Tokens.kt`
+//! （FilledCard/OutlinedCard/ElevatedCard/Menu/Dialog/Snackbar/AppBar/List）。已登记的两处偏离：
+//! - `Tooltip`：`PlainTooltipTokens.kt` 只有 Corner 行、**没有 Elevation 行**，Table 的 Level2 是
+//!   B 级（沿用 M3 旧规范「浮层 3dp」的直觉），有官方值后以官方为准；
+//! - `ListItem`：官方 `ListTokens` 用 `CornerNone`（直角行），本项目取 `Small(8)`——列表行在本
+//!   启动器里是**卡片内的独立可点块**（不是贴边通栏行），圆角与卡片同族更协调；偏差 8dp 已登记。
+
+use super::{Component, ComponentSpec};
+use crate::elevation::Elevation;
+use crate::motion::{
+    DurationToken, Easing, SPRING_EXPRESSIVE_SPATIAL_DEFAULT, SPRING_EXPRESSIVE_SPATIAL_FAST,
+};
+use crate::shape::{ComponentRadius, ShapeMorph, ShapeScale};
+use crate::typography::TypeRole;
+
+/// 一个组件的档位行（`const fn` 便捷构造，字段名在 [`ComponentSpec`] 里）。
+const fn spec(
+    component: Component,
+    shape: ShapeScale,
+    elevation: Elevation,
+    text: TypeRole,
+    support: Option<TypeRole>,
+    motion: Easing,
+    duration: DurationToken,
+    morph: Option<ShapeMorph>,
+) -> ComponentSpec {
+    ComponentSpec {
+        component,
+        shape,
+        micro_radius: None,
+        elevation,
+        text,
+        support,
+        motion,
+        duration,
+        morph,
+    }
+}
+
+/// 圆角走「微控件层」（D32）的档位行：`shape` 自动填占位 `None`，半径取白名单值。
+///
+/// 为什么单独一个构造器：`micro_radius` 与 `shape = None` 必须成对出现，用构造器保证配对，
+/// 不让 25 行表里出现「填了微半径忘了把 shape 清掉」。
+const fn spec_micro(
+    component: Component,
+    micro_radius: ComponentRadius,
+    elevation: Elevation,
+    text: TypeRole,
+    support: Option<TypeRole>,
+    motion: Easing,
+    duration: DurationToken,
+    morph: Option<ShapeMorph>,
+) -> ComponentSpec {
+    ComponentSpec {
+        component,
+        shape: ShapeScale::None,
+        micro_radius: Some(micro_radius),
+        elevation,
+        text,
+        support,
+        motion,
+        duration,
+        morph,
+    }
+}
+
+/// 25 个组件的档位表。
+pub(super) const SPECS: [ComponentSpec; 25] = [
+    spec(
+        Component::TopAppBar,
+        ShapeScale::None,
+        Elevation::Level0,
+        TypeRole::TitleLarge,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Medium2,
+        None,
+    ),
+    spec(
+        Component::NavigationItem,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelLarge,
+        None,
+        Easing::Emphasized,
+        DurationToken::Medium2,
+        Some(ShapeMorph::new(
+            ShapeScale::Large,
+            ShapeScale::Full,
+            SPRING_EXPRESSIVE_SPATIAL_FAST,
+        )),
+    ),
+    spec(
+        Component::PrimaryButton,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelLarge,
+        None,
+        Easing::Emphasized,
+        DurationToken::Short4,
+        None,
+    ),
+    spec(
+        Component::SecondaryButton,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelLarge,
+        None,
+        Easing::Standard,
+        DurationToken::Short4,
+        None,
+    ),
+    spec(
+        Component::TextButton,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelLarge,
+        None,
+        Easing::Standard,
+        DurationToken::Short4,
+        None,
+    ),
+    spec(
+        Component::IconButton,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelMedium,
+        None,
+        Easing::Standard,
+        DurationToken::Short3,
+        Some(ShapeMorph::new(
+            ShapeScale::Medium,
+            ShapeScale::Full,
+            SPRING_EXPRESSIVE_SPATIAL_FAST,
+        )),
+    ),
+    // FilledCardTokens.ContainerElevation = Level0（hover 才到 L1、dragged 到 L3）。
+    spec(
+        Component::OutlinedCard,
+        ShapeScale::Medium,
+        Elevation::Level0,
+        TypeRole::TitleMedium,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Medium1,
+        None,
+    ),
+    spec(
+        Component::FilledCard,
+        ShapeScale::Medium,
+        Elevation::Level0,
+        TypeRole::TitleMedium,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Medium1,
+        Some(ShapeMorph::new(
+            ShapeScale::Medium,
+            ShapeScale::Large,
+            SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+        )),
+    ),
+    spec(
+        Component::ListItem,
+        ShapeScale::Small,
+        Elevation::Level0,
+        TypeRole::BodyLarge,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Short4,
+        None,
+    ),
+    spec(
+        Component::TextField,
+        ShapeScale::ExtraSmall,
+        Elevation::Level0,
+        TypeRole::BodyLarge,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Short4,
+        None,
+    ),
+    spec(
+        Component::SegmentedButton,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelLarge,
+        None,
+        Easing::Emphasized,
+        DurationToken::Medium2,
+        None,
+    ),
+    spec(
+        Component::Chip,
+        ShapeScale::Small,
+        Elevation::Level0,
+        TypeRole::LabelMedium,
+        None,
+        Easing::Standard,
+        DurationToken::Short3,
+        Some(ShapeMorph::new(
+            ShapeScale::ExtraSmall,
+            ShapeScale::Small,
+            SPRING_EXPRESSIVE_SPATIAL_FAST,
+        )),
+    ),
+    spec(
+        Component::Switch,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::BodyMedium,
+        Some(TypeRole::BodySmall),
+        Easing::Emphasized,
+        DurationToken::Medium2,
+        None,
+    ),
+    spec(
+        Component::Slider,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::BodyMedium,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Short2,
+        None,
+    ),
+    spec(
+        Component::ProgressIndicator,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::LabelMedium,
+        None,
+        Easing::Linear,
+        DurationToken::Long2,
+        None,
+    ),
+    // DialogTokens.ContainerElevation = Level3，CornerExtraLarge = 28。
+    spec(
+        Component::Dialog,
+        ShapeScale::ExtraLarge,
+        Elevation::Level3,
+        TypeRole::HeadlineSmall,
+        Some(TypeRole::BodyMedium),
+        Easing::EmphasizedDecelerate,
+        DurationToken::Long4,
+        Some(ShapeMorph::new(
+            ShapeScale::Large,
+            ShapeScale::ExtraLarge,
+            SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+        )),
+    ),
+    // MenuTokens：CornerExtraSmall(4) + Level2。
+    spec(
+        Component::Menu,
+        ShapeScale::ExtraSmall,
+        Elevation::Level2,
+        TypeRole::BodyMedium,
+        None,
+        Easing::StandardDecelerate,
+        DurationToken::Short4,
+        None,
+    ),
+    spec(
+        Component::Snackbar,
+        ShapeScale::ExtraSmall,
+        Elevation::Level3,
+        TypeRole::BodyMedium,
+        None,
+        Easing::EmphasizedDecelerate,
+        DurationToken::Medium2,
+        None,
+    ),
+    spec(
+        Component::Tooltip,
+        ShapeScale::ExtraSmall,
+        Elevation::Level2,
+        TypeRole::BodySmall,
+        None,
+        Easing::StandardDecelerate,
+        DurationToken::Short2,
+        None,
+    ),
+    spec(
+        Component::EmptyState,
+        ShapeScale::Large,
+        Elevation::Level0,
+        TypeRole::HeadlineSmall,
+        Some(TypeRole::BodySmall),
+        Easing::Standard,
+        DurationToken::Medium2,
+        None,
+    ),
+    // ---- M69 G9：末尾追加的 5 个（`research/15` §18~§23；前 20 行次序不许动）----
+    // Checkbox：圆角 **2dp** 不在 `ShapeScale` 刻度里 → 走 `spec_micro`（D32 第二层）。
+    // 高程 L0：`CheckboxTokens` 没有 Elevation 行，容器是「描边/填充」两态而非浮层。
+    // 字级 `BodyLarge` 是**团队口径**：官方没有「框 + 标签」组合 token（§18.9），取列表行同一档。
+    // 动效取 M3 motion scheme 的 fast-effects（100ms standard）——[推导]，非 token 原文。
+    spec_micro(
+        Component::Checkbox,
+        ComponentRadius::Micro,
+        Elevation::Level0,
+        TypeRole::BodyLarge,
+        None,
+        Easing::Standard,
+        DurationToken::Short2,
+        None,
+    ),
+    // Radio：真圆（`RadioButtonTokens.IconSize = 20` + `CornerFull`），内点/环线宽见
+    // `ComponentMetrics::RADIO`。字级同 Checkbox（团队口径）。
+    spec(
+        Component::Radio,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::BodyLarge,
+        None,
+        Easing::Standard,
+        DurationToken::Short2,
+        None,
+    ),
+    // Search bar：圆角 `CornerFull` / `SearchBarCornerRadius = 56/2 = 28`。
+    // **高程取 L0**——`SearchBarTokens.ContainerElevation = Level3` 与
+    // `SearchBarDefaults.TonalElevation/ShadowElevation = Level0` 冲突（§26.2 矛盾 ②），
+    // 判据按观感取「无可见阴影 + tone 分层」，这条已在 `design-令牌约定` 登记。
+    // 无 shape morph：bar ⇄ docked 展开时**半径不变**（28 → 28），只长面积（§20C）。
+    spec(
+        Component::Search,
+        ShapeScale::Full,
+        Elevation::Level0,
+        TypeRole::BodyLarge,
+        Some(TypeRole::BodySmall),
+        Easing::Emphasized,
+        DurationToken::Medium2,
+        None,
+    ),
+    // Navigation drawer：官方 `ContainerShape = CornerLargeEnd`（只有靠内容那侧两角 16，
+    // 贴边侧直角）。`ShapeScale` 表达不了「部分角」，这里记内侧角的 `Large(16)`，
+    // 哪两个角由组件按侧位决定；写四角 16 = 变成浮动卡片（§21.2 判据）。
+    // 常驻形态 `Surface` + L0（模态才用 `SurfaceContainerLow` + scrim，本项目只在 <600 窗宽兜底）。
+    spec(
+        Component::NavigationDrawer,
+        ShapeScale::Large,
+        Elevation::Level0,
+        TypeRole::LabelLarge,
+        Some(TypeRole::TitleSmall),
+        Easing::Emphasized,
+        DurationToken::Medium2,
+        None,
+    ),
+    // Divider：无高程、无圆角、**无文字**（`text` 是占位值，消费方不得据此排版）；
+    // 厚度是一像素线 `LayoutMetrics::divider_thickness`，颜色 `OutlineVariant`
+    // （search view 头部分隔是 `Outline`，两个不同角色，§20.8）。
+    // **`motion` / `duration` 也是占位值**（`ComponentSpec.motion` 不是 `Option`）：Divider 没有
+    // 官方状态过渡令牌，消费方**不得据此排动效**；下轮把该字段改成 `Option` 更彻底。
+    spec(
+        Component::Divider,
+        ShapeScale::None,
+        Elevation::Level0,
+        TypeRole::BodySmall,
+        None,
+        Easing::Standard,
+        DurationToken::Short2,
+        None,
+    ),
+];

crates/design/src/component_map/tests.rs

@@ -0,0 +1,202 @@
+//! `component_map` 的守门测试：表槽位 ↔ 枚举次序、官方高程/形状、圆角分层（D32）、微度量入口。
+//!
+//! 拆成独立文件是为了让 `mod.rs` 留出文档空间（项目硬约束：单文件 ≤400 行）。
+
+use super::*;
+
+#[test]
+fn table_matches_component_order() {
+    for (i, spec) in table::SPECS.iter().enumerate() {
+        assert_eq!(
+            spec.component as usize, i,
+            "SPECS 第 {i} 行顺序与枚举不一致"
+        );
+    }
+}
+
+#[test]
+fn every_component_resolves() {
+    assert_eq!(Component::ALL.len(), table::SPECS.len());
+    for component in Component::ALL {
+        let spec = component.spec();
+        assert_eq!(spec.component, component);
+        assert!(spec.text.style().size_px >= 11.0);
+    }
+}
+
+#[test]
+fn names_are_unique() {
+    let mut seen = std::collections::BTreeSet::new();
+    for component in Component::ALL {
+        assert!(
+            seen.insert(component.name()),
+            "组件名重复：{}",
+            component.name()
+        );
+    }
+}
+
+#[test]
+fn elevation_matches_official_component_tokens() {
+    // A 级来源（androidx.compose.material3.tokens）：
+    //   FilledCardTokens/OutlinedCardTokens.ContainerElevation = Level0
+    //   MenuTokens.ContainerElevation = Level2
+    //   DialogTokens.ContainerElevation = Level3
+    //   SnackbarTokens.ContainerElevation = Level3
+    //   AppBarTokens = Level0、ListTokens.ItemContainerElevation = Level0
+    // 偏离只允许出现在有登记的地方（Tooltip 是 B 级：token 文件里没有 Elevation 行）。
+    for (component, expect) in [
+        (Component::FilledCard, Elevation::Level0),
+        (Component::OutlinedCard, Elevation::Level0),
+        (Component::Menu, Elevation::Level2),
+        (Component::Dialog, Elevation::Level3),
+        (Component::Snackbar, Elevation::Level3),
+        (Component::TopAppBar, Elevation::Level0),
+        (Component::ListItem, Elevation::Level0),
+        (Component::TextField, Elevation::Level0),
+    ] {
+        assert_eq!(
+            component.spec().elevation,
+            expect,
+            "{} 的高程与官方组件令牌不一致",
+            component.name()
+        );
+    }
+    // R4「全屏都在飘」的守门：一屏常见元素里带阴影（>Level0）的只允许是浮层。
+    for component in Component::ALL {
+        if component.spec().elevation > Elevation::Level0 {
+            assert!(
+                matches!(
+                    component,
+                    Component::Menu | Component::Dialog | Component::Snackbar | Component::Tooltip
+                ),
+                "{} 不该有阴影（只有浮层允许）",
+                component.name()
+            );
+        }
+    }
+}
+
+#[test]
+fn shapes_match_official_component_tokens() {
+    // 官方：卡片 CornerMedium(12)、对话框 CornerExtraLarge(28)、菜单 CornerExtraSmall(4)、
+    // 按钮/导航指示条 CornerFull、chip CornerSmall(8)。
+    assert_eq!(Component::FilledCard.spec().shape, ShapeScale::Medium);
+    assert_eq!(Component::OutlinedCard.spec().shape, ShapeScale::Medium);
+    assert_eq!(Component::Dialog.spec().shape, ShapeScale::ExtraLarge);
+    assert_eq!(Component::Menu.spec().shape, ShapeScale::ExtraSmall);
+    assert_eq!(Component::PrimaryButton.spec().shape, ShapeScale::Full);
+    assert_eq!(Component::Chip.spec().shape, ShapeScale::Small);
+}
+
+#[test]
+fn only_primary_actions_use_filled_emphasis_and_one_dialog_layer() {
+    // 契约 §1：状态色不复用 accent、每屏最多一个实心 accent → 只有 primary-button 是
+    // 「实心强调」，其余按钮的形态由页面决定但不能是 Full + Level0 + Emphasized 的组合。
+    let primary = Component::PrimaryButton.spec();
+    assert_eq!(primary.shape, ShapeScale::Full);
+    assert_eq!(primary.text, TypeRole::LabelLarge);
+    // 浮层类必须比卡片层高。
+    assert!(Component::Dialog.spec().elevation > Component::OutlinedCard.spec().elevation);
+    assert!(Component::Menu.spec().elevation > Component::FilledCard.spec().elevation);
+}
+
+#[test]
+fn morphs_always_expand_upwards() {
+    for component in Component::ALL {
+        if let Some(morph) = component.spec().morph {
+            assert_ne!(
+                morph.from,
+                morph.to,
+                "{} 的形变起止不能相同",
+                component.name()
+            );
+            // 方向必须「沿阶梯胀开」（morph 对 `Full` 也没问题，rank 把它排在末尾），
+            // 不比较像素跨度：`Full` 的半径依赖边长，用固定边长比会被 `None` 之外的大档拉爆。
+            assert!(
+                morph.from.rank() < morph.to.rank(),
+                "{} 的形变方向反了：{:?} → {:?}",
+                component.name(),
+                morph.from,
+                morph.to
+            );
+        }
+    }
+}
+
+#[test]
+fn appended_variants_keep_the_frozen_order() {
+    // 枚举冻结为「只可末尾追加」：前 20 个的次序不能动（M69 只在末尾加 5 个）。
+    assert_eq!(Component::ALL.len(), 25);
+    assert_eq!(Component::ALL[0], Component::TopAppBar);
+    assert_eq!(Component::ALL[19], Component::EmptyState);
+    assert_eq!(Component::ALL[20], Component::Checkbox);
+    assert_eq!(Component::ALL[24], Component::Divider);
+    for (i, component) in Component::ALL.iter().enumerate() {
+        assert_eq!(*component as usize, i, "ALL 的次序与枚举判别值不一致");
+    }
+}
+
+#[test]
+fn micro_radius_only_on_micro_controls() {
+    // D32：微半径只能给 ≤24dp 的微控件，且此时 `shape` 必须是占位 None（不参与渲染）。
+    let mut owners = Vec::new();
+    for component in Component::ALL {
+        let spec = component.spec();
+        let Some(radius) = spec.micro_radius else {
+            continue;
+        };
+        owners.push(component);
+        assert_eq!(radius, ComponentRadius::Micro, "白名单外的微半径不许过表");
+        assert_eq!(
+            spec.shape,
+            ShapeScale::None,
+            "{} 有微半径时 shape 必须占位 None（2dp 不在刻度里）",
+            component.name()
+        );
+        let metrics = component
+            .metrics()
+            .expect("带微半径的组件必须有 ComponentMetrics");
+        assert!(
+            metrics.width <= crate::shape::MICRO_CONTROL_MAX_SIZE
+                && metrics.height <= crate::shape::MICRO_CONTROL_MAX_SIZE,
+            "{} 超出微控件尺寸上限",
+            component.name()
+        );
+        assert_eq!(
+            radius.radius_px(metrics.width),
+            Some(radius.dp()),
+            "{} 的微半径按自身尺寸取不到",
+            component.name()
+        );
+    }
+    assert_eq!(
+        owners,
+        vec![Component::Checkbox],
+        "当前只允许 Checkbox 用微半径"
+    );
+}
+
+#[test]
+fn metrics_resolve_only_for_controls_with_inner_geometry() {
+    for component in [
+        Component::Checkbox,
+        Component::Radio,
+        Component::Search,
+        Component::NavigationDrawer,
+    ] {
+        assert!(
+            component.metrics().is_some(),
+            "{} 缺 ComponentMetrics",
+            component.name()
+        );
+    }
+    // Divider 只有厚度，而厚度是一像素线（LM），不该出现在 CM 里。
+    assert!(Component::Divider.metrics().is_none());
+    // 骨架级尺寸不许在 CM 里重复一份（Single Source of Truth）。
+    for component in [Component::Search, Component::NavigationDrawer] {
+        let metrics = component.metrics().unwrap();
+        assert_eq!(metrics.width, 0.0, "{} 的宽度属骨架级", component.name());
+        assert_eq!(metrics.height, 0.0, "{} 的高度属骨架级", component.name());
+    }
+}

crates/design/src/elevation.rs

@@ -0,0 +1,226 @@
+//! 高程令牌：elevation level、阴影参数、surface container 映射。
+//!
+//! M3 在 2024 之后改了「怎么表达高程」：**不再**往表面上叠半透明的 surface tint，
+//! 而是用 `surface-container-*` 这一族中性容器色表达层级（GPU 路径再叠阴影做空间感）。
+//! 本模块两种口径都给出，旧口径显式标为 deprecated，避免页面线混用。
+
+use crate::color::Role;
+
+/// M3 高程级别 0..5（对应 0 / 1 / 3 / 6 / 8 / 12 dp）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub enum Elevation {
+    /// 0dp：贴底内容（窗口底、内联区）。
+    Level0,
+    /// 1dp：卡片、可抬起的列表项。
+    Level1,
+    /// 3dp：可交互卡片、导航栏。
+    Level2,
+    /// 6dp：FAB、侧栏、浮动工具条。
+    Level3,
+    /// 8dp：菜单、popover。
+    Level4,
+    /// 12dp：对话框、模态。
+    Level5,
+}
+
+impl Elevation {
+    /// 全部级别。
+    pub const ALL: [Elevation; 6] = [
+        Elevation::Level0,
+        Elevation::Level1,
+        Elevation::Level2,
+        Elevation::Level3,
+        Elevation::Level4,
+        Elevation::Level5,
+    ];
+
+    /// 标称高度（dp）。
+    pub const fn dp(self) -> f32 {
+        match self {
+            Elevation::Level0 => 0.0,
+            Elevation::Level1 => 1.0,
+            Elevation::Level2 => 3.0,
+            Elevation::Level3 => 6.0,
+            Elevation::Level4 => 8.0,
+            Elevation::Level5 => 12.0,
+        }
+    }
+
+    /// 该级别应使用的表面容器色角色（M3 现行口径）。
+    ///
+    /// 层级靠**换底色**表达，不靠 tint；浅深模式都成立。
+    pub const fn surface_role(self) -> Role {
+        match self {
+            Elevation::Level0 => Role::SurfaceContainerLowest,
+            Elevation::Level1 => Role::SurfaceContainerLow,
+            Elevation::Level2 => Role::SurfaceContainer,
+            Elevation::Level3 => Role::SurfaceContainerHigh,
+            Elevation::Level4 | Elevation::Level5 => Role::SurfaceContainerHighest,
+        }
+    }
+
+    /// 阴影参数（**占位值，待 M63 视觉规格** — 见下面的 TODO）。
+    ///
+    /// TODO(M63): 取值待视觉规格。官方只给 dp 与设计稿示意，没有可移植的 blur/alpha 公式；
+    /// 这里的 blur/offset/alpha 是临时占位（按「blur ≈ dp × 1.3 + 1.5」凑的数），
+    /// M63 的玻璃规格表落地后以那张表为准，别在页面里引用这些绝对值。
+    pub const fn shadow(self) -> ShadowSpec {
+        match self {
+            Elevation::Level0 => ShadowSpec {
+                blur_px: 0.0,
+                offset_y_px: 0.0,
+                alpha: 0.0,
+            },
+            Elevation::Level1 => ShadowSpec {
+                blur_px: 3.0,
+                offset_y_px: 1.0,
+                alpha: 0.12,
+            },
+            Elevation::Level2 => ShadowSpec {
+                blur_px: 6.0,
+                offset_y_px: 2.0,
+                alpha: 0.14,
+            },
+            Elevation::Level3 => ShadowSpec {
+                blur_px: 9.0,
+                offset_y_px: 4.0,
+                alpha: 0.16,
+            },
+            Elevation::Level4 => ShadowSpec {
+                blur_px: 12.0,
+                offset_y_px: 6.0,
+                alpha: 0.18,
+            },
+            Elevation::Level5 => ShadowSpec {
+                blur_px: 17.0,
+                offset_y_px: 8.0,
+                alpha: 0.20,
+            },
+        }
+    }
+
+    /// 旧口径（M3 2022）：把 `surface-tint` 按这个 alpha 叠在 `surface` 上表达高程。
+    ///
+    /// **deprecated**——现行 M3 用 [`Elevation::surface_role`]；保留只为读旧稿时能对上数，
+    /// 新代码不要用。
+    pub const fn deprecated_tint_alpha(self) -> f32 {
+        match self {
+            Elevation::Level0 => 0.0,
+            Elevation::Level1 => 0.05,
+            Elevation::Level2 => 0.08,
+            Elevation::Level3 => 0.11,
+            Elevation::Level4 => 0.12,
+            Elevation::Level5 => 0.14,
+        }
+    }
+}
+
+/// 一层阴影的绘制参数。
+///
+/// TODO(M63): 取值待视觉规格（这份结构只是「接口预留」，数值由 M63 的玻璃规格表填充）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct ShadowSpec {
+    /// 高斯模糊半径（px）。
+    pub blur_px: f32,
+    /// 向下偏移（px）。
+    pub offset_y_px: f32,
+    /// 阴影色 alpha（叠在 [`crate::color::Scheme::shadow`] 之上）。
+    pub alpha: f32,
+}
+
+impl ShadowSpec {
+    /// 是否可见（0 表示这一级不画阴影）。
+    pub fn is_visible(&self) -> bool {
+        self.alpha > 0.0 && self.blur_px > 0.0
+    }
+}
+
+/// 三个「材质层」的语义（沿用 `ui-integration-contract.md` §2 的三层，映射到 M3 令牌）。
+///
+/// 页面线按层取色，不许自己决定「这一层比那一层深一点」。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MaterialLayer {
+    /// 底层（canvas）：窗口底，永远不透明。
+    Canvas,
+    /// 卡片层：页面内容/设置分组/AI 面板。
+    Card,
+    /// 浮层：对话框、菜单、Toast。
+    Overlay,
+}
+
+impl MaterialLayer {
+    /// 该层的底色角色。
+    pub const fn surface_role(self) -> Role {
+        match self {
+            MaterialLayer::Canvas => Role::Surface,
+            MaterialLayer::Card => Role::SurfaceContainerLow,
+            MaterialLayer::Overlay => Role::SurfaceContainerHigh,
+        }
+    }
+
+    /// 该层的高程级别。
+    pub const fn elevation(self) -> Elevation {
+        match self {
+            MaterialLayer::Canvas => Elevation::Level0,
+            MaterialLayer::Card => Elevation::Level1,
+            MaterialLayer::Overlay => Elevation::Level3,
+        }
+    }
+
+    /// 该层是否允许半透明（D27：**只有 GPU 路径**才允许；CPU 路径一律纯色）。
+    pub const fn allows_translucency(self) -> bool {
+        matches!(self, MaterialLayer::Card | MaterialLayer::Overlay)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn elevation_dp_ladder() {
+        let ladder: Vec<f32> = Elevation::ALL.iter().map(|e| e.dp()).collect();
+        assert_eq!(ladder, vec![0.0, 1.0, 3.0, 6.0, 8.0, 12.0]);
+    }
+
+    #[test]
+    fn shadow_grows_with_elevation() {
+        let mut prev = Elevation::Level0.shadow();
+        for level in &Elevation::ALL[1..] {
+            let cur = level.shadow();
+            assert!(cur.blur_px > prev.blur_px, "{level:?} 的模糊应更大");
+            assert!(cur.offset_y_px >= prev.offset_y_px);
+            assert!(cur.alpha >= prev.alpha);
+            assert!(cur.is_visible());
+            prev = cur;
+        }
+        assert!(!Elevation::Level0.shadow().is_visible());
+    }
+
+    #[test]
+    fn higher_levels_use_higher_surface_containers() {
+        assert_eq!(
+            Elevation::Level5.surface_role(),
+            Role::SurfaceContainerHighest
+        );
+        assert_eq!(
+            Elevation::Level0.surface_role(),
+            Role::SurfaceContainerLowest
+        );
+    }
+
+    #[test]
+    fn material_layers_are_ordered() {
+        assert_eq!(MaterialLayer::Canvas.surface_role(), Role::Surface);
+        assert_eq!(
+            MaterialLayer::Card.surface_role(),
+            Role::SurfaceContainerLow
+        );
+        assert_eq!(
+            MaterialLayer::Overlay.surface_role(),
+            Role::SurfaceContainerHigh
+        );
+        assert!(!MaterialLayer::Canvas.allows_translucency());
+        assert!(MaterialLayer::Overlay.allows_translucency());
+    }
+}

crates/design/src/icons/glyphs.rs

@@ -0,0 +1,184 @@
+//! 图标几何数据：24 网格、1.5px 视觉描边的 SVG path 字符串。
+//!
+//! 源流：`DevDocs/ops/slint-reference/crates/app/ui/components/icons.slint`（M54 重画过一轮的
+//! Fluent 2 线性几何）。命令集沿用 `M/L/H/V/A/C/Q/Z`，与 SVG 路径语法一致，可直接交给
+//! 任何 SVG path 解析器（iced 侧是 `iced::widget::canvas` 的 `Path`/`lyon`）。
+//!
+//! 这里只有数据：不许在数据里写颜色、尺寸、dpi——那些由渲染层决定。
+
+use super::{Icon, IconKind, IconPaint};
+
+/// 全部图标几何，**下标必须等于 `IconKind as usize`**（由测试钉死）。
+pub(super) const GLYPHS: [Icon; 28] = [
+    // 实例：2×2 圆角方块（原 Slint 版是 4 个 Rectangle 描边，这里折成一条 path）
+    Icon::data(
+        IconKind::Instances,
+        "M 5 3 H 8 A 2 2 0 0 1 10 5 V 8 A 2 2 0 0 1 8 10 H 5 A 2 2 0 0 1 3 8 V 5 A 2 2 0 0 1 5 3 Z \
+         M 16 3 H 19 A 2 2 0 0 1 21 5 V 8 A 2 2 0 0 1 19 10 H 16 A 2 2 0 0 1 14 8 V 5 A 2 2 0 0 1 16 3 Z \
+         M 5 14 H 8 A 2 2 0 0 1 10 16 V 19 A 2 2 0 0 1 8 21 H 5 A 2 2 0 0 1 3 19 V 16 A 2 2 0 0 1 5 14 Z \
+         M 16 14 H 19 A 2 2 0 0 1 21 16 V 19 A 2 2 0 0 1 19 21 H 16 A 2 2 0 0 1 14 19 V 16 A 2 2 0 0 1 16 14 Z",
+        IconPaint::Stroke,
+    ),
+    // 下载：箭头入托盘
+    Icon::data(
+        IconKind::Download,
+        "M 12 3.5 V 15 M 7 10.5 L 12 15.5 L 17 10.5 M 4.5 20.5 H 19.5",
+        IconPaint::Stroke,
+    ),
+    // 日志：卷角文档 + 两行正文（不是三横——三横读作「菜单」）
+    Icon::data(
+        IconKind::Logs,
+        "M 6 3.5 H 14 L 18.5 8 V 20.5 H 6 Z M 14 3.5 V 8 H 18.5 M 9 12.5 H 15.5 M 9 16.5 H 15.5",
+        IconPaint::Stroke,
+    ),
+    // 设置：八齿齿轮 + 中心孔
+    Icon::data(
+        IconKind::Settings,
+        "M 18.89 14.11 L 21.51 13.34 L 21.51 10.66 L 18.89 9.89 A 7.2 7.2 0 0 1 18.36 8.62 \
+         L 19.67 6.22 L 17.78 4.33 L 15.38 5.64 A 7.2 7.2 0 0 1 14.11 5.11 L 13.34 2.49 L 10.66 2.49 \
+         L 9.89 5.11 A 7.2 7.2 0 0 1 8.62 5.64 L 6.22 4.33 L 4.33 6.22 L 5.64 8.62 A 7.2 7.2 0 0 1 5.11 9.89 \
+         L 2.49 10.66 L 2.49 13.34 L 5.11 14.11 A 7.2 7.2 0 0 1 5.64 15.38 L 4.33 17.78 L 6.22 19.67 \
+         L 8.62 18.36 A 7.2 7.2 0 0 1 9.89 18.89 L 10.66 21.51 L 13.34 21.51 L 14.11 18.89 A 7.2 7.2 0 0 1 15.38 18.36 \
+         L 17.78 19.67 L 19.67 17.78 L 18.36 15.38 A 7.2 7.2 0 0 1 18.89 14.11 Z \
+         M 8.8 12 A 3.2 3.2 0 1 0 15.2 12 A 3.2 3.2 0 1 0 8.8 12 Z",
+        IconPaint::Stroke,
+    ),
+    // AI：四角星（凹边四角星，不是直线菱形）
+    Icon::data(
+        IconKind::Ai,
+        "M 12 3 Q 13.6 10.4 21 12 Q 13.6 13.6 12 21 Q 10.4 13.6 3 12 Q 10.4 10.4 12 3 Z",
+        IconPaint::Stroke,
+    ),
+    // 播放 / 停止：实心（与文字并排时不至于太轻）
+    Icon::data(
+        IconKind::Play,
+        "M 7.5 4.5 L 19 12 L 7.5 19.5 Z",
+        IconPaint::Fill,
+    ),
+    Icon::data(
+        IconKind::Stop,
+        "M 8 7 H 16 A 1 1 0 0 1 17 8 V 16 A 1 1 0 0 1 16 17 H 8 A 1 1 0 0 1 7 16 V 8 A 1 1 0 0 1 8 7 Z",
+        IconPaint::Fill,
+    ),
+    // 搜索：放大镜
+    Icon::data(
+        IconKind::Search,
+        "M 10.5 4 A 6.5 6.5 0 1 0 10.5 17 A 6.5 6.5 0 1 0 10.5 4 Z M 15.4 15.4 L 20.5 20.5",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::Plus,
+        "M 12 5 V 19 M 5 12 H 19",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::Close,
+        "M 6.5 6.5 L 17.5 17.5 M 17.5 6.5 L 6.5 17.5",
+        IconPaint::Stroke,
+    ),
+    Icon::data(IconKind::Minimize, "M 6 12 H 18", IconPaint::Stroke),
+    Icon::data(
+        IconKind::Maximize,
+        "M 7.5 5.5 H 16.5 A 2 2 0 0 1 18.5 7.5 V 16.5 A 2 2 0 0 1 16.5 18.5 H 7.5 \
+         A 2 2 0 0 1 5.5 16.5 V 7.5 A 2 2 0 0 1 7.5 5.5 Z",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::ChevronLeft,
+        "M 14.5 5.5 L 8 12 L 14.5 18.5",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::ChevronRight,
+        "M 9.5 5.5 L 16 12 L 9.5 18.5",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::ChevronDown,
+        "M 5.5 9.5 L 12 16 L 18.5 9.5",
+        IconPaint::Stroke,
+    ),
+    // 展开为独立页：双对角外箭头
+    Icon::data(
+        IconKind::Expand,
+        "M 14 4 H 20 V 10 M 20 4 L 13.5 10.5 M 10 20 H 4 V 14 M 4 20 L 10.5 13.5",
+        IconPaint::Stroke,
+    ),
+    // 发送：纸飞机
+    Icon::data(
+        IconKind::Send,
+        "M 21 3 L 3 10.5 L 10.2 13.6 L 13.4 20.5 Z M 10.2 13.6 L 21 3",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::Check,
+        "M 5 12.5 L 9.8 17.3 L 19 6.5",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::Warn,
+        "M 12 4.5 L 20.5 19.5 H 3.5 Z M 12 9.5 V 14 M 12 16.6 V 17",
+        IconPaint::Stroke,
+    ),
+    Icon::data(
+        IconKind::Error,
+        "M 12 4 A 8 8 0 1 0 12 20 A 8 8 0 1 0 12 4 Z M 12 7.5 V 13 M 12 16.6 V 17",
+        IconPaint::Stroke,
+    ),
+    // 更多：三圆点（实心，原 Slint 版是三个 filled Rectangle）
+    Icon::data(
+        IconKind::More,
+        "M 7.5 12 A 1.5 1.5 0 1 0 4.5 12 A 1.5 1.5 0 1 0 7.5 12 Z \
+         M 13.5 12 A 1.5 1.5 0 1 0 10.5 12 A 1.5 1.5 0 1 0 13.5 12 Z \
+         M 19.5 12 A 1.5 1.5 0 1 0 16.5 12 A 1.5 1.5 0 1 0 19.5 12 Z",
+        IconPaint::Fill,
+    ),
+    // 侧栏：面板框 + 左侧分栏线
+    Icon::data(
+        IconKind::Sidebar,
+        "M 6 5 H 18 A 2 2 0 0 1 20 7 V 17 A 2 2 0 0 1 18 19 H 6 A 2 2 0 0 1 4 17 V 7 \
+         A 2 2 0 0 1 6 5 Z M 9.5 5.5 V 18.5",
+        IconPaint::Stroke,
+    ),
+    // 还原（已最大化时的标题栏按钮）：前后两层方框
+    Icon::data(
+        IconKind::Restore,
+        "M 9 4.5 H 19.5 V 15 M 15 8.5 H 4.5 V 19.5 H 15 Z",
+        IconPaint::Stroke,
+    ),
+    // 账户占位：头像剪影
+    Icon::data(
+        IconKind::User,
+        "M 12 5.3 A 3.7 3.7 0 1 0 12 12.7 A 3.7 3.7 0 1 0 12 5.3 Z \
+         M 4.5 20.5 C 4.5 16.9 8 15 12 15 C 16 15 19.5 16.9 19.5 20.5",
+        IconPaint::Stroke,
+    ),
+    // ── M61 新增（追加在末尾，不动既有次序；iced 页面需要而 Slint 版没有的）──
+    // 刷新：顺时针单圈 + 右上角箭头
+    Icon::data(
+        IconKind::Refresh,
+        "M 20 12 A 8 8 0 1 1 12 4 C 14.2 4 16.3 4.9 17.8 6.4 L 20 8.5 \
+         M 20 4.5 V 8.5 H 16",
+        IconPaint::Stroke,
+    ),
+    // 筛选：漏斗
+    Icon::data(
+        IconKind::Filter,
+        "M 4.5 5.5 H 19.5 L 14 12.5 V 19 L 10 16.5 V 12.5 Z",
+        IconPaint::Stroke,
+    ),
+    // 目录：文件夹（实例目录 / 日志目录入口）
+    Icon::data(
+        IconKind::Folder,
+        "M 4 7.5 A 2 2 0 0 1 6 5.5 H 9.5 L 11.5 7.5 H 18 A 2 2 0 0 1 20 9.5 V 17 \
+         A 2 2 0 0 1 18 19 H 6 A 2 2 0 0 1 4 17 Z",
+        IconPaint::Stroke,
+    ),
+    // 删除：垃圾桶
+    Icon::data(
+        IconKind::Trash,
+        "M 4.5 7 H 19.5 M 9.5 7 V 4.5 H 14.5 V 7 M 6.8 7 L 7.8 19.5 H 16.2 L 17.2 7 \
+         M 10.5 10.5 V 16 M 13.5 10.5 V 16",
+        IconPaint::Stroke,
+    ),
+];

crates/design/src/icons/kinds.rs

@@ -0,0 +1,208 @@
+//! `IconKind` 枚举：**API 已冻结，只允许在末尾追加**（序号即持久化 id，插到中间会静默换图）。
+
+use super::glyphs::GLYPHS;
+use super::Icon;
+
+/// 图标种类。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
+#[non_exhaustive]
+pub enum IconKind {
+    /// 实例（2×2 网格）。
+    Instances,
+    /// 下载。
+    Download,
+    /// 日志（文档 + 正文）。
+    Logs,
+    /// 设置（齿轮）。
+    Settings,
+    /// AI（四角星）。
+    Ai,
+    /// 播放（实心三角）。
+    Play,
+    /// 停止（实心圆角方）。
+    Stop,
+    /// 搜索（放大镜）。
+    Search,
+    /// 加号。
+    Plus,
+    /// 关闭（叉）。
+    Close,
+    /// 最小化（横线）。
+    Minimize,
+    /// 最大化（方框）。
+    Maximize,
+    /// 左尖角。
+    ChevronLeft,
+    /// 右尖角。
+    ChevronRight,
+    /// 下尖角。
+    ChevronDown,
+    /// 展开为独立页（双对角箭头）。
+    Expand,
+    /// 发送（纸飞机）。
+    Send,
+    /// 勾选。
+    Check,
+    /// 警告（三角感叹）。
+    Warn,
+    /// 错误（圆形感叹）。
+    Error,
+    /// 更多（三点，实心）。
+    More,
+    /// 侧栏开关。
+    Sidebar,
+    /// 还原窗口（双层方框）。
+    Restore,
+    /// 账户占位（头像剪影）。
+    User,
+    /// 刷新（M61 新增）。
+    Refresh,
+    /// 筛选（M61 新增）。
+    Filter,
+    /// 目录（M61 新增）。
+    Folder,
+    /// 删除（M61 新增）。
+    Trash,
+}
+
+impl IconKind {
+    /// 全部图标，按枚举声明顺序。
+    pub const ALL: [IconKind; 28] = [
+        IconKind::Instances,
+        IconKind::Download,
+        IconKind::Logs,
+        IconKind::Settings,
+        IconKind::Ai,
+        IconKind::Play,
+        IconKind::Stop,
+        IconKind::Search,
+        IconKind::Plus,
+        IconKind::Close,
+        IconKind::Minimize,
+        IconKind::Maximize,
+        IconKind::ChevronLeft,
+        IconKind::ChevronRight,
+        IconKind::ChevronDown,
+        IconKind::Expand,
+        IconKind::Send,
+        IconKind::Check,
+        IconKind::Warn,
+        IconKind::Error,
+        IconKind::More,
+        IconKind::Sidebar,
+        IconKind::Restore,
+        IconKind::User,
+        IconKind::Refresh,
+        IconKind::Filter,
+        IconKind::Folder,
+        IconKind::Trash,
+    ];
+
+    /// 取几何数据。
+    pub fn icon(self) -> Icon {
+        GLYPHS[self as usize]
+    }
+
+    /// 稳定字符串名（kebab-case）：写配置、日志、测试快照都用它，不要用 `Debug` 输出。
+    pub const fn name(self) -> &'static str {
+        match self {
+            IconKind::Instances => "instances",
+            IconKind::Download => "download",
+            IconKind::Logs => "logs",
+            IconKind::Settings => "settings",
+            IconKind::Ai => "ai",
+            IconKind::Play => "play",
+            IconKind::Stop => "stop",
+            IconKind::Search => "search",
+            IconKind::Plus => "plus",
+            IconKind::Close => "close",
+            IconKind::Minimize => "minimize",
+            IconKind::Maximize => "maximize",
+            IconKind::ChevronLeft => "chevron-left",
+            IconKind::ChevronRight => "chevron-right",
+            IconKind::ChevronDown => "chevron-down",
+            IconKind::Expand => "expand",
+            IconKind::Send => "send",
+            IconKind::Check => "check",
+            IconKind::Warn => "warn",
+            IconKind::Error => "error",
+            IconKind::More => "more",
+            IconKind::Sidebar => "sidebar",
+            IconKind::Restore => "restore",
+            IconKind::User => "user",
+            IconKind::Refresh => "refresh",
+            IconKind::Filter => "filter",
+            IconKind::Folder => "folder",
+            IconKind::Trash => "trash",
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::icons::IconPaint;
+
+    #[test]
+    fn glyph_table_matches_enum_order() {
+        for (i, icon) in GLYPHS.iter().enumerate() {
+            assert_eq!(
+                icon.kind as usize,
+                i,
+                "GLYPHS 第 {i} 项是 {}，与 IconKind 顺序不一致",
+                icon.kind.name()
+            );
+        }
+    }
+
+    #[test]
+    fn all_kinds_resolve() {
+        assert_eq!(IconKind::ALL.len(), GLYPHS.len());
+        for kind in IconKind::ALL {
+            let icon = kind.icon();
+            assert_eq!(icon.kind, kind);
+            assert!(!icon.path.is_empty());
+        }
+    }
+
+    #[test]
+    fn names_are_unique_and_kebab() {
+        let mut seen = std::collections::BTreeSet::new();
+        for kind in IconKind::ALL {
+            let name = kind.name();
+            assert!(seen.insert(name), "图标名重复：{name}");
+            assert!(name
+                .chars()
+                .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-'));
+        }
+    }
+
+    #[test]
+    fn migrated_kinds_keep_their_positions() {
+        // 前 24 个是 Slint 版迁移来的（次序必须原样），后 4 个是 M61 追加的。
+        assert_eq!(IconKind::ALL[0], IconKind::Instances);
+        assert_eq!(IconKind::ALL[4], IconKind::Ai);
+        assert_eq!(IconKind::ALL[20], IconKind::More);
+        assert_eq!(IconKind::ALL[23], IconKind::User);
+        assert_eq!(IconKind::ALL[24], IconKind::Refresh);
+        assert_eq!(IconKind::ALL[27], IconKind::Trash);
+    }
+
+    #[test]
+    fn only_solid_icons_are_filled() {
+        for kind in IconKind::ALL {
+            let icon = kind.icon();
+            let expect_fill = matches!(kind, IconKind::Play | IconKind::Stop | IconKind::More);
+            assert_eq!(
+                icon.paint,
+                if expect_fill {
+                    IconPaint::Fill
+                } else {
+                    IconPaint::Stroke
+                },
+                "{} 的 fill/stroke 判定不对",
+                kind.name()
+            );
+        }
+    }
+}

crates/design/src/icons/mod.rs

@@ -0,0 +1,251 @@
+//! 图标令牌：`IconKind`（一次冻结，只允许在末尾追加）+ 24 网格几何数据。
+//!
+//! ```no_run
+//! use unlucky_design::icons::{IconKind, IconSize};
+//!
+//! let icon = IconKind::Settings.icon();
+//! let w = icon.stroke_width(IconSize::Nav.px());
+//! assert!((w - 1.8).abs() < 1e-6);
+//! ```
+//!
+//! ## 几何口径（三线统一，M54 定稿）
+//!
+//! - **网格 24×24**（[`VIEWBOX`]），内容留 2~3 单位边距；
+//! - **视觉描边 1.5px**（[`VISUAL_STROKE_PX`]）：不管渲染多大，线宽看起来都是 1.5 逻辑像素；
+//! - **圆头端点 + 圆角连接**（`stroke-linecap: round` / `stroke-linejoin: round`），
+//!   适配层设这两个属性，数据里不表达；
+//! - **实心图形才用 fill**（播放/停止/三点），其余一律描边，保证与文字并排时重量一致；
+//! - 不用字体字符当图标（`+` `→` 一律禁止）。
+//!
+//! ## ⚠️ 描边语义差异：Slint 与 SVG **不是一回事**
+//!
+//! - Slint 的 `Path.stroke-width` 是**绝对像素**：只乘 DPI 缩放，**不乘 viewBox**。
+//!   所以老代码写 `stroke-width: 1.5px` 意味着「渲染出来就是 1.5px」，viewBox 缩放对它无影响
+//!   （实证：femtovg 后端 `PathItemRenderer::render` 里的
+//!   `paint.set_line_width(stroke_width * scale_factor)`——只有 DPI 缩放因子，没有 viewBox 项）。
+//! - SVG / iced canvas 的 `stroke-width` 是**用户单位**（viewBox 单位）：渲染时会被
+//!   `render_px / VIEWBOX` 缩放。同样的 `1.5` 在 20px 渲染下只有 1.25px 视觉宽度。
+//!
+//! 因此 iced 侧必须**按 SVG 语义重算**：要保持 1.5px 视觉线宽，viewBox 里的 stroke-width 得取
+//! `1.5 × 24 / render_px`（20px → 1.8、16px → 2.25、24px → 1.5）。[`Icon::stroke_width`] 就是这个
+//! 换算的纯函数——**不要在适配层手抄 1.5 这个数**，那是 Slint 口径。
+
+mod glyphs;
+mod kinds;
+
+pub use kinds::IconKind;
+
+/// 图标网格边长（viewBox 宽高）。
+pub const VIEWBOX: f32 = 24.0;
+
+/// 视觉描边宽度（逻辑像素，与渲染尺寸无关）。
+pub const VISUAL_STROKE_PX: f32 = 1.5;
+
+/// 描边语义换算：给定渲染尺寸与目标视觉线宽，返回 **viewBox 单位**的 stroke-width。
+///
+/// `render_px <= 0` 时返回 `visual_px`（退化情形不产生除零/无穷大）。
+pub fn stroke_width_for(render_px: f32, visual_px: f32) -> f32 {
+    if render_px <= 0.0 {
+        return visual_px;
+    }
+    visual_px * VIEWBOX / render_px
+}
+
+/// 反向换算：viewBox 单位的 stroke-width 在实际渲染尺寸下的视觉线宽。
+pub fn visual_stroke_px(render_px: f32, stroke_width: f32) -> f32 {
+    stroke_width * render_px / VIEWBOX
+}
+
+/// 图标的绘制方式。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum IconPaint {
+    /// 只描边（默认，绝大多数图标）。
+    Stroke,
+    /// 填充（播放/停止/三点这类实心图形）。
+    Fill,
+}
+
+/// 图标的标准渲染尺寸（页面只从这几档里取，不许自定义零散值）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum IconSize {
+    /// 12px：行内小图标（徽标内）。
+    Inline,
+    /// 16px：按钮/标题栏按钮。
+    Button,
+    /// 20px：导航项、列表行。
+    Nav,
+    /// 24px：卡片头、工具栏。
+    Toolbar,
+    /// 32px：空态图标块。
+    Empty,
+}
+
+impl IconSize {
+    /// 像素值。
+    pub const fn px(self) -> f32 {
+        match self {
+            IconSize::Inline => 12.0,
+            IconSize::Button => 16.0,
+            IconSize::Nav => 20.0,
+            IconSize::Toolbar => 24.0,
+            IconSize::Empty => 32.0,
+        }
+    }
+
+    /// 全部档位，由小到大。
+    pub const ALL: [IconSize; 5] = [
+        IconSize::Inline,
+        IconSize::Button,
+        IconSize::Nav,
+        IconSize::Toolbar,
+        IconSize::Empty,
+    ];
+}
+
+/// 一个图标的几何数据。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Icon {
+    /// 图标种类。
+    pub kind: IconKind,
+    /// SVG path 数据（viewBox `0 0 24 24`，可能含多个子路径）。
+    pub path: &'static str,
+    /// 描边还是填充。
+    pub paint: IconPaint,
+}
+
+impl Icon {
+    /// 表项构造器（只在 [`glyphs`] 的数据表里用）。
+    pub(super) const fn data(kind: IconKind, path: &'static str, paint: IconPaint) -> Self {
+        Self { kind, path, paint }
+    }
+
+    /// 该图标在 `render_px` 下的 **viewBox 单位** stroke-width（[`IconPaint::Fill`] 返回 0）。
+    pub fn stroke_width(self, render_px: f32) -> f32 {
+        match self.paint {
+            IconPaint::Fill => 0.0,
+            IconPaint::Stroke => stroke_width_for(render_px, VISUAL_STROKE_PX),
+        }
+    }
+
+    /// 是否实心填充。
+    pub fn is_filled(self) -> bool {
+        self.paint == IconPaint::Fill
+    }
+
+    /// 路径里是否含曲线命令（适配层可选：纯直线路径走不走曲线细分）。
+    pub fn has_curves(self) -> bool {
+        self.path
+            .bytes()
+            .any(|b| matches!(b, b'C' | b'Q' | b'A' | b'c' | b'q' | b'a'))
+    }
+
+    /// 子路径个数（`M` 命令计数）：适配层可以据此一次性分配 `lyon` 的缓冲区。
+    pub fn subpath_count(self) -> usize {
+        self.path.matches('M').count() + self.path.matches('m').count()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn paths_use_only_svg_commands() {
+        const ALLOWED: &str = "MmLlHhVvAaCcQqZz0123456789 .,-";
+        for kind in IconKind::ALL {
+            let path = kind.icon().path;
+            assert!(path.starts_with('M'), "{} 的路径必须以 M 开头", kind.name());
+            for byte in path.bytes() {
+                assert!(
+                    byte.is_ascii(),
+                    "{} 的路径含非 ASCII（不许用字体字符/中文）",
+                    kind.name()
+                );
+            }
+            for ch in path.chars() {
+                assert!(
+                    ALLOWED.contains(ch),
+                    "{} 的路径含非法字符 {ch:?}",
+                    kind.name()
+                );
+            }
+            // 不许出现科学计数法（能解析但可读性差、易手误）。
+            assert!(
+                !path.contains('e') && !path.contains('E'),
+                "{} 用了科学计数法",
+                kind.name()
+            );
+            assert!(
+                path.matches(' ').count() >= 2,
+                "{} 的坐标分隔异常",
+                kind.name()
+            );
+        }
+    }
+
+    #[test]
+    fn coordinates_stay_inside_the_grid() {
+        for kind in IconKind::ALL {
+            for token in kind.icon().path.split([' ', ',']) {
+                if let Ok(value) = token.parse::<f32>() {
+                    assert!(
+                        (-1.0..=VIEWBOX + 1.0).contains(&value),
+                        "{} 出现 {value}：超出 24 网格（弧半径/控制点也受这条约束）",
+                        kind.name()
+                    );
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn subpaths_are_counted() {
+        assert_eq!(IconKind::Plus.icon().subpath_count(), 2);
+        assert_eq!(IconKind::Instances.icon().subpath_count(), 4);
+        assert_eq!(IconKind::Play.icon().subpath_count(), 1);
+    }
+
+    #[test]
+    fn filled_icons_have_no_stroke() {
+        for kind in IconKind::ALL {
+            let icon = kind.icon();
+            if icon.is_filled() {
+                assert_eq!(icon.stroke_width(20.0), 0.0, "{}", kind.name());
+            } else {
+                assert!(icon.stroke_width(20.0) > 1.0, "{}", kind.name());
+            }
+        }
+    }
+
+    #[test]
+    fn stroke_width_follows_svg_semantics() {
+        // SVG 语义：viewBox 单位 × (render/24) = 视觉像素。
+        assert!((stroke_width_for(20.0, VISUAL_STROKE_PX) - 1.8).abs() < 1.0e-6);
+        assert!((stroke_width_for(16.0, VISUAL_STROKE_PX) - 2.25).abs() < 1.0e-6);
+        assert!((stroke_width_for(24.0, VISUAL_STROKE_PX) - 1.5).abs() < 1.0e-6);
+        assert!((stroke_width_for(48.0, VISUAL_STROKE_PX) - 0.75).abs() < 1.0e-6);
+        // 退化输入不炸、不产生无穷大（Slint 口径的 1.5 绝对值这里不能照抄）。
+        assert_eq!(stroke_width_for(0.0, VISUAL_STROKE_PX), VISUAL_STROKE_PX);
+        assert_eq!(stroke_width_for(-4.0, VISUAL_STROKE_PX), VISUAL_STROKE_PX);
+        // 往返一致。
+        for size in IconSize::ALL {
+            let w = stroke_width_for(size.px(), VISUAL_STROKE_PX);
+            assert!((visual_stroke_px(size.px(), w) - VISUAL_STROKE_PX).abs() < 1.0e-6);
+        }
+    }
+
+    #[test]
+    fn icon_sizes_are_ordered() {
+        let px: Vec<f32> = IconSize::ALL.iter().map(|s| s.px()).collect();
+        for pair in px.windows(2) {
+            assert!(pair[0] < pair[1]);
+        }
+    }
+
+    #[test]
+    fn curve_flags_are_reported() {
+        assert!(IconKind::Settings.icon().has_curves());
+        assert!(!IconKind::Plus.icon().has_curves());
+        assert!(!IconKind::ChevronDown.icon().has_curves());
+    }
+}

crates/design/src/lib.rs

@@ -0,0 +1,141 @@
+//! # unlucky-design · ULL 设计令牌唯一真源
+//!
+//! 视觉基线 = **Material 3 Expressive**（D26 锁定，风格与框架不再更换）。这个 crate 只装
+//! **渲染无关的数据与纯函数**：色彩角色、排版 ramp、形状刻度、高程、动效参数、图标几何。
+//! 它不依赖任何 UI / 渲染框架（iced / slint / winit / wgpu / gtk …），也不依赖任何第三方 crate，
+//! 因此 iced 迁移、CLI、甚至离屏截图工具都能吃同一套值——这是「UI 整体性」的地基。
+//!
+//! ## 边界（谁负责什么）
+//!
+//! | 层 | 负责 | 不负责 |
+//! |---|---|---|
+//! | `unlucky-design`（本 crate） | 令牌的值与它们之间的纯函数关系（tone→色、type role→字号/行高/字重、shape→半径、spring→时长） | 布局、控件、绘制、字体加载、图片、动画驱动 |
+//! | iced 适配层（后续 mission） | 把令牌翻成 iced 的类型（`Color` / `Length` / `Font` / 动画时钟） | 自己发明新令牌名或新取值 |
+//! | 页面 mission | 消费令牌与 [`component_map`] 的档位约定 | 硬编码色值 / 字号 / 半径 / 时长 |
+//!
+//! ## 分模块
+//!
+//! - [`color`]：M3 语义色角色（49 个）× light/dark 双套 + tone 调色板（**真 HCT**：CAM16 色相/彩度
+//!   + CIELAB `L*`，官方 `ColorSpec2021` tone 表，与官方 Java 实现逐通道对齐——口径见模块文档）
+//! - [`typography`]：M3 type scale 15 档 + 三平台字体族回退栈
+//! - [`shape`]：M3 Expressive 形状刻度 + shape morph 数据 + [`shape::ComponentRadius`]（微控件圆角层，D32）
+//! - [`elevation`]：elevation level 与 surface tint / surface container 规则
+//! - [`motion`]：时长、easing（可采样）、Expressive 弹簧参数
+//! - [`spacing`]：4px 栅格、骨架尺寸（原 `metrics.slint` 的框架无关部分）、[`stroke::HAIRLINE`]（一像素线）
+//! - [`icons`]：24 网格图标几何（SVG path 字符串）+ 描边语义
+//! - [`component_map`]：组件 → 档位映射表（哪个组件用哪档形状/高程/动效/字体）
+//!   + [`component_map::ComponentMetrics`]（控件内部微几何，与 `LayoutMetrics` 分工见该模块文档）
+//!
+//! ## 最小用法
+//!
+//! ```
+//! use unlucky_design::color::{Role, Scheme, SchemeFlavor};
+//! use unlucky_design::typography::{FontFamily, Platform, TypeRole};
+//!
+//! let light = Scheme::baseline(SchemeFlavor::Light);
+//! let ratio = light.contrast(Role::OnSurface, Role::Surface);
+//! assert!(ratio >= 4.5, "正文对表面必须满足 WCAG AA");
+//!
+//! let title = TypeRole::TitleLarge.style();
+//! assert_eq!(title.size_px, 22.0);
+//! let stack = Platform::current().font_stack(FontFamily::Display);
+//! assert!(!stack.is_empty());
+//! ```
+//!
+//! ## baseline MD3 vs M3 Expressive 差异清单
+//!
+//! 「M3 Expressive」不是「M3 换皮」——它真的加了一批令牌。本 crate 两代都提供，差异如下
+//! （来源等级：**A** = androidx 源码 / 官方 token 文件；**B** = m3.material.io 文档表格；**C** = 社区转述）。
+//!
+//! | 领域 | baseline MD3 | M3 Expressive 新增/不同 | 本 crate 落点 | 等级 |
+//! |---|---|---|---|---|
+//! | 排版 | 15 档 type role，只有 Regular/Medium 两种字重档 | **每档多一条 `*Emphasized`**：字号/行高不变，字重升到 Medium(500) 或 Bold(700)，字距按表微调（display-large −0.2→0、body-large 0.5→0.15、title-medium 0.2→0.15、body-medium 0.2→0.25） | [`typography::TypeRole::emphasized`]（官方值）；[`typography::TypeRole::emphasized_simplified`] 是我们的「只加一档字重」简化规则，**非官方** | A |
+//! | 形状 | ExtraSmall 4 / Small 8 / Medium 12 / Large 16 / **ExtraLarge 28** / Full | 多出 **LargeIncreased 20 / ExtraLargeIncreased 32 / ExtraExtraLarge 48**，并引入 **shape morph**（按下/选中时档位之间弹性过渡） | [`shape::ShapeScale`]（10 档）+ [`shape::ShapeMorph`] + [`component_map`] 的 `morph` 列 | A |
+//! | 动效 | 16 档 duration + 7 条 cubic-bezier easing（时间驱动） | 把弹簧打包成 **standard / expressive 两套方案**，每套各有 spatial（位移，会回弹）与 effects（颜色/透明度，不回弹）× fast/default/slow。standard spatial ζ=0.9（k 1400/700/300），expressive spatial ζ=0.6~0.8（k 800/380/200），effects 两套同值 ζ=1.0（k 3800/1600/800） | [`motion::spring`] 的 **方案 × 类别 × 速度**二维表（12 格，`StandardMotionTokens`/`ExpressiveMotionTokens` 原值）+ 9 个具名常量；duration/easing 两代共用 | A |
+//! | 组件尺寸 | 触控目标 48dp（无障碍下限本来就是 48） | Expressive 把按钮/列表的整体节奏放大（列表项 56/72/88），并明确 48dp 为**可点下限** | [`spacing::LayoutMetrics::DESKTOP`]：`touch_target = 48`（照规范）+ `control_height = 40`（可见高度，上下各 4px 内边距凑满 48）+ `row_height`/`nav_item_height` = 44、`titlebar_height` = 48（M63 §1.4+R13 的桌面档） | A/B |
+//! | 字体 | 只有 400/500/700 的「概念」字重，没规定字体族要覆盖几档 | Expressive 的强调档**真的会要 700**（label-*、title-medium/small），中文字体覆盖差异巨大：雅黑只有 400/700（无 500）、苹方到 600 断（无 700）、Noto/思源可变字体全覆盖 | [`typography::FontFace`] 的 `WeightCoverage`（可变区间 / 静态表）+ [`typography::Platform::resolve_weight`] 纯函数给出「原生 / 最近档 / 合成加粗」三档结论 | B |
+//! | 色彩 | 49 个角色（primary/secondary/tertiary/error 族、surface-container 系、`*-fixed*` 系、outline、inverse、scrim/shadow） | **没有新增颜色角色**；变化在用法：surface-container 系（Lowest…Highest）取代旧的 elevation tint 叠色，表达层级 | [`color::Role`] 全 49 个；[`elevation::Elevation::surface_role`] 给出层级映射，`deprecated_tint_alpha` 保留旧口径作对照 | A |
+//! | 高程 | Level0..5 = 0/1/3/6/8/12dp | 数值不变；组件默认值不同（卡片 L0、菜单 L2、对话框 L3，见 [`component_map`]） | [`elevation::Elevation`] | A |
+//!
+//! ### 两条由此衍生的项目纪律
+//!
+//! 1. **shape morph 是克制的状态信号，不是每屏装饰**：Expressive 官方鼓励「形状即状态」，但
+//!    桌面端信息密度高，圆角到处变会显得凌乱（社区已有人批评控制中心这么做）。本项目的约束是
+//!    **一屏最多 1 处形变、且只用于状态切换信号**；静态元素一律用 [`shape::ShapeScale`] 的固定档。
+//!    [`component_map`] 的 `morph` 列就是允许清单——不在表里的组件不许自己加形变。
+//! 2. **中文字重必须真的有三档**：Expressive 的 700 落在中文字体上，雅黑缺 500、苹方缺 700，
+//!    缺档就走「合成加粗」= 观感廉价。所以字体栈带 `WeightCoverage`，并在
+//!    [`typography::Platform::resolve_weight`] 里把降级路径显式化（合成加粗是最后一档）。
+//!
+//! 已知与文档的 0.05px 级差异：Compose 这一代 `TypeScaleTokens` 的 tracking 与 m3.material.io
+//! 网页表格不同（display-large −0.2 vs −0.25、body-medium 0.2 vs 0.25、title-medium 0.2 vs 0.15），
+//! 本项目**跟 Compose**（那是真正渲染出来的值，A 级）。
+//!
+//! ## 未支持的官方能力（gap 登记，不要以为已经有了）
+//!
+//! - **对比度等级**：Android 16 的「默认 / 中 / 高」三档对比度本 crate **不支持**。将来扩法是
+//!   **按等级偏移角色 tone 表**（例如高对比把 `on-*` 与承载色的 tone 差拉大 5~10），
+//!   而不是新增一批角色——`Role` 的数量保持 49 不变，`Scheme` 多一个 `contrast_level` 维度。
+//!   （M63 的 G4 只说「高对比模式走 CPU 档」，那是渲染档位，不等价于支持对比度等级。）
+//! - **动态壁纸取色**：Material You 的多色种子派生未实现（本启动器用不到）。
+//! - **M3 的 elevation tint 叠色**：现行 M3 已改用 surface-container 表达层级，旧的
+//!   `deprecated_tint_alpha()` 只为读旧稿保留。
+
+#![forbid(unsafe_code)]
+
+pub mod color;
+pub mod component_map;
+pub mod elevation;
+pub mod icons;
+pub mod motion;
+pub mod shape;
+pub mod spacing;
+pub mod typography;
+
+pub use color::{Color, Role, Scheme, SchemeFlavor};
+pub use motion::MotionScale;
+pub use spacing::stroke;
+pub use typography::TypeRole;
+
+/// 设计令牌的整体入口：一份「当前该长什么样」的聚合快照。
+///
+/// iced 适配层只持有这个结构（深浅切换 = 重新 `DesignTokens::baseline(mode)`），
+/// 不要在适配层里缓存散装色值——那样深浅热切会有一半画对一半画错。
+#[derive(Debug, Clone, Copy)]
+pub struct DesignTokens {
+    /// 当前深浅模式。
+    pub flavor: SchemeFlavor,
+    /// 当前模式的 M3 语义色角色全表。
+    pub colors: Scheme,
+    /// 动效时长的全局缩放（`1.0` = 标准；用户关掉动画时适配层传 `0.0`）。
+    pub motion_scale: MotionScale,
+}
+
+impl DesignTokens {
+    /// 按模式给一套**产品默认**令牌：种子 `#3C8DBC`（M70 ④ 天蓝，用户 2026-11-01 拍板）
+    /// + 中性彩度 12，即 `color::palettes::DEFAULT_SEED` / `DEFAULT_NEUTRAL_CHROMA`。
+    ///
+    /// 想要**官方 M3 baseline** 口径（种子 `#6750A4` + 中性彩度 6 / neutral-variant 8）请走
+    /// `color::Scheme::official_baseline(flavor)`——两条路径的算法完全相同，只差入参。
+    pub fn baseline(flavor: SchemeFlavor) -> Self {
+        Self {
+            flavor,
+            colors: Scheme::baseline(flavor),
+            motion_scale: MotionScale::STANDARD,
+        }
+    }
+
+    /// 按用户强调色重建一套令牌（表面中性色仍走 baseline，强调色只驱动 primary/secondary/tertiary）。
+    pub fn with_accent(flavor: SchemeFlavor, accent: Color) -> Self {
+        Self {
+            flavor,
+            colors: Scheme::from_accent(flavor, accent),
+            motion_scale: MotionScale::STANDARD,
+        }
+    }
+
+    /// 便捷取色：`tokens.color(Role::Surface)`。
+    pub fn color(&self, role: Role) -> Color {
+        self.colors.get(role)
+    }
+}

crates/design/src/motion/mod.rs

@@ -0,0 +1,308 @@
+//! 动效令牌：时长、缓动（可采样）、M3 Expressive 弹簧参数。
+//!
+//! 三件东西分开表达，因为适配层要的接口不同：
+//! - [`DurationToken`]：M3 的 short/medium/long/extra-long 十六档，给「固定时长 + easing」用；
+//! - [`Easing`]：cubic-bezier 曲线，纯函数采样（适配层自己决定帧率）；
+//! - [`Spring`]（见 [`spring`]）：Expressive 的物理参数（stiffness/damping/mass），
+//!   可用于实时求解或预估时长。
+//!
+//! **CPU / 减少动效路径**：把 [`MotionScale`] 设成 [`MotionScale::NONE`]，
+//! 所有时长归零、`Easing::sample` 仍返回 0/1 端值（适配层按 `t >= 1` 直接落终态）。
+
+mod spring;
+
+pub use spring::{
+    spring, MotionScale, MotionSchemeKind, Spring, SpringCategory, SpringSpeed,
+    SPRING_EFFECTS_DEFAULT, SPRING_EFFECTS_FAST, SPRING_EFFECTS_SLOW,
+    SPRING_EXPRESSIVE_SPATIAL_DEFAULT, SPRING_EXPRESSIVE_SPATIAL_FAST,
+    SPRING_EXPRESSIVE_SPATIAL_SLOW, SPRING_STANDARD_SPATIAL_DEFAULT, SPRING_STANDARD_SPATIAL_FAST,
+    SPRING_STANDARD_SPATIAL_SLOW,
+};
+
+/// 动效时长档位（M3 动效令牌，单位毫秒）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum DurationToken {
+    /// 50ms：最小状态回弹。
+    Short1,
+    /// 100ms：小图标/勾选。
+    Short2,
+    /// 150ms：开关、小尺寸 fade。
+    Short3,
+    /// 200ms：按钮状态、hover。
+    Short4,
+    /// 250ms：小卡片展开。
+    Medium1,
+    /// 300ms：导航指示条、tab 切换。
+    Medium2,
+    /// 350ms：卡片展开、列表重排。
+    Medium3,
+    /// 400ms：面板开合。
+    Medium4,
+    /// 450ms：页面切换。
+    Long1,
+    /// 500ms：大面板进出。
+    Long2,
+    /// 550ms：全屏浮层。
+    Long3,
+    /// 600ms：对话框进出。
+    Long4,
+    /// 700ms：结构化过渡。
+    ExtraLong1,
+    /// 800ms：结构化过渡。
+    ExtraLong2,
+    /// 900ms：结构化过渡。
+    ExtraLong3,
+    /// 1000ms：整屏形变（shape morph 的慢档）。
+    ExtraLong4,
+}
+
+impl DurationToken {
+    /// 毫秒值。
+    pub const fn ms(self) -> u32 {
+        match self {
+            DurationToken::Short1 => 50,
+            DurationToken::Short2 => 100,
+            DurationToken::Short3 => 150,
+            DurationToken::Short4 => 200,
+            DurationToken::Medium1 => 250,
+            DurationToken::Medium2 => 300,
+            DurationToken::Medium3 => 350,
+            DurationToken::Medium4 => 400,
+            DurationToken::Long1 => 450,
+            DurationToken::Long2 => 500,
+            DurationToken::Long3 => 550,
+            DurationToken::Long4 => 600,
+            DurationToken::ExtraLong1 => 700,
+            DurationToken::ExtraLong2 => 800,
+            DurationToken::ExtraLong3 => 900,
+            DurationToken::ExtraLong4 => 1000,
+        }
+    }
+
+    /// 稳定字符串名（`short1` … `extra-long4`），写配置与日志用。
+    pub const fn name(self) -> &'static str {
+        match self {
+            DurationToken::Short1 => "short1",
+            DurationToken::Short2 => "short2",
+            DurationToken::Short3 => "short3",
+            DurationToken::Short4 => "short4",
+            DurationToken::Medium1 => "medium1",
+            DurationToken::Medium2 => "medium2",
+            DurationToken::Medium3 => "medium3",
+            DurationToken::Medium4 => "medium4",
+            DurationToken::Long1 => "long1",
+            DurationToken::Long2 => "long2",
+            DurationToken::Long3 => "long3",
+            DurationToken::Long4 => "long4",
+            DurationToken::ExtraLong1 => "extra-long1",
+            DurationToken::ExtraLong2 => "extra-long2",
+            DurationToken::ExtraLong3 => "extra-long3",
+            DurationToken::ExtraLong4 => "extra-long4",
+        }
+    }
+}
+
+/// 三次贝塞尔缓动曲线（CSS `cubic-bezier` 同样的参数含义）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct CubicBezier {
+    /// 控制点 1 的 x（0..1）。
+    pub x1: f32,
+    /// 控制点 1 的 y。
+    pub y1: f32,
+    /// 控制点 2 的 x（0..1）。
+    pub x2: f32,
+    /// 控制点 2 的 y。
+    pub y2: f32,
+}
+
+impl CubicBezier {
+    /// 线性。
+    pub const LINEAR: Self = Self {
+        x1: 0.0,
+        y1: 0.0,
+        x2: 1.0,
+        y2: 1.0,
+    };
+
+    /// 给定时间参数 `t`（0..1），返回进度（0..1，标准曲线不越界）。
+    pub fn sample(self, t: f32) -> f32 {
+        let t = t.clamp(0.0, 1.0);
+        if t == 0.0 || t == 1.0 {
+            return t;
+        }
+        // 二分求 x(s) = t 的曲线参数 s，再取 y(s)。
+        let mut lo = 0.0_f32;
+        let mut hi = 1.0_f32;
+        let mut s = t;
+        for _ in 0..24 {
+            s = 0.5 * (lo + hi);
+            let x = bezier_axis(self.x1, self.x2, s);
+            if x < t {
+                lo = s;
+            } else {
+                hi = s;
+            }
+        }
+        bezier_axis(self.y1, self.y2, s)
+    }
+}
+
+/// 一维三次贝塞尔：端点固定为 0/1，控制点为 `c1`/`c2`。
+fn bezier_axis(c1: f32, c2: f32, s: f32) -> f32 {
+    let u = 1.0 - s;
+    3.0 * u * u * s * c1 + 3.0 * u * s * s * c2 + s * s * s
+}
+
+/// M3 缓动档位（值取自 Material 动效令牌）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Easing {
+    /// 线性（进度指示器）。
+    Linear,
+    /// 标准：起止都平滑。
+    Standard,
+    /// 标准减速：进场（出现在屏幕上）。
+    StandardDecelerate,
+    /// 标准加速：退场。
+    StandardAccelerate,
+    /// 强调：注意力转移的主曲线。
+    Emphasized,
+    /// 强调减速：强调类进场。
+    EmphasizedDecelerate,
+    /// 强调加速：强调类退场。
+    EmphasizedAccelerate,
+}
+
+impl Easing {
+    /// 曲线参数。
+    pub const fn curve(self) -> CubicBezier {
+        match self {
+            Easing::Linear => CubicBezier::LINEAR,
+            Easing::Standard | Easing::Emphasized => CubicBezier {
+                x1: 0.2,
+                y1: 0.0,
+                x2: 0.0,
+                y2: 1.0,
+            },
+            Easing::StandardDecelerate => CubicBezier {
+                x1: 0.0,
+                y1: 0.0,
+                x2: 0.0,
+                y2: 1.0,
+            },
+            Easing::StandardAccelerate => CubicBezier {
+                x1: 0.3,
+                y1: 0.0,
+                x2: 1.0,
+                y2: 1.0,
+            },
+            Easing::EmphasizedDecelerate => CubicBezier {
+                x1: 0.05,
+                y1: 0.7,
+                x2: 0.1,
+                y2: 1.0,
+            },
+            Easing::EmphasizedAccelerate => CubicBezier {
+                x1: 0.3,
+                y1: 0.0,
+                x2: 0.8,
+                y2: 0.15,
+            },
+        }
+    }
+
+    /// 采样：`t` 0..1 → 进度 0..1。
+    pub fn sample(self, t: f32) -> f32 {
+        self.curve().sample(t)
+    }
+
+    /// 该曲线搭配的常用时长（我们的组件映射口径，非规范值）。
+    pub const fn default_duration(self) -> DurationToken {
+        match self {
+            Easing::Linear => DurationToken::Long2,
+            _ => DurationToken::Medium2,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const ALL_EASINGS: [Easing; 7] = [
+        Easing::Linear,
+        Easing::Standard,
+        Easing::StandardDecelerate,
+        Easing::StandardAccelerate,
+        Easing::Emphasized,
+        Easing::EmphasizedDecelerate,
+        Easing::EmphasizedAccelerate,
+    ];
+
+    #[test]
+    fn durations_are_monotone() {
+        let ladder = [
+            DurationToken::Short1,
+            DurationToken::Short2,
+            DurationToken::Short3,
+            DurationToken::Short4,
+            DurationToken::Medium1,
+            DurationToken::Medium2,
+            DurationToken::Medium3,
+            DurationToken::Medium4,
+            DurationToken::Long1,
+            DurationToken::Long2,
+            DurationToken::Long3,
+            DurationToken::Long4,
+            DurationToken::ExtraLong1,
+            DurationToken::ExtraLong2,
+            DurationToken::ExtraLong3,
+            DurationToken::ExtraLong4,
+        ];
+        assert_eq!(ladder.len(), 16);
+        for pair in ladder.windows(2) {
+            assert!(pair[0].ms() < pair[1].ms());
+        }
+        assert_eq!(DurationToken::Short1.ms(), 50);
+        assert_eq!(DurationToken::ExtraLong4.ms(), 1000);
+        // 名字唯一
+        let mut names = std::collections::BTreeSet::new();
+        for token in ladder {
+            assert!(names.insert(token.name()), "时长名重复：{}", token.name());
+        }
+    }
+
+    #[test]
+    fn easing_hits_endpoints_and_stays_in_range() {
+        for easing in ALL_EASINGS {
+            assert!(
+                (easing.sample(0.0) - 0.0).abs() < 1.0e-6,
+                "{easing:?} 起点不为 0"
+            );
+            assert!(
+                (easing.sample(1.0) - 1.0).abs() < 1.0e-6,
+                "{easing:?} 终点不为 1"
+            );
+            let mut prev = 0.0;
+            for step in 1..=20 {
+                let v = easing.sample(step as f32 / 20.0);
+                assert!((-0.001..=1.001).contains(&v), "{easing:?} 采样越界：{v}");
+                assert!(v + 1.0e-3 >= prev, "{easing:?} 采样非单调：{prev} → {v}");
+                prev = v;
+            }
+        }
+    }
+
+    #[test]
+    fn emphasized_decelerate_is_faster_early_than_accelerate() {
+        let early_decel = Easing::EmphasizedDecelerate.sample(0.25);
+        let early_accel = Easing::EmphasizedAccelerate.sample(0.25);
+        assert!(early_decel > early_accel);
+    }
+
+    #[test]
+    fn default_durations_are_registered_tokens() {
+        for easing in ALL_EASINGS {
+            assert!(easing.default_duration().ms() >= 250);
+        }
+    }
+}

crates/design/src/motion/spring.rs

@@ -0,0 +1,380 @@
+//! 弹簧参数（M3 Expressive 动效的物理表达）与动效时长缩放。
+//!
+//! **来源 A 级**：`androidx.compose.material3.tokens.ExpressiveMotionTokens`（v0_14_0）给出六组
+//! `Spring{Damping, Stiffness}`——注意 Compose 的 `Damping` 是**阻尼比 ζ**（不是绝对阻尼系数），
+//! 所以本模块的 [`Spring`] 也按 (stiffness, damping_ratio, mass) 存，两者可直接对照。
+//! 阶跃响应用标准二阶系统闭式解（欠阻尼 / 临界 / 过阻尼三分支），是纯数学、无状态。
+
+/// 弹簧参数（Compose 口径：刚度 + 阻尼比 + 质量）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Spring {
+    /// 刚度 k（越大越快）。
+    pub stiffness: f32,
+    /// 阻尼比 ζ（1.0 = 临界阻尼，< 1 会轻微弹过）。
+    pub damping_ratio: f32,
+    /// 质量 m。
+    pub mass: f32,
+}
+
+impl Spring {
+    /// 按 M3 令牌口径构造（刚度 + 阻尼比 + 质量）。
+    pub const fn from_ratio(stiffness: f32, damping_ratio: f32, mass: f32) -> Self {
+        Self {
+            stiffness,
+            damping_ratio,
+            mass,
+        }
+    }
+
+    /// 自然角频率 ωn（rad/s）。
+    pub fn natural_frequency(self) -> f32 {
+        (self.stiffness / self.mass).sqrt()
+    }
+
+    /// 绝对阻尼系数 c = 2·ζ·√(k·m)（需要喂给「阻尼系数」式积分器时用）。
+    pub fn damping_coefficient(self) -> f32 {
+        2.0 * self.damping_ratio * (self.stiffness * self.mass).sqrt()
+    }
+
+    /// 阶跃响应：`t_ms` 毫秒后的进度（0..1，欠阻尼时会轻微超过 1 = 回弹）。
+    pub fn sample(self, t_ms: f32) -> f32 {
+        if t_ms <= 0.0 {
+            return 0.0;
+        }
+        let t = t_ms / 1000.0;
+        let wn = self.natural_frequency();
+        let zeta = self.damping_ratio;
+        if wn <= 0.0 {
+            return 1.0;
+        }
+        if zeta < 1.0 {
+            let wd = wn * (1.0 - zeta * zeta).sqrt();
+            let decay = (-zeta * wn * t).exp();
+            1.0 - decay * ((wd * t).cos() + (zeta * wn / wd) * (wd * t).sin())
+        } else if (zeta - 1.0).abs() < 1.0e-4 {
+            let decay = (-wn * t).exp();
+            1.0 - decay * (1.0 + wn * t)
+        } else {
+            let root = (zeta * zeta - 1.0).sqrt();
+            let r1 = -wn * (zeta - root);
+            let r2 = -wn * (zeta + root);
+            let denom = r2 - r1;
+            if denom.abs() < f32::EPSILON {
+                return 1.0;
+            }
+            1.0 - (r2 * (r1 * t).exp() - r1 * (r2 * t).exp()) / denom
+        }
+    }
+
+    /// 收敛到 `threshold`（0.1% 是常用的「停下来」判定）所需毫秒数。
+    pub fn settle_ms(self, threshold: f32) -> f32 {
+        let wn = self.natural_frequency();
+        let zeta = self.damping_ratio;
+        if wn <= 0.0 {
+            return 0.0;
+        }
+        let thr = threshold.clamp(1.0e-6, 0.5);
+        let seconds = if zeta < 1.0 {
+            let wd = (1.0 - zeta * zeta).sqrt().max(1.0e-4);
+            -(thr * wd).ln() / (zeta * wn)
+        } else if (zeta - 1.0).abs() < 1.0e-4 {
+            -(thr).ln() / wn
+        } else {
+            let root = (zeta * zeta - 1.0).sqrt();
+            let slow = wn * (zeta - root);
+            -(thr).ln() / slow
+        };
+        (seconds * 1000.0).max(0.0)
+    }
+}
+
+/// 动效方案（Expressive 把弹簧打包成 standard / expressive **两套**，不是一组）。
+///
+/// - [`MotionSchemeKind::Standard`]：保守、几乎不弹（spatial ζ=0.9）；
+/// - [`MotionSchemeKind::Expressive`]：D26 的视觉基线，回弹明显（spatial ζ=0.6~0.8）。
+///
+/// `effects`（透明度/颜色类）在两套方案里数值相同——效应类不该有可见回弹。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum MotionSchemeKind {
+    /// 标准方案（保守）。
+    Standard,
+    /// Expressive 方案（本项目默认）。
+    Expressive,
+}
+
+/// 弹簧类别：空间类管**位移/尺寸**，效应类管**颜色/透明度**。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SpringCategory {
+    /// 位移/尺寸（会产生可见回弹）。
+    Spatial,
+    /// 颜色/透明度（不允许过冲）。
+    Effects,
+}
+
+/// 弹簧速度档。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SpringSpeed {
+    /// 快速：hover/press、小元素。
+    Fast,
+    /// 默认：面板、卡片、按下形变。
+    Default,
+    /// 慢速：大位移（>120px 的面板/抽屉）。
+    Slow,
+}
+
+/// 二维表查询：`方案 × 类别 × 速度 → 弹簧`（A 级：`StandardMotionTokens` 与
+/// `ExpressiveMotionTokens`，经 `MotionScheme.standard()/expressive()` 组装）。
+pub const fn spring(
+    scheme: MotionSchemeKind,
+    category: SpringCategory,
+    speed: SpringSpeed,
+) -> Spring {
+    use MotionSchemeKind::{Expressive, Standard};
+    use SpringCategory::{Effects, Spatial};
+    use SpringSpeed::{Default, Fast, Slow};
+    match (scheme, category, speed) {
+        (Standard, Spatial, Fast) => Spring::from_ratio(1400.0, 0.9, 1.0),
+        (Standard, Spatial, Default) => Spring::from_ratio(700.0, 0.9, 1.0),
+        (Standard, Spatial, Slow) => Spring::from_ratio(300.0, 0.9, 1.0),
+        (Expressive, Spatial, Fast) => Spring::from_ratio(800.0, 0.6, 1.0),
+        (Expressive, Spatial, Default) => Spring::from_ratio(380.0, 0.8, 1.0),
+        (Expressive, Spatial, Slow) => Spring::from_ratio(200.0, 0.8, 1.0),
+        // effects 两套同值：ζ=1.0（临界阻尼，不过冲）。
+        (_, Effects, Fast) => Spring::from_ratio(3800.0, 1.0, 1.0),
+        (_, Effects, Default) => Spring::from_ratio(1600.0, 1.0, 1.0),
+        (_, Effects, Slow) => Spring::from_ratio(800.0, 1.0, 1.0),
+    }
+}
+
+/// 标准方案 · 空间 · 快速。
+pub const SPRING_STANDARD_SPATIAL_FAST: Spring = spring(
+    MotionSchemeKind::Standard,
+    SpringCategory::Spatial,
+    SpringSpeed::Fast,
+);
+/// 标准方案 · 空间 · 默认。
+pub const SPRING_STANDARD_SPATIAL_DEFAULT: Spring = spring(
+    MotionSchemeKind::Standard,
+    SpringCategory::Spatial,
+    SpringSpeed::Default,
+);
+/// 标准方案 · 空间 · 慢速。
+pub const SPRING_STANDARD_SPATIAL_SLOW: Spring = spring(
+    MotionSchemeKind::Standard,
+    SpringCategory::Spatial,
+    SpringSpeed::Slow,
+);
+/// Expressive 方案 · 空间 · 快速（D26 基线的默认选择）。
+pub const SPRING_EXPRESSIVE_SPATIAL_FAST: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Spatial,
+    SpringSpeed::Fast,
+);
+/// Expressive 方案 · 空间 · 默认：面板、卡片、按下形变。
+pub const SPRING_EXPRESSIVE_SPATIAL_DEFAULT: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Spatial,
+    SpringSpeed::Default,
+);
+/// Expressive 方案 · 空间 · 慢速：大位移（>120px）。
+pub const SPRING_EXPRESSIVE_SPATIAL_SLOW: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Spatial,
+    SpringSpeed::Slow,
+);
+/// 效应类 · 快速（两套方案同值）：hover/press 颜色。
+pub const SPRING_EFFECTS_FAST: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Effects,
+    SpringSpeed::Fast,
+);
+/// 效应类 · 默认（两套方案同值）。
+pub const SPRING_EFFECTS_DEFAULT: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Effects,
+    SpringSpeed::Default,
+);
+/// 效应类 · 慢速（两套方案同值）。
+pub const SPRING_EFFECTS_SLOW: Spring = spring(
+    MotionSchemeKind::Expressive,
+    SpringCategory::Effects,
+    SpringSpeed::Slow,
+);
+
+/// 动效时长的全局缩放（用户「减少动效」/CPU 路径关动画时用）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct MotionScale {
+    factor: f32,
+}
+
+impl MotionScale {
+    /// 标准（1.0）。
+    pub const STANDARD: MotionScale = MotionScale { factor: 1.0 };
+    /// 关闭动效（时长归零；适配层应直接落终态）。
+    pub const NONE: MotionScale = MotionScale { factor: 0.0 };
+    /// 半速（弱动效机器/低帧率兜底）。
+    pub const HALF: MotionScale = MotionScale { factor: 0.5 };
+
+    /// 自定义缩放（夹取到 0.0..=1.0；不放大，避免慢到不可用）。
+    pub fn new(factor: f32) -> Self {
+        Self {
+            factor: factor.clamp(0.0, 1.0),
+        }
+    }
+
+    /// 缩放系数。
+    pub fn factor(self) -> f32 {
+        self.factor
+    }
+
+    /// 是否完全关闭（适配层据此跳过动画）。
+    pub fn is_off(self) -> bool {
+        self.factor <= 0.0
+    }
+
+    /// 把某一档时长换算成实际毫秒。
+    pub fn ms(self, token: super::DurationToken) -> f32 {
+        token.ms() as f32 * self.factor
+    }
+
+    /// 把弹簧的收敛时间换算成实际毫秒。
+    pub fn spring_ms(self, spring: Spring) -> f32 {
+        spring.settle_ms(0.001) * self.factor
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::motion::DurationToken;
+
+    const PRESETS: [Spring; 9] = [
+        SPRING_STANDARD_SPATIAL_FAST,
+        SPRING_STANDARD_SPATIAL_DEFAULT,
+        SPRING_STANDARD_SPATIAL_SLOW,
+        SPRING_EXPRESSIVE_SPATIAL_FAST,
+        SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+        SPRING_EXPRESSIVE_SPATIAL_SLOW,
+        SPRING_EFFECTS_FAST,
+        SPRING_EFFECTS_DEFAULT,
+        SPRING_EFFECTS_SLOW,
+    ];
+
+    #[test]
+    fn every_cell_of_the_two_dimensional_table_resolves() {
+        for scheme in [MotionSchemeKind::Standard, MotionSchemeKind::Expressive] {
+            for category in [SpringCategory::Spatial, SpringCategory::Effects] {
+                for speed in [SpringSpeed::Fast, SpringSpeed::Default, SpringSpeed::Slow] {
+                    let spring = spring(scheme, category, speed);
+                    assert!(spring.stiffness > 0.0);
+                    assert!(spring.damping_ratio > 0.0);
+                }
+            }
+        }
+        // effects 两套方案同值（效应类不该有可见回弹差异）。
+        for speed in [SpringSpeed::Fast, SpringSpeed::Default, SpringSpeed::Slow] {
+            assert_eq!(
+                spring(MotionSchemeKind::Standard, SpringCategory::Effects, speed),
+                spring(MotionSchemeKind::Expressive, SpringCategory::Effects, speed)
+            );
+        }
+        // expressive 的空间类更弹（阻尼比更低）。
+        for speed in [SpringSpeed::Fast, SpringSpeed::Default, SpringSpeed::Slow] {
+            assert!(
+                spring(MotionSchemeKind::Expressive, SpringCategory::Spatial, speed).damping_ratio
+                    < spring(MotionSchemeKind::Standard, SpringCategory::Spatial, speed)
+                        .damping_ratio
+            );
+        }
+    }
+
+    #[test]
+    fn spring_presets_behave() {
+        for spring in PRESETS {
+            assert_eq!(spring.sample(0.0), 0.0);
+            let settle = spring.settle_ms(0.001);
+            assert!(
+                (60.0..1500.0).contains(&settle),
+                "收敛时间 {settle}ms 不合理（k={} ζ={}）",
+                spring.stiffness,
+                spring.damping_ratio
+            );
+            let end = spring.sample(settle);
+            assert!((end - 1.0).abs() < 0.01, "收敛后应回到 1.0，实测 {end}");
+        }
+    }
+
+    #[test]
+    fn effects_presets_are_critically_damped_and_never_overshoot() {
+        for spring in [
+            SPRING_EFFECTS_FAST,
+            SPRING_EFFECTS_DEFAULT,
+            SPRING_EFFECTS_SLOW,
+        ] {
+            assert!((spring.damping_ratio - 1.0).abs() < 1.0e-6);
+            for step in 1..=60 {
+                let v = spring.sample(step as f32 * 5.0);
+                assert!(v <= 1.0 + 1.0e-3, "效应类弹簧不应过冲：{v}");
+            }
+        }
+    }
+
+    #[test]
+    fn spatial_presets_overdamp_into_settle_without_wild_overshoot() {
+        for spring in [
+            SPRING_EXPRESSIVE_SPATIAL_FAST,
+            SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+            SPRING_EXPRESSIVE_SPATIAL_SLOW,
+        ] {
+            assert!(
+                spring.damping_ratio < 1.0,
+                "空间类弹簧欠阻尼（允许轻微过冲）"
+            );
+            let mut peak: f32 = 0.0;
+            for step in 1..=200 {
+                peak = peak.max(spring.sample(step as f32 * 2.0));
+            }
+            assert!(peak < 1.15, "过冲 {peak} 太大");
+        }
+    }
+
+    #[test]
+    fn critically_damped_spring_does_not_overshoot() {
+        let wn = SPRING_EXPRESSIVE_SPATIAL_DEFAULT.natural_frequency();
+        let critical = Spring::from_ratio(wn * wn, 1.0, 1.0);
+        for step in 1..=40 {
+            let v = critical.sample(step as f32 * 5.0);
+            assert!(v <= 1.0 + 1.0e-3, "临界阻尼不应过冲：{v}");
+        }
+    }
+
+    #[test]
+    fn overdamped_spring_converges_slowly_without_overshoot() {
+        let wn = SPRING_EXPRESSIVE_SPATIAL_DEFAULT.natural_frequency();
+        let over = Spring::from_ratio(wn * wn, 2.0, 1.0);
+        let settle = over.settle_ms(0.001);
+        assert!((over.sample(settle) - 1.0).abs() < 0.01);
+        for step in 1..=40 {
+            assert!(over.sample(step as f32 * 10.0) <= 1.0 + 1.0e-3);
+        }
+    }
+
+    #[test]
+    fn damping_coefficient_matches_ratio() {
+        let spring = SPRING_EXPRESSIVE_SPATIAL_DEFAULT;
+        let c = spring.damping_coefficient();
+        let zeta = c / (2.0 * (spring.stiffness * spring.mass).sqrt());
+        assert!((zeta - spring.damping_ratio).abs() < 1.0e-5);
+    }
+
+    #[test]
+    fn motion_scale_scales_or_kills_duration() {
+        assert_eq!(MotionScale::STANDARD.ms(DurationToken::Medium2), 300.0);
+        assert_eq!(MotionScale::HALF.ms(DurationToken::Medium2), 150.0);
+        assert_eq!(MotionScale::NONE.ms(DurationToken::Medium2), 0.0);
+        assert!(MotionScale::NONE.is_off());
+        assert_eq!(MotionScale::new(5.0).factor(), 1.0);
+        assert_eq!(MotionScale::new(-1.0).factor(), 0.0);
+        assert!(MotionScale::STANDARD.spring_ms(SPRING_EXPRESSIVE_SPATIAL_DEFAULT) > 0.0);
+    }
+}

crates/design/src/shape.rs

@@ -0,0 +1,302 @@
+//! M3 Expressive 形状刻度 + shape morph 数据。
+//!
+//! 形状是「唯一真源」的一部分：组件不许写裸半径（`border_radius(8)`），一律引用
+//! [`ShapeScale`]；需要动起来的（按下、选中、展开）用 [`ShapeMorph`] 的 from→to 数据。
+//!
+//! ## 圆角分两层（D32）
+//!
+//! 官方实现与官方刻度表并不总一致：Checkbox 的圆角是 **2dp**，但 `ShapeScale` 的刻度是
+//! `{0,4,8,12,16,20,28,32,48,full}`——2 不在里面。D32 的判决是**分层**而不是放宽判据：
+//!
+//! - **容器级**（卡片、弹窗、抽屉、按钮、面板、输入框外壳）只许用 [`ShapeScale`] 的刻度值；
+//! - **微控件级**（≤24dp 的 Checkbox 等）用 [`ComponentRadius`] 的白名单值。
+//!
+//! 一个元素该查哪一层由 [`radius_layer_for`] 判定（按尺寸，唯一入口）；微控件层取值走
+//! [`ComponentRadius::radius_px`]，**尺寸超界时返回 `None`**——这不是文档约定，是签名保证。
+
+use crate::motion::Spring;
+
+/// M3 形状刻度（含 Expressive 新增档）。
+///
+/// 基础档（M3）：none 0 / extra-small 4 / small 8 / medium 12 / large 16 / extra-large 28 / full。
+/// Expressive 新增档：`large-increased` 20 / `extra-large-increased` 32 / `extra-extra-large` 48。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ShapeScale {
+    /// 直角（0dp）：仅用于贴边容器/分隔。
+    None,
+    /// 4dp：小控件（chip、小徽标）。
+    ExtraSmall,
+    /// 8dp：控件（按钮、输入框、菜单项）。
+    Small,
+    /// 12dp：卡片、列表容器（Expressive 里卡片默认升到这一档）。
+    Medium,
+    /// 16dp：大卡片、面板。
+    Large,
+    /// 20dp（Expressive）：按下/选中时的「胀开」档。
+    LargeIncreased,
+    /// 28dp：浮层、对话框。
+    ExtraLarge,
+    /// 32dp（Expressive）：大浮层、FAB 展开态。
+    ExtraLargeIncreased,
+    /// 48dp（Expressive）：超大容器、模态全屏卡。
+    ExtraExtraLarge,
+    /// 药丸/圆：按边长取半径一半（导航指示条、头像、switch 轨道）。
+    Full,
+}
+
+impl ShapeScale {
+    /// 半径（dp；[`ShapeScale::Full`] 返回 `f32::INFINITY`，由 [`ShapeScale::radius_px`] 折算）。
+    pub const fn dp(self) -> f32 {
+        match self {
+            ShapeScale::None => 0.0,
+            ShapeScale::ExtraSmall => 4.0,
+            ShapeScale::Small => 8.0,
+            ShapeScale::Medium => 12.0,
+            ShapeScale::Large => 16.0,
+            ShapeScale::LargeIncreased => 20.0,
+            ShapeScale::ExtraLarge => 28.0,
+            ShapeScale::ExtraLargeIncreased => 32.0,
+            ShapeScale::ExtraExtraLarge => 48.0,
+            ShapeScale::Full => f32::INFINITY,
+        }
+    }
+
+    /// 实际渲染半径：`Full` 取边长一半，其余不超过边长一半（避免方角变圆角溢出）。
+    pub fn radius_px(self, size_px: f32) -> f32 {
+        let half = size_px.max(0.0) / 2.0;
+        if self == ShapeScale::Full {
+            half
+        } else {
+            self.dp().min(half)
+        }
+    }
+
+    /// 是否是 Expressive 才有的档位（基础 M3 没有）。
+    pub const fn is_expressive(self) -> bool {
+        matches!(
+            self,
+            ShapeScale::LargeIncreased
+                | ShapeScale::ExtraLargeIncreased
+                | ShapeScale::ExtraExtraLarge
+        )
+    }
+
+    /// 在形状阶梯上的序号（0 = None，9 = Full），用于断言形变方向是「胀开」而不是「收紧」。
+    pub const fn rank(self) -> u8 {
+        match self {
+            ShapeScale::None => 0,
+            ShapeScale::ExtraSmall => 1,
+            ShapeScale::Small => 2,
+            ShapeScale::Medium => 3,
+            ShapeScale::Large => 4,
+            ShapeScale::LargeIncreased => 5,
+            ShapeScale::ExtraLarge => 6,
+            ShapeScale::ExtraLargeIncreased => 7,
+            ShapeScale::ExtraExtraLarge => 8,
+            ShapeScale::Full => 9,
+        }
+    }
+}
+
+/// 微控件（≤24dp）的尺寸上限（dp）。
+///
+/// 超过这条线的元素属**容器级**，圆角必须查 [`ShapeScale`] 的严格刻度；[`ComponentRadius`]
+/// 只在这条线以内有效——由 [`ComponentRadius::radius_px`] 在运行期拦住（传大尺寸拿不到微半径）。
+/// 24 这个门槛不是官方数字，是 D32 给「微控件」划的界（Checkbox 20、指示点、徽标都在以内）。
+pub const MICRO_CONTROL_MAX_SIZE: f32 = 24.0;
+
+/// 微控件圆角（D32 第二层）：**来源官方组件实现，不是 [`ShapeScale`] 的成员**。
+///
+/// 为什么要有这一层：官方 Checkbox 的圆角是 **2dp**（`Checkbox.kt:738 RadiusSize = 2.dp`，
+/// `CheckboxTokens.ContainerShape = RoundedCornerShape(2)`），而 M3 形状刻度只有
+/// `{0,4,8,12,16,20,28,32,48,full}`。把 2 塞进刻度会废掉「无任意圆角」这条守门（D30 rubric K1），
+/// 不收又只能在组件里抄 `2.0` 字面量。D32 的判决是**分层**，不是放宽：
+///
+/// | 层 | 管什么 | 取值 |
+/// |---|---|---|
+/// | [`ShapeScale`] | 容器级：卡片/弹窗/抽屉/按钮/面板/输入框外壳 | 严格刻度，不许自造 |
+/// | `ComponentRadius` | 微控件级：Checkbox 等 ≤24dp 的元素 | 白名单，当前只有 [`ComponentRadius::Micro`] |
+///
+/// 用法：先 [`radius_layer_for`] 判层，微控件再 `radius_px(size)`。**返回 `None` 说明尺寸超界，
+/// 必须改查 [`ShapeScale`]**，不许把微半径硬套到容器上。
+///
+/// 公开的**唯一取值口是 [`ComponentRadius::radius_px`]**（带尺寸闸）：本类型的 `dp()` 是
+/// `pub(crate)`，故意不对外开放——否则任何调用方都能无条件拿到 `2.0`，「只许 ≤24dp」就成了
+/// 自觉而不是约束（D32 的原意是拦住，不是提醒）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ComponentRadius {
+    /// 2dp：官方 Checkbox 容器圆角。
+    Micro,
+}
+
+impl ComponentRadius {
+    /// 白名单里的全部微半径（D32 当前只有一项；加值必须先在 `design-令牌约定` 登记）。
+    ///
+    /// 枚举得出的只是**变体**（`Micro` 这个名字），拿不到数值——取值必须走 [`Self::radius_px`]。
+    pub const ALL: [ComponentRadius; 1] = [ComponentRadius::Micro];
+
+    /// 半径（dp）。**`pub(crate)`：crate 内推导与自己用，不对外开放。**
+    ///
+    /// 对任何尺寸都返回同一个数，所以它天然绕开 D32 的尺寸闸；对外只留
+    /// [`Self::radius_px`]（`Option<f32>`，>24dp 返回 `None`）。
+    pub(crate) const fn dp(self) -> f32 {
+        match self {
+            ComponentRadius::Micro => 2.0,
+        }
+    }
+
+    /// 微控件的实际半径：尺寸超过 [`MICRO_CONTROL_MAX_SIZE`] 时返回 **`None`**。
+    ///
+    /// 这是 D32 里「能编译期拦住就别靠自觉」的落点——文档约定拦不住，签名拦得住：
+    /// 拿到 `None` 的调用点没法「顺手用一下 2dp」，只能改查 [`ShapeScale`]。
+    /// 另外半径不超过边长一半（2dp 半径放到更小的元素上会溢成圆）。
+    pub fn radius_px(self, size_px: f32) -> Option<f32> {
+        if size_px > 0.0 && size_px <= MICRO_CONTROL_MAX_SIZE {
+            Some(self.dp().min(size_px / 2.0))
+        } else {
+            None
+        }
+    }
+}
+
+/// 一个元素的圆角该查哪一层（[`radius_layer_for`] 的返回）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum RadiusLayer {
+    /// 容器级：查 [`ShapeScale`] 的严格刻度。
+    Scale,
+    /// 微控件级（≤24dp）：查 [`ComponentRadius`] 的白名单。
+    Component,
+}
+
+/// 纯函数：按元素尺寸判定圆角该查哪一层。
+///
+/// 「某尺寸的元素该查哪一个」是 D32 里唯一需要判断的地方，所以只留这一个入口——
+/// 组件层不许自己写 `if size <= 24.0`，那等于把阈值抄了第二份。
+pub fn radius_layer_for(size_px: f32) -> RadiusLayer {
+    if size_px > 0.0 && size_px <= MICRO_CONTROL_MAX_SIZE {
+        RadiusLayer::Component
+    } else {
+        RadiusLayer::Scale
+    }
+}
+
+/// 一次形状形变（Expressive 的「按下胀开」「展开成药丸」等）。
+///
+/// 数据形态是纯的：起止档位 + 弹簧参数。适配层负责跑时钟，`progress` 由弹簧/缓动给出。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct ShapeMorph {
+    /// 静息档位。
+    pub from: ShapeScale,
+    /// 目标档位。
+    pub to: ShapeScale,
+    /// 驱动这次形变的弹簧。
+    pub spring: Spring,
+}
+
+impl ShapeMorph {
+    /// 恒定弹簧的形变。
+    pub const fn new(from: ShapeScale, to: ShapeScale, spring: Spring) -> Self {
+        Self { from, to, spring }
+    }
+
+    /// 在 `progress`（0..1，已含缓动）处的半径。`Full` 端点按 `size_px` 折算。
+    pub fn radius_px(&self, size_px: f32, progress: f32) -> f32 {
+        let t = progress.clamp(0.0, 1.0);
+        let a = self.from.radius_px(size_px);
+        let b = self.to.radius_px(size_px);
+        a + (b - a) * t
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::motion::SPRING_EXPRESSIVE_SPATIAL_DEFAULT;
+
+    #[test]
+    fn scale_ladder_is_monotone() {
+        let ladder = [
+            ShapeScale::None,
+            ShapeScale::ExtraSmall,
+            ShapeScale::Small,
+            ShapeScale::Medium,
+            ShapeScale::Large,
+            ShapeScale::LargeIncreased,
+            ShapeScale::ExtraLarge,
+            ShapeScale::ExtraLargeIncreased,
+            ShapeScale::ExtraExtraLarge,
+        ];
+        for pair in ladder.windows(2) {
+            assert!(
+                pair[0].dp() < pair[1].dp(),
+                "{:?} 应小于 {:?}",
+                pair[0],
+                pair[1]
+            );
+        }
+    }
+
+    #[test]
+    fn full_is_half_of_edge_and_clamped() {
+        assert_eq!(ShapeScale::Full.radius_px(48.0), 24.0);
+        assert_eq!(ShapeScale::ExtraLarge.radius_px(20.0), 10.0);
+        assert_eq!(ShapeScale::ExtraLarge.radius_px(200.0), 28.0);
+        assert_eq!(ShapeScale::None.radius_px(200.0), 0.0);
+    }
+
+    #[test]
+    fn morph_hits_both_endpoints() {
+        let morph = ShapeMorph::new(
+            ShapeScale::Small,
+            ShapeScale::LargeIncreased,
+            SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+        );
+        assert_eq!(morph.radius_px(200.0, 0.0), 8.0);
+        assert_eq!(morph.radius_px(200.0, 1.0), 20.0);
+        assert_eq!(morph.radius_px(200.0, 0.5), 14.0);
+        // 越界 progress 夹取，不产生负半径/超大半径。
+        assert_eq!(morph.radius_px(200.0, -2.0), 8.0);
+        assert_eq!(morph.radius_px(200.0, 3.0), 20.0);
+    }
+
+    #[test]
+    fn component_radius_is_whitelisted_and_refuses_containers() {
+        // D32：微半径白名单当前只有 2dp，且永远不是 ShapeScale 的成员。
+        assert_eq!(ComponentRadius::ALL.len(), 1);
+        assert_eq!(ComponentRadius::Micro.dp(), 2.0);
+        for scale in [
+            ShapeScale::None,
+            ShapeScale::ExtraSmall,
+            ShapeScale::Small,
+            ShapeScale::Medium,
+            ShapeScale::Large,
+            ShapeScale::LargeIncreased,
+            ShapeScale::ExtraLarge,
+            ShapeScale::ExtraLargeIncreased,
+            ShapeScale::ExtraExtraLarge,
+        ] {
+            assert_ne!(scale.dp(), 2.0, "{scale:?} 不该等于微半径（2 不在刻度里）");
+        }
+
+        // 20×20 的 checkbox 拿 2dp；超 24 的元素必须拿不到。
+        assert_eq!(ComponentRadius::Micro.radius_px(20.0), Some(2.0));
+        assert_eq!(ComponentRadius::Micro.radius_px(24.0), Some(2.0));
+        assert_eq!(ComponentRadius::Micro.radius_px(24.5), None);
+        assert_eq!(ComponentRadius::Micro.radius_px(200.0), None);
+        assert_eq!(ComponentRadius::Micro.radius_px(0.0), None);
+        // 半径不超过边长一半。
+        assert_eq!(ComponentRadius::Micro.radius_px(2.0), Some(1.0));
+    }
+
+    #[test]
+    fn radius_layer_follows_the_size_threshold() {
+        assert_eq!(radius_layer_for(20.0), RadiusLayer::Component);
+        assert_eq!(
+            radius_layer_for(MICRO_CONTROL_MAX_SIZE),
+            RadiusLayer::Component
+        );
+        assert_eq!(radius_layer_for(24.5), RadiusLayer::Scale);
+        assert_eq!(radius_layer_for(320.0), RadiusLayer::Scale);
+        assert_eq!(radius_layer_for(0.0), RadiusLayer::Scale);
+    }
+}

crates/design/src/spacing.rs

@@ -0,0 +1,290 @@
+//! 形状 / 高程 / 动效之外的「尺子」：4px 栅格、骨架尺寸、一像素线。
+//!
+//! 源流有两条：`DevDocs/ops/slint-reference/crates/app/ui/theme/metrics.slint`（M52 定稿的骨架节奏），
+//! 以及 `ui-integration-contract.md` §3「间距只允许 4/8/12/16/24/32」。M3 同样用 4dp 栅格，
+//! 所以这层**不用改口径**，只是把值搬进唯一真源。
+//!
+//! ## 职责边界：`LayoutMetrics` vs `ComponentMetrics`（M69 / G10）
+//!
+//! | 结构 | 管什么 | 例子 |
+//! |---|---|---|
+//! | [`LayoutMetrics`] | **窗口骨架与布局节奏**：标题栏/页头/行的节奏、dock 宽度（导航、AI 面板）、命中区 | [`LayoutMetrics::nav_drawer_width`] / [`LayoutMetrics::search_bar_height`] / `touch_target` |
+//! | `component_map::ComponentMetrics` | **单个控件内部几何**：外框尺寸、微圆角、描边/环线宽、状态层直径、内点、图标偏移 | checkbox 20×20 + 描边 2 + 状态层 Ø40 |
+//! | [`stroke::HAIRLINE`] | **一像素线**的唯一真源：分隔线厚度、容器描边、聚焦指示 | [`LayoutMetrics::divider_thickness`] |
+//!
+//! 判据：一个值若随窗口/列宽变化、或决定一块面板占多宽，归 LM；若它只在某个控件自己的方框
+//! 内起作用（画进去的那几个像素），归 CM。**同一个值不许两边各写一份**。
+
+/// 一像素线（G12）：全站 1px 线的**唯一真源**。
+///
+/// 为什么要单独开一个命名空间：`1.0` 在项目里同时承担三种语义——分隔线厚度、容器描边宽度、
+/// 聚焦指示描边宽度。各自抄字面量就会漂成 1.0 / 1.5 / 2.0 混排（M66 的 G12 正是这么来的）。
+/// 从这里取，语义和数值只有一个落点。
+///
+/// iced 侧怎么落地（适配层照此抄，别再自己定 `STROKE_PX`）：
+/// - **容器描边**：`Border { width: unlucky_design::stroke::HAIRLINE, .. }`（卡片/输入框/chip/菜单）；
+/// - **分隔线**：[`LayoutMetrics::divider_thickness`]（数值就是 [`stroke::HAIRLINE`]）——
+///   横向分隔线是容器高度、纵向是宽度，都取它；
+/// - **聚焦环**：内描边与外描边**都用**它（M3 的聚焦指示是 1dp，做成 2dp 就是加粗）；
+/// - **不用于**：elevation 的 blur / offset（那是 [`crate::elevation`] 的量）、
+///   图标描边（图标走 SVG 的 viewBox 单位，见 [`crate::icons::stroke_width_for`]）。
+pub mod stroke {
+    /// 一像素线宽度（逻辑 px @100% DPI = 1dp；DividerTokens.Thickness）。
+    pub const HAIRLINE: f32 = 1.0;
+}
+
+/// 栅格基数（dp）。
+pub const GRID: f32 = 4.0;
+
+/// 间距档位（M3/M2 通用 4px 栅格）。禁止 6/10/14 这类非整倍数值。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Space {
+    /// 4dp：图标与文字之间。
+    X1,
+    /// 8dp：控件内边距、行内元素间距。
+    X2,
+    /// 12dp：控件间距。
+    X3,
+    /// 16dp：区块内行距、卡片内边距下限。
+    X4,
+    /// 24dp：区块间距、页面内边距。
+    X6,
+    /// 32dp：页级大留白。
+    X8,
+}
+
+impl Space {
+    /// 间距值（dp）。
+    pub const fn dp(self) -> f32 {
+        match self {
+            Space::X1 => 4.0,
+            Space::X2 => 8.0,
+            Space::X3 => 12.0,
+            Space::X4 => 16.0,
+            Space::X6 => 24.0,
+            Space::X8 => 32.0,
+        }
+    }
+
+    /// 全部档位，由小到大。
+    pub const ALL: [Space; 6] = [
+        Space::X1,
+        Space::X2,
+        Space::X3,
+        Space::X4,
+        Space::X6,
+        Space::X8,
+    ];
+}
+
+/// 把任意数值对齐到 4px 栅格（最近档）。
+pub fn snap_to_grid(value: f32) -> f32 {
+    (value / GRID).round() * GRID
+}
+
+/// 骨架尺寸：窗口结构（标题栏、导航、页头、行高）的单一来源。
+///
+/// 这些值不是 M3 规范值（M3 只规定组件内部节奏），而是本启动器的**布局契约**，
+/// 由页面/组件两条线共同消费——任何页面自己写 `56px` 都是重复定义。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct LayoutMetrics {
+    /// 标题栏高度。
+    pub titlebar_height: f32,
+    /// 标题栏按钮宽度（关闭/最大化/最小化）。
+    pub titlebar_button_width: f32,
+    /// 展开态导航（drawer 形态）宽度。
+    ///
+    /// **G11 语义修正（M69 / D33）**：D16「左侧固定、允许折叠」落地为**同一个常驻容器**的两种
+    /// 宽度——展开 240（drawer）、折叠 88（rail）。旧字段 `nav_expanded_width = 88` 的名字与值
+    /// 相反（88 其实是 rail），已删除，**不留别名**：两个名字指同一个量等于把选择权还给组件层。
+    ///
+    /// 官方 `NavigationDrawerTokens.ContainerWidth = 360`、`MinimumDrawerWidth = 240`；
+    /// 本项目取官方下限 240——360 + AI 面板 320 = 680 = 1180 窗宽的 58%，内容区只剩 500 放不下两列卡片。
+    pub nav_drawer_width: f32,
+    /// 折叠态导航（rail 形态）宽度。
+    ///
+    /// 88 = 12b §5.1 对官方 rail 96 的登记偏离（−8）：指示器宽 88 − 2×16 = 56 仍成立，
+    /// 再窄就装不下 56 宽的选中指示器。
+    pub nav_rail_width: f32,
+    /// 搜索条高度（G11）。
+    ///
+    /// 官方 `SearchBarTokens.ContainerHeight = 56`。**不走 [`LayoutMetrics::control_height`]（40）**：
+    /// 搜索条是页级入口而不是密集行控件；56 也顺带 ≥ 命中下限 48。圆角由 `ShapeScale::Full`
+    /// 按边长折算（56 → 28，正好等于官方 `SearchBarCornerRadius`）。
+    pub search_bar_height: f32,
+    /// 分隔线厚度（G11 + G12）。
+    ///
+    /// 官方 `DividerTokens.Thickness = 1.0.dp`。值就是 [`stroke::HAIRLINE`]——**一像素线不受 4px
+    /// 栅格约束**，所以它不在栅格测试的表里（测试里显式豁免并写明原因）。
+    pub divider_thickness: f32,
+    /// 导航项高度。
+    pub nav_item_height: f32,
+    /// 导航项间距。
+    pub nav_item_gap: f32,
+    /// 单行页头高度。
+    pub page_header_height: f32,
+    /// 两行页头高度（日志页）。
+    pub page_header_tall_height: f32,
+    /// 运行中状态条高度。
+    pub running_strip_height: f32,
+    /// 列表行高（桌面密集列表；见模块文档的「触控目标」说明）。
+    pub row_height: f32,
+    /// 标准控件可见高度（按钮/输入框）。
+    pub control_height: f32,
+    /// 最小**命中**区域（M3 Expressive 的无障碍下限）。
+    pub touch_target: f32,
+    /// 卡片内边距。
+    pub card_padding: f32,
+    /// AI 面板宽度。
+    pub ai_panel_width: f32,
+}
+
+impl LayoutMetrics {
+    /// 桌面基线（1180×760 窗口）。
+    ///
+    /// **触控目标的换算依据**（reviewer P3-1：不许和 `metrics.slint` 沉默地不一致）：
+    /// - 规范：M3 Expressive 要求可点目标 ≥**48dp**（无障碍下限，手机与桌面同标准）。
+    /// - 我们取 `touch_target = 48`（照规范），`control_height = 40`（**可见**高度）：
+    ///   两者差 8，正好由控件上下各 4px 的内边距补足，于是「看起来 40 高的按钮」有 48 的命中区。
+    /// - `row_height = 44` / `nav_item_height = 44` 是 M63 §R13 + §1.4 表定的桌面密集档
+    ///   （`metrics.slint` 的导航 56 是 Fluent 2 时代的旧节奏，D25 已终止）：可见高度 44，
+    ///   点击命中也按 `touch_target`（48）判定，不靠行高本身。
+    /// - `titlebar_height = 48` 取自 M63 §1.4 的 S2 面板表（旧值 40 是 Fluent 口径）。
+    pub const DESKTOP: Self = Self {
+        titlebar_height: 48.0,
+        titlebar_button_width: 46.0,
+        // G11 / D33：展开 = drawer 240，折叠 = rail 88（旧 `nav_expanded_width=88` /
+        // `nav_collapsed_width=48` 的名字与值相反，已删）。
+        nav_drawer_width: 240.0,
+        nav_rail_width: 88.0,
+        // G11：官方 SearchBarTokens.ContainerHeight = 56。
+        search_bar_height: 56.0,
+        // G11/G12：官方 DividerTokens.Thickness = 1.0dp → 一像素线的唯一真源。
+        divider_thickness: stroke::HAIRLINE,
+        nav_item_height: 44.0,
+        nav_item_gap: 4.0,
+        page_header_height: 56.0,
+        page_header_tall_height: 84.0,
+        running_strip_height: 32.0,
+        row_height: 44.0,
+        control_height: 40.0,
+        touch_target: 48.0,
+        card_padding: 20.0,
+        ai_panel_width: 320.0,
+    };
+}
+
+impl LayoutMetrics {
+    /// 页头是否两行（日志页），决定主区与 AI 面板分隔线对齐的高度。
+    pub fn header_height(&self, two_line: bool) -> f32 {
+        if two_line {
+            self.page_header_tall_height
+        } else {
+            self.page_header_height
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn every_space_is_on_the_grid() {
+        for space in Space::ALL {
+            assert_eq!(space.dp() % GRID, 0.0, "{space:?} 不在 4px 栅格上");
+        }
+    }
+
+    #[test]
+    fn layout_values_are_on_the_grid() {
+        let m = LayoutMetrics::DESKTOP;
+        // 受 4px 栅格约束的字段（间距/高度/宽度类）。
+        // `titlebar_button_width` 刻意不在表内：46 对齐 Windows 11 原生 caption 按钮宽度，
+        // 属 OS 惯例值，单列一条断言钉住，不让它静默漂移。
+        // `divider_thickness` 同理不在表内：它是**一像素线**（1 不是 4 的倍数），
+        // 归 `stroke::HAIRLINE` 那条规则管，下面单独断言。
+        for (name, value) in [
+            ("titlebar_height", m.titlebar_height),
+            ("nav_drawer_width", m.nav_drawer_width),
+            ("nav_rail_width", m.nav_rail_width),
+            ("search_bar_height", m.search_bar_height),
+            ("nav_item_height", m.nav_item_height),
+            ("nav_item_gap", m.nav_item_gap),
+            ("page_header_height", m.page_header_height),
+            ("page_header_tall_height", m.page_header_tall_height),
+            ("running_strip_height", m.running_strip_height),
+            ("row_height", m.row_height),
+            ("control_height", m.control_height),
+            ("touch_target", m.touch_target),
+            ("card_padding", m.card_padding),
+            ("ai_panel_width", m.ai_panel_width),
+        ] {
+            assert_eq!(value % GRID, 0.0, "{name} = {value} 不在 4px 栅格上");
+        }
+        assert_eq!(
+            m.titlebar_button_width, 46.0,
+            "标题栏按钮宽度应对齐 Win11 原生 caption"
+        );
+        // 一像素线的显式豁免（不是「忘了加进表」，是它本来就不受栅格约束）。
+        assert_eq!(m.divider_thickness, stroke::HAIRLINE);
+        assert_ne!(m.divider_thickness % GRID, 0.0);
+    }
+
+    #[test]
+    fn nav_widths_follow_the_two_form_decision() {
+        // D33：左侧导航是同一容器的两种宽度，展开（drawer）必须比折叠（rail）宽。
+        let m = LayoutMetrics::DESKTOP;
+        assert_eq!(m.nav_drawer_width, 240.0, "展开 drawer 取官方下限 240");
+        assert_eq!(m.nav_rail_width, 88.0, "折叠 rail 为 88（登记偏离官方 96）");
+        assert!(m.nav_rail_width < m.nav_drawer_width);
+        // rail 里的选中指示器 = 容器宽 − 2×16；88 − 32 = 56，再窄就装不下 56 宽指示器。
+        assert_eq!(m.nav_rail_width - Space::X4.dp() * 2.0, 56.0);
+        // 内容区下限：1180 窗宽 − drawer − AI 面板 仍 ≥600（够放两列卡片）。
+        assert!(1180.0 - m.nav_drawer_width - m.ai_panel_width >= 600.0);
+    }
+
+    #[test]
+    fn search_bar_height_is_a_page_level_entry() {
+        let m = LayoutMetrics::DESKTOP;
+        assert_eq!(m.search_bar_height, 56.0, "官方 ContainerHeight = 56");
+        assert!(
+            m.search_bar_height >= m.touch_target,
+            "页级入口必须 ≥ 命中下限"
+        );
+        // 圆角走 ShapeScale::Full，56 → 28，正好是官方 SearchBarCornerRadius。
+        assert_eq!(
+            crate::shape::ShapeScale::Full.radius_px(m.search_bar_height),
+            28.0
+        );
+    }
+
+    #[test]
+    fn touch_target_meets_the_expressive_48dp_minimum() {
+        let m = LayoutMetrics::DESKTOP;
+        // M3 Expressive 无障碍下限：可点目标 ≥48dp。
+        assert_eq!(m.touch_target, 48.0);
+        // 可见控件高 + 上下各 4px 内边距 = 命中区。
+        assert_eq!(m.control_height + 2.0 * Space::X1.dp(), m.touch_target);
+        // 密集行（M63 §1.4/R13 的桌面档）可见高度 44，命中仍按 touch_target。
+        assert_eq!(m.row_height, 44.0);
+        assert_eq!(m.nav_item_height, 44.0);
+        assert!(m.row_height <= m.touch_target);
+        // M63 §1.4 的 S2 面板表：标题栏 48。
+        assert_eq!(m.titlebar_height, 48.0);
+    }
+
+    #[test]
+    fn snap_rounds_to_nearest_grid_step() {
+        assert_eq!(snap_to_grid(5.0), 4.0);
+        assert_eq!(snap_to_grid(6.5), 8.0);
+        assert_eq!(snap_to_grid(0.0), 0.0);
+    }
+
+    #[test]
+    fn header_height_follows_line_count() {
+        let m = LayoutMetrics::DESKTOP;
+        assert_eq!(m.header_height(false), 56.0);
+        assert_eq!(m.header_height(true), 84.0);
+    }
+}

crates/design/src/typography/emphasized.rs

@@ -0,0 +1,88 @@
+//! 官方 M3 **Expressive** 强调排版表（15 档，A 级来源）。
+//!
+//! 来源：`androidx.compose.material3.tokens.TypeScaleTokens` v0_103 的
+//! `<Role>Emphasized{Size,LineHeight,Tracking,Weight}` 四元组。要点：
+//!
+//! - **字号与行高与 baseline 完全相同**（Expressive 的强调不改变排版高度）；
+//! - 只动**字重**与**字距**：display/headline/title-large/body-* → Medium(500)；
+//!   title-medium / title-small / label-* → Bold(700)（baseline 是 500）；
+//! - display-large 的字距从 −0.2 回 0；body-large 0.5 → 0.15；title-medium 0.2 → 0.15；
+//!   body-medium 0.2 → 0.25（唯一一个「强调后字距变大」的档）。
+
+use super::{style, FontFamily, TypeRole, TypeStyle, Weight};
+
+/// 取某档的官方强调样式。非 [`TypeRole`] 的每个变体都有值（15/15，无缺口）。
+pub(super) const fn style_of(role: TypeRole) -> TypeStyle {
+    match role {
+        TypeRole::DisplayLarge => style(57.0, 64.0, Weight::Medium, 0.0, FontFamily::Display),
+        TypeRole::DisplayMedium => style(45.0, 52.0, Weight::Medium, 0.0, FontFamily::Display),
+        TypeRole::DisplaySmall => style(36.0, 44.0, Weight::Medium, 0.0, FontFamily::Display),
+        TypeRole::HeadlineLarge => style(32.0, 40.0, Weight::Medium, 0.0, FontFamily::Display),
+        TypeRole::HeadlineMedium => style(28.0, 36.0, Weight::Medium, 0.0, FontFamily::Display),
+        TypeRole::HeadlineSmall => style(24.0, 32.0, Weight::Medium, 0.0, FontFamily::Display),
+        // TitleLarge 官方用 Brand 族（与 Display 同栈）。
+        TypeRole::TitleLarge => style(22.0, 28.0, Weight::Medium, 0.0, FontFamily::Display),
+        TypeRole::TitleMedium => style(16.0, 24.0, Weight::Bold, 0.15, FontFamily::Text),
+        TypeRole::TitleSmall => style(14.0, 20.0, Weight::Bold, 0.1, FontFamily::Text),
+        TypeRole::BodyLarge => style(16.0, 24.0, Weight::Medium, 0.15, FontFamily::Text),
+        TypeRole::BodyMedium => style(14.0, 20.0, Weight::Medium, 0.25, FontFamily::Text),
+        TypeRole::BodySmall => style(12.0, 16.0, Weight::Medium, 0.4, FontFamily::Text),
+        TypeRole::LabelLarge => style(14.0, 20.0, Weight::Bold, 0.1, FontFamily::Text),
+        TypeRole::LabelMedium => style(12.0, 16.0, Weight::Bold, 0.5, FontFamily::Text),
+        TypeRole::LabelSmall => style(11.0, 16.0, Weight::Bold, 0.5, FontFamily::Text),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn emphasized_keeps_size_and_line_height() {
+        for role in TypeRole::ALL {
+            let base = role.style();
+            let emph = style_of(role);
+            assert_eq!(
+                base.size_px,
+                emph.size_px,
+                "{} 强调档不该改字号",
+                role.name()
+            );
+            assert_eq!(
+                base.line_height_px,
+                emph.line_height_px,
+                "{} 强调档不该改行高",
+                role.name()
+            );
+        }
+    }
+
+    #[test]
+    fn emphasized_weights_follow_the_official_split() {
+        // 官方两档：正文/展示类 → Medium(500)；小标题与标签类 → Bold(700)。
+        for role in TypeRole::ALL {
+            let expect = match role {
+                TypeRole::TitleMedium
+                | TypeRole::TitleSmall
+                | TypeRole::LabelLarge
+                | TypeRole::LabelMedium
+                | TypeRole::LabelSmall => Weight::Bold,
+                _ => Weight::Medium,
+            };
+            assert_eq!(
+                style_of(role).weight,
+                expect,
+                "{} 强调档字重不对",
+                role.name()
+            );
+        }
+    }
+
+    #[test]
+    fn display_large_tracking_returns_to_zero() {
+        assert_eq!(TypeRole::DisplayLarge.style().letter_spacing_px, -0.2);
+        assert_eq!(TypeRole::DisplayLarge.emphasized().letter_spacing_px, 0.0);
+        assert_eq!(TypeRole::BodyLarge.style().letter_spacing_px, 0.5);
+        assert_eq!(TypeRole::BodyLarge.emphasized().letter_spacing_px, 0.15);
+    }
+}

crates/design/src/typography/fonts.rs

@@ -0,0 +1,304 @@
+//! 三平台字体族回退栈（Win10+ / macOS 12+ / Linux）+ **字重覆盖**模型。
+//!
+//! 只写族名，不写文件路径、不内嵌字体（D14 + D28）。每条栈的**最后一项必须是通用族名**，
+//! 否则干净安装的系统上会退化成豆腐块。
+//!
+//! ## 为什么要表达「这个族有哪几档字重」
+//!
+//! M3 Expressive 的强调档会要 **700**（title-medium/title-small/label-*）与 **500**
+//! （display/headline/body-*）。而中文字体的字重覆盖差别很大：
+//! **Windows 的 Microsoft YaHei UI 只有 400 / 700 两档**，没有 500；macOS 苹方到 600 就断了、
+//! 没有 700；只有 Linux 常见的 Noto Sans CJK / 思源黑体（可变字体）才 100~900 全覆盖。
+//!
+//! 所以栈项不是「一个族名」，而是 `(族名, 字重覆盖)`（[`FontFace`]），并且提供一个纯函数
+//! [`Platform::resolve_weight`] 说明「这一档字重最终落到哪个族、是原生还是降级」：
+//!
+//! | 结果 | 含义 |
+//! |---|---|
+//! | [`WeightMatch::Native`] | 该族有这一档（可变字体在区间内也算原生） |
+//! | [`WeightMatch::Nearest`] | 该族没有这一档，取最近的静态档（视觉上是「淡一点/粗一点」，不假） |
+//! | [`WeightMatch::Synthetic`] | 最近的档差 ≥2 级（如只有 400 却要 700）→ 引擎**合成加粗**，观感廉价 |
+//!
+//! **合成加粗是降级，不是正常路径**（用户令：不许拿合成加粗当「还原到位」）。
+//! iced/cosmic-text 侧机制：`Font { family, weight, .. }` 由 cosmic-text 按 (family, weight)
+//! 选面，同族缺档时选最近字重；glyphon 另可用 swash 的合成（fake bold）兜底。
+//! 中文缺档时的降级顺序：**① 换下一个有该档的族 → ② 用可变字体的 weight 轴 → ③ 最近静态档
+//! → ④ 最后才是合成加粗**（并且不要用 700 排长中文正文）。
+//!
+//! ## 待确认（D28 联动，不在本 mission 拍板）
+//!
+//! 将来从 CDN 下载中文字体时，「一个 Regular 文件」不够——至少要 400/500/700 三档子集，
+//! 或者一个可变字体（体积更大）。这个差异登记在这里，等 D28 的字体下载 mission 决定。
+
+#[cfg(test)]
+mod tests;
+
+/// 平台（决定字体族回退栈）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Platform {
+    /// Windows 10/11。
+    Windows,
+    /// macOS 12+。
+    MacOs,
+    /// Linux（X11/Wayland，桌面发行版）。
+    Linux,
+}
+
+/// 字重覆盖（一个族实际提供了哪些字重）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum WeightCoverage {
+    /// 可变字体：一个连续区间（weight 轴）。
+    Variable {
+        /// 最细一档。
+        min: u16,
+        /// 最粗一档。
+        max: u16,
+    },
+    /// 静态字体：离散字重表。
+    Static(&'static [u16]),
+}
+
+impl WeightCoverage {
+    /// 是否原生覆盖某档字重。
+    pub fn supports(&self, weight: u16) -> bool {
+        match self {
+            WeightCoverage::Variable { min, max } => (*min..=*max).contains(&weight),
+            WeightCoverage::Static(list) => list.contains(&weight),
+        }
+    }
+
+    /// 最近的可选字重（静态表取绝对值最近；可变字体夹取到区间内）。
+    pub fn nearest(&self, weight: u16) -> u16 {
+        match self {
+            WeightCoverage::Variable { min, max } => weight.clamp(*min, *max),
+            WeightCoverage::Static(list) => {
+                let mut best = list[0];
+                let mut best_delta = u16::MAX;
+                for candidate in *list {
+                    let delta = candidate.abs_diff(weight);
+                    if delta < best_delta {
+                        best = *candidate;
+                        best_delta = delta;
+                    }
+                }
+                best
+            }
+        }
+    }
+}
+
+/// 一条字体栈项：族名 + 字重覆盖。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct FontFace {
+    /// 族名（只写名字，不带路径/文件名）。
+    pub family: &'static str,
+    /// 该族提供的字重。
+    pub weights: WeightCoverage,
+}
+
+impl FontFace {
+    /// 构造。
+    pub const fn new(family: &'static str, weights: WeightCoverage) -> Self {
+        Self { family, weights }
+    }
+
+    /// 该族是否原生覆盖某档字重。
+    pub fn supports(&self, weight: crate::typography::Weight) -> bool {
+        self.weights.supports(weight.value())
+    }
+}
+
+/// 字重匹配的质量。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum WeightMatch {
+    /// 原生有这一档。
+    Native,
+    /// 同族最近档（差 <2 级）。
+    Nearest,
+    /// 差 ≥2 级，引擎只能合成加粗/减细（降级）。
+    Synthetic,
+}
+
+/// 字重解析结果：最终用哪个族、哪个字重、是原生还是降级。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct FontChoice {
+    /// 选中的族名。
+    pub family: &'static str,
+    /// 请求的字重。
+    pub requested: u16,
+    /// 实际可用的字重。
+    pub available: u16,
+    /// 匹配质量。
+    pub quality: WeightMatch,
+}
+
+impl FontChoice {
+    /// 是否走了合成加粗（降级路径）。
+    pub fn is_synthetic(&self) -> bool {
+        self.quality == WeightMatch::Synthetic
+    }
+}
+
+/// 字体族的用途分类（决定取哪条栈）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum FontFamily {
+    /// 大字号展示（display/headline/title-large）：光学尺寸更大。
+    Display,
+    /// 正文（title/body/label）。
+    Text,
+    /// 等宽（日志、代码、版本号）。
+    Mono,
+}
+
+// 字重覆盖来源等级：**B**（各平台字体规格/厂商文档；没有一份官方 token 文件能一次给全，
+// 所以按「常见安装」标定，并用测试钉死——改值要连带改测试与协作文档）。
+const W_VARIABLE_SEGOE: WeightCoverage = WeightCoverage::Variable { min: 300, max: 700 };
+const W_VARIABLE_SF: WeightCoverage = WeightCoverage::Variable { min: 100, max: 900 };
+const W_VARIABLE_NOTO: WeightCoverage = WeightCoverage::Variable { min: 100, max: 900 };
+const W_VARIABLE_CASCADIA: WeightCoverage = WeightCoverage::Variable { min: 200, max: 700 };
+const W_VARIABLE_JETBRAINS: WeightCoverage = WeightCoverage::Variable { min: 100, max: 800 };
+const W_STATIC_SEGOE: WeightCoverage = WeightCoverage::Static(&[300, 400, 600, 700]);
+const W_STATIC_YAHEI: WeightCoverage = WeightCoverage::Static(&[400, 700]);
+const W_STATIC_HELVETICA: WeightCoverage = WeightCoverage::Static(&[300, 400, 500, 700]);
+const W_STATIC_PINGFANG: WeightCoverage = WeightCoverage::Static(&[100, 200, 300, 400, 500, 600]);
+const W_STATIC_MENLO: WeightCoverage = WeightCoverage::Static(&[400, 700]);
+const W_STATIC_DEJAVU: WeightCoverage = WeightCoverage::Static(&[400, 700]);
+
+// 各平台字体栈（写成 const 数组，好让 `font_stack` 的 `const fn` 直接返回 `&'static [_]`）。
+const WIN_DISPLAY: [FontFace; 5] = [
+    FontFace::new("Segoe UI Variable Display", W_VARIABLE_SEGOE),
+    FontFace::new("Segoe UI", W_STATIC_SEGOE),
+    FontFace::new("Microsoft YaHei UI", W_STATIC_YAHEI),
+    FontFace::new("Microsoft YaHei", W_STATIC_YAHEI),
+    FontFace::new("sans-serif", W_VARIABLE_NOTO),
+];
+const WIN_TEXT: [FontFace; 5] = [
+    FontFace::new("Segoe UI Variable Text", W_VARIABLE_SEGOE),
+    FontFace::new("Segoe UI", W_STATIC_SEGOE),
+    FontFace::new("Microsoft YaHei UI", W_STATIC_YAHEI),
+    FontFace::new("Microsoft YaHei", W_STATIC_YAHEI),
+    FontFace::new("sans-serif", W_VARIABLE_NOTO),
+];
+const WIN_MONO: [FontFace; 4] = [
+    FontFace::new("Cascadia Mono", W_VARIABLE_CASCADIA),
+    FontFace::new("Consolas", W_STATIC_SEGOE),
+    FontFace::new("Courier New", W_STATIC_MENLO),
+    FontFace::new("monospace", W_STATIC_DEJAVU),
+];
+const MAC_DISPLAY: [FontFace; 4] = [
+    FontFace::new("SF Pro Display", W_VARIABLE_SF),
+    FontFace::new("Helvetica Neue", W_STATIC_HELVETICA),
+    FontFace::new("PingFang SC", W_STATIC_PINGFANG),
+    FontFace::new("sans-serif", W_VARIABLE_NOTO),
+];
+const MAC_TEXT: [FontFace; 4] = [
+    FontFace::new("SF Pro Text", W_VARIABLE_SF),
+    FontFace::new("Helvetica Neue", W_STATIC_HELVETICA),
+    FontFace::new("PingFang SC", W_STATIC_PINGFANG),
+    FontFace::new("sans-serif", W_VARIABLE_NOTO),
+];
+const MAC_MONO: [FontFace; 4] = [
+    FontFace::new("SF Mono", W_VARIABLE_SF),
+    FontFace::new("Menlo", W_STATIC_MENLO),
+    FontFace::new("Monaco", W_STATIC_MENLO),
+    FontFace::new("monospace", W_STATIC_DEJAVU),
+];
+const LINUX_SANS: [FontFace; 5] = [
+    FontFace::new("Roboto", W_VARIABLE_NOTO),
+    FontFace::new("Noto Sans", W_VARIABLE_NOTO),
+    FontFace::new("Noto Sans CJK SC", W_VARIABLE_NOTO),
+    FontFace::new("DejaVu Sans", W_STATIC_DEJAVU),
+    FontFace::new("sans-serif", W_VARIABLE_NOTO),
+];
+const LINUX_MONO: [FontFace; 4] = [
+    FontFace::new("JetBrains Mono", W_VARIABLE_JETBRAINS),
+    FontFace::new("Noto Sans Mono", W_VARIABLE_NOTO),
+    FontFace::new("DejaVu Sans Mono", W_STATIC_DEJAVU),
+    FontFace::new("monospace", W_STATIC_DEJAVU),
+];
+
+impl Platform {
+    /// 当前编译目标对应的平台（运行时用户覆盖请显式传 [`Platform`]）。
+    pub const fn current() -> Self {
+        if cfg!(target_os = "windows") {
+            Platform::Windows
+        } else if cfg!(target_os = "macos") {
+            Platform::MacOs
+        } else {
+            Platform::Linux
+        }
+    }
+
+    /// 稳定字符串名。
+    pub const fn name(self) -> &'static str {
+        match self {
+            Platform::Windows => "windows",
+            Platform::MacOs => "macos",
+            Platform::Linux => "linux",
+        }
+    }
+
+    /// 字体族回退栈（由首选到兜底，最后一项是通用族名）。
+    pub const fn font_stack(self, family: FontFamily) -> &'static [FontFace] {
+        match (self, family) {
+            // Win10 起 Segoe UI 一定在；Win11 有光学尺寸分离的 Variable 版。
+            (Platform::Windows, FontFamily::Display) => &WIN_DISPLAY,
+            (Platform::Windows, FontFamily::Text) => &WIN_TEXT,
+            (Platform::Windows, FontFamily::Mono) => &WIN_MONO,
+            // macOS 12+：SF Pro 分 Display/Text 光学尺寸；中文走苹方（只到 600）。
+            (Platform::MacOs, FontFamily::Display) => &MAC_DISPLAY,
+            (Platform::MacOs, FontFamily::Text) => &MAC_TEXT,
+            (Platform::MacOs, FontFamily::Mono) => &MAC_MONO,
+            // Linux：不假设发行版预装什么，Roboto/Noto 是最常见的两套（Display 与 Text 同栈）。
+            (Platform::Linux, FontFamily::Display | FontFamily::Text) => &LINUX_SANS,
+            (Platform::Linux, FontFamily::Mono) => &LINUX_MONO,
+        }
+    }
+
+    /// 该平台的**中文**兜底族（CJK 字形实际落到的那个）。
+    ///
+    /// 注意：栈里的 CJK 族只是「缺字形时的候选」，最终由文本引擎逐字形回退决定；
+    /// 这个函数把它单独暴露出来，好让调用方按模块文档的降级顺序处理字重。
+    pub const fn cjk_face(self) -> FontFace {
+        match self {
+            Platform::Windows => FontFace::new("Microsoft YaHei UI", W_STATIC_YAHEI),
+            Platform::MacOs => FontFace::new("PingFang SC", W_STATIC_PINGFANG),
+            Platform::Linux => FontFace::new("Noto Sans CJK SC", W_VARIABLE_NOTO),
+        }
+    }
+
+    /// 按栈顺序解析某档字重的落点（纯函数，不查系统）。
+    ///
+    /// 规则：**优先原生**（栈里第一个真有的族）→ 都做不到时取首选族的最近档，
+    /// 差距 ≥200 判为 [`WeightMatch::Synthetic`]。
+    pub fn resolve_weight(
+        self,
+        family: FontFamily,
+        weight: crate::typography::Weight,
+    ) -> FontChoice {
+        let stack = self.font_stack(family);
+        let requested = weight.value();
+        for face in stack {
+            if face.weights.supports(requested) {
+                return FontChoice {
+                    family: face.family,
+                    requested,
+                    available: requested,
+                    quality: WeightMatch::Native,
+                };
+            }
+        }
+        let first = stack[0];
+        let available = first.weights.nearest(requested);
+        FontChoice {
+            family: first.family,
+            requested,
+            available,
+            quality: if available.abs_diff(requested) >= 200 {
+                WeightMatch::Synthetic
+            } else {
+                WeightMatch::Nearest
+            },
+        }
+    }
+}

crates/design/src/typography/fonts/tests.rs

@@ -0,0 +1,149 @@
+//! 字体栈与字重解析的测试（独立文件是为了守住单文件 ≤400 行的硬约束）。
+
+use super::*;
+use crate::typography::Weight;
+
+const PLATFORMS: [Platform; 3] = [Platform::Windows, Platform::MacOs, Platform::Linux];
+const FAMILIES: [FontFamily; 3] = [FontFamily::Display, FontFamily::Text, FontFamily::Mono];
+
+#[test]
+fn font_stacks_are_well_formed() {
+    for platform in PLATFORMS {
+        for family in FAMILIES {
+            let stack = platform.font_stack(family);
+            assert!(
+                !stack.is_empty(),
+                "{} 的 {family:?} 栈为空",
+                platform.name()
+            );
+            let last = stack[stack.len() - 1].family;
+            let generic = match family {
+                FontFamily::Mono => "monospace",
+                _ => "sans-serif",
+            };
+            assert_eq!(
+                last,
+                generic,
+                "{} 的 {family:?} 栈必须以通用族名兜底",
+                platform.name()
+            );
+            for face in stack {
+                assert!(!face.family.is_empty());
+                assert!(
+                    !face.family.contains(['/', '\\', '.', ':']),
+                    "字体栈只允许族名，不得出现路径/文件名：{}",
+                    face.family
+                );
+                assert!(
+                    face.family.is_ascii(),
+                    "族名应为 ASCII（非 ASCII 名交给系统匹配）：{}",
+                    face.family
+                );
+                // 每条栈项都必须声明字重覆盖（连 400 都没有的族写进栈没有意义）。
+                assert!(
+                    face.supports(Weight::Regular),
+                    "{} 连 400 都没有，写它没意义",
+                    face.family
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn display_and_text_stacks_differ_on_windows_and_macos() {
+    assert_ne!(
+        Platform::Windows.font_stack(FontFamily::Display)[0].family,
+        Platform::Windows.font_stack(FontFamily::Text)[0].family
+    );
+    assert_ne!(
+        Platform::MacOs.font_stack(FontFamily::Display)[0].family,
+        Platform::MacOs.font_stack(FontFamily::Text)[0].family
+    );
+}
+
+#[test]
+fn chinese_fallback_is_present_but_not_first() {
+    // 中文族名必须在栈里，但不能排第一（纯英文环境不加载中文字体，D28）。
+    for platform in PLATFORMS {
+        let stack = platform.font_stack(FontFamily::Text);
+        let cjk = ["Microsoft YaHei UI", "PingFang SC", "Noto Sans CJK SC"];
+        assert!(
+            stack.iter().any(|face| cjk.contains(&face.family)),
+            "{} 的正文栈缺 CJK 兜底",
+            platform.name()
+        );
+        assert!(
+            !cjk.contains(&stack[0].family),
+            "{} 的首选字体不该是 CJK 族",
+            platform.name()
+        );
+    }
+}
+
+#[test]
+fn cjk_weight_coverage_is_registered() {
+    // 用户点名的坑：中文字重覆盖三平台差别很大。
+    let win = Platform::Windows.cjk_face();
+    assert!(win.supports(Weight::Regular) && win.supports(Weight::Bold));
+    assert!(
+        !win.supports(Weight::Medium),
+        "雅黑没有 500——这条断言就是「中文 500 会掉到降级路径」的登记"
+    );
+    let mac = Platform::MacOs.cjk_face();
+    assert!(mac.supports(Weight::Medium));
+    assert!(
+        !mac.supports(Weight::Bold),
+        "苹方到 600 为止，700 要合成/换族"
+    );
+    let linux = Platform::Linux.cjk_face();
+    for weight in [Weight::Regular, Weight::Medium, Weight::Bold] {
+        assert!(
+            linux.supports(weight),
+            "思源黑体/Noto CJK 应覆盖 400/500/700"
+        );
+    }
+}
+
+#[test]
+fn resolve_prefers_native_and_flags_synthetic() {
+    // Windows 正文 700：Segoe UI Variable 覆盖 → 原生。
+    let bold = Platform::Windows.resolve_weight(FontFamily::Text, Weight::Bold);
+    assert_eq!(bold.quality, WeightMatch::Native);
+    assert_eq!(bold.available, 700);
+    assert!(!bold.is_synthetic());
+    // Linux 正文 500：Roboto 可变 → 原生。
+    assert_eq!(
+        Platform::Linux
+            .resolve_weight(FontFamily::Text, Weight::Medium)
+            .quality,
+        WeightMatch::Native
+    );
+    // 静态族缺档：只有 400 的族请求 700 → nearest 400，差 300 → 判为合成降级。
+    let only_regular = FontFace::new("Courier New", WeightCoverage::Static(&[400]));
+    assert_eq!(only_regular.weights.nearest(700), 400);
+    let synthetic = FontChoice {
+        family: only_regular.family,
+        requested: 700,
+        available: only_regular.weights.nearest(700),
+        quality: WeightMatch::Synthetic,
+    };
+    assert!(synthetic.is_synthetic());
+}
+
+#[test]
+fn nearest_picks_closest_static_weight() {
+    let coverage = WeightCoverage::Static(&[300, 400, 600, 700]);
+    assert_eq!(coverage.nearest(500), 400);
+    assert_eq!(coverage.nearest(650), 600);
+    assert_eq!(coverage.nearest(900), 700);
+    let variable = WeightCoverage::Variable { min: 100, max: 900 };
+    assert_eq!(variable.nearest(500), 500);
+    assert_eq!(variable.nearest(50), 100);
+}
+
+#[test]
+fn current_platform_returns_a_stack() {
+    let platform = Platform::current();
+    assert!(!platform.font_stack(FontFamily::Text).is_empty());
+}

crates/design/src/typography/mod.rs

@@ -0,0 +1,346 @@
+//! M3 type scale（15 档，baseline + Expressive 强调两套）+ 三平台字体族回退栈。
+//!
+//! **数值来源 A 级**：`androidx.compose.material3.tokens.TypeScaleTokens`（v0_103）。
+//! baseline 四元组取 `<Role>{Size,LineHeight,Tracking,Weight}`，Expressive 强调档取
+//! `<Role>Emphasized{...}`（见 [`emphasized`] 模块）。注意 Compose 这一代 token 的 tracking 与
+//! m3.material.io 网页表格有 0.05px 级别的差异（display-large −0.2 vs −0.25、body-medium 0.2 vs
+//! 0.25、title-medium 0.2 vs 0.15），本项目跟 **Compose（实际渲染值）**，差异登记在
+//! crate 文档「baseline vs Expressive 差异清单」里。
+//!
+//! **只写字体族名，不内嵌任何字体文件**（Segoe UI / SF Pro / Roboto 都受各自许可约束，
+//! 内嵌再分发是违规的；引用系统已安装的族名是合规且体积为零的做法——这是 D14 与 D28 的共同要求）。
+//! 中文由系统字体匹配：栈里显式列出 CJK 族名，纯英文环境不会去加载任何中文字体（D28）。
+
+mod emphasized;
+mod fonts;
+
+pub use fonts::{FontChoice, FontFace, FontFamily, Platform, WeightCoverage, WeightMatch};
+
+/// 字重（M3 只用这四档；可变字体按连续值渲染时取 [`Weight::value`]）。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Weight {
+    /// 400：正文。
+    Regular,
+    /// 500：label / title-medium / Expressive 强调的正文与展示类。
+    Medium,
+    /// 600：本项目的「区块标题」档（介于 Medium 与 Bold 之间）。
+    SemiBold,
+    /// 700：页面标题 / 空态主文案 / Expressive 强调的 label 与 title-small-medium。
+    Bold,
+}
+
+impl Weight {
+    /// 数值字重（CSS/OpenType 口径）。
+    pub const fn value(self) -> u16 {
+        match self {
+            Weight::Regular => 400,
+            Weight::Medium => 500,
+            Weight::SemiBold => 600,
+            Weight::Bold => 700,
+        }
+    }
+
+    /// 再重一档（最重封顶 Bold）。
+    pub const fn heavier(self) -> Self {
+        match self {
+            Weight::Regular => Weight::Medium,
+            Weight::Medium => Weight::SemiBold,
+            Weight::SemiBold | Weight::Bold => Weight::Bold,
+        }
+    }
+}
+
+/// 一条排版样式（已解析成渲染要用的四个数）。
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct TypeStyle {
+    /// 字号（px；1.0 缩放时与 dp 同值）。
+    pub size_px: f32,
+    /// 行高（px）。
+    pub line_height_px: f32,
+    /// 字重。
+    pub weight: Weight,
+    /// 字间距（px；M3 的 type scale 用 px 表达，中文场景下正字距更易读）。
+    pub letter_spacing_px: f32,
+    /// 用哪条字体栈。
+    pub family: FontFamily,
+}
+
+impl TypeStyle {
+    /// 按用户字号缩放（`factor` 1.0 = 标准；行高与字距同比例，夹取到 0.5..2.0）。
+    pub fn scaled(self, factor: f32) -> Self {
+        let f = factor.clamp(0.5, 2.0);
+        Self {
+            size_px: self.size_px * f,
+            line_height_px: self.line_height_px * f,
+            letter_spacing_px: self.letter_spacing_px * f,
+            ..self
+        }
+    }
+
+    /// 该样式的字体族回退栈（栈项带字重覆盖，见 [`FontFace`]）。
+    pub fn font_stack(self, platform: Platform) -> &'static [FontFace] {
+        platform.font_stack(self.family)
+    }
+
+    /// 该样式在这台平台上「字重最终落到哪个族」——中文缺档时看它判断是否走降级。
+    pub fn resolve(self, platform: Platform) -> FontChoice {
+        platform.resolve_weight(self.family, self.weight)
+    }
+}
+
+/// M3 type scale 的 15 个角色。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum TypeRole {
+    /// 57/64：落地页大标题（本启动器基本不用）。
+    DisplayLarge,
+    /// 45/52。
+    DisplayMedium,
+    /// 36/44。
+    DisplaySmall,
+    /// 32/40：空态主标题的大档。
+    HeadlineLarge,
+    /// 28/36。
+    HeadlineMedium,
+    /// 24/32。
+    HeadlineSmall,
+    /// 22/28：页面标题（导航栏下的主标题）。
+    TitleLarge,
+    /// 16/24：卡片标题。
+    TitleMedium,
+    /// 14/20：行标题。
+    TitleSmall,
+    /// 16/24：正文大档（说明文字）。
+    BodyLarge,
+    /// 14/20：默认正文。
+    BodyMedium,
+    /// 12/16：辅助说明。
+    BodySmall,
+    /// 14/20：按钮文字。
+    LabelLarge,
+    /// 12/16：标签、徽标。
+    LabelMedium,
+    /// 11/16：最小标签（谨慎使用，中文 11px 可读性差）。
+    LabelSmall,
+}
+
+impl TypeRole {
+    /// 全部 15 档，按 M3 的族序排列。
+    pub const ALL: [TypeRole; 15] = [
+        TypeRole::DisplayLarge,
+        TypeRole::DisplayMedium,
+        TypeRole::DisplaySmall,
+        TypeRole::HeadlineLarge,
+        TypeRole::HeadlineMedium,
+        TypeRole::HeadlineSmall,
+        TypeRole::TitleLarge,
+        TypeRole::TitleMedium,
+        TypeRole::TitleSmall,
+        TypeRole::BodyLarge,
+        TypeRole::BodyMedium,
+        TypeRole::BodySmall,
+        TypeRole::LabelLarge,
+        TypeRole::LabelMedium,
+        TypeRole::LabelSmall,
+    ];
+
+    /// 稳定字符串名（`display-large` … `label-small`）。
+    pub const fn name(self) -> &'static str {
+        match self {
+            TypeRole::DisplayLarge => "display-large",
+            TypeRole::DisplayMedium => "display-medium",
+            TypeRole::DisplaySmall => "display-small",
+            TypeRole::HeadlineLarge => "headline-large",
+            TypeRole::HeadlineMedium => "headline-medium",
+            TypeRole::HeadlineSmall => "headline-small",
+            TypeRole::TitleLarge => "title-large",
+            TypeRole::TitleMedium => "title-medium",
+            TypeRole::TitleSmall => "title-small",
+            TypeRole::BodyLarge => "body-large",
+            TypeRole::BodyMedium => "body-medium",
+            TypeRole::BodySmall => "body-small",
+            TypeRole::LabelLarge => "label-large",
+            TypeRole::LabelMedium => "label-medium",
+            TypeRole::LabelSmall => "label-small",
+        }
+    }
+
+    /// **baseline MD3** 样式（官方 type scale 值：字号 / 行高 / 字重 / 字距 + 字体族分类）。
+    pub const fn style(self) -> TypeStyle {
+        match self {
+            TypeRole::DisplayLarge => style(57.0, 64.0, Weight::Regular, -0.2, FontFamily::Display),
+            TypeRole::DisplayMedium => style(45.0, 52.0, Weight::Regular, 0.0, FontFamily::Display),
+            TypeRole::DisplaySmall => style(36.0, 44.0, Weight::Regular, 0.0, FontFamily::Display),
+            TypeRole::HeadlineLarge => style(32.0, 40.0, Weight::Regular, 0.0, FontFamily::Display),
+            TypeRole::HeadlineMedium => {
+                style(28.0, 36.0, Weight::Regular, 0.0, FontFamily::Display)
+            }
+            TypeRole::HeadlineSmall => style(24.0, 32.0, Weight::Regular, 0.0, FontFamily::Display),
+            // 官方 TitleLarge 用 Brand 族（与 Display 同栈），其余 title 用 Plain（Text）。
+            TypeRole::TitleLarge => style(22.0, 28.0, Weight::Regular, 0.0, FontFamily::Display),
+            TypeRole::TitleMedium => style(16.0, 24.0, Weight::Medium, 0.2, FontFamily::Text),
+            TypeRole::TitleSmall => style(14.0, 20.0, Weight::Medium, 0.1, FontFamily::Text),
+            TypeRole::BodyLarge => style(16.0, 24.0, Weight::Regular, 0.5, FontFamily::Text),
+            TypeRole::BodyMedium => style(14.0, 20.0, Weight::Regular, 0.2, FontFamily::Text),
+            TypeRole::BodySmall => style(12.0, 16.0, Weight::Regular, 0.4, FontFamily::Text),
+            TypeRole::LabelLarge => style(14.0, 20.0, Weight::Medium, 0.1, FontFamily::Text),
+            TypeRole::LabelMedium => style(12.0, 16.0, Weight::Medium, 0.5, FontFamily::Text),
+            TypeRole::LabelSmall => style(11.0, 16.0, Weight::Medium, 0.5, FontFamily::Text),
+        }
+    }
+
+    /// **M3 Expressive** 官方强调档（15/15 全有值，A 级来源）。
+    ///
+    /// 规则（官方）：字号与行高不变；字重升到 500（展示/正文类）或 700（label 与小标题）；
+    /// 字距按官方表微调（display-large −0.2→0、body-large 0.5→0.15、title-medium 0.2→0.15、
+    /// body-medium 0.2→0.25）。这是**官方值，不是我们的近似**。
+    pub const fn emphasized(self) -> TypeStyle {
+        emphasized::style_of(self)
+    }
+
+    /// **简化强调规则（非官方）**：只把字重升一级，字号/行高/字距全不动。
+    ///
+    /// 用途：需要在「同一 role 内加强语气但不想引入任何字距变化」的场合（例如同屏多行标题
+    /// 需要严格对齐基线网格时）。**优先用 [`TypeRole::emphasized`]**——那才是 Expressive 的定义。
+    pub const fn emphasized_simplified(self) -> TypeStyle {
+        let base = self.style();
+        TypeStyle {
+            weight: base.weight.heavier(),
+            ..base
+        }
+    }
+}
+
+/// `const fn` 用的构造器。
+const fn style(
+    size: f32,
+    line_height: f32,
+    weight: Weight,
+    tracking_px: f32,
+    family: FontFamily,
+) -> TypeStyle {
+    TypeStyle {
+        size_px: size,
+        line_height_px: line_height,
+        weight,
+        letter_spacing_px: tracking_px,
+        family,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn every_role_has_sane_metrics() {
+        for role in TypeRole::ALL {
+            let s = role.style();
+            assert!(s.size_px >= 11.0, "{} 字号过小", role.name());
+            assert!(
+                s.line_height_px >= s.size_px,
+                "{} 行高小于字号（{} < {}）",
+                role.name(),
+                s.line_height_px,
+                s.size_px
+            );
+            assert!(
+                (1.1..=1.8).contains(&(s.line_height_px / s.size_px)),
+                "{} 行高倍数 {} 超出 1.1..1.8（M3 的行高是 1.12~1.5 量级）",
+                role.name(),
+                s.line_height_px / s.size_px
+            );
+            assert!(s.letter_spacing_px.abs() < 1.0, "{} 字距过大", role.name());
+        }
+    }
+
+    #[test]
+    fn each_family_is_monotone_by_size() {
+        // M3 的 type scale 是「五族 × 三档」，跨族不保证单调（title-small 14 → body-large 16），
+        // 但族内必须由大到小。
+        for family in [
+            [
+                TypeRole::DisplayLarge,
+                TypeRole::DisplayMedium,
+                TypeRole::DisplaySmall,
+            ],
+            [
+                TypeRole::HeadlineLarge,
+                TypeRole::HeadlineMedium,
+                TypeRole::HeadlineSmall,
+            ],
+            [
+                TypeRole::TitleLarge,
+                TypeRole::TitleMedium,
+                TypeRole::TitleSmall,
+            ],
+            [
+                TypeRole::BodyLarge,
+                TypeRole::BodyMedium,
+                TypeRole::BodySmall,
+            ],
+            [
+                TypeRole::LabelLarge,
+                TypeRole::LabelMedium,
+                TypeRole::LabelSmall,
+            ],
+        ] {
+            for pair in family.windows(2) {
+                assert!(
+                    pair[0].style().size_px > pair[1].style().size_px,
+                    "{} 应大于 {}",
+                    pair[0].name(),
+                    pair[1].name()
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn names_are_unique_and_kebab() {
+        let mut seen = std::collections::BTreeSet::new();
+        for role in TypeRole::ALL {
+            let name = role.name();
+            assert!(seen.insert(name), "排版角色名重复：{name}");
+            assert!(name.chars().all(|c| c.is_ascii_lowercase() || c == '-'));
+        }
+    }
+
+    #[test]
+    fn simplified_emphasis_only_bumps_weight() {
+        for role in TypeRole::ALL {
+            let base = role.style();
+            let emph = role.emphasized_simplified();
+            assert_eq!(base.size_px, emph.size_px);
+            assert_eq!(base.line_height_px, emph.line_height_px);
+            assert_eq!(base.letter_spacing_px, emph.letter_spacing_px);
+            assert!(emph.weight.value() > base.weight.value() || base.weight == Weight::Bold);
+        }
+    }
+
+    #[test]
+    fn official_emphasis_is_at_least_as_heavy_as_baseline() {
+        for role in TypeRole::ALL {
+            assert!(
+                role.emphasized().weight.value() >= role.style().weight.value(),
+                "{} 的官方强调档不该比 baseline 更轻",
+                role.name()
+            );
+            assert_ne!(
+                role.emphasized(),
+                role.style(),
+                "{} 强调档与 baseline 相同",
+                role.name()
+            );
+        }
+    }
+
+    #[test]
+    fn scaling_is_proportional_and_bounded() {
+        let base = TypeRole::BodyMedium.style();
+        let big = base.scaled(1.25);
+        assert!((big.size_px - 17.5).abs() < 1.0e-4);
+        assert!((big.line_height_px - 25.0).abs() < 1.0e-4);
+        assert_eq!(base.scaled(10.0).size_px, base.size_px * 2.0);
+        assert_eq!(base.scaled(0.1).size_px, base.size_px * 0.5);
+    }
+}

crates/design/tests/contrast_aa.rs

@@ -0,0 +1,255 @@
+//! WCAG AA 对比度门禁（M61 任务：「on-* 与其承载色至少满足 4.5:1，不达标的角色要显式标注例外」）。
+//!
+//! 三个性质让这条门禁可以做到「**换任何种子色都成立**」，而不是只对出厂紫成立：
+//! 1. 颜色建在 CIELAB `L*`（tone）轴上，`TonalPalette::tone` 精确命中 tone（误差 ≤1）；
+//! 2. WCAG 相对亮度只取决于同一条 Y 轴（`L*` ↔ Y 是双射）；
+//! 3. 角色 → tone 的映射与色相/彩度无关。
+//!
+//! 所以对比度主要由「两个角色的 tone 差」决定，与 user 选的强调色无关——下面对多组种子
+//! 逐一验证，就是在钉这个性质。
+
+use unlucky_design::color::{Color, Role, Scheme, SchemeFlavor};
+
+/// 正文文字：要求 ≥ 4.5:1（WCAG AA normal text）。
+const AA_TEXT: f32 = 4.5;
+/// 非文字元素（描边、图标块）：要求 ≥ 3:1（WCAG AA non-text）。
+const AA_NON_TEXT: f32 = 3.0;
+
+/// 文字/图标对（前景, 承载色）。两个模式都要过。
+const TEXT_PAIRS: [(Role, Role); 26] = [
+    (Role::OnPrimary, Role::Primary),
+    (Role::OnPrimaryContainer, Role::PrimaryContainer),
+    (Role::OnSecondary, Role::Secondary),
+    (Role::OnSecondaryContainer, Role::SecondaryContainer),
+    (Role::OnTertiary, Role::Tertiary),
+    (Role::OnTertiaryContainer, Role::TertiaryContainer),
+    (Role::OnError, Role::Error),
+    (Role::OnErrorContainer, Role::ErrorContainer),
+    (Role::OnSurface, Role::Surface),
+    (Role::OnSurfaceVariant, Role::SurfaceVariant),
+    (Role::OnBackground, Role::Background),
+    (Role::InverseOnSurface, Role::InverseSurface),
+    (Role::InversePrimary, Role::InverseSurface),
+    (Role::OnPrimaryFixed, Role::PrimaryFixed),
+    (Role::OnPrimaryFixedVariant, Role::PrimaryFixedDim),
+    (Role::OnSecondaryFixed, Role::SecondaryFixed),
+    (Role::OnSecondaryFixedVariant, Role::SecondaryFixedDim),
+    (Role::OnTertiaryFixed, Role::TertiaryFixed),
+    (Role::OnTertiaryFixedVariant, Role::TertiaryFixedDim),
+    // 卡片/浮层容器上的文字（M3 现行口径：层级靠 surface-container-* 表达）
+    (Role::OnSurface, Role::SurfaceContainerLowest),
+    (Role::OnSurface, Role::SurfaceContainerLow),
+    (Role::OnSurface, Role::SurfaceContainer),
+    (Role::OnSurface, Role::SurfaceContainerHigh),
+    (Role::OnSurface, Role::SurfaceContainerHighest),
+    (Role::OnSurfaceVariant, Role::SurfaceContainerHighest),
+    (Role::OnSurfaceVariant, Role::SurfaceContainerLow),
+];
+
+/// 显式登记的例外：`(前景, 承载色, 目标阈值, 原因)`。
+///
+/// 这些不是缺陷，是 M3 定义决定的（非文字元素 3:1、装饰件无要求）。
+const EXCEPTIONS: [(Role, Role, f32, &str); 3] = [
+    (
+        Role::Outline,
+        Role::Surface,
+        AA_NON_TEXT,
+        "输入框/卡片描边是 M3 定义的非文字元素，规范目标 3:1（light 实测 4.26:1、dark 5.89:1 已高于目标）",
+    ),
+    (
+        Role::OutlineVariant,
+        Role::Surface,
+        AA_NON_TEXT * 0.5,
+        "分隔线是纯装饰，M3 不要求对比度下限；light 1.62:1 / dark 1.99:1 是「几乎看不见但要能数出层级」的取值",
+    ),
+    (
+        Role::SurfaceVariant,
+        Role::Surface,
+        1.0,
+        "surface-variant 是容器色而不是前景色，不参与对比度门禁（M3 已不推荐用它做容器，保留仅为兼容旧值）",
+    ),
+];
+
+fn seeds() -> Vec<Color> {
+    vec![
+        // 出厂基线（M3 baseline 紫）
+        Color::from_hex("#6750A4").expect("基线种子"),
+        // 冷蓝（原 Fluent 强调色，用户大概率会选这一族）
+        Color::from_hex("#0078D4").expect("蓝"),
+        // 青绿
+        Color::from_hex("#006A5C").expect("青"),
+        // 暖橙（高彩度，gamut 压力大）
+        Color::from_hex("#E8710A").expect("橙"),
+        // 亮黄（最容易被白字吃掉的极端）
+        Color::from_hex("#FFD400").expect("黄"),
+        // 近灰（低彩度种子，检验 neutral 不塌）
+        Color::from_hex("#6E6E6E").expect("灰"),
+    ]
+}
+
+#[test]
+fn text_pairs_meet_wcag_aa_for_every_seed_and_flavor() {
+    let mut failures = Vec::new();
+    for seed in seeds() {
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let scheme = Scheme::from_seed(flavor, seed);
+            for (fg, bg) in TEXT_PAIRS {
+                let ratio = scheme.contrast(fg, bg);
+                if ratio < AA_TEXT {
+                    failures.push(format!(
+                        "seed {} / {} / {} on {} = {ratio:.2}",
+                        seed.to_hex(),
+                        flavor.name(),
+                        fg.name(),
+                        bg.name()
+                    ));
+                }
+            }
+        }
+    }
+    assert!(
+        failures.is_empty(),
+        "以下角色对未达 WCAG AA（4.5:1）：\n{}",
+        failures.join("\n")
+    );
+}
+
+#[test]
+fn exception_list_is_honest_about_its_thresholds() {
+    // 例外必须**真的**是「非文字级」，不能悄悄把低于 3:1 的文字对塞进来。
+    for seed in seeds() {
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let scheme = Scheme::from_seed(flavor, seed);
+            for (fg, bg, threshold, reason) in EXCEPTIONS {
+                assert!(
+                    !fg.is_foreground(),
+                    "例外 {} 不该是文字前景色（{reason}）",
+                    fg.name()
+                );
+                let ratio = scheme.contrast(fg, bg);
+                assert!(
+                    ratio >= threshold,
+                    "例外 {} on {} 实测 {ratio:.2}，低于登记阈值 {threshold}（seed {} / {}）",
+                    fg.name(),
+                    bg.name(),
+                    seed.to_hex(),
+                    flavor.name()
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn baseline_light_and_dark_both_pass() {
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let scheme = Scheme::baseline(flavor);
+        for (fg, bg) in TEXT_PAIRS {
+            let ratio = scheme.contrast(fg, bg);
+            assert!(
+                ratio >= AA_TEXT,
+                "baseline {} 的 {} on {} 只有 {ratio:.2}",
+                flavor.name(),
+                fg.name(),
+                bg.name()
+            );
+        }
+    }
+}
+
+#[test]
+fn sky_seed_candidates_meet_wcag_aa() {
+    // M70：四档默认色候选（种子 + 中性彩度）必须过同一条 26 组门禁。
+    // 中性彩度改变只影响色相/彩度，不影响 tone 轴，所以理论上恒过——这里就是要**证明**它恒过，
+    // 而不是相信它。任何一档不达标，该档直接判为不可用（不许为了好看放宽阈值）。
+    let candidates = [
+        ("① 保守蓝", "#2196F3", 6.0_f64),
+        ("② 冷调蓝", "#2196F3", 12.0),
+        ("③ 浅冷蓝", "#87CEEB", 12.0),
+        ("④ 天蓝", "#3C8DBC", 12.0),
+    ];
+    let mut failures = Vec::new();
+    let mut worst = (f32::MAX, String::new());
+    let mut checked = 0;
+    for (title, seed_hex, neutral_chroma) in candidates {
+        let seed = Color::from_hex(seed_hex).expect("候选种子");
+        let palettes =
+            unlucky_design::color::Palettes::from_seed_with_neutral_chroma(seed, neutral_chroma);
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let scheme = Scheme::from_palettes(&palettes, flavor);
+            for (fg, bg) in TEXT_PAIRS {
+                let ratio = scheme.contrast(fg, bg);
+                checked += 1;
+                if ratio < worst.0 {
+                    worst = (
+                        ratio,
+                        format!(
+                            "{title}/{} 的 {} on {}",
+                            flavor.name(),
+                            fg.name(),
+                            bg.name()
+                        ),
+                    );
+                }
+                if ratio < AA_TEXT {
+                    failures.push(format!(
+                        "{title}（{seed_hex} / 中性 {neutral_chroma}）/ {} / {} on {} = {ratio:.2}",
+                        flavor.name(),
+                        fg.name(),
+                        bg.name()
+                    ));
+                }
+            }
+        }
+    }
+    println!(
+        "候选 WCAG：{checked} 项，最紧的一对 {} = {:.2}:1（阈值 {AA_TEXT}）",
+        worst.1, worst.0
+    );
+    assert!(
+        failures.is_empty(),
+        "以下候选未达 WCAG AA（4.5:1），该档不可用：\n{}",
+        failures.join("\n")
+    );
+}
+
+#[test]
+fn accent_override_cannot_break_contrast() {
+    // 换了强调色之后，primary 族仍必须过 AA——这是「tone 轴固定」带来的结构性保证。
+    let base = Scheme::baseline(SchemeFlavor::Light);
+    for seed in seeds() {
+        let custom = Scheme::from_accent(SchemeFlavor::Light, seed);
+        for (fg, bg) in [
+            (Role::OnPrimary, Role::Primary),
+            (Role::OnPrimaryContainer, Role::PrimaryContainer),
+            (Role::OnSecondary, Role::Secondary),
+            (Role::OnTertiary, Role::Tertiary),
+        ] {
+            let ratio = custom.contrast(fg, bg);
+            assert!(
+                ratio >= AA_TEXT,
+                "强调色 {} 下 {} on {} 只有 {ratio:.2}",
+                seed.to_hex(),
+                fg.name(),
+                bg.name()
+            );
+        }
+        // 表面色不受强调色影响（这条同时是 `from_accent` 的语义断言）。
+        assert_eq!(custom.get(Role::Surface), base.get(Role::Surface));
+    }
+}
+
+#[test]
+fn outline_is_registered_as_non_text_exception() {
+    // 把「为什么 outline 不是 AA 例外失败项」钉死：它在 light 下 4.29:1（低于 4.5 但高于 3:1）。
+    let light = Scheme::baseline(SchemeFlavor::Light);
+    let ratio = light.contrast(Role::Outline, Role::Surface);
+    assert!(
+        ratio < AA_TEXT,
+        "light 的 outline 若已达 4.5 应把例外删掉：{ratio:.2}"
+    );
+    assert!(
+        ratio >= AA_NON_TEXT,
+        "light 的 outline 低于非文字 3:1：{ratio:.2}"
+    );
+}

crates/design/tests/official_accent.rs

@@ -0,0 +1,307 @@
+//! 自定义强调色 × 官方算法的**逐角色对齐**（`Scheme::from_accent`）。
+//!
+//! 期望值来自官方 Java 实现：`SchemeTonalSpot(seed, isDark, 0, SPEC_2021)` 的强调族角色。
+//! 判据：每通道误差 ≤1（见 `official_baseline.rs` 的说明）。
+//!
+//! 为什么只比强调族（primary/secondary/tertiary 共 12 个角色）：本项目的产品语义是
+//! 「换强调色不动底色」——中性表面与 error 刻意留在 baseline（见 `Palettes::with_accent`），
+//! 而官方 `from_seed` 会把中性色也染上种子色相。中性派生的正确性由本文件末尾的
+//! `from_seed_*` 用例单独验证（那一处必须与官方完全一致）。
+
+use unlucky_design::color::{Color, Role, Scheme, SchemeFlavor};
+
+/// 每通道允许的最大误差。
+const CHANNEL_TOLERANCE: i16 = 1;
+
+/// 一条官方期望值：角色 + light 色值 + dark 色值。
+type RoleRow = (Role, &'static str, &'static str);
+
+/// 一个种子 + 它 12 个强调族角色的官方色值。
+type SeedRows = (&'static str, [RoleRow; 12]);
+
+/// 八个种子：官方基线紫、纯红/绿/蓝、低彩度灰蓝、高彩度紫，外加纯黑与纯白两个边缘用例
+/// （无彩色种子的色相是病态的，官方的处理方式见 `Hct`：黑 → 色相 0、白 → 色相 209.5）。
+/// 每个种子带 12 个强调族角色的官方色值（light, dark）。
+const ACCENT_SEEDS: [SeedRows; 8] = [
+    (
+        "#6750A4",
+        [
+            (Role::Primary, "#65558F", "#CFBDFE"),
+            (Role::OnPrimary, "#FFFFFF", "#36275D"),
+            (Role::PrimaryContainer, "#E9DDFF", "#4D3D75"),
+            (Role::OnPrimaryContainer, "#4D3D75", "#E9DDFF"),
+            (Role::Secondary, "#625B71", "#CBC2DB"),
+            (Role::OnSecondary, "#FFFFFF", "#332D41"),
+            (Role::SecondaryContainer, "#E8DEF8", "#4A4458"),
+            (Role::OnSecondaryContainer, "#4A4458", "#E8DEF8"),
+            (Role::Tertiary, "#7E5260", "#EFB8C8"),
+            (Role::OnTertiary, "#FFFFFF", "#4A2532"),
+            (Role::TertiaryContainer, "#FFD9E3", "#633B48"),
+            (Role::OnTertiaryContainer, "#633B48", "#FFD9E3"),
+        ],
+    ),
+    (
+        "#FF0000",
+        [
+            (Role::Primary, "#904B40", "#FFB4A8"),
+            (Role::OnPrimary, "#FFFFFF", "#561E16"),
+            (Role::PrimaryContainer, "#FFDAD4", "#73342A"),
+            (Role::OnPrimaryContainer, "#73342A", "#FFDAD4"),
+            (Role::Secondary, "#775651", "#E7BDB6"),
+            (Role::OnSecondary, "#FFFFFF", "#442925"),
+            (Role::SecondaryContainer, "#FFDAD4", "#5D3F3B"),
+            (Role::OnSecondaryContainer, "#5D3F3B", "#FFDAD4"),
+            (Role::Tertiary, "#705C2E", "#DEC48C"),
+            (Role::OnTertiary, "#FFFFFF", "#3E2E04"),
+            (Role::TertiaryContainer, "#FBDFA6", "#564419"),
+            (Role::OnTertiaryContainer, "#564419", "#FBDFA6"),
+        ],
+    ),
+    (
+        "#00FF00",
+        [
+            (Role::Primary, "#406836", "#A5D395"),
+            (Role::OnPrimary, "#FFFFFF", "#11380B"),
+            (Role::PrimaryContainer, "#C0EFB0", "#285020"),
+            (Role::OnPrimaryContainer, "#285020", "#C0EFB0"),
+            (Role::Secondary, "#54634D", "#BBCBB2"),
+            (Role::OnSecondary, "#FFFFFF", "#263422"),
+            (Role::SecondaryContainer, "#D7E8CD", "#3C4B37"),
+            (Role::OnSecondaryContainer, "#3C4B37", "#D7E8CD"),
+            (Role::Tertiary, "#386568", "#A0CFD2"),
+            (Role::OnTertiary, "#FFFFFF", "#003739"),
+            (Role::TertiaryContainer, "#BCEBEE", "#1E4D50"),
+            (Role::OnTertiaryContainer, "#1E4D50", "#BCEBEE"),
+        ],
+    ),
+    (
+        "#0000FF",
+        [
+            (Role::Primary, "#555992", "#BEC2FF"),
+            (Role::OnPrimary, "#FFFFFF", "#272B60"),
+            (Role::PrimaryContainer, "#E0E0FF", "#3E4278"),
+            (Role::OnPrimaryContainer, "#3E4278", "#E0E0FF"),
+            (Role::Secondary, "#5C5D72", "#C5C4DD"),
+            (Role::OnSecondary, "#FFFFFF", "#2E2F42"),
+            (Role::SecondaryContainer, "#E1E0F9", "#444559"),
+            (Role::OnSecondaryContainer, "#444559", "#E1E0F9"),
+            (Role::Tertiary, "#78536B", "#E8B9D5"),
+            (Role::OnTertiary, "#FFFFFF", "#46263B"),
+            (Role::TertiaryContainer, "#FFD8EE", "#5E3C52"),
+            (Role::OnTertiaryContainer, "#5E3C52", "#FFD8EE"),
+        ],
+    ),
+    (
+        "#6E7C8A",
+        [
+            (Role::Primary, "#2B638B", "#98CCF9"),
+            (Role::OnPrimary, "#FFFFFF", "#003350"),
+            (Role::PrimaryContainer, "#CCE5FF", "#044B71"),
+            (Role::OnPrimaryContainer, "#044B71", "#CCE5FF"),
+            (Role::Secondary, "#50606F", "#B8C8D9"),
+            (Role::OnSecondary, "#FFFFFF", "#23323F"),
+            (Role::SecondaryContainer, "#D4E4F6", "#394856"),
+            (Role::OnSecondaryContainer, "#394856", "#D4E4F6"),
+            (Role::Tertiary, "#66587B", "#D1BFE7"),
+            (Role::OnTertiary, "#FFFFFF", "#372A4A"),
+            (Role::TertiaryContainer, "#ECDCFF", "#4E4162"),
+            (Role::OnTertiaryContainer, "#4E4162", "#ECDCFF"),
+        ],
+    ),
+    (
+        "#D000FF",
+        [
+            (Role::Primary, "#794F81", "#E9B5EF"),
+            (Role::OnPrimary, "#FFFFFF", "#472150"),
+            (Role::PrimaryContainer, "#FDD6FF", "#603768"),
+            (Role::OnPrimaryContainer, "#603768", "#FDD6FF"),
+            (Role::Secondary, "#6A596C", "#D6C0D6"),
+            (Role::OnSecondary, "#FFFFFF", "#3A2B3C"),
+            (Role::SecondaryContainer, "#F3DBF2", "#524153"),
+            (Role::OnSecondaryContainer, "#524153", "#F3DBF2"),
+            (Role::Tertiary, "#82524C", "#F5B7B0"),
+            (Role::OnTertiary, "#FFFFFF", "#4C2521"),
+            (Role::TertiaryContainer, "#FFDAD6", "#673B36"),
+            (Role::OnTertiaryContainer, "#673B36", "#FFDAD6"),
+        ],
+    ),
+    (
+        "#000000",
+        [
+            (Role::Primary, "#8C4A60", "#FFB1C8"),
+            (Role::OnPrimary, "#FFFFFF", "#541D32"),
+            (Role::PrimaryContainer, "#FFD9E2", "#703348"),
+            (Role::OnPrimaryContainer, "#703348", "#FFD9E2"),
+            (Role::Secondary, "#74565F", "#E3BDC6"),
+            (Role::OnSecondary, "#FFFFFF", "#422931"),
+            (Role::SecondaryContainer, "#FFD9E2", "#5A3F47"),
+            (Role::OnSecondaryContainer, "#5A3F47", "#FFD9E2"),
+            (Role::Tertiary, "#7C5635", "#EFBD94"),
+            (Role::OnTertiary, "#FFFFFF", "#48290B"),
+            (Role::TertiaryContainer, "#FFDCC1", "#623F20"),
+            (Role::OnTertiaryContainer, "#623F20", "#FFDCC1"),
+        ],
+    ),
+    (
+        "#FFFFFF",
+        [
+            (Role::Primary, "#006874", "#82D3E0"),
+            (Role::OnPrimary, "#FFFFFF", "#00363D"),
+            (Role::PrimaryContainer, "#9EEFFD", "#004F58"),
+            (Role::OnPrimaryContainer, "#004F58", "#9EEFFD"),
+            (Role::Secondary, "#4A6267", "#B1CBD0"),
+            (Role::OnSecondary, "#FFFFFF", "#1C3438"),
+            (Role::SecondaryContainer, "#CDE7EC", "#334B4F"),
+            (Role::OnSecondaryContainer, "#334B4F", "#CDE7EC"),
+            (Role::Tertiary, "#525E7D", "#BAC6EA"),
+            (Role::OnTertiary, "#FFFFFF", "#24304D"),
+            (Role::TertiaryContainer, "#DAE2FF", "#3B4664"),
+            (Role::OnTertiaryContainer, "#3B4664", "#DAE2FF"),
+        ],
+    ),
+];
+
+/// 官方 `SchemeTonalSpot(seed)` 的中性表面（surface 与 surface-container-highest，light/dark）。
+const SEED_NEUTRALS: [(&str, &str, &str, &str, &str); 8] = [
+    ("#6750A4", "#FDF7FF", "#141218", "#E6E0E9", "#36343A"),
+    ("#FF0000", "#FFF8F6", "#1A1110", "#F1DFDC", "#3D3230"),
+    ("#00FF00", "#F8FBF1", "#11140F", "#E1E4DA", "#32362F"),
+    ("#0000FF", "#FBF8FF", "#131318", "#E4E1E9", "#34343A"),
+    ("#6E7C8A", "#F7F9FF", "#101418", "#E0E2E8", "#313539"),
+    ("#D000FF", "#FFF7FA", "#171217", "#EAE0E7", "#393338"),
+    ("#000000", "#FFF8F8", "#191113", "#EFDFE1", "#3C3235"),
+    ("#FFFFFF", "#F5FAFB", "#0E1415", "#DEE3E5", "#303637"),
+];
+
+fn worst_channel(got: Color, want: Color) -> i16 {
+    [(got.r, want.r), (got.g, want.g), (got.b, want.b)]
+        .iter()
+        .map(|(a, b)| (i16::from(*a) - i16::from(*b)).abs())
+        .max()
+        .unwrap_or(0)
+}
+
+#[test]
+fn accent_schemes_match_official_on_the_accent_families() {
+    let mut worst = 0;
+    let mut off_by_one = 0;
+    let mut checked = 0;
+    let mut failures = Vec::new();
+    for (seed_hex, roles) in ACCENT_SEEDS {
+        let accent = Color::from_hex(seed_hex).expect("合法 hex");
+        for (flavor, is_dark) in [(SchemeFlavor::Light, false), (SchemeFlavor::Dark, true)] {
+            let scheme = Scheme::from_accent(flavor, accent);
+            for (role, want_light, want_dark) in roles {
+                let want_hex = if is_dark { want_dark } else { want_light };
+                let got = scheme.get(role);
+                let want = Color::from_hex(want_hex).expect("官方 hex 必须合法");
+                let delta = worst_channel(got, want);
+                worst = worst.max(delta);
+                checked += 1;
+                if delta > 0 {
+                    off_by_one += 1;
+                }
+                if delta > CHANNEL_TOLERANCE {
+                    failures.push(format!(
+                        "{seed_hex}/{}/{} 是 {}，官方 {want_hex}（差 {delta}）",
+                        flavor.name(),
+                        role.name(),
+                        got.to_hex()
+                    ));
+                }
+            }
+        }
+    }
+    assert!(
+        failures.is_empty(),
+        "{} 项强调色与官方不一致（容差 {CHANNEL_TOLERANCE}）：\n{}",
+        failures.len(),
+        failures.join("\n")
+    );
+    println!("强调色对齐：{checked} 项，最大通道误差 {worst}，非零误差 {off_by_one} 项");
+}
+
+#[test]
+fn accent_scheme_keeps_baseline_surfaces() {
+    // 产品语义：换强调色不许让底色变脏（这是 `from_accent` 与官方 `from_seed` 的唯一差别）。
+    let base = Scheme::baseline(SchemeFlavor::Light);
+    for (seed_hex, _) in ACCENT_SEEDS {
+        let accent = Color::from_hex(seed_hex).expect("合法 hex");
+        let custom = Scheme::from_accent(SchemeFlavor::Light, accent);
+        assert_eq!(custom.get(Role::Surface), base.get(Role::Surface));
+        assert_eq!(custom.get(Role::Outline), base.get(Role::Outline));
+        assert_eq!(custom.get(Role::Error), base.get(Role::Error));
+    }
+}
+
+#[test]
+fn from_seed_matches_official_neutrals() {
+    // 全量 `from_seed` 的中性派生必须与官方一致（否则「整窗染色」的色相就是错的）。
+    for (seed_hex, light_surface, dark_surface, light_highest, dark_highest) in SEED_NEUTRALS {
+        let seed = Color::from_hex(seed_hex).expect("合法 hex");
+        for (flavor, want_surface, want_highest) in [
+            (SchemeFlavor::Light, light_surface, light_highest),
+            (SchemeFlavor::Dark, dark_surface, dark_highest),
+        ] {
+            let scheme = Scheme::from_seed(flavor, seed);
+            for (role, want_hex) in [
+                (Role::Surface, want_surface),
+                (Role::SurfaceContainerHighest, want_highest),
+            ] {
+                let got = scheme.get(role);
+                let want = Color::from_hex(want_hex).expect("官方 hex 必须合法");
+                assert!(
+                    worst_channel(got, want) <= CHANNEL_TOLERANCE,
+                    "{seed_hex}/{}/{} 是 {}，官方 {want_hex}",
+                    flavor.name(),
+                    role.name(),
+                    got.to_hex()
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn from_seed_and_from_accent_agree_on_the_accent_families() {
+    // 两个入口的强调族应当逐像素相同：换种子时中性色不同，强调色只取决于种子色相。
+    for (seed_hex, _) in ACCENT_SEEDS {
+        let seed = Color::from_hex(seed_hex).expect("合法 hex");
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let by_seed = Scheme::from_seed(flavor, seed);
+            let by_accent = Scheme::from_accent(flavor, seed);
+            for role in [
+                Role::Primary,
+                Role::OnPrimary,
+                Role::PrimaryContainer,
+                Role::OnPrimaryContainer,
+                Role::Secondary,
+                Role::SecondaryContainer,
+                Role::Tertiary,
+                Role::TertiaryContainer,
+            ] {
+                assert_eq!(
+                    by_seed.get(role),
+                    by_accent.get(role),
+                    "{seed_hex}/{} 的 {} 两个入口不一致",
+                    flavor.name(),
+                    role.name()
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn accent_hue_is_not_clipped_away() {
+    // 旧缺陷②：强调色色相被 gamut 硬裁导致偏移。现在色相由 HCT 保住（只压彩度）。
+    use unlucky_design::color::Hct;
+    for (seed_hex, _) in ACCENT_SEEDS {
+        let seed = Color::from_hex(seed_hex).expect("合法 hex");
+        let seed_hue = Hct::from_color(seed).hue;
+        let primary = Scheme::from_accent(SchemeFlavor::Light, seed).get(Role::Primary);
+        let got = Hct::from_color(primary).hue;
+        let delta = (got - seed_hue).abs().min(360.0 - (got - seed_hue).abs());
+        assert!(delta < 1.0, "{seed_hex} 的 primary 色相偏了 {delta}°");
+    }
+}

crates/design/tests/official_baseline.rs

@@ -0,0 +1,198 @@
+//! 与官方 `material-color-utilities` 的**逐角色对齐**（baseline 方案）。
+//!
+//! 期望值不是「我们觉得对的颜色」，而是把官方 Java 实现（Apache-2.0）编译跑出来的结果：
+//! `new SchemeTonalSpot(Hct.fromInt(0xFF6750A4), isDark, 0.0, SpecVersion.SPEC_2021, Platform.PHONE)`
+//! 配上 `ColorSpec2021` 的 49 个动态色。跑法见 `NOTICE` 的归属声明——期望值表就是那份输出的
+//! 抄本（`seed,flavor,role,hex`）。
+//!
+//! 判据是**每通道误差 ≤1**：8 bit 量化本身就有半格误差，再加上 Java `double` 与 Rust `f64`
+//! 的末位差异，1 是「同一个算法」的合理上限；2 以上就是实现真的不一样了。
+
+use unlucky_design::color::{Color, Hct, Role, Scheme, SchemeFlavor, BASELINE_SEED};
+
+/// 每通道允许的最大误差。
+const CHANNEL_TOLERANCE: i16 = 1;
+
+/// 官方 baseline 输出（seed `#6750A4`，Tonal Spot，ColorSpec2021，contrastLevel 0）。
+const BASELINE: [(Role, &str, &str); 49] = [
+    (Role::Primary, "#65558F", "#CFBDFE"),
+    (Role::OnPrimary, "#FFFFFF", "#36275D"),
+    (Role::PrimaryContainer, "#E9DDFF", "#4D3D75"),
+    (Role::OnPrimaryContainer, "#4D3D75", "#E9DDFF"),
+    (Role::Secondary, "#625B71", "#CBC2DB"),
+    (Role::OnSecondary, "#FFFFFF", "#332D41"),
+    (Role::SecondaryContainer, "#E8DEF8", "#4A4458"),
+    (Role::OnSecondaryContainer, "#4A4458", "#E8DEF8"),
+    (Role::Tertiary, "#7E5260", "#EFB8C8"),
+    (Role::OnTertiary, "#FFFFFF", "#4A2532"),
+    (Role::TertiaryContainer, "#FFD9E3", "#633B48"),
+    (Role::OnTertiaryContainer, "#633B48", "#FFD9E3"),
+    (Role::Error, "#BA1A1A", "#FFB4AB"),
+    (Role::OnError, "#FFFFFF", "#690005"),
+    (Role::ErrorContainer, "#FFDAD6", "#93000A"),
+    (Role::OnErrorContainer, "#93000A", "#FFDAD6"),
+    (Role::Surface, "#FDF7FF", "#141218"),
+    (Role::OnSurface, "#1D1B20", "#E6E0E9"),
+    (Role::SurfaceVariant, "#E7E0EB", "#49454E"),
+    (Role::OnSurfaceVariant, "#49454E", "#CAC4CF"),
+    (Role::Background, "#FDF7FF", "#141218"),
+    (Role::OnBackground, "#1D1B20", "#E6E0E9"),
+    (Role::SurfaceDim, "#DED8E0", "#141218"),
+    (Role::SurfaceBright, "#FDF7FF", "#3B383E"),
+    (Role::SurfaceContainerLowest, "#FFFFFF", "#0F0D13"),
+    (Role::SurfaceContainerLow, "#F8F2FA", "#1D1B20"),
+    (Role::SurfaceContainer, "#F2ECF4", "#211F24"),
+    (Role::SurfaceContainerHigh, "#ECE6EE", "#2B292F"),
+    (Role::SurfaceContainerHighest, "#E6E0E9", "#36343A"),
+    (Role::Outline, "#7A757F", "#948F99"),
+    (Role::OutlineVariant, "#CAC4CF", "#49454E"),
+    (Role::InverseSurface, "#322F35", "#E6E0E9"),
+    (Role::InverseOnSurface, "#F5EFF7", "#322F35"),
+    (Role::InversePrimary, "#CFBDFE", "#65558F"),
+    (Role::Shadow, "#000000", "#000000"),
+    (Role::Scrim, "#000000", "#000000"),
+    (Role::SurfaceTint, "#65558F", "#CFBDFE"),
+    (Role::PrimaryFixed, "#E9DDFF", "#E9DDFF"),
+    (Role::PrimaryFixedDim, "#CFBDFE", "#CFBDFE"),
+    (Role::OnPrimaryFixed, "#201047", "#201047"),
+    (Role::OnPrimaryFixedVariant, "#4D3D75", "#4D3D75"),
+    (Role::SecondaryFixed, "#E8DEF8", "#E8DEF8"),
+    (Role::SecondaryFixedDim, "#CBC2DB", "#CBC2DB"),
+    (Role::OnSecondaryFixed, "#1E192B", "#1E192B"),
+    (Role::OnSecondaryFixedVariant, "#4A4458", "#4A4458"),
+    (Role::TertiaryFixed, "#FFD9E3", "#FFD9E3"),
+    (Role::TertiaryFixedDim, "#EFB8C8", "#EFB8C8"),
+    (Role::OnTertiaryFixed, "#31101D", "#31101D"),
+    (Role::OnTertiaryFixedVariant, "#633B48", "#633B48"),
+];
+
+/// 官方 `Hct.from(hue, chroma, tone)` 的色值（求解器与 gamut 映射的直接证据）。
+const HCT_PROBES: [(f64, f64, f64, &str); 12] = [
+    (95.0, 36.0, 40.0, "#705D0D"),
+    (95.0, 36.0, 90.0, "#FCE186"),
+    (95.0, 16.0, 90.0, "#F0E2BB"),
+    (96.0, 24.0, 80.0, "#D7C68D"),
+    (25.0, 84.0, 40.0, "#BA1A1A"),
+    (0.0, 0.0, 50.0, "#777777"),
+    (200.0, 120.0, 70.0, "#00BEC3"),
+    (30.0, 0.5, 98.0, "#FDF8F7"),
+    (270.0, 200.0, 10.0, "#001847"),
+    (120.0, 60.0, 99.0, "#FCFFDD"),
+    (60.0, 6.0, 6.0, "#19120C"),
+    (95.0, 36.0, 30.0, "#554500"),
+];
+
+/// 三通道里最大的绝对误差。
+fn worst_channel(got: Color, want: Color) -> i16 {
+    let pairs = [(got.r, want.r), (got.g, want.g), (got.b, want.b)];
+    pairs
+        .iter()
+        .map(|(a, b)| (i16::from(*a) - i16::from(*b)).abs())
+        .max()
+        .unwrap_or(0)
+}
+
+#[test]
+fn baseline_matches_official_on_all_forty_nine_roles() {
+    // 注意：对齐的是**官方锚点**（种子 #6750A4 + 中性彩度 6），不是产品默认（M70 起是浅冷蓝）。
+    let light = Scheme::official_baseline(SchemeFlavor::Light);
+    let dark = Scheme::official_baseline(SchemeFlavor::Dark);
+    let mut worst = 0;
+    let mut off_by_one = 0;
+    let mut failures = Vec::new();
+    for (role, want_light, want_dark) in BASELINE {
+        for (flavor, scheme, want_hex) in [
+            (SchemeFlavor::Light, light, want_light),
+            (SchemeFlavor::Dark, dark, want_dark),
+        ] {
+            let got = scheme.get(role);
+            let want = Color::from_hex(want_hex).expect("官方 hex 必须合法");
+            let delta = worst_channel(got, want);
+            worst = worst.max(delta);
+            if delta > 0 {
+                off_by_one += 1;
+            }
+            if delta > CHANNEL_TOLERANCE {
+                failures.push(format!(
+                    "{}/{} 是 {}，官方 {want_hex}（差 {delta}）",
+                    flavor.name(),
+                    role.name(),
+                    got.to_hex()
+                ));
+            }
+        }
+    }
+    assert!(
+        failures.is_empty(),
+        "{} 个角色与官方不一致（容差 {CHANNEL_TOLERANCE}）：\n{}",
+        failures.len(),
+        failures.join("\n")
+    );
+    // 把误差统计打出来（`cargo test -- --nocapture` 可见），报告里要引用。
+    println!("baseline 对齐：98 项，最大通道误差 {worst}，非零误差 {off_by_one} 项");
+}
+
+#[test]
+fn hct_solver_matches_official_color_spec_2021() {
+    for (hue, chroma, tone, want_hex) in HCT_PROBES {
+        let got = Hct::from_components(hue, chroma, tone).to_color();
+        let want = Color::from_hex(want_hex).expect("官方 hex 必须合法");
+        assert!(
+            worst_channel(got, want) <= CHANNEL_TOLERANCE,
+            "HCT({hue}, {chroma}, {tone}) 是 {}，官方 {want_hex}",
+            got.to_hex()
+        );
+    }
+}
+
+#[test]
+fn baseline_primary_is_not_the_seed_and_that_is_official() {
+    // 常见误解：官方基线的 primary 应该等于种子 #6750A4。官方不是——Tonal Spot 变体把
+    // primary 的彩度固定成 36，而 #6750A4 的 HCT 彩度是 47.86，所以 primary 被收到 #65558F。
+    // 这也是 Flutter `ColorScheme.fromSeed(0xFF6750A4)` 的 primary 值。
+    let seed = Hct::from_color(BASELINE_SEED);
+    assert!(
+        (seed.chroma - 47.856_526).abs() < 1.0e-4,
+        "种子彩度 {}",
+        seed.chroma
+    );
+    let primary = Scheme::official_baseline(SchemeFlavor::Light).get(Role::Primary);
+    assert_eq!(primary.to_hex(), "#65558F");
+    assert_ne!(primary, BASELINE_SEED);
+}
+
+#[test]
+fn baseline_tone_axis_is_still_exact_lstar() {
+    // gamut 映射只动彩度，不动 tone：每个角色的实测 L* 与它声明的 tone 相差 ≤1。
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let scheme = Scheme::official_baseline(flavor);
+        for (role, color) in scheme.iter() {
+            let tone = Scheme::tone_of(role, flavor);
+            let got = f64::from(color.lstar());
+            assert!(
+                (got - tone).abs() <= 1.0,
+                "{}/{} 的 tone 声明 {tone}、实测 {got}",
+                flavor.name(),
+                role.name()
+            );
+        }
+    }
+}
+
+#[test]
+fn same_family_containers_are_separated_by_hct_chroma() {
+    // 旧缺陷①：light 下 primary-container 与 secondary-container 撞色。
+    // 现在两者彩度不同（36 vs 16），在 tone 90 上都不会被色域裁到同一个上限。
+    let light = Scheme::official_baseline(SchemeFlavor::Light);
+    let primary = light.get(Role::PrimaryContainer);
+    let secondary = light.get(Role::SecondaryContainer);
+    assert_ne!(primary, secondary);
+    let c_primary = Hct::from_color(primary).chroma;
+    let c_secondary = Hct::from_color(secondary).chroma;
+    assert!(
+        c_secondary < c_primary,
+        "secondary-container 彩度 {c_secondary} 应低于 primary-container {c_primary}"
+    );
+    // 深层原因：tone 90 上彩度 36 装得下，所以容器色是「真的有彩度的浅色」而不是被裁到灰。
+    assert!(c_primary > 12.0, "primary-container 彩度只剩 {c_primary}");
+}

crates/design/tests/skyseed_candidates.rs

@@ -0,0 +1,341 @@
+//! M70：默认色候选（保守蓝 / 冷调蓝 / 浅冷蓝 / 天蓝）——四档的**唯一真源**与 pin。
+//!
+//! ## 这档候选到底改了什么
+//!
+//! 四档走的是**同一条** HCT 管道（`Palettes::from_seed_with_neutral_chroma` → `ColorSpec2021`
+//! tone 表 → `HctSolver` gamut 映射），差别只有两个入参：
+//!
+//! | 档 | 种子 | 种子 HCT 色相 | 中性调色板彩度 | 表面 | 主色观感 |
+//! |---|---|---|---|---|---|
+//! | ① 保守蓝 | `#2196F3` | 253.7° | 6（官方） | 近白/近黑，几乎无色 | 钢蓝 |
+//! | ② 冷调蓝 | `#2196F3` | 253.7° | 12 | 冷白/冷黑，带淡蓝调 | 钢蓝 |
+//! | ③ 浅冷蓝（备选） | `#87CEEB`（CSS `skyblue`） | 225.7° | 12 | 浅天蓝 | 偏青（teal） |
+//! | ④ 天蓝（**出厂默认，用户 2026-11-01 拍板**） | `#3C8DBC` | 239.5° | 12 | 浅天蓝 | 偏蓝的天蓝 |
+//!
+//! ③ 与 ④ 是同一件事的两种「蓝」：色相越低越偏青（teal），越高越偏钢蓝；
+//! 239.5° 正好夹在中间，主色从 ③ 的 `#0C6780` 变成 `#236488`。
+//!
+//! 两条必须知道的物理事实（写在测试里，免得下次又有人想「把主色调浅一点」）：
+//!
+//! 1. **种子彩度是废参数**：Tonal Spot 把 primary 彩度钉在 36，种子只贡献色相。
+//!    所以「低彩度天蓝种子」得到的色板与「高彩度天蓝种子」**逐像素相同**
+//!    （`seed_chroma_never_leaks_into_the_primary_ramp` 在 `palettes.rs` 里也钉了这条）。
+//!    ③ 与 ② 的真正差别是**色相**（226° vs 254°），不是彩度。
+//! 2. **primary 的 tone 被钉在 40**，所以四档主色都是「中蓝」，不会更浅。
+//!    「浅」只能落在中性色上——这就是②/③/④提高中性彩度的原因，也是本项目唯一一处
+//!    对官方 Tonal Spot 的**有意偏离**（登记在 `color` 模块文档的「出厂默认色」小节）。
+//!
+//! ## 换默认色要动哪里
+//!
+//! `palettes::DEFAULT_SEED` / `palettes::DEFAULT_NEUTRAL_CHROMA` 两行常量，
+//! 然后重跑本文件：pin 表会逐角色告诉你哪几个 hex 变了，照抄即可（pin 是**抄本**，不是推导）。
+
+use unlucky_design::color::{
+    Color, Hct, Palettes, Role, Scheme, SchemeFlavor, DEFAULT_NEUTRAL_CHROMA, DEFAULT_SEED,
+};
+
+/// 一档候选：只有两个变量（种子 + 中性彩度），其余全是官方常数。
+struct Candidate {
+    /// 短标签（色卡与 CSV 用）。
+    tag: &'static str,
+    /// 中文档名。
+    title: &'static str,
+    /// 种子 hex。
+    seed_hex: &'static str,
+    /// 中性调色板彩度（官方 Tonal Spot 是 6）。
+    neutral_chroma: f64,
+    /// 9 个展示角色的 **(角色, light, dark)** 抄本。
+    pins: [(Role, &'static str, &'static str); 9],
+}
+
+/// 四档候选（色卡 `DevDocs/ops/skyseed-candidates/` 用的就是这份数据）。
+const CANDIDATES: [Candidate; 4] = [
+    Candidate {
+        tag: "C1",
+        title: "① 保守蓝（中性彩度 6 = 官方）",
+        seed_hex: "#2196F3",
+        neutral_chroma: 6.0,
+        pins: [
+            (Role::Primary, "#36618E", "#A0CAFD"),
+            (Role::OnPrimary, "#FFFFFF", "#003258"),
+            (Role::PrimaryContainer, "#D1E4FF", "#194975"),
+            (Role::Secondary, "#535F70", "#BBC7DB"),
+            (Role::Tertiary, "#6B5778", "#D6BEE4"),
+            (Role::Surface, "#F8F9FF", "#111418"),
+            (Role::SurfaceContainerLow, "#F2F3FA", "#191C20"),
+            (Role::SurfaceContainerHighest, "#E1E2E8", "#32353A"),
+            (Role::Outline, "#73777F", "#8D9199"),
+        ],
+    },
+    Candidate {
+        tag: "C2",
+        title: "② 冷调蓝（中性彩度 12）",
+        seed_hex: "#2196F3",
+        neutral_chroma: 12.0,
+        pins: [
+            (Role::Primary, "#36618E", "#A0CAFD"),
+            (Role::OnPrimary, "#FFFFFF", "#003258"),
+            (Role::PrimaryContainer, "#D1E4FF", "#194975"),
+            (Role::Secondary, "#535F70", "#BBC7DB"),
+            (Role::Tertiary, "#6B5778", "#D6BEE4"),
+            (Role::Surface, "#F8F9FF", "#0C141E"),
+            (Role::SurfaceContainerLow, "#EEF4FF", "#141C26"),
+            (Role::SurfaceContainerHighest, "#DBE3F1", "#2D3540"),
+            (Role::Outline, "#6D7887", "#8791A1"),
+        ],
+    },
+    Candidate {
+        tag: "C3",
+        title: "③ 浅冷蓝（中性彩度 12 + 偏青天蓝种子）",
+        seed_hex: "#87CEEB",
+        neutral_chroma: 12.0,
+        pins: [
+            (Role::Primary, "#0C6780", "#89D0ED"),
+            (Role::OnPrimary, "#FFFFFF", "#003544"),
+            (Role::PrimaryContainer, "#BAEAFF", "#004D62"),
+            (Role::Secondary, "#4C626B", "#B3CAD5"),
+            (Role::Tertiary, "#5B5B7E", "#C4C3EB"),
+            (Role::Surface, "#F3FAFF", "#07151B"),
+            (Role::SurfaceContainerLow, "#E7F6FE", "#0F1D23"),
+            (Role::SurfaceContainerHighest, "#D6E5ED", "#29373D"),
+            (Role::Outline, "#687A82", "#81949C"),
+        ],
+    },
+    Candidate {
+        tag: "C4",
+        title: "④ 天蓝（中性彩度 12 + 夹在中间的天蓝种子）",
+        seed_hex: "#3C8DBC",
+        neutral_chroma: 12.0,
+        pins: [
+            (Role::Primary, "#236488", "#93CDF6"),
+            (Role::OnPrimary, "#FFFFFF", "#00344C"),
+            (Role::PrimaryContainer, "#C8E6FF", "#004C6D"),
+            (Role::Secondary, "#4F616E", "#B7C9D8"),
+            (Role::Tertiary, "#63597C", "#CDC0E9"),
+            (Role::Surface, "#F6FAFF", "#09151C"),
+            (Role::SurfaceContainerLow, "#EBF5FF", "#111D25"),
+            (Role::SurfaceContainerHighest, "#D8E4EF", "#2B363F"),
+            (Role::Outline, "#6A7985", "#84939F"),
+        ],
+    },
+];
+
+/// 四档共同点：种子的 HCT 坐标（色相是候选之间**唯一**有效的差别）。
+fn seed_hct(candidate: &Candidate) -> Hct {
+    Hct::from_color(Color::from_hex(candidate.seed_hex).expect("候选种子必须是合法 hex"))
+}
+
+/// 按候选参数走**产品同一条**派生路径。
+fn scheme(candidate: &Candidate, flavor: SchemeFlavor) -> Scheme {
+    Scheme::from_palettes(
+        &Palettes::from_seed_with_neutral_chroma(
+            seed_hct(candidate).to_color(),
+            candidate.neutral_chroma,
+        ),
+        flavor,
+    )
+}
+
+#[test]
+fn candidates_match_their_pins() {
+    let mut drift = Vec::new();
+    for candidate in &CANDIDATES {
+        for (role, want_light, want_dark) in candidate.pins {
+            for (flavor, want_hex) in [
+                (SchemeFlavor::Light, want_light),
+                (SchemeFlavor::Dark, want_dark),
+            ] {
+                let got = scheme(candidate, flavor).get(role).to_hex();
+                if got != want_hex {
+                    drift.push(format!(
+                        "{}{} / {}/{} 实测 {got}，pin {want_hex}",
+                        candidate.tag,
+                        if flavor.is_dark() { "-dark" } else { "" },
+                        candidate.title,
+                        role.name()
+                    ));
+                }
+            }
+        }
+    }
+    assert!(
+        drift.is_empty(),
+        "候选色值漂了（换默认色后请照抄下面这些 hex 到 pin 表）：\n{}",
+        drift.join("\n")
+    );
+}
+
+#[test]
+fn candidates_only_move_the_two_declared_inputs() {
+    // 「不绕算法」的证据：四档的调色板彩度与官方 Tonal Spot 逐项一致，
+    // 唯一的差别是中性彩度的入参（以及种子色相）。
+    let official = Palettes::official_baseline();
+    for candidate in &CANDIDATES {
+        let p = Palettes::from_seed_with_neutral_chroma(
+            seed_hct(candidate).to_color(),
+            candidate.neutral_chroma,
+        );
+        assert_eq!(p.primary.chroma(), official.primary.chroma());
+        assert_eq!(p.secondary.chroma(), official.secondary.chroma());
+        assert_eq!(p.tertiary.chroma(), official.tertiary.chroma());
+        assert_eq!(p.error, official.error, "error 族不该被候选影响");
+        assert_eq!(p.neutral.chroma(), candidate.neutral_chroma);
+        assert!(
+            (p.tertiary.hue_deg() - (p.primary.hue_deg() + 60.0)).abs() < 1.0e-9,
+            "{} 的 tertiary 不再是 +60°",
+            candidate.tag
+        );
+    }
+}
+
+#[test]
+fn the_candidates_are_actually_distinguishable() {
+    // 「四档不像同一档」的机器判据。注意 light 的 surface（tone 98）在 8 bit 下已经贴顶，
+    // 中性彩度 6→12 会量化到同一个 #F8F9FF——所以 ①② 的判据落在 container 系与 dark 模式上，
+    // 这也是色卡上 ①② 的差别主要体现在卡片/浮层与深色模式的原因。
+    let light = |c: &Candidate| scheme(c, SchemeFlavor::Light);
+    let dark = |c: &Candidate| scheme(c, SchemeFlavor::Dark);
+    let (c1, c2, c3, c4) = (
+        light(&CANDIDATES[0]),
+        light(&CANDIDATES[1]),
+        light(&CANDIDATES[2]),
+        light(&CANDIDATES[3]),
+    );
+    for role in [Role::SurfaceContainerLow, Role::SurfaceContainerHighest] {
+        assert_ne!(
+            c1.get(role),
+            c2.get(role),
+            "①与②的 {} 相同：中性彩度没起作用",
+            role.name()
+        );
+        assert_ne!(c2.get(role), c3.get(role), "②与③的 {} 相同", role.name());
+        // ③④ 的中性彩度相同，差别只允许来自色相
+        assert_ne!(c3.get(role), c4.get(role), "③与④的 {} 相同", role.name());
+    }
+    assert_ne!(
+        c3.get(Role::Primary),
+        c4.get(Role::Primary),
+        "③与④的主色必须真的不同（否则第 4 档白加）"
+    );
+    assert_ne!(
+        dark(&CANDIDATES[0]).get(Role::Surface),
+        dark(&CANDIDATES[1]).get(Role::Surface),
+        "深色模式的 surface 应当能看出中性彩度差别"
+    );
+    let hue_gap = |a: &Candidate, b: &Candidate| {
+        let (x, y) = (seed_hct(a).hue, seed_hct(b).hue);
+        (x - y).abs().min(360.0 - (x - y).abs())
+    };
+    assert!(
+        hue_gap(&CANDIDATES[0], &CANDIDATES[1]) < 0.01,
+        "①② 应当只差中性彩度"
+    );
+    // ③ 偏青 / ④ 居中的分界靠色相：②→③ 与 ③→④ 都要肉眼可分的量级。
+    for (i, j) in [(1, 2), (2, 3)] {
+        assert!(
+            (10.0..=40.0).contains(&hue_gap(&CANDIDATES[i], &CANDIDATES[j])),
+            "{}→{} 的色相差应当明显（10°~40°），实测 {}",
+            CANDIDATES[i].tag,
+            CANDIDATES[j].tag,
+            hue_gap(&CANDIDATES[i], &CANDIDATES[j])
+        );
+    }
+}
+
+#[test]
+fn product_default_is_the_adopted_candidate() {
+    // 用户 2026-11-01 拍板采用 **④ 天蓝**。这条用例就是「默认值 ↔ 候选表」的绑定器：
+    // 谁改了 `DEFAULT_SEED`/`DEFAULT_NEUTRAL_CHROMA` 却没同步这里（或反过来），它会立刻红。
+    // 断言一律比 **hex / 数值**，这样失败信息里直接能读到「期望 ④、实测几」。
+    let adopted = &CANDIDATES[3];
+    assert_eq!(
+        DEFAULT_SEED.to_hex(),
+        "#3C8DBC",
+        "DEFAULT_SEED 必须仍是已采用的 ④ 天蓝：期望 #3C8DBC（④），实测 {}（{}）",
+        DEFAULT_SEED.to_hex(),
+        if DEFAULT_SEED.to_hex() == CANDIDATES[2].seed_hex {
+            "③ 浅冷蓝——要改回 ③ 请连偏离登记与 pin 一起改"
+        } else {
+            "不是候选表里的任何一个种子"
+        }
+    );
+    assert_eq!(
+        DEFAULT_SEED.to_hex(),
+        adopted.seed_hex,
+        "DEFAULT_SEED（{}）与已采用档 {} 的种子（{}）不一致",
+        DEFAULT_SEED.to_hex(),
+        adopted.tag,
+        adopted.seed_hex
+    );
+    assert_eq!(
+        DEFAULT_NEUTRAL_CHROMA, 12.0,
+        "DEFAULT_NEUTRAL_CHROMA 必须仍是已采用的 12，实测 {}",
+        DEFAULT_NEUTRAL_CHROMA
+    );
+    assert_eq!(
+        DEFAULT_NEUTRAL_CHROMA, adopted.neutral_chroma,
+        "DEFAULT_NEUTRAL_CHROMA（{}）与已采用档 {} 的中性彩度（{}）不一致",
+        DEFAULT_NEUTRAL_CHROMA, adopted.tag, adopted.neutral_chroma
+    );
+    for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+        let product = Scheme::baseline(flavor);
+        let expected = scheme(adopted, flavor);
+        for (role, got) in product.iter() {
+            assert_eq!(
+                got.to_hex(),
+                expected.get(role).to_hex(),
+                "产品默认与已采用档 {} 的 {}（{} 模式）不一致",
+                adopted.tag,
+                role.name(),
+                flavor.name()
+            );
+        }
+    }
+}
+
+#[test]
+fn surface_tint_stays_a_tint() {
+    // 门禁：中性彩度提高是「淡蓝调」不是「把窗口染成蓝纸」。surface 的 HCT 彩度必须
+    // 明显低于 primary 的 36，且 surface 的 Y 仍 > 0.85（浅色模式还是浅底）。
+    for candidate in &CANDIDATES {
+        let light = scheme(candidate, SchemeFlavor::Light);
+        let surface = light.get(Role::Surface);
+        let chroma = Hct::from_color(surface).chroma;
+        assert!(
+            chroma <= 1.2 * candidate.neutral_chroma,
+            "{} 的 surface 彩度 {chroma} 超过中性彩度入参的两倍",
+            candidate.tag
+        );
+        assert!(surface.relative_luminance() > 0.85);
+    }
+}
+
+#[test]
+fn dump_candidates_for_the_color_card() {
+    // 色卡脚本读的就是这两行格式（`SEED|` / `ROLE|`）。跑法：
+    //   cargo test -p unlucky-design --test skyseed_candidates -- --nocapture
+    for candidate in &CANDIDATES {
+        let hct = seed_hct(candidate);
+        println!(
+            "SEED|{}|{}|{}|{}|hue={:.2}|chroma={:.2}",
+            candidate.tag,
+            candidate.title,
+            candidate.seed_hex,
+            candidate.neutral_chroma,
+            hct.hue,
+            hct.chroma
+        );
+        for flavor in [SchemeFlavor::Light, SchemeFlavor::Dark] {
+            let s = scheme(candidate, flavor);
+            for role in Role::ALL {
+                println!(
+                    "ROLE|{}|{}|{}|{}",
+                    candidate.tag,
+                    flavor.name(),
+                    role.name(),
+                    s.get(role).to_hex().trim_start_matches('#')
+                );
+            }
+        }
+    }
+}

crates/design/tests/token_contract.rs

@@ -0,0 +1,228 @@
+//! 令牌契约测试：从**消费方视角**（只用公开 API）钉住 M61 承诺的那些性质。
+//!
+//! 这份测试的作用是「冻结」：`IconKind`/`Role` 的次序与个数、type scale 的取值、形状/高程阶梯、
+//! 描边的 SVG 语义换算。后续 iced 页面线靠它保证不会因为一次「顺手改动」而悄悄换观感。
+
+use unlucky_design::color::{Role, Scheme, SchemeFlavor, TonalPalette};
+use unlucky_design::component_map::Component;
+use unlucky_design::elevation::{Elevation, MaterialLayer};
+use unlucky_design::icons::{
+    stroke_width_for, visual_stroke_px, IconKind, IconPaint, IconSize, VIEWBOX,
+};
+use unlucky_design::motion::{
+    DurationToken, Easing, MotionScale, SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+};
+use unlucky_design::shape::ShapeScale;
+use unlucky_design::spacing::{LayoutMetrics, Space};
+use unlucky_design::typography::{FontFamily, Platform, TypeRole, Weight};
+use unlucky_design::DesignTokens;
+
+#[test]
+fn color_role_table_is_frozen() {
+    assert_eq!(Role::ALL.len(), 49, "M3 基础角色集共 49 个");
+    assert_eq!(Role::ALL[0], Role::Primary);
+    assert_eq!(Role::ALL[16], Role::Surface);
+    assert_eq!(Role::ALL[48], Role::OnTertiaryFixedVariant);
+    // 每个角色都能从两套 scheme 里取到值，且前景角色都带 on- 语义。
+    let light = Scheme::baseline(SchemeFlavor::Light);
+    let dark = Scheme::baseline(SchemeFlavor::Dark);
+    for role in Role::ALL {
+        assert!(
+            light.get(role).is_opaque(),
+            "{} 应当是不透明色",
+            role.name()
+        );
+        assert!(dark.get(role).is_opaque());
+        if role.name().starts_with("on-") {
+            assert!(role.is_foreground(), "{} 应被判为前景色", role.name());
+        }
+    }
+    assert!(light.get(Role::Primary).is_opaque());
+}
+
+#[test]
+fn tone_mapping_is_the_m3_table() {
+    // 抽查几行关键映射（light / dark），防止有人改 tone 表时静默换观感。
+    assert_eq!(Scheme::tone_of(Role::Primary, SchemeFlavor::Light), 40.0);
+    assert_eq!(Scheme::tone_of(Role::Surface, SchemeFlavor::Light), 98.0);
+    assert_eq!(Scheme::tone_of(Role::Surface, SchemeFlavor::Dark), 6.0);
+    assert_eq!(
+        Scheme::tone_of(Role::OnPrimaryContainer, SchemeFlavor::Dark),
+        90.0
+    );
+    assert_eq!(Scheme::tone_of(Role::Outline, SchemeFlavor::Light), 50.0);
+}
+
+#[test]
+fn type_scale_values_are_the_m3_baseline() {
+    assert_eq!(TypeRole::ALL.len(), 15);
+    let title = TypeRole::TitleLarge.style();
+    assert_eq!((title.size_px, title.line_height_px), (22.0, 28.0));
+    let body = TypeRole::BodyMedium.style();
+    assert_eq!((body.size_px, body.line_height_px), (14.0, 20.0));
+    assert_eq!(body.weight, Weight::Regular);
+    let label = TypeRole::LabelLarge.style();
+    assert_eq!(label.weight, Weight::Medium);
+    assert_eq!(TypeRole::BodySmall.style().size_px, 12.0);
+    // 强调档只动字重。
+    assert_eq!(TypeRole::TitleLarge.emphasized().size_px, 22.0);
+    assert!(TypeRole::TitleMedium.emphasized().weight.value() > Weight::Medium.value());
+}
+
+#[test]
+fn font_stacks_never_embed_font_files() {
+    for platform in [Platform::Windows, Platform::MacOs, Platform::Linux] {
+        for family in [FontFamily::Display, FontFamily::Text, FontFamily::Mono] {
+            let stack = platform.font_stack(family);
+            assert!(!stack.is_empty());
+            for face in stack {
+                let lower = face.family.to_ascii_lowercase();
+                for banned in [".ttf", ".otf", ".ttc", "woff", "file"] {
+                    assert!(
+                        !lower.contains(banned),
+                        "{} 的字体栈出现文件引用 {}（只允许族名，禁止内嵌受限字体）",
+                        platform.name(),
+                        face.family
+                    );
+                }
+            }
+        }
+    }
+}
+
+#[test]
+fn cjk_weight_gap_is_registered() {
+    // 中文 700（Expressive 强调档要用的）在三平台都要能找到原生落点，否则就是合成加粗降级。
+    use unlucky_design::typography::{Weight, WeightMatch};
+    // Windows：Segoe UI Variable 覆盖 700（原生）；CJK 落点是雅黑 700（原生，雅黑有 Bold）。
+    let win = Platform::Windows.resolve_weight(FontFamily::Text, Weight::Bold);
+    assert_eq!(win.quality, WeightMatch::Native);
+    assert!(Platform::Windows.cjk_face().supports(Weight::Bold));
+    // macOS：苹方只到 600 → CJK 的 700 只能合成/换族，这条 gap 已在文档登记。
+    assert!(!Platform::MacOs.cjk_face().supports(Weight::Bold));
+    // Linux：Noto Sans CJK 可变字体全覆盖。
+    for weight in [Weight::Regular, Weight::Medium, Weight::Bold] {
+        assert!(Platform::Linux.cjk_face().supports(weight));
+    }
+}
+
+#[test]
+fn icon_kind_is_frozen_and_append_only() {
+    assert_eq!(IconKind::ALL.len(), 28, "M61 冻结 28 个图标");
+    // 迁移来的 24 个必须保持原次序（序号即持久化 id）。
+    assert_eq!(IconKind::ALL[0], IconKind::Instances);
+    assert_eq!(IconKind::ALL[4], IconKind::Ai);
+    assert_eq!(IconKind::ALL[20], IconKind::More);
+    assert_eq!(IconKind::ALL[23], IconKind::User);
+    // 新增的 4 个追加在末尾。
+    assert_eq!(IconKind::ALL[24], IconKind::Refresh);
+    assert_eq!(IconKind::ALL[27], IconKind::Trash);
+    for kind in IconKind::ALL {
+        assert!(kind.icon().path.starts_with('M'));
+        assert_eq!(kind.icon().kind, kind);
+    }
+}
+
+#[test]
+fn icon_stroke_follows_svg_semantics_not_slint() {
+    // Slint 口径（绝对 1.5px）在 20px 渲染下会得到 1.5px 视觉线宽；SVG 口径要写 1.8。
+    let nav_width = IconKind::Settings.icon().stroke_width(IconSize::Nav.px());
+    assert!(
+        (nav_width - 1.8).abs() < 1.0e-6,
+        "20px 渲染应取 1.8 个 viewBox 单位"
+    );
+    let button_width = IconKind::Settings
+        .icon()
+        .stroke_width(IconSize::Button.px());
+    assert!((button_width - 2.25).abs() < 1.0e-6);
+    // 视觉宽度的往返一致性（这条是「别照抄 Slint 的 1.5」的守门测试）。
+    for size in IconSize::ALL {
+        let w = stroke_width_for(size.px(), 1.5);
+        assert!((visual_stroke_px(size.px(), w) - 1.5).abs() < 1.0e-6);
+    }
+    assert!((VIEWBOX - 24.0).abs() < f32::EPSILON);
+    // 实心图标不描边。
+    assert_eq!(IconKind::Play.icon().paint, IconPaint::Fill);
+    assert_eq!(IconKind::Play.icon().stroke_width(24.0), 0.0);
+}
+
+#[test]
+fn shape_and_elevation_ladders() {
+    assert_eq!(ShapeScale::ExtraSmall.dp(), 4.0);
+    assert_eq!(ShapeScale::Medium.dp(), 12.0);
+    assert_eq!(ShapeScale::ExtraLarge.dp(), 28.0);
+    assert_eq!(ShapeScale::Full.radius_px(40.0), 20.0);
+    assert!(ShapeScale::ExtraLargeIncreased.is_expressive());
+
+    let dp: Vec<f32> = Elevation::ALL.iter().map(|e| e.dp()).collect();
+    assert_eq!(dp, vec![0.0, 1.0, 3.0, 6.0, 8.0, 12.0]);
+    assert_eq!(
+        MaterialLayer::Card.surface_role(),
+        Role::SurfaceContainerLow
+    );
+}
+
+#[test]
+fn motion_tokens_are_usable_as_data() {
+    assert_eq!(DurationToken::Medium2.ms(), 300);
+    assert!((Easing::Standard.sample(0.0)).abs() < 1.0e-6);
+    assert!((Easing::Standard.sample(1.0) - 1.0).abs() < 1.0e-6);
+    let settle = SPRING_EXPRESSIVE_SPATIAL_DEFAULT.settle_ms(0.001);
+    assert!(settle > 0.0 && settle < 2000.0);
+    assert_eq!(MotionScale::NONE.ms(DurationToken::Long4), 0.0);
+}
+
+#[test]
+fn spacing_and_layout_metrics_are_shared() {
+    assert_eq!(Space::X4.dp(), 16.0);
+    let metrics = LayoutMetrics::DESKTOP;
+    assert_eq!(metrics.header_height(false), 56.0);
+    assert_eq!(metrics.header_height(true), 84.0);
+}
+
+#[test]
+fn component_map_covers_the_page_skeleton() {
+    // M69（G9）在末尾追加 Checkbox/Radio/Search/NavigationDrawer/Divider：20 → 25。
+    assert_eq!(Component::ALL.len(), 25);
+    for component in Component::ALL {
+        let spec = component.spec();
+        assert_eq!(spec.component, component);
+        assert!(spec.text.style().size_px >= 11.0);
+    }
+    assert_eq!(Component::PrimaryButton.spec().shape, ShapeScale::Full);
+    // 浮层必须高于卡片层。
+    assert!(Component::Dialog.spec().elevation > Component::OutlinedCard.spec().elevation);
+    // 末尾追加的 5 个不许改动既有次序。
+    assert_eq!(Component::ALL[0], Component::TopAppBar);
+    assert_eq!(Component::ALL[19], Component::EmptyState);
+}
+
+#[test]
+fn design_tokens_entry_point() {
+    let light = DesignTokens::baseline(SchemeFlavor::Light);
+    let dark = DesignTokens::baseline(SchemeFlavor::Dark);
+    assert_eq!(light.flavor, SchemeFlavor::Light);
+    assert!(light.color(Role::Surface).relative_luminance() > 0.8);
+    assert!(dark.color(Role::Surface).relative_luminance() < 0.05);
+    assert!(!light.motion_scale.is_off());
+
+    let accent = DesignTokens::with_accent(
+        SchemeFlavor::Light,
+        unlucky_design::Color::from_hex("#006A5C").unwrap(),
+    );
+    assert_ne!(accent.color(Role::Primary), light.color(Role::Primary));
+    assert_eq!(accent.color(Role::Surface), light.color(Role::Surface));
+}
+
+#[test]
+fn tonal_palette_hits_requested_tones() {
+    let palette = TonalPalette::new(150.0, 36.0);
+    for tone in [20.0_f64, 40.0, 60.0, 80.0] {
+        let color = palette.tone(tone);
+        assert!(
+            (f64::from(color.lstar()) - tone).abs() <= 1.0,
+            "tone {tone} 实际 {}",
+            color.lstar()
+        );
+    }
+}

crates/design/tests/token_pins.rs

@@ -0,0 +1,252 @@
+//! 官方数值钉死（二）：**色彩 tone 表 49 条**、7 条 easing 曲线、16 档时长、28 个图标下标、
+//! 形状阶梯，以及「同族容器不撞色」的回归（reviewer P3-2）。
+//!
+//! 期望值全部独立于实现重写；实现改一个数、表不改，这里就红。
+
+use unlucky_design::color::{Role, Scheme, SchemeFlavor};
+use unlucky_design::icons::IconKind;
+use unlucky_design::motion::{DurationToken, Easing};
+use unlucky_design::shape::ShapeScale;
+
+fn expect_tone(role: Role, light: f64, dark: f64) {
+    assert_eq!(
+        Scheme::tone_of(role, SchemeFlavor::Light),
+        light,
+        "{} 的 light tone 被改动了",
+        role.name()
+    );
+    assert_eq!(
+        Scheme::tone_of(role, SchemeFlavor::Dark),
+        dark,
+        "{} 的 dark tone 被改动了",
+        role.name()
+    );
+}
+
+#[test]
+fn all_forty_nine_tones_are_pinned() {
+    expect_tone(Role::Primary, 40.0, 80.0);
+    expect_tone(Role::OnPrimary, 100.0, 20.0);
+    expect_tone(Role::PrimaryContainer, 90.0, 30.0);
+    expect_tone(Role::OnPrimaryContainer, 30.0, 90.0);
+    expect_tone(Role::Secondary, 40.0, 80.0);
+    expect_tone(Role::OnSecondary, 100.0, 20.0);
+    expect_tone(Role::SecondaryContainer, 90.0, 30.0);
+    expect_tone(Role::OnSecondaryContainer, 30.0, 90.0);
+    expect_tone(Role::Tertiary, 40.0, 80.0);
+    expect_tone(Role::OnTertiary, 100.0, 20.0);
+    expect_tone(Role::TertiaryContainer, 90.0, 30.0);
+    expect_tone(Role::OnTertiaryContainer, 30.0, 90.0);
+    expect_tone(Role::Error, 40.0, 80.0);
+    expect_tone(Role::OnError, 100.0, 20.0);
+    expect_tone(Role::ErrorContainer, 90.0, 30.0);
+    expect_tone(Role::OnErrorContainer, 30.0, 90.0);
+    expect_tone(Role::Surface, 98.0, 6.0);
+    expect_tone(Role::OnSurface, 10.0, 90.0);
+    expect_tone(Role::SurfaceVariant, 90.0, 30.0);
+    expect_tone(Role::OnSurfaceVariant, 30.0, 80.0);
+    expect_tone(Role::Background, 98.0, 6.0);
+    expect_tone(Role::OnBackground, 10.0, 90.0);
+    expect_tone(Role::SurfaceDim, 87.0, 6.0);
+    expect_tone(Role::SurfaceBright, 98.0, 24.0);
+    expect_tone(Role::SurfaceContainerLowest, 100.0, 4.0);
+    expect_tone(Role::SurfaceContainerLow, 96.0, 10.0);
+    expect_tone(Role::SurfaceContainer, 94.0, 12.0);
+    expect_tone(Role::SurfaceContainerHigh, 92.0, 17.0);
+    expect_tone(Role::SurfaceContainerHighest, 90.0, 22.0);
+    expect_tone(Role::Outline, 50.0, 60.0);
+    expect_tone(Role::OutlineVariant, 80.0, 30.0);
+    expect_tone(Role::InverseSurface, 20.0, 90.0);
+    expect_tone(Role::InverseOnSurface, 95.0, 20.0);
+    expect_tone(Role::InversePrimary, 80.0, 40.0);
+    expect_tone(Role::Shadow, 0.0, 0.0);
+    expect_tone(Role::Scrim, 0.0, 0.0);
+    expect_tone(Role::SurfaceTint, 40.0, 80.0);
+    expect_tone(Role::PrimaryFixed, 90.0, 90.0);
+    expect_tone(Role::PrimaryFixedDim, 80.0, 80.0);
+    expect_tone(Role::OnPrimaryFixed, 10.0, 10.0);
+    expect_tone(Role::OnPrimaryFixedVariant, 30.0, 30.0);
+    expect_tone(Role::SecondaryFixed, 90.0, 90.0);
+    expect_tone(Role::SecondaryFixedDim, 80.0, 80.0);
+    expect_tone(Role::OnSecondaryFixed, 10.0, 10.0);
+    expect_tone(Role::OnSecondaryFixedVariant, 30.0, 30.0);
+    expect_tone(Role::TertiaryFixed, 90.0, 90.0);
+    expect_tone(Role::TertiaryFixedDim, 80.0, 80.0);
+    expect_tone(Role::OnTertiaryFixed, 10.0, 10.0);
+    expect_tone(Role::OnTertiaryFixedVariant, 30.0, 30.0);
+}
+
+#[test]
+fn easing_curves_are_pinned() {
+    let cases: [(Easing, f32, f32, f32, f32); 7] = [
+        (Easing::Linear, 0.0, 0.0, 1.0, 1.0),
+        (Easing::Standard, 0.2, 0.0, 0.0, 1.0),
+        (Easing::StandardDecelerate, 0.0, 0.0, 0.0, 1.0),
+        (Easing::StandardAccelerate, 0.3, 0.0, 1.0, 1.0),
+        (Easing::Emphasized, 0.2, 0.0, 0.0, 1.0),
+        (Easing::EmphasizedDecelerate, 0.05, 0.7, 0.1, 1.0),
+        (Easing::EmphasizedAccelerate, 0.3, 0.0, 0.8, 0.15),
+    ];
+    for (easing, x1, y1, x2, y2) in cases {
+        let curve = easing.curve();
+        assert_eq!(
+            (curve.x1, curve.y1, curve.x2, curve.y2),
+            (x1, y1, x2, y2),
+            "{easing:?} 的曲线参数被改动了"
+        );
+    }
+}
+
+#[test]
+fn durations_are_pinned() {
+    let cases: [(DurationToken, u32); 16] = [
+        (DurationToken::Short1, 50),
+        (DurationToken::Short2, 100),
+        (DurationToken::Short3, 150),
+        (DurationToken::Short4, 200),
+        (DurationToken::Medium1, 250),
+        (DurationToken::Medium2, 300),
+        (DurationToken::Medium3, 350),
+        (DurationToken::Medium4, 400),
+        (DurationToken::Long1, 450),
+        (DurationToken::Long2, 500),
+        (DurationToken::Long3, 550),
+        (DurationToken::Long4, 600),
+        (DurationToken::ExtraLong1, 700),
+        (DurationToken::ExtraLong2, 800),
+        (DurationToken::ExtraLong3, 900),
+        (DurationToken::ExtraLong4, 1000),
+    ];
+    for (token, ms) in cases {
+        assert_eq!(token.ms(), ms, "{} 的毫秒值被改动了", token.name());
+    }
+}
+
+#[test]
+fn spring_presets_are_pinned() {
+    use unlucky_design::motion::{
+        spring, MotionSchemeKind, Spring, SpringCategory, SpringSpeed, SPRING_EFFECTS_DEFAULT,
+        SPRING_EFFECTS_FAST, SPRING_EFFECTS_SLOW, SPRING_EXPRESSIVE_SPATIAL_DEFAULT,
+        SPRING_EXPRESSIVE_SPATIAL_FAST, SPRING_EXPRESSIVE_SPATIAL_SLOW,
+        SPRING_STANDARD_SPATIAL_DEFAULT, SPRING_STANDARD_SPATIAL_FAST,
+        SPRING_STANDARD_SPATIAL_SLOW,
+    };
+    // A 级：StandardMotionTokens / ExpressiveMotionTokens（damping = 阻尼比 ζ，stiffness = k）。
+    let cases: [(Spring, f32, f32); 9] = [
+        // standard 方案 spatial：ζ=0.9（保守）
+        (SPRING_STANDARD_SPATIAL_FAST, 1400.0, 0.9),
+        (SPRING_STANDARD_SPATIAL_DEFAULT, 700.0, 0.9),
+        (SPRING_STANDARD_SPATIAL_SLOW, 300.0, 0.9),
+        // expressive 方案 spatial：ζ=0.6/0.8（回弹明显）
+        (SPRING_EXPRESSIVE_SPATIAL_FAST, 800.0, 0.6),
+        (SPRING_EXPRESSIVE_SPATIAL_DEFAULT, 380.0, 0.8),
+        (SPRING_EXPRESSIVE_SPATIAL_SLOW, 200.0, 0.8),
+        // effects 两套同值：ζ=1.0（不过冲）
+        (SPRING_EFFECTS_FAST, 3800.0, 1.0),
+        (SPRING_EFFECTS_DEFAULT, 1600.0, 1.0),
+        (SPRING_EFFECTS_SLOW, 800.0, 1.0),
+    ];
+    for (entry, stiffness, damping_ratio) in cases {
+        assert_eq!(entry.stiffness, stiffness, "弹簧刚度被改动");
+        assert_eq!(entry.damping_ratio, damping_ratio, "弹簧阻尼比被改动");
+    }
+    // 二维表查询与常量必须一致（改了表结构也别想绕过 pin）。
+    assert_eq!(
+        spring(
+            MotionSchemeKind::Expressive,
+            SpringCategory::Spatial,
+            SpringSpeed::Default
+        ),
+        SPRING_EXPRESSIVE_SPATIAL_DEFAULT
+    );
+    assert_eq!(
+        spring(
+            MotionSchemeKind::Standard,
+            SpringCategory::Spatial,
+            SpringSpeed::Fast
+        ),
+        SPRING_STANDARD_SPATIAL_FAST
+    );
+}
+
+#[test]
+fn icon_indices_are_pinned() {
+    let names = [
+        "instances",
+        "download",
+        "logs",
+        "settings",
+        "ai",
+        "play",
+        "stop",
+        "search",
+        "plus",
+        "close",
+        "minimize",
+        "maximize",
+        "chevron-left",
+        "chevron-right",
+        "chevron-down",
+        "expand",
+        "send",
+        "check",
+        "warn",
+        "error",
+        "more",
+        "sidebar",
+        "restore",
+        "user",
+        "refresh",
+        "filter",
+        "folder",
+        "trash",
+    ];
+    assert_eq!(IconKind::ALL.len(), names.len());
+    for (i, kind) in IconKind::ALL.iter().enumerate() {
+        assert_eq!(
+            kind.name(),
+            names[i],
+            "第 {i} 个图标被换位/改名了（序号即持久化 id）"
+        );
+    }
+}
+
+#[test]
+fn shape_ladder_is_pinned() {
+    let cases: [(ShapeScale, f32); 9] = [
+        (ShapeScale::None, 0.0),
+        (ShapeScale::ExtraSmall, 4.0),
+        (ShapeScale::Small, 8.0),
+        (ShapeScale::Medium, 12.0),
+        (ShapeScale::Large, 16.0),
+        (ShapeScale::LargeIncreased, 20.0),
+        (ShapeScale::ExtraLarge, 28.0),
+        (ShapeScale::ExtraLargeIncreased, 32.0),
+        (ShapeScale::ExtraExtraLarge, 48.0),
+    ];
+    for (scale, dp) in cases {
+        assert_eq!(scale.dp(), dp, "{scale:?} 的半径档位被改动了");
+    }
+    assert_eq!(ShapeScale::Full.radius_px(64.0), 32.0);
+}
+
+#[test]
+fn same_family_containers_do_not_collide() {
+    // P3-2 回归：light 模式下 primary-container / secondary-container 曾经被 gamut 裁剪成同色。
+    let light = Scheme::baseline(SchemeFlavor::Light);
+    let primary = light.get(Role::PrimaryContainer);
+    let secondary = light.get(Role::SecondaryContainer);
+    assert_ne!(
+        primary, secondary,
+        "同族容器撞色（彩度压缩没生效）：{primary:?}"
+    );
+    // secondary-container 必须比 primary-container 更灰（M3 的「次级」语义）。
+    let c_primary = unlucky_design::color::Hct::from_color(primary).chroma;
+    let c_secondary = unlucky_design::color::Hct::from_color(secondary).chroma;
+    assert!(
+        c_secondary < c_primary,
+        "secondary-container 彩度 {c_secondary} 应低于 primary-container {c_primary}"
+    );
+    // tertiary 与 primary 也该可区分（不同色相）。
+    assert_ne!(light.get(Role::TertiaryContainer), primary);
+}

crates/design/tests/tokext_pins.rs

@@ -0,0 +1,297 @@
+//! M69（TOKEXT）的数值钉死：G9~G13 五项缺口逐条关门。
+//!
+//! 期望值全部**独立于实现重写**（照 `research/15` §18~§23 与 `00-decision-log.md` D32/D33 抄），
+//! 实现改一个数、这里不改就红。覆盖：
+//! - **G13** `ComponentRadius` 白名单 + 尺寸闸（2 不在 `ShapeScale` 里，刻度不许被加宽）；
+//! - **G11** `LayoutMetrics` 的 4 个新骨架值 + nav 语义修正；
+//! - **G10** `ComponentMetrics` 逐字段；
+//! - **G9** `Component` 25 个变体与档位表一行对一行；
+//! - **G12** 一像素线单一真源。
+
+use unlucky_design::component_map::{Component, ComponentMetrics};
+use unlucky_design::elevation::Elevation;
+use unlucky_design::icons::IconSize;
+use unlucky_design::shape::{radius_layer_for, ComponentRadius, RadiusLayer, ShapeScale};
+use unlucky_design::spacing::{stroke, LayoutMetrics, Space};
+use unlucky_design::typography::TypeRole;
+
+// ---------- G13：圆角分层（D32） ----------
+
+#[test]
+fn shape_scale_is_unchanged_and_never_contains_two() {
+    // 刻度一个字都不许动（D32 第 1 条：ShapeScale 保持严格）。
+    let ladder: [(ShapeScale, f32); 9] = [
+        (ShapeScale::None, 0.0),
+        (ShapeScale::ExtraSmall, 4.0),
+        (ShapeScale::Small, 8.0),
+        (ShapeScale::Medium, 12.0),
+        (ShapeScale::Large, 16.0),
+        (ShapeScale::LargeIncreased, 20.0),
+        (ShapeScale::ExtraLarge, 28.0),
+        (ShapeScale::ExtraLargeIncreased, 32.0),
+        (ShapeScale::ExtraExtraLarge, 48.0),
+    ];
+    for (scale, dp) in ladder {
+        assert_eq!(scale.dp(), dp, "{scale:?} 的刻度被改动了");
+        // 2 是官方 Checkbox 的圆角，但它**不在**刻度里——加进来就等于废掉 K1 守门。
+        assert_ne!(dp, 2.0, "2dp 不许进 ShapeScale（走 ComponentRadius）");
+    }
+    assert_eq!(ShapeScale::Full.radius_px(64.0), 32.0);
+}
+
+#[test]
+fn component_radius_is_a_one_item_whitelist() {
+    assert_eq!(ComponentRadius::ALL, [ComponentRadius::Micro]);
+    // 2dp 只能通过带尺寸闸的 `radius_px` 拿到（`dp()` 是 crate 内部口，外部看不见）。
+    assert_eq!(
+        ComponentRadius::Micro.radius_px(20.0),
+        Some(2.0),
+        "官方 Checkbox RadiusSize = 2.dp"
+    );
+    // 尺寸闸：>24dp 一律拿不到微半径（D32 的「只允许 ≤24dp 微控件」）。
+    assert_eq!(ComponentRadius::Micro.radius_px(24.0), Some(2.0));
+    assert_eq!(ComponentRadius::Micro.radius_px(25.0), None);
+    assert_eq!(ComponentRadius::Micro.radius_px(240.0), None);
+    assert_eq!(ComponentRadius::Micro.radius_px(0.0), None);
+    // 边长小于两倍半径时按边长一半折算（2dp 元素不能有 2dp 圆角）。
+    assert_eq!(ComponentRadius::Micro.radius_px(2.0), Some(1.0));
+}
+
+#[test]
+fn radius_layer_for_routes_by_size() {
+    assert_eq!(radius_layer_for(20.0), RadiusLayer::Component);
+    assert_eq!(radius_layer_for(24.0), RadiusLayer::Component);
+    assert_eq!(radius_layer_for(28.0), RadiusLayer::Scale);
+    assert_eq!(radius_layer_for(360.0), RadiusLayer::Scale);
+    // 抽屉/面板这类容器永远不该被判成微控件。
+    for container in [
+        LayoutMetrics::DESKTOP.nav_drawer_width,
+        LayoutMetrics::DESKTOP.ai_panel_width,
+    ] {
+        assert_eq!(radius_layer_for(container), RadiusLayer::Scale);
+    }
+}
+
+// ---------- G11：骨架值 + nav 语义修正 ----------
+
+#[test]
+fn layout_metrics_new_skeleton_values_are_pinned() {
+    let m = LayoutMetrics::DESKTOP;
+    // A 级：SearchBarTokens.ContainerHeight = 56。
+    assert_eq!(m.search_bar_height, 56.0);
+    // A 级：NavigationDrawer 下限 240（官方 ContainerWidth = 360，1180 窗下过宽，D33 取 240）。
+    assert_eq!(m.nav_drawer_width, 240.0);
+    // 12b §5.1 登记偏离：官方 rail 96 → 本项目 88。
+    assert_eq!(m.nav_rail_width, 88.0);
+    // A 级：DividerTokens.Thickness = 1.0dp（一像素线，不受 4px 栅格约束）。
+    assert_eq!(m.divider_thickness, 1.0);
+}
+
+#[test]
+fn nav_widths_mean_what_their_names_say() {
+    // D33：展开（drawer）比折叠（rail）宽；旧字段 nav_expanded_width=88 / nav_collapsed_width=48
+    // 的名字与值相反，已在 M69 改名并删除，这里钉住「新名字不会再次反向」。
+    let m = LayoutMetrics::DESKTOP;
+    assert!(
+        m.nav_drawer_width > m.nav_rail_width,
+        "展开态（drawer {}）必须比折叠态（rail {}）宽",
+        m.nav_drawer_width,
+        m.nav_rail_width
+    );
+    // rail 里 56 宽的选中指示器要放得下（88 − 2×16）。
+    assert_eq!(m.nav_rail_width - Space::X4.dp() * 2.0, 56.0);
+    // drawer 里 216 宽的指示器同样由「宽 − 2×12」推出（见 ComponentMetrics::indicator_width）。
+    assert_eq!(
+        ComponentMetrics::NAVIGATION_DRAWER.indicator_width(m.nav_drawer_width),
+        216.0
+    );
+}
+
+// ---------- G10：组件级微度量 ----------
+
+#[test]
+fn checkbox_metrics_are_pinned() {
+    let cm = ComponentMetrics::CHECKBOX;
+    // 20×20（不是 token 文件里那个死值 18，见 research/15 §26.2 矛盾 ①）。
+    assert_eq!((cm.width, cm.height), (20.0, 20.0));
+    assert_eq!(
+        cm.radius,
+        Some(ComponentRadius::Micro),
+        "圆角 2dp 走 D32 第二层"
+    );
+    assert_eq!(cm.stroke, 2.0, "CheckboxTokens.UnselectedOutlineWidth = 2");
+    assert_eq!(cm.state_layer, 40.0, "StateLayerSize = 40");
+    assert_eq!(cm.inner_dot, 0.0);
+    assert_eq!(cm.gap, Space::X2.dp(), "框 ↔ 标签 8（团队口径）");
+    assert_eq!(
+        Component::Checkbox.metrics(),
+        Some(ComponentMetrics::CHECKBOX)
+    );
+}
+
+#[test]
+fn radio_metrics_are_pinned() {
+    let cm = ComponentMetrics::RADIO;
+    assert_eq!(
+        (cm.width, cm.height),
+        (20.0, 20.0),
+        "RadioButtonTokens.IconSize = 20"
+    );
+    assert_eq!(cm.stroke, 2.0, "RadioStrokeWidth = 2.dp");
+    // 内点 10 不是 12：12 是含描边前的名义值（绘制半径 = 6 − 1 = 5）。
+    assert_eq!(cm.inner_dot, 10.0);
+    assert_eq!(cm.state_layer, 40.0);
+    assert_eq!(cm.radius, None, "radio 是真圆，圆角走 ShapeScale::Full");
+    assert_eq!(Component::Radio.spec().shape, ShapeScale::Full);
+}
+
+#[test]
+fn search_bar_metrics_are_pinned() {
+    let cm = ComponentMetrics::SEARCH_BAR;
+    // 高 56 属骨架级：CM 里必须留 0，不许重复一份。
+    assert_eq!((cm.width, cm.height), (0.0, 0.0));
+    assert_eq!(cm.icon, IconSize::Toolbar.px(), "leading/trailing 图标 24");
+    // A 级（§20.4）：图标可视左缘 16 = 文本框内容内边距 12 + `SearchBarIconOffsetX = 4`。
+    assert_eq!(cm.pad_start, Space::X3.dp(), "内容内边距 12");
+    assert_eq!(cm.icon_offset, 4.0, "SearchBarIconOffsetX = 4");
+    assert_eq!(cm.pad_start + cm.icon_offset, 16.0, "图标可视左缘必须是 16");
+    // 右侧同式：图标右缘也是 16。
+    assert_eq!(cm.pad_end, Space::X3.dp());
+    assert_eq!(cm.pad_end + cm.icon_offset, 16.0, "图标可视右缘必须是 16");
+    // 守门：不许把 pad 本身写成 16（否则 pad + offset = 20，越过 rubric 的 ±2px）。
+    assert_ne!(cm.pad_start, 16.0);
+    assert_ne!(cm.pad_end, 16.0);
+    // 搜索条圆角 = 高/2 = 28，等于官方 SearchBarCornerRadius。
+    assert_eq!(
+        ShapeScale::Full.radius_px(LayoutMetrics::DESKTOP.search_bar_height),
+        28.0
+    );
+}
+
+#[test]
+fn navigation_drawer_metrics_are_pinned() {
+    let cm = ComponentMetrics::NAVIGATION_DRAWER;
+    assert_eq!((cm.width, cm.height), (0.0, 0.0), "宽/项高属骨架级");
+    assert_eq!(
+        cm.inset, 12.0,
+        "NavigationDrawerItemDefaults.ItemPadding = 12"
+    );
+    assert_eq!(cm.pad_start, Space::X4.dp(), "项内 start 16");
+    assert_eq!(cm.pad_end, Space::X6.dp(), "项内 end 24");
+    assert_eq!(cm.icon, IconSize::Toolbar.px());
+    // 与 search bar 同一条公式：图标边 = pad + icon_offset（抽屉的 offset 是 0）。
+    assert_eq!(cm.pad_start + cm.icon_offset, 16.0, "图标起点 = 项内 start");
+    assert_eq!(cm.gap, Space::X3.dp(), "图标 ↔ label 12");
+    // 指示器宽 = 容器宽 − 24；官方 360 − 24 = 336，本项目 240 − 24 = 216。
+    assert_eq!(cm.indicator_width(360.0), 336.0);
+    assert_eq!(cm.indicator_width(240.0), 216.0);
+}
+
+#[test]
+fn component_metrics_never_duplicate_layout_metrics() {
+    // 同一量只许一份：CM 里出现的骨架级尺寸必须留 0。
+    let m = LayoutMetrics::DESKTOP;
+    for component in [Component::Search, Component::NavigationDrawer] {
+        let cm = component.metrics().expect("这两个控件必须有 CM");
+        assert_eq!(cm.width, 0.0, "{} 的宽度属 LM", component.name());
+        assert_eq!(cm.height, 0.0, "{} 的高度属 LM", component.name());
+        assert_ne!(cm.height, m.search_bar_height);
+        assert_ne!(cm.width, m.nav_drawer_width);
+    }
+    // Divider 的厚度也是 LM（一像素线）→ 它没有 CM。
+    assert_eq!(Component::Divider.metrics(), None);
+    assert_eq!(m.divider_thickness, stroke::HAIRLINE);
+}
+
+// ---------- G12：一像素线 ----------
+
+#[test]
+fn hairline_is_the_single_source_of_one_pixel_lines() {
+    assert_eq!(stroke::HAIRLINE, 1.0);
+    // 分隔线厚度直接引用它，不是另写一个字面量。
+    assert_eq!(LayoutMetrics::DESKTOP.divider_thickness, stroke::HAIRLINE);
+    // 一像素线不受 4px 栅格约束（栅格测试里显式豁免，这里反向钉一次）。
+    assert_ne!(stroke::HAIRLINE % unlucky_design::spacing::GRID, 0.0);
+}
+
+// ---------- G9：枚举 25 变体 ↔ 表槽位 ----------
+
+#[test]
+fn component_enum_is_the_frozen_twenty_five() {
+    let names = [
+        "top-app-bar",
+        "navigation-item",
+        "primary-button",
+        "secondary-button",
+        "text-button",
+        "icon-button",
+        "outlined-card",
+        "filled-card",
+        "list-item",
+        "text-field",
+        "segmented-button",
+        "chip",
+        "switch",
+        "slider",
+        "progress-indicator",
+        "dialog",
+        "menu",
+        "snackbar",
+        "tooltip",
+        "empty-state",
+        // M69 末尾追加的 5 个
+        "checkbox",
+        "radio",
+        "search",
+        "navigation-drawer",
+        "divider",
+    ];
+    assert_eq!(Component::ALL.len(), names.len(), "M66 的 G9：20 → 25");
+    for (i, component) in Component::ALL.iter().enumerate() {
+        assert_eq!(component.name(), names[i], "第 {i} 个组件被换位/改名了");
+        // 表槽位与枚举判别值一一对应（`spec()` 就是按下标取的）。
+        assert_eq!(*component as usize, i);
+        assert_eq!(component.spec().component, *component);
+    }
+}
+
+#[test]
+fn new_components_carry_the_official_elevation_and_shape() {
+    // Checkbox / Radio / Search / NavigationDrawer / Divider：全部 L0（都不是浮层）。
+    for component in [
+        Component::Checkbox,
+        Component::Radio,
+        Component::Search,
+        Component::NavigationDrawer,
+        Component::Divider,
+    ] {
+        assert_eq!(
+            component.spec().elevation,
+            Elevation::Level0,
+            "{} 不该有阴影（R4：只有浮层允许）",
+            component.name()
+        );
+    }
+    // Checkbox 的圆角真源是 micro_radius，shape 只是占位 None。
+    let checkbox = Component::Checkbox.spec();
+    assert_eq!(checkbox.micro_radius, Some(ComponentRadius::Micro));
+    assert_eq!(checkbox.shape, ShapeScale::None);
+    // 其余 4 个不碰微半径层。
+    for component in [
+        Component::Radio,
+        Component::Search,
+        Component::NavigationDrawer,
+        Component::Divider,
+    ] {
+        assert_eq!(component.spec().micro_radius, None, "{}", component.name());
+    }
+    // NavigationDrawer = CornerLargeEnd 的内侧角 16；Divider 无圆角。
+    assert_eq!(Component::NavigationDrawer.spec().shape, ShapeScale::Large);
+    assert_eq!(Component::Divider.spec().shape, ShapeScale::None);
+    // Checkbox / Radio 的标签字级是团队口径（官方无「框 + 标签」token）。
+    assert_eq!(Component::Checkbox.spec().text, TypeRole::BodyLarge);
+    assert_eq!(Component::Radio.spec().text, TypeRole::BodyLarge);
+    // Search 的字级：输入 BodyLarge、占位/辅助 BodySmall。
+    assert_eq!(Component::Search.spec().text, TypeRole::BodyLarge);
+    assert_eq!(Component::Search.spec().support, Some(TypeRole::BodySmall));
+}

crates/design/tests/type_scale_pins.rs

@@ -0,0 +1,106 @@
+//! 官方数值钉死（一）：**排版两张表**（baseline 15 档 + Expressive 强调 15 档）。
+//!
+//! 表的来源是 A 级 `androidx.compose.material3.tokens.TypeScaleTokens`（v0_103）。这里的期望值是
+//! **独立于实现重写的一份**：任何人改动 `TypeRole::style()` / `emphasized()` 的数值，都必须同时改
+//! 这张表才会同时绿——这就是「冻结」的含义（reviewer P2-1 的变异测试就是打这里）。
+
+use unlucky_design::typography::{FontFamily, TypeRole, Weight};
+
+/// baseline 单档对拍。
+fn expect_baseline(
+    role: TypeRole,
+    size: f32,
+    line_height: f32,
+    weight: Weight,
+    tracking: f32,
+    family: FontFamily,
+) {
+    let got = role.style();
+    assert_eq!(
+        (
+            got.size_px,
+            got.line_height_px,
+            got.weight,
+            got.letter_spacing_px,
+            got.family
+        ),
+        (size, line_height, weight, tracking, family),
+        "{} 的 baseline 值被改动了（官方 TypeScaleTokens）",
+        role.name()
+    );
+}
+
+/// Expressive 强调档单档对拍。
+fn expect_emphasized(role: TypeRole, size: f32, line_height: f32, weight: Weight, tracking: f32) {
+    let got = role.emphasized();
+    assert_eq!(
+        (
+            got.size_px,
+            got.line_height_px,
+            got.weight,
+            got.letter_spacing_px
+        ),
+        (size, line_height, weight, tracking),
+        "{} 的 Expressive 强调档值被改动了（官方 TypeScaleTokens *Emphasized*）",
+        role.name()
+    );
+}
+
+#[test]
+fn baseline_type_scale_matches_official_tokens() {
+    use FontFamily::{Display, Text};
+    use Weight::{Bold, Medium, Regular};
+    expect_baseline(TypeRole::DisplayLarge, 57.0, 64.0, Regular, -0.2, Display);
+    expect_baseline(TypeRole::DisplayMedium, 45.0, 52.0, Regular, 0.0, Display);
+    expect_baseline(TypeRole::DisplaySmall, 36.0, 44.0, Regular, 0.0, Display);
+    expect_baseline(TypeRole::HeadlineLarge, 32.0, 40.0, Regular, 0.0, Display);
+    expect_baseline(TypeRole::HeadlineMedium, 28.0, 36.0, Regular, 0.0, Display);
+    expect_baseline(TypeRole::HeadlineSmall, 24.0, 32.0, Regular, 0.0, Display);
+    expect_baseline(TypeRole::TitleLarge, 22.0, 28.0, Regular, 0.0, Display);
+    expect_baseline(TypeRole::TitleMedium, 16.0, 24.0, Medium, 0.2, Text);
+    expect_baseline(TypeRole::TitleSmall, 14.0, 20.0, Medium, 0.1, Text);
+    expect_baseline(TypeRole::BodyLarge, 16.0, 24.0, Regular, 0.5, Text);
+    expect_baseline(TypeRole::BodyMedium, 14.0, 20.0, Regular, 0.2, Text);
+    expect_baseline(TypeRole::BodySmall, 12.0, 16.0, Regular, 0.4, Text);
+    expect_baseline(TypeRole::LabelLarge, 14.0, 20.0, Medium, 0.1, Text);
+    expect_baseline(TypeRole::LabelMedium, 12.0, 16.0, Medium, 0.5, Text);
+    expect_baseline(TypeRole::LabelSmall, 11.0, 16.0, Medium, 0.5, Text);
+    let _ = Bold;
+}
+
+#[test]
+fn expressive_emphasis_matches_official_tokens() {
+    use Weight::{Bold, Medium};
+    // 展示/正文类强调 → Medium(500)；label 与小标题 → Bold(700)。
+    expect_emphasized(TypeRole::DisplayLarge, 57.0, 64.0, Medium, 0.0);
+    expect_emphasized(TypeRole::DisplayMedium, 45.0, 52.0, Medium, 0.0);
+    expect_emphasized(TypeRole::DisplaySmall, 36.0, 44.0, Medium, 0.0);
+    expect_emphasized(TypeRole::HeadlineLarge, 32.0, 40.0, Medium, 0.0);
+    expect_emphasized(TypeRole::HeadlineMedium, 28.0, 36.0, Medium, 0.0);
+    expect_emphasized(TypeRole::HeadlineSmall, 24.0, 32.0, Medium, 0.0);
+    expect_emphasized(TypeRole::TitleLarge, 22.0, 28.0, Medium, 0.0);
+    expect_emphasized(TypeRole::TitleMedium, 16.0, 24.0, Bold, 0.15);
+    expect_emphasized(TypeRole::TitleSmall, 14.0, 20.0, Bold, 0.1);
+    expect_emphasized(TypeRole::BodyLarge, 16.0, 24.0, Medium, 0.15);
+    expect_emphasized(TypeRole::BodyMedium, 14.0, 20.0, Medium, 0.25);
+    expect_emphasized(TypeRole::BodySmall, 12.0, 16.0, Medium, 0.4);
+    expect_emphasized(TypeRole::LabelLarge, 14.0, 20.0, Bold, 0.1);
+    expect_emphasized(TypeRole::LabelMedium, 12.0, 16.0, Bold, 0.5);
+    expect_emphasized(TypeRole::LabelSmall, 11.0, 16.0, Bold, 0.5);
+}
+
+#[test]
+fn both_tables_cover_all_fifteen_roles() {
+    // 防止「表里少写一档」：15 个角色都必须被上面两张表摸到。
+    let mut names = std::collections::BTreeSet::new();
+    for role in TypeRole::ALL {
+        names.insert(role.name());
+        assert_ne!(
+            role.style(),
+            role.emphasized(),
+            "{} 强调档等同 baseline",
+            role.name()
+        );
+    }
+    assert_eq!(names.len(), 15);
+}

packaging/README.md

@@ -9,7 +9,9 @@
 | 槽位 | 产物文件名 | 形态 | 归档内容 |
 |------|-----------|------|---------|
 | `windows-x64` | `unlucky-launcher-<ver>-windows-x64.exe` | **裸 exe**（双击即用） | exe 单文件；三份合规文本作为并列 Release 资产 |
+| `windows-arm64` | `unlucky-launcher-<ver>-windows-arm64.exe` | **裸 exe**（同 x64 策略） | 同上；在 x64 宿主上交叉编译到 `aarch64-pc-windows-msvc` |
 | `linux-x64` | `unlucky-launcher-<ver>-linux-x64.tar.gz` | 单二进制归档 | `unlucky-launcher` + `LICENSE` + `NOTICE` + `README.md` |
+| `linux-arm64` | `unlucky-launcher-<ver>-linux-arm64.tar.gz` | 单二进制归档（原生 ARM64 runner 构建） | 同上 |
 | `macos-arm64` | `unlucky-launcher-<ver>-macos-arm64.tar.gz` | 单二进制归档 | 同上 |
 | `macos-x64` | `unlucky-launcher-<ver>-macos-x64.tar.gz` | 单二进制归档 | 同上 |
 | 全平台 | `SHA256SUMS.txt` | 校验清单 | 每行 `<sha256>␠␠<文件名>`（`sha256sum -c` 可直吃） |
@@ -23,6 +25,9 @@
 - `<ver>` 不带前导 `v`（tag 是 `v0.1.0`，文件名是 `0.1.0`）——由脚本统一裁剪。
 - UNIX 归档内 `mtime`/`uid`/`gid` 归零、权限固定（二进制 0755、文本 0644），
   同源构建的 sha256 不受打包时刻影响。
+- **架构不靠猜**：脚本打包前回读二进制的可执行文件头（PE 机器码 / ELF `e_machine` /
+  Mach-O `cputype`），与槽位声明的架构不符即失败——交叉槽位（x64 宿主产 arm64 exe）不会
+  出现"名字是 arm64、内容还是 x64"的假产物。
 
 ## 2. 版本来源（唯一真相源）
 
@@ -47,10 +52,26 @@ python packaging/make_artifacts.py --version v0.1.0   # 顺带校验版本一致
 python packaging/make_artifacts.py --no-smoke         # 跳过 ull --version 冒烟
 ```
 
-脚本按宿主自动判定槽位（Windows x64 / Linux x64 / macOS arm64 / macOS x64），
-其它组合直接报错退出——不在矩阵里的平台不出"凑合能跑"的产物。
+脚本按宿主自动判定槽位（Windows x64 / Windows arm64 / Linux x64 / Linux arm64 / macOS arm64 /
+macOS x64），其它组合直接报错退出——不在矩阵里的平台不出"凑合能跑"的产物。
 
-### CI（三平台矩阵）
+交叉构建（例如在 x64 宿主上产 Windows arm64 产物）靠两个参数把"产物根"和"槽位"显式喂进去，
+脚本不去猜宿主与产物是不是同一架构：
+
+```bash
+rustup target add aarch64-pc-windows-msvc
+cargo build --release --locked --target aarch64-pc-windows-msvc \
+  --bin unlucky-launcher --bin ull
+python packaging/make_artifacts.py --slot windows-arm64 \
+  --build-dir target/aarch64-pc-windows-msvc/release --out dist
+```
+
+`--slot` 与宿主槽位不一致时，`ull --version` 冒烟会**自动跳过并打印原因**（arm64 产物在 x64
+宿主机上根本执行不了；拿"跳过"当通过是假证据，所以跳过永远带原因）——那条路径的验证只能落在
+CI 真机上：`windows-arm64` 由 cross 构建产物 + M50 的 dumpbin 导入表门禁覆盖，`linux-arm64`
+由 `ubuntu-22.04-arm` 原生 runner 上真跑冒烟覆盖。
+
+### CI（四平台六槽位矩阵）
 
 `.github/workflows/release.yml`：
 
@@ -59,9 +80,15 @@ python packaging/make_artifacts.py --no-smoke         # 跳过 ull --version 冒
   要跑 tag 得 `gh workflow run release.yml --ref v0.1.0`。分支 ref 的 dispatch 与 push 一样被
   `release` job 的 `if: github.ref_type == 'tag'` 挡在发布之外，所以「dispatch 只构建不发布」
   与「dispatch 能关 pre-release」是两条互不冲突的规则。
-- 矩阵：`windows-latest`（MSVC + `-C target-feature=+crt-static`）、`ubuntu-22.04`（glibc 2.35 地板）、
-  `macos-latest`（arm64）、`macos-15-intel`（Intel x64；`macos-13` 已下线，`macos-26-intel` 为更新替位）。
-- 每个槽位 `cargo build --release --locked` → `make_artifacts.py` → 归档内容自检 → 上传 artifact。
+- 矩阵（六槽位；`matrix.build_dir` 参数化产物根，脚本不再假设产物一定在 `target/release`）：
+  `windows-latest` x64（MSVC + `-C target-feature=+crt-static`）、`windows-latest` **交叉编译**到
+  `aarch64-pc-windows-msvc`（产物在 `target/aarch64-pc-windows-msvc/release`）、`ubuntu-22.04`
+  （glibc 2.35 地板）、`ubuntu-22.04-arm`（原生 ARM64 runner，**与 x64 同 2.35 地板**）、`macos-latest`（arm64）、
+  `macos-15-intel`（Intel x64；`macos-13` 已下线，`macos-26-intel` 为更新替位）。
+- 每个槽位 `cargo build --release --locked`（交叉槽位多两步：`rustup target add` + ARM64 库体检
+  ——查 VC 的 `lib/arm64/libcmt.lib`（`+crt-static` 靠它）与 SDK 的 `um/arm64/kernel32.lib`，
+  缺了直接给出"给 VS 加 `VC.Tools.ARM64` 或改用原生 `windows-11-arm`"的可执行提示）→
+  `make_artifacts.py --slot … --build-dir …` → 归档内容自检 → 上传 artifact。
 - `release` job：下载全部 artifact → 重算一份全量 `SHA256SUMS.txt` → 用 `packaging/release-notes.md`
   模板渲染支持矩阵 → `gh release create`（**pre-release 默认开**：首建时 `push` 触发按 pre-release，`workflow_dispatch` 可关）。
 - **同一 tag 重跑幂等**：`gh release view` 命中已存在的 Release 时改走 `gh release upload --clobber`
@@ -91,6 +118,22 @@ Windows 为什么用 MSVC 静态 CRT 而不是本机这套 GNU 工具链：两
 
 本机（GNU 工具链）实测导入表证据见 §7。
 
+### Windows ARM64（Win11 on ARM）
+
+产物形态与门禁跟 x64 一模一样（裸 exe + 静态 CRT + dumpbin 导入表硬门禁），差别只在**怎么编**：
+CI 在 `windows-latest`（x64 宿主）上交叉编译到 `aarch64-pc-windows-msvc`，产物落在
+`target/aarch64-pc-windows-msvc/release`（由 `matrix.build_dir` 注入，脚本不硬编码路径）。
+GitHub 文档（2026）已把 `windows-11-arm` / `windows-11-vs2026-arm` 列为公开仓库**免费**的标准
+arm64 runner，原生路线可行；本流水线仍选交叉编译，因为①双 Windows 槽位共用同一套已验证镜像与
+工具链、②M50 的 dumpbin 定位链取的是 `Hostx64/x64/dumpbin.exe`（读 ARM64 PE 的导入表没问题），
+原生 ARM 宿主上那条链得再补 `Hostarm64` 分支——不为一个槽位放宽刚立的门禁。
+
+运行时依赖与 x64 同表（UCRT 是 Win11 ARM 的系统组件，`+crt-static` 静态链 CRT，不需要可再发行包）。
+游戏侧如实说：**启动器原生运行**；Temurin 没有 windows-aarch64 产物，Microsoft OpenJDK 有该
+发行版（core 的 `microsoft` 源按 `<os>-<arch>` 拼名，命名已覆盖），但 Minecraft 本体没有
+Windows ARM64 原生库（Mojang/LWJGL 只发 x64/x86），实际游玩仍走系统 x64 模拟层 + x64 JDK。
+所以本槽位只承诺「启动器产物」支持，不替 Java/游戏管理做架构级承诺。
+
 ### Linux x64
 
 | 依赖 | 说明 |
@@ -105,6 +148,15 @@ Windows 为什么用 MSVC 静态 CRT 而不是本机这套 GNU 工具链：两
 Debian/Ubuntu 一行：`sudo apt install libxkbcommon0 fontconfig libgl1 libegl1 libxcb1 libx11-6 libwayland-client0`。
 运行期**不需要** `-dev` 包、不需要 Java（Java 是启动游戏时才由启动器自己管理的东西）。
 
+### Linux arm64（aarch64）
+
+依赖与 x64 完全同一套（`libxkbcommon` / `fontconfig` / `libGL` / `libxcb` / `libwayland-client`），
+**glibc 地板也相同**：arm64 槽位跑在原生 `ubuntu-22.04-arm` runner 上，地板 = **2.35**，与 x64
+用的 `ubuntu-22.04` 一致。选 22.04 而不是 24.04 就是为了这个地板——24.04 的 glibc 更高，会把
+Debian 12（2.36）、Raspberry Pi OS Bookworm（2.36）这些实际在跑的 ARM 发行版挡在门外。
+要抬地板（例如将来 ARM 生态整体上移）换 `release.yml` 里那个槽位的 `os` 即可，脚本与产物名都不用动；
+`ubuntu-24.04-arm` / `ubuntu-26.04-arm` 都是同一家族的标准公开仓库标签（4C/16GB、免费不限量）。
+
 ### macOS 12+
 
 | 依赖 | 说明 |
@@ -216,6 +268,26 @@ CI 的 MSVC `+crt-static` 产物同理（静态 CRT）；`release.yml` 里用 `d
 总之不允许"悄悄要用户装可再发行包"。
 注意：本机只装了 GNU 工具链，MSVC 那个槽位的产物本身**没有在本机验证过**，由 CI 首跑验证。
 
+### 7.5 arm64 槽位的本机验证（脚本层取证，不假装跑得动 arm64 二进制）
+
+本机没有 ARM 机器，也不具备 MSVC ARM64 链接库组合，所以只做**能真实证明的东西**（`python` 直接加载
+`packaging/make_artifacts.py` 调函数 + 走 CLI 全流程，证据见下）：
+
+| 取证项 | 结果 |
+|--------|------|
+| 宿主判定注入 | `win32/AMD64`→`windows-x64`、`win32/ARM64`→`windows-arm64`、`linux/x86_64`→`linux-x64`、`linux/aarch64`→`linux-arm64`、`linux/arm64`→`linux-arm64`、`darwin/arm64`→`macos-arm64`、`darwin/x86_64`→`macos-x64`、`freebsd/riscv64`→exit 1 |
+| 文件头架构识别 | 真 `unlucky-launcher.exe`→`x64`；合成 PE `0xAA64`→`arm64` / `0x8664`→`x64`；ELF `0xB7`→`arm64` / `0x3E`→`x64`；Mach-O `0x0100000C`→`arm64` / `0x01000007`→`x64`；垃圾字节→`None`（拒绝出包） |
+| `windows-arm64` stub 全流程 | 把真 exe 的 PE 机器码改成 ARM64 当 stub：`arch: … -> arm64 (ok for windows-arm64)`、`smoke: skipped (host is windows-x64, artifact is windows-arm64)`、产物 `unlucky-launcher-0.1.0-windows-arm64.exe` 14.01 MiB，`SHA256SUMS.txt` 行名一致 |
+| 架构守卫真拦 | x64 二进制冒充 `--slot windows-arm64` → exit 1：`is a x64 binary but slot windows-arm64 says arm64` |
+| `linux-arm64` stub 归档 | 成员 `unlucky-launcher-0.1.0-linux-arm64/{LICENSE,NOTICE,README.md,unlucky-launcher}`，权限 0644/0755、`uid=gid=0`、mtime 0、gzip 头 mtime 字段 `00 00 00 00`；连调两次 sha256 完全一致（`f949d0f5…`）→ 可复现规则与 x64 同源 |
+| `windows-x64` 原生回归 | `arch: … -> x64`、`smoke: ull.exe --version -> 0.1.0 (ok)`、产物 14.01 MiB、`sha256sum -c SHA256SUMS.txt` OK（这一次用的是当前工作树的二进制，与 §7.3 那次不是同一次构建，sha256 自然不同） |
+
+**没在本地验证、只能由 CI 补的**：`windows-arm64` 的交叉链接与真实 ARM64 导入表、`linux-arm64` 在
+原生 arm64 runner 上的真跑。本机连 `raw.githubusercontent.com` 都解析不了，所以 runner 镜像里到底装没装
+ARM64 的 MSVC 库**没法在这里查证**——`release.yml` 为此加了一道链接前的体检（查 `libcmt.lib` 与
+`um/arm64/kernel32.lib`，缺了直接给"加 `VC.Tools.ARM64` 组件或改原生 runner"的提示），首跑即见分晓。
+merge 后由 tower 重指 tag 重跑流水线，两槽位进 `SHA256SUMS.txt` 即算闭环。
+
 ## 8. 发行合规
 
 - `LICENSE`（Apache-2.0 全文）与 `NOTICE`（含 Slint Royalty-Free 2.0 义务说明）随包分发，
@@ -232,15 +304,22 @@ CI 的 MSVC `+crt-static` 产物同理（静态 CRT）；`release.yml` 里用 `d
 | 平台 | 级别 | 运行时要求 |
 |------|------|-----------|
 | Windows 10/11 x64 | 一等 | 无（UCRT 系统自带） |
+| Windows 11 ARM64 | 一等（启动器产物） | 无额外库；启动器原生运行，游戏本体走系统 x64 模拟层 + x64 JDK |
 | macOS 12+（arm64 / x64） | 一等 | 无第三方库；未签名需去 quarantine |
 | Linux x64 X11 | 一等 | glibc 2.35+、xkbcommon、fontconfig、libGL、xcb |
 | Linux x64 Wayland | 支持 | 上述 + wayland-client |
+| Linux arm64 X11 | 一等 | glibc 2.35+（`ubuntu-22.04-arm` 原生构建，**与 x64 同地板**）、xkbcommon、fontconfig、libGL、xcb |
+| Linux arm64 Wayland | 支持 | 上述 + wayland-client |
 | Windows 8.1/8/7 | 不支持 | 基线已上调（D21） |
 | Android Termux + X11 | 试验级（不承诺） | 仅 CLI（源码自建），GUI 未验证，不在本发布矩阵内 |
 
 `packaging/release-notes.md` 的 "Support matrix" 表与上表逐行对应（英文版，Termux 行同样标注
 experimental / not part of this release matrix）——改一边必须同步另一边，否则标题里的"一致"就是假话。
 
+两个 arm64 槽位都是**正式发布槽位**（产物进 Release、进 `SHA256SUMS.txt`、release job 的六槽位齐全性
+检查会拦下缺失），不要跟 Termux 那行混为一谈：Termux 是"源码自建的实验级旁路"，Linux arm64 是
+"原生 runner 编、原生跑"的一等产物。
+
 ## 10. 已知边界 / 后续
 
 1. **GUI 无 `--version`**：`unlucky-launcher.exe` 目前只解析 `--software-renderer` / `--screenshot*` /
@@ -256,12 +335,40 @@ experimental / not part of this release matrix）——改一边必须同步另
 6. **本机 GNU 链接器的已知无害告警**：`cargo build --release`（GNU 工具链）会打一行
    `warning: linker stderr: corrupt .drectve at end of def file`，来自 MinGW `ld` 对 `.drectve` 段的
    老式抱怨，不影响产物（体积/导入表/冒烟均已实测正常）；CI 的 MSVC 槽位不会出现这条。
+7. **两个 arm64 槽位本机跑不了**：本机是 x64 Windows，既没有 ARM 机器也没有 MSVC 的 ARM64 链接库
+   组合，`windows-arm64` / `linux-arm64` 的**真实产物只能由 CI 出**：前者靠 `dumpbin -dependents`
+   的静态 CRT 门禁 + 架构校验，后者在 `ubuntu-22.04-arm` 上真跑 `ull --version` 冒烟。
+   本机能做且已做的是脚本层取证（见 §7.5）：宿主判定注入（`win32/ARM64`、`linux/aarch64` 等全槽位）、
+   可执行文件头架构识别（真 x64 exe + 合成 PE/ELF/Mach-O 头）、以及把真 exe 的 PE 机器码改成 ARM64
+   当 stub 走完命名/校验/归档全流程 —— 不假装能在 x64 上执行 arm64 二进制。
 
-## 11. 文件清单
+## 11. CI 运行时冒烟（Linux 真渲染一帧）
+
+**细节与依据在 [`packaging/ci-runtime-smoke.md`](ci-runtime-smoke.md)**（本节再增长也往那里写，两个文件都必须 ≤400 行）。
+
+`ci.yml` 的 `runtime-smoke` job 在 `ubuntu-latest` 上补第一份**真实图形环境**运行证据：装 `xvfb` + 软渲染
+依赖 + 字体，用 `xvfb-run` 起 GUI 进程，走既有进程内截图通道渲出一帧 PNG，再对**像素本身**断言
+（退出码 0 / PNG 尺寸 / 非空白三项，artifact `runtime-smoke-screenshot`）。
+
+要点三条：
+
+- 只看退出码不够：PNG 是进程自己编码写出的，「合法 PNG + 退出码 0」不等于画面有内容，像素断言是纵深防御；
+  而「完全没有字体」与「非软渲染」这两种失效都是**硬失败**（panic / 报错，不产生 PNG；review 实测），运行步就红。
+- 闸门下限 ≈「至少画出一条标题栏」（review 实测切片仍 pass）：证明「场景被真实渲染过」，**不证明界面元素齐全，
+  更不证明视觉正确**——视觉靠人眼看 artifact。
+- 只覆盖 Linux x64；macOS 是 dispatch-only 探针（无实测证据），Windows 已有本机人眼验收。
+
+**本地复跑**：`bash packaging/linux-smoke-docker.sh . D:/tmp/ull-smoke`（输出目录别写 `/tmp`，Git Bash 下会
+静默落进 Docker VM；脚本内部用 `cygpath -m` 归一并回显真实路径）。
+
+## 12. 文件清单
 
 | 文件 | 作用 | 行数上限 |
 |------|------|---------|
 | `packaging/README.md` | 本文：矩阵/依赖/版本/合规契约 | ≤400 |
 | `packaging/make_artifacts.py` | 打包与校验（本地 + CI 共用） | ≤400 |
 | `packaging/release-notes.md` | GitHub Release 说明模板（`{{VERSION}}` / `{{SUMS}}` 占位） | ≤400 |
+| `packaging/check_screenshot.py` | 截图非空白判定（CI 门禁 + 本地手动跑，零第三方依赖） | ≤400 |
+| `packaging/ci-runtime-smoke.md` | §11 的细节：断言口径/阈值依据/失效模式/复跑 | ≤400 |
+| `packaging/linux-smoke-docker.sh` | 本地复跑 `runtime-smoke`（Docker + xvfb） | ≤400 |
 | `.github/workflows/release.yml` | tag 触发 → 矩阵构建 → Release | ≤400 |

packaging/check_screenshot.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""截图「不是一帧空白」判定：CI 运行时冒烟的门禁脚本（零第三方依赖）。
+
+为什么需要它：`--screenshot` 的 PNG 是进程自己编码写出的，只要流程走到 `take_snapshot` 就会得到
+「合法 PNG + 退出码 0」；像素断言是**纵深防御**，守的是「进程活着、写出合法 PNG，但场景几乎没画」这一档。
+本机可复现的两种失效都是硬失败（运行步就红，不必等像素断言）：①完全没有字体 → fontique panic
+（退出码 101，不产生 PNG）；②不是软渲染（默认 femtovg）→ `take_snapshot is not supported by this
+FemtoVG backend`（退出码 1）。其余「渲染器出图但内容没上去」的情形本机暂无样本，属防御性设计。
+
+三个判据（阈值依据见 `--selftest` 与 packaging/ci-runtime-smoke.md）：
+
+- `unique_colors`：唯一色数。全白 / 全黑图 = 1；真实 UI 数百到上千。
+- `luma_stddev`：亮度标准差。纯色图 = 0；真实 UI 有面板/文字/渐变的明暗层次。
+- `edge_ratio`：**强边缘像素占比**——水平相邻像素对里亮度差 ≥8 的比例。纯色图 = 0；真实 UI 的文字与
+  边框占千分之几到百分之几。用它而不是「平均亮度差」：空数据目录的主界面 57% 是同一片底色，
+  平均差会被大片平面稀释（实测只有 0.4），而强边缘占比只数真正的边界，跨主题/跨字体都稳定。
+
+只用 Python 标准库：`zlib` 解压 PNG 的 deflate 流，自己反过滤（filter 0~4）。
+不引 Pillow 是因为 CI 不该为了「看一张图」多装一套图像栈（也符合项目的依赖白名单纪律）。
+
+用法::
+
+    python packaging/check_screenshot.py shot.png            # 判定，退出码 0/1
+    python packaging/check_screenshot.py shot.png --json     # 机器可读（CI 日志用）
+    python packaging/check_screenshot.py --selftest          # 打印阈值依据的两组数值
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import struct
+import sys
+import tempfile
+import zlib
+from collections import Counter
+from pathlib import Path
+
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+# 判定阈值。两侧数值实测（M62 本机 Docker + xvfb + Windows 历史截图）：
+# - 真实帧：唯一色 342~2352、亮度σ 19.45~27.46、强边缘占比 0.0076~0.0433（最弱是 Linux 空数据主界面）；
+# - 人为纯色帧：1 / 0.0 / 0.0。
+# 阈值取在两者之间、贴近真实下限的 1/5~1/8：换主题/换字体/换窗口尺寸都不会误报，空白帧一定红。
+DEFAULT_MIN_UNIQUE = 64
+DEFAULT_MIN_STDDEV = 3.0
+DEFAULT_MIN_EDGE_RATIO = 0.001
+
+# 「强边缘」的亮度差门槛：≥8/255 肉眼即视为一条边界；抗锯齿造成的 1~2 级抖动不算。
+EDGE_LUMA_DELTA = 8
+
+# PNG 颜色类型 → 每像素通道数（调色板 3 走索引，需要 PLTE，本脚本不解）
+CHANNELS_BY_COLOR_TYPE = {0: 1, 2: 3, 4: 2, 6: 4}
+
+
+class PngError(Exception):
+    """PNG 结构不受支持或损坏。"""
+
+
+def _iter_chunks(data: bytes):
+    """按 PNG 规范切块：长度(4) + 类型(4) + 数据 + CRC(4)。"""
+    offset = len(PNG_SIGNATURE)
+    while offset + 12 <= len(data):
+        (length,) = struct.unpack(">I", data[offset : offset + 4])
+        yield data[offset + 4 : offset + 8], data[offset + 8 : offset + 8 + length]
+        offset += 12 + length
+
+
+def _unfilter(kind: int, line: bytearray, prev: bytearray, bpp: int) -> None:
+    """就地把一条扫描线反过滤（PNG 规范 §9.2 的五个过滤类型）。"""
+    if kind == 0:
+        return
+    if kind == 1:  # Sub：加上左边
+        for index in range(bpp, len(line)):
+            line[index] = (line[index] + line[index - bpp]) & 0xFF
+    elif kind == 2:  # Up：加上正上方
+        for index in range(len(line)):
+            line[index] = (line[index] + prev[index]) & 0xFF
+    elif kind == 3:  # Average：加上 (左 + 上) // 2
+        for index in range(len(line)):
+            left = line[index - bpp] if index >= bpp else 0
+            line[index] = (line[index] + ((left + prev[index]) >> 1)) & 0xFF
+    elif kind == 4:  # Paeth：加上 Paeth 预测子
+        for index in range(len(line)):
+            left = line[index - bpp] if index >= bpp else 0
+            up = prev[index]
+            upper_left = prev[index - bpp] if index >= bpp else 0
+            estimate = left + up - upper_left
+            dist_left = abs(estimate - left)
+            dist_up = abs(estimate - up)
+            dist_corner = abs(estimate - upper_left)
+            if dist_left <= dist_up and dist_left <= dist_corner:
+                predictor = left
+            elif dist_up <= dist_corner:
+                predictor = up
+            else:
+                predictor = upper_left
+            line[index] = (line[index] + predictor) & 0xFF
+    else:
+        raise PngError(f"未知的行过滤类型 {kind}")
+
+
+def decode_png(path: Path) -> tuple[int, int, list[bytearray], int]:
+    """读 8bit 非隔行 PNG，返回 (宽, 高, 每行原始字节, 通道数)。"""
+    data = path.read_bytes()
+    if not data.startswith(PNG_SIGNATURE):
+        raise PngError(f"{path} 不是 PNG（签名不符，可能是 0 字节文件或半截写入）")
+
+    width = height = depth = color_type = interlace = None
+    compressed = bytearray()
+    for kind, body in _iter_chunks(data):
+        if kind == b"IHDR":
+            width, height, depth, color_type, _, _, interlace = struct.unpack(">IIBBBBB", body)
+        elif kind == b"IDAT":
+            compressed.extend(body)
+        elif kind == b"IEND":
+            break
+
+    if width is None or height is None:
+        raise PngError("缺 IHDR 块")
+    if interlace:
+        raise PngError("不支持隔行（Adam7）PNG")
+    if depth != 8:
+        raise PngError(f"只支持 8bit PNG，实际 {depth}bit")
+    channels = CHANNELS_BY_COLOR_TYPE.get(color_type)
+    if channels is None:
+        raise PngError(f"不支持的颜色类型 {color_type}（调色板 PNG 请先转成 RGB/RGBA）")
+
+    raw = zlib.decompress(bytes(compressed))
+    stride = width * channels
+    if len(raw) < (stride + 1) * height:
+        raise PngError(f"像素数据不足：期望 {(stride + 1) * height} 字节，实际 {len(raw)}")
+
+    rows: list[bytearray] = []
+    previous = bytearray(stride)
+    offset = 0
+    for _ in range(height):
+        kind = raw[offset]
+        offset += 1
+        line = bytearray(raw[offset : offset + stride])
+        offset += stride
+        _unfilter(kind, line, previous, channels)
+        rows.append(line)
+        previous = line
+    return width, height, rows, channels
+
+
+def measure(width: int, height: int, rows: list[bytearray], channels: int) -> dict:
+    """统计「这帧图里有没有信息」的三项指标。"""
+    colors: Counter[int] = Counter()
+    luma_sum = 0
+    luma_square_sum = 0
+    strong_edges = 0
+    pair_count = 0
+
+    for row in rows:
+        previous_luma = None
+        for x in range(width):
+            base = x * channels
+            if channels >= 3:
+                red, green, blue = row[base], row[base + 1], row[base + 2]
+            else:
+                red = green = blue = row[base]
+            colors[(red << 16) | (green << 8) | blue] += 1
+            # 整数亮度（ITU-R BT.601 系数），避免浮点误差影响阈值比较
+            luma = (red * 299 + green * 587 + blue * 114) // 1000
+            luma_sum += luma
+            luma_square_sum += luma * luma
+            if previous_luma is not None:
+                pair_count += 1
+                if abs(luma - previous_luma) >= EDGE_LUMA_DELTA:
+                    strong_edges += 1
+            previous_luma = luma
+
+    total = width * height
+    mean = luma_sum / total if total else 0.0
+    variance = max(luma_square_sum / total - mean * mean, 0.0) if total else 0.0
+    top_color, top_count = colors.most_common(1)[0] if colors else (0, 0)
+    return {
+        "width": width,
+        "height": height,
+        "pixels": total,
+        "unique_colors": len(colors),
+        "top_color": f"#{top_color:06x}",
+        "top_color_share": round(top_count / total, 4) if total else 0.0,
+        "luma_mean": round(mean, 2),
+        "luma_stddev": round(math.sqrt(variance), 2),
+        "edge_ratio": round(strong_edges / pair_count, 5) if pair_count else 0.0,
+    }
+
+
+def verdict(
+    stats: dict, min_unique: int, min_stddev: float, min_edge_ratio: float
+) -> list[str]:
+    """把指标折成「失败原因清单」；空清单 = 通过。"""
+    problems = []
+    if stats["pixels"] <= 0:
+        problems.append("图像尺寸为 0（宽或高是 0）")
+        return problems
+    if stats["unique_colors"] < min_unique:
+        problems.append(
+            f"唯一色数 {stats['unique_colors']} < 阈值 {min_unique}（像纯色/空白帧）"
+        )
+    if stats["luma_stddev"] < min_stddev:
+        problems.append(
+            f"亮度标准差 {stats['luma_stddev']} < 阈值 {min_stddev}（整帧明暗无层次）"
+        )
+    if stats["edge_ratio"] < min_edge_ratio:
+        problems.append(
+            f"强边缘占比 {stats['edge_ratio']} < 阈值 {min_edge_ratio}（没有边界/文字的迹象）"
+        )
+    return problems
+
+
+def encode_png(width: int, height: int, rgb_row) -> bytes:
+    """最小 PNG 编码器（8bit RGB、filter 0、zlib 压缩）——只给 `--selftest` 造样图。"""
+    raw = bytearray()
+    for y in range(height):
+        raw.append(0)
+        raw.extend(rgb_row(y))
+    out = bytearray(PNG_SIGNATURE)
+    for kind, body in (
+        (b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)),
+        (b"IDAT", zlib.compress(bytes(raw), 6)),
+        (b"IEND", b""),
+    ):
+        out.extend(struct.pack(">I", len(body)))
+        out.extend(kind)
+        out.extend(body)
+        out.extend(struct.pack(">I", zlib.crc32(kind + body) & 0xFFFFFFFF))
+    return bytes(out)
+
+
+def selftest() -> int:
+    """造两张对照样图跑一遍，打印阈值依据的两组数值。
+
+    - 全白 / 全黑：模拟「窗口起来了但一个像素都没画」的空白帧；
+    - 一像素黑边框 + 中部一条横线：最弱的「有内容」下限（远弱于真实 UI）。
+    """
+    width, height = 1180, 760
+    cases = {
+        "flat-white": lambda y: b"\xff" * (width * 3),
+        "flat-black": lambda y: b"\x00" * (width * 3),
+        "border-line": lambda y: b"".join(
+            b"\x00\x00\x00"
+            if (y in (0, height - 1) or x in (0, width - 1) or y == height // 2)
+            else b"\xff\xff\xff"
+            for x in range(width)
+        ),
+    }
+    with tempfile.TemporaryDirectory() as tmp:
+        for name, describe in cases.items():
+            path = Path(tmp) / f"{name}.png"
+            path.write_bytes(encode_png(width, height, describe))
+            stats = measure(*decode_png(path))
+            failed = verdict(
+                stats, DEFAULT_MIN_UNIQUE, DEFAULT_MIN_STDDEV, DEFAULT_MIN_EDGE_RATIO
+            )
+            print(
+                json.dumps(
+                    {
+                        "case": name,
+                        "unique_colors": stats["unique_colors"],
+                        "luma_stddev": stats["luma_stddev"],
+                        "edge_ratio": stats["edge_ratio"],
+                        "verdict": "fail" if failed else "pass",
+                    },
+                    ensure_ascii=False,
+                )
+            )
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="截图非空白判定（CI 运行时冒烟门禁）")
+    parser.add_argument("png", nargs="?", type=Path, help="待判定的 PNG 路径")
+    parser.add_argument("--json", action="store_true", help="以 JSON 输出统计结果")
+    parser.add_argument("--min-unique", type=int, default=DEFAULT_MIN_UNIQUE, help="唯一色数下限")
+    parser.add_argument("--min-stddev", type=float, default=DEFAULT_MIN_STDDEV, help="亮度标准差下限")
+    parser.add_argument(
+        "--min-edge-ratio", type=float, default=DEFAULT_MIN_EDGE_RATIO, help="强边缘占比下限"
+    )
+    parser.add_argument("--selftest", action="store_true", help="打印阈值依据的对照数值后退出")
+    args = parser.parse_args(argv)
+
+    if args.selftest:
+        return selftest()
+    if args.png is None:
+        parser.error("需要给出 PNG 路径（或 --selftest）")
+
+    try:
+        stats = measure(*decode_png(args.png))
+    except (PngError, OSError, zlib.error) as error:
+        print(f"[fail] 读不出截图 {args.png}: {error}", file=sys.stderr)
+        return 1
+
+    problems = verdict(stats, args.min_unique, args.min_stddev, args.min_edge_ratio)
+    if args.json:
+        print(json.dumps({**stats, "problems": problems}, ensure_ascii=False))
+    else:
+        print(
+            f"{args.png}: {stats['width']}x{stats['height']} "
+            f"唯一色 {stats['unique_colors']} 亮度σ {stats['luma_stddev']} "
+            f"强边缘 {stats['edge_ratio']} 主色 {stats['top_color']}"
+            f"({stats['top_color_share'] * 100:.1f}%)"
+        )
+    if problems:
+        for problem in problems:
+            print(f"[fail] {problem}", file=sys.stderr)
+        return 1
+    print("[ok] 截图非空白")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

packaging/ci-runtime-smoke.md

@@ -0,0 +1,78 @@
+# CI 运行时冒烟（Linux 真渲染一帧）
+
+`packaging/README.md` §11 是本节的索引；细节在这里。为什么拆：本节要写阈值依据、失效模式与复跑口径，
+塞回 README 会撞 400 行硬门禁——**两文件都必须 ≤400 行**，任一边再增长就再拆一节。
+
+「编得过」≠「跑得起来」。`ci.yml` 的 `runtime-smoke` job 在 `ubuntu-latest` 上补第一份**真实图形环境**
+运行证据：装 `xvfb`（虚拟 X 服务器）+ 软渲染依赖 + 字体，用 `xvfb-run` 把 GUI 进程拉起来，走既有的
+进程内截图通道（`--software-renderer --screenshot <png> --data-dir <tmp>`）渲出一帧 PNG，再对**像素本身**断言。
+
+## 1. 三道断言
+
+`packaging/check_screenshot.py` 退出码 0 才算过；artifact 名 `runtime-smoke-screenshot`。
+
+1. 进程退出码 0（截图通道失败会以非 0 退出，不留半张图）；
+2. PNG 存在、可解析、宽高 > 0（0 字节 / 非 PNG / 路径不存在都是硬失败，脚本 exit 1）；
+3. **非空白**：唯一色数 / 亮度标准差 / 强边缘占比三项同时过阈值。
+
+为什么不能只看退出码：`--screenshot` 的 PNG 是进程自己编码写出的，只要流程走到 `take_snapshot` 就会得到
+「合法 PNG + 退出码 0」；像素断言是**纵深防御**，守的是「进程活着、写出合法 PNG，但场景几乎没画」这一档。
+本机可复现的两种失效都是硬失败（运行步就红，不必等像素断言）：①完全没有字体 → fontique panic
+（退出码 101，不产生 PNG）；②不是软渲染（默认 femtovg）→ `take_snapshot is not supported by this
+FemtoVG backend`（退出码 1）。这两条由 M62 review 实测复现（本 mission 未自己跑这两种破坏性实验）。
+其余「渲染器出图但内容没上去」的情形本机暂无样本，属防御性设计，不宣称已复现。
+
+## 2. 阈值与依据
+
+`python packaging/check_screenshot.py --selftest` 可复现后三行：
+
+| 样本 | 唯一色数 | 亮度σ | 强边缘占比 | 判定 |
+|------|---------|-------|-----------|------|
+| 本机 Docker 真截图（xvfb + 软渲染，1180x760，空数据目录） | 342 | 19.45 | 0.00761 | pass |
+| Windows 历史截图（M45/M52，同一界面深浅两套，1180x760） | 529~699 | 20.29~27.46 | 0.0186~0.0433 | pass |
+| 人为纯白 / 纯黑（空白帧） | 1 | 0.0 | 0.0 | fail |
+| 最弱内容（1 像素黑边框 + 一条中线） | 2 | 19.09 | 0.00169 | fail（卡唯一色数） |
+| **阈值** | ≥64 | ≥3.0 | ≥0.001 | — |
+
+阈值留 **5~8 倍**余量（342/64 = 5.3×、19.45/3.0 = 6.5×、0.00761/0.001 = 7.6×）：换主题/换字体不会误报，
+空白帧一定红。
+
+第三项用**强边缘占比**（水平相邻像素亮度差 ≥8 的比例）而不是平均亮度差：空数据目录的主界面 57% 是同一片
+底色，平均差被稀释到 0.4，强边缘只数真正的边界，跨主题稳定（同一界面深浅两套差 2 倍，仍都过线）。
+
+**这道闸门的下限 ≈「至少画出一条标题栏」**（review 实测切片）：只画 1180×40 标题栏的切片（174 / 35.10 /
+0.02623）仍 pass，右下 400×300 的切片也 pass。所以它证明的是「场景被真实渲染过」，**不证明界面元素齐全、
+更不证明视觉正确**；视觉正确只能靠人眼看 artifact。
+
+## 3. 覆盖哪个平台
+
+只有 Linux x64（X11 + Xvfb + 软渲染）。
+
+- **macOS**：`runtime-smoke-macos` 只在 `workflow_dispatch` 触发且 `continue-on-error: true`。官方 macOS
+  runner 处于 LaunchDaemon 上下文、无登录 WindowServer 会话，winit 大概率建不了窗口；本机没有 macOS
+  且 worker 禁 push，这条路径**尚无实测证据**，故不拿它卡 PR 门禁。首跑定去留：绿 → 删 `if` 与
+  `continue-on-error` 升常驻；红 → 错误原文进 progress，按 D26 归入 iced 重写再规划。
+- **Windows**：不新增 job——`--software-renderer --screenshot` 已在本机验收里多次人眼验证（M45/M52）。
+
+## 4. 本地复跑
+
+```bash
+bash packaging/linux-smoke-docker.sh . D:/tmp/ull-smoke
+```
+
+用 Docker（`rust:1-bookworm` + TUNA apt/rustup 源）复刻同一套步骤，截图落在 `<输出目录>/runtime-smoke.png`。
+**输出目录别写 `/tmp/...`**：Git Bash 里 `/tmp` 是 MSYS 虚拟路径，`docker -v` 会把它当 Linux VM 内的路径，
+结果是「脚本说成功、宿主机什么都没有」。脚本对 `out_dir`/`repo_root` 统一做 `cygpath -m` 归一，并回显真实
+路径；没有 `cygpath` 的平台（Linux/macOS）按原样用。
+
+诚实边界：本机容器是 Debian 12（glibc 2.36），官方 runner 是 Ubuntu 24.04（glibc 2.39），图形栈来源不同，
+容器绿只证明「这条通道能跑」，官方 runner 首跑仍要单独看。
+
+## 5. 已知跳过项与迁移风险
+
+**跳过项**（D26 收窄，本条只做「框架无关的最小运行时冒烟」）：Wayland（`weston --headless`）、
+`--screenshot-page` 子页覆盖、gsettings 主题探测回退都不在本 job 内，随 iced 重写另行规划。
+
+**迁移风险**：本 job 绑死 Slint 的截图通道（`Window::take_snapshot`）。**UI 迁 iced 后必须重新验证**——
+iced 没有等价快照 API，届时要提供「离屏渲染出一帧 PNG」的等价通道，否则本 job 会静默退化成「能起进程」
+而不是「能出图」（它本来也只证明「能出图」，不证明视觉正确）。

packaging/linux-smoke-docker.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# 本地复跑 `.github/workflows/ci.yml` 的 `runtime-smoke` job：Linux + Xvfb + 软渲染截图。
+#
+# 为什么要有这条脚本：CI 的 runtime-smoke 在 GitHub 的 ubuntu-latest 上跑，
+# 但「改动这个 job 的人」需要在没有 Linux 桌面的开发机上先自证一遍——否则改的就是没人验过的 YAML。
+# 本脚本在 Docker 里复刻 job 的步骤（同样的 apt 依赖、同样的构建、同样的 xvfb-run 命令），
+# 并把截图与判定结果留在宿主目录，供人眼与 `check_screenshot.py` 复核。
+#
+# 用法：
+#   bash packaging/linux-smoke-docker.sh [仓库根目录] [输出目录]
+#   ULL_SMOKE_SKIP_BUILD=1 bash packaging/linux-smoke-docker.sh   # 复用缓存的二进制
+#
+# 说明（诚实边界）：
+# - 基础镜像 `rust:1-bookworm` 是 **Debian 12（glibc 2.36）**，官方 runner 是 **Ubuntu 24.04（glibc 2.39）**。
+#   两者图形栈（X11/xvfb/Mesa 软渲染）来源不同，因此本脚本证明的是「Linux 上这条通道能真跑出图」，
+#   不能代替官方 runner 的首跑验证。
+# - 国内网络慢时可换 TUNA 镜像：脚本默认就用 TUNA 的 Debian 源（`ULL_APT_MIRROR` 可覆盖）。
+
+set -euo pipefail
+
+repo_root=$(cd "${1:-.}" && pwd)
+out_dir=${2:-ull-smoke}
+image=${ULL_SMOKE_IMAGE:-ull-linux-smoke:bookworm}
+cargo_volume=${ULL_CARGO_VOLUME:-ull-cargo-reg}
+target_volume=${ULL_CARGO_TARGET_VOLUME:-ull-linux-target}
+apt_mirror=${ULL_APT_MIRROR:-https://mirrors.tuna.tsinghua.edu.cn}
+rustup_mirror=${ULL_RUSTUP_MIRROR:-https://mirrors.tuna.tsinghua.edu.cn/rustup}
+
+mkdir -p "$out_dir"
+out_dir=$(cd "$out_dir" && pwd)
+# Git Bash 里 /tmp、/d/x 都是 MSYS 虚拟路径：直接喂给 `docker -v` 会被当成 Linux VM 内的路径，
+# 结果「脚本说成功、宿主机什么都没有」。有 cygpath 就统一转成 Windows 混合路径（D:/x）并回显真实位置。
+if command -v cygpath >/dev/null 2>&1; then
+  repo_root=$(cygpath -m "$repo_root")
+  out_dir=$(cygpath -m "$out_dir")
+fi
+echo "== 仓库: $repo_root"
+echo "== 输出: $out_dir（截图 $out_dir/runtime-smoke.png）"
+
+# 1) 构建镜像：rust 工具链 + xvfb + 图形栈编译依赖 + 字体（软渲染器要从系统字体库取字形）
+if ! docker image inspect "$image" >/dev/null 2>&1 || [ "${ULL_SMOKE_REBUILD_IMAGE:-0}" = "1" ]; then
+  context=$(mktemp -d)
+  trap 'rm -rf "$context"' EXIT
+  cat >"$context/Dockerfile" <<EOF
+FROM rust:1-bookworm
+# 工具链组件（rustfmt/clippy）在 rust-toolchain.toml 里是必备项，rustup 会去补齐；
+# 默认 dist 服务器在国内会挂成「rustc 0.6% CPU 睡 12 分钟」的假死（M62 实测），所以走 TUNA。
+ENV RUSTUP_DIST_SERVER=$rustup_mirror \\
+    RUSTUP_UPDATE_ROOT=$rustup_mirror/rustup
+RUN sed -i 's|http://deb.debian.org|$apt_mirror|g' /etc/apt/sources.list.d/debian.sources \\
+ && apt-get update \\
+ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \\
+      xvfb xauth python3 \\
+      libxkbcommon-dev libxkbcommon-x11-0 libfontconfig1-dev \\
+      libgl1-mesa-dev libegl1-mesa-dev libwayland-dev libxcb1-dev \\
+      libx11-6 libxcursor1 libxrandr2 libxi6 \\
+      fonts-dejavu-core fonts-liberation2 \\
+ && rm -rf /var/lib/apt/lists/*
+RUN rustup component add rustfmt clippy && rustup toolchain list
+WORKDIR /src
+EOF
+  docker build -t "$image" "$context"
+fi
+
+# 2) 跑容器：构建 → xvfb 截图 → 像素判定
+# 注意缓存卷要挂到 `registry` 子目录：直接挂 /usr/local/cargo 会把镜像里的 `bin/`（cargo 本体）盖掉，
+# 变成 `cargo: command not found`（M62 实测踩到）。
+MSYS_NO_PATHCONV=1 docker run --rm \
+  -v "$repo_root:/src" \
+  -v "$cargo_volume:/usr/local/cargo/registry" \
+  -v "$target_volume:/target" \
+  -v "$out_dir:/out" \
+  -w /src \
+  -e CARGO_TARGET_DIR=/target \
+  -e ULL_SMOKE_SKIP_BUILD="${ULL_SMOKE_SKIP_BUILD:-0}" \
+  -e CARGO_TERM_COLOR=never \
+  "$image" bash -euo pipefail -c '
+    rustc --version && cargo --version && cat /etc/debian_version
+    if [ "$ULL_SMOKE_SKIP_BUILD" != "1" ]; then
+      # 共享热缓存卷可能喂陈旧产物（踩坑记录 N7）：先清掉受检 crate 再编
+      # 清不掉就算了（N7 兜底用）；CI 里**没有**对应两行，别误抄进 ci.yml —— 那边每次都是干净 runner
+      cargo clean -p unlucky-app || true
+      cargo build --bin unlucky-launcher --locked -j 6
+    fi
+    mkdir -p /out/data
+    set +e
+    xvfb-run -a --server-args="-screen 0 1280x1024x24" \
+      /target/debug/unlucky-launcher --software-renderer \
+      --screenshot /out/runtime-smoke.png --data-dir /out/data
+    code=$?
+    set -e
+    echo "exit=$code"
+    python3 packaging/check_screenshot.py /out/runtime-smoke.png
+    exit $code
+  '
+
+echo "== 截图与数据目录已留在 $out_dir"

packaging/make_artifacts.py

@@ -3,11 +3,13 @@
 
 Release matrix (see `packaging/README.md` for the full contract):
 
-    Windows x64   unlucky-launcher-<ver>-windows-x64.exe        (bare exe, no zip)
-    Linux x64     unlucky-launcher-<ver>-linux-x64.tar.gz
-    macOS arm64   unlucky-launcher-<ver>-macos-arm64.tar.gz
-    macOS x64     unlucky-launcher-<ver>-macos-x64.tar.gz
-    all           SHA256SUMS.txt
+    Windows x64     unlucky-launcher-<ver>-windows-x64.exe      (bare exe, no zip)
+    Windows arm64   unlucky-launcher-<ver>-windows-arm64.exe    (bare exe, cross-built)
+    Linux x64       unlucky-launcher-<ver>-linux-x64.tar.gz
+    Linux arm64     unlucky-launcher-<ver>-linux-arm64.tar.gz
+    macOS arm64     unlucky-launcher-<ver>-macos-arm64.tar.gz
+    macOS x64       unlucky-launcher-<ver>-macos-x64.tar.gz
+    all             SHA256SUMS.txt
 
 `--version` is taken from the cargo workspace so a tag can never drift away from
 `Cargo.toml`; pass `--version` to cross-check a tag against it (mismatch is fatal).
@@ -15,9 +17,17 @@ The archives carry the launcher binary plus LICENSE / NOTICE / README.md, which
 what the license obligations ask for; Windows ships the bare `.exe` (the single-file
 selling point) and the same three documents are attached to the Release next to it.
 
+Slot and build directory are overridable because a cross build's binaries live in
+`target/<triple>/release` and the build host (x64) is not the artifact (arm64): CI
+passes both from its matrix, and the executable header is read back so a binary can
+never be shipped under a slot name it was not built for.
+
 Usage:
     cargo build --release --locked
     python3 packaging/make_artifacts.py [--version v0.1.0] [--out dist] [--no-smoke]
+    # cross build (arm64 exe from an x64 host):
+    python3 packaging/make_artifacts.py --slot windows-arm64 \\
+        --build-dir target/aarch64-pc-windows-msvc/release
 """
 
 from __future__ import annotations
@@ -26,7 +36,6 @@ import argparse
 import gzip
 import hashlib
 import json
-import os
 import platform
 import shutil
 import subprocess
@@ -40,9 +49,32 @@ CLI_BIN = "ull"
 # 随包分发的合规文本（仓库根目录）；英文主版 README 是对外分发口径。
 COMPLIANCE_DOCS = ("LICENSE", "NOTICE", "README.md")
 SUMS_NAME = "SHA256SUMS.txt"
+DEFAULT_BUILD_DIR = "target/release"
+
+# 发布矩阵：槽位 -> (OS 家族, 架构, 产物形态)。键名即产物文件名里的槽位段，
+# 单一真相源是 packaging/README.md §1；未知槽位一律拒绝，不出"凑合能跑"的产物。
+SLOTS = {
+    "windows-x64": ("windows", "x64", "exe"),
+    "windows-arm64": ("windows", "arm64", "exe"),
+    "linux-x64": ("linux", "x64", "tar"),
+    "linux-arm64": ("linux", "arm64", "tar"),
+    "macos-arm64": ("macos", "arm64", "tar"),
+    "macos-x64": ("macos", "x64", "tar"),
+}
+# `sys.platform` / `platform.machine()` 的别名归一（aarch64 与 arm64 是同一架构的两种叫法）。
+OS_FAMILIES = (("win", "windows"), ("linux", "linux"), ("darwin", "macos"))
+MACHINE_ALIASES = {"amd64": "x64", "x86_64": "x64", "aarch64": "arm64", "arm64": "arm64"}
+# 可执行文件头里的机器码 -> 架构（PE / ELF / Mach-O）。
+IMAGE_ARCH = {
+    ("pe", 0x8664): "x64",
+    ("pe", 0xAA64): "arm64",
+    ("elf", 0x3E): "x64",
+    ("elf", 0xB7): "arm64",
+    ("macho", 0x01000007): "x64",
+    ("macho", 0x0100000C): "arm64",
+}
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
-TARGET_DIR = REPO_ROOT / "target" / "release"
 
 
 def fail(message: str) -> NoReturn:
@@ -72,28 +104,59 @@ def workspace_version() -> str:
     return versions.pop()
 
 
-def platform_tag() -> str:
-    """Map the build host to the artifact matrix slot (hard-fail on unsupported ones)."""
-    os_name = sys.platform
-    machine = platform.machine().lower()
-    if os_name.startswith("win") and machine in ("amd64", "x86_64"):
-        return "windows-x64"
-    if os_name.startswith("linux") and machine in ("x86_64", "amd64"):
-        return "linux-x64"
-    if os_name == "darwin" and machine in ("arm64", "aarch64"):
-        return "macos-arm64"
-    if os_name == "darwin" and machine in ("x86_64", "amd64"):
-        return "macos-x64"
-    fail(f"unsupported build host {os_name}/{machine}; matrix is windows-x64 / linux-x64 / macos-arm64 / macos-x64")
+def host_slot(os_name: str | None = None, machine: str | None = None) -> str:
+    """Map the build host to a matrix slot.
+
+    Both arguments are injectable so the mapping can be exercised for a host we do not
+    own (no ARM machine here); they default to the real ones.
+    """
+    os_name = (sys.platform if os_name is None else os_name).lower()
+    raw_machine = platform.machine() if machine is None else machine
+    arch = MACHINE_ALIASES.get(raw_machine.lower())
+    family = next((fam for prefix, fam in OS_FAMILIES if os_name.startswith(prefix)), None)
+    for slot, (slot_os, slot_arch, _) in SLOTS.items():
+        if (slot_os, slot_arch) == (family, arch):
+            return slot
+    # 报错带**原始**取值而不是归一后的 None：`riscv64` 这类不认识的架构得在诊断里看得见。
+    fail(f"unsupported build host {os_name}/{raw_machine}; matrix is {' / '.join(SLOTS)}")
 
 
-def binary(name: str) -> Path:
-    path = TARGET_DIR / (f"{name}.exe" if sys.platform.startswith("win") else name)
+def binary(name: str, build_dir: Path, family: str) -> Path:
+    path = build_dir / (f"{name}.exe" if family == "windows" else name)
     if not path.is_file():
         fail(f"missing {path}; run `cargo build --release --locked` first")
     return path
 
 
+def image_arch(path: Path) -> str | None:
+    """Architecture stamped into the executable header, or `None` if unreadable."""
+    with path.open("rb") as handle:
+        head = handle.read(0x40)
+        if head[:4] == b"\x7fELF":
+            order = "little" if head[5] == 1 else "big"
+            return IMAGE_ARCH.get(("elf", int.from_bytes(head[18:20], order)))
+        if head[:2] == b"MZ":
+            handle.seek(int.from_bytes(head[0x3C:0x40], "little"))
+            pe = handle.read(6)
+            if pe[:4] == b"PE\0\0":
+                return IMAGE_ARCH.get(("pe", int.from_bytes(pe[4:6], "little")))
+            return None
+        if head[:4] == b"\xcf\xfa\xed\xfe":  # thin 64-bit little-endian Mach-O
+            return IMAGE_ARCH.get(("macho", int.from_bytes(head[4:8], "little")))
+    return None
+
+
+def verify_arch(path: Path, slot: str) -> None:
+    """Prove the binary really is built for the slot it is about to be named after."""
+    want = SLOTS[slot][1]
+    got = image_arch(path)
+    if got is None:
+        fail(f"cannot read the machine type of {path}; refusing to ship an unverified binary")
+    if got != want:
+        fail(f"{path} is a {got} binary but slot {slot} says {want}")
+    print(f"arch:     {path.name} -> {got} (ok for {slot})")
+
+
 def smoke_version(cli: Path, version: str) -> None:
     """`ull --version` must report the workspace version (guards tag/version drift)."""
     proc = subprocess.run(
@@ -108,7 +171,7 @@ def smoke_version(cli: Path, version: str) -> None:
         fail(f"`{cli.name} --version` exited {proc.returncode}: {out.strip()}")
     if version not in out:
         fail(f"`{cli.name} --version` does not report {version}: {out.strip()}")
-    print(f"smoke: {cli.name} --version -> {version} (ok)")
+    print(f"smoke:    {cli.name} --version -> {version} (ok)")
 
 
 def sha256(path: Path) -> str:
@@ -160,6 +223,8 @@ def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--version", help="expected version (a leading 'v' is stripped); cross-checks Cargo.toml")
     parser.add_argument("--out", default="dist", help="output directory (default: dist/)")
+    parser.add_argument("--slot", choices=list(SLOTS), help="matrix slot; defaults to the one derived from the host")
+    parser.add_argument("--build-dir", default=DEFAULT_BUILD_DIR, help=f"directory holding the built binaries (default: {DEFAULT_BUILD_DIR})")
     parser.add_argument("--no-smoke", action="store_true", help="skip the `ull --version` smoke run")
     args = parser.parse_args()
 
@@ -168,22 +233,32 @@ def main() -> int:
         expected = args.version[1:] if args.version.startswith("v") else args.version
         if expected != version:
             fail(f"tag/version mismatch: requested {expected}, Cargo.toml says {version}")
-    tag = platform_tag()
-    launcher = binary(LAUNCHER_BIN)
-    cli = binary(CLI_BIN)
-    if not args.no_smoke:
-        smoke_version(cli, version)
+    native = host_slot()
+    slot = args.slot or native
+    family, _, kind = SLOTS[slot]
+    build_dir = Path(args.build_dir)
+    if not build_dir.is_absolute():
+        build_dir = REPO_ROOT / build_dir
+    launcher = binary(LAUNCHER_BIN, build_dir, family)
+    verify_arch(launcher, slot)
+    # 跨槽位产物（宿主 x64 / 目标 arm64）在本机根本执行不了，冒烟只能等 CI 真机；
+    # 拿"跳过了"当通过是假证据，所以把跳过原因原样打出来。
+    if args.no_smoke or slot != native:
+        reason = "--no-smoke" if args.no_smoke else f"host is {native}, artifact is {slot}"
+        print(f"smoke:    skipped ({reason})")
+    else:
+        smoke_version(binary(CLI_BIN, build_dir, family), version)
 
     out_dir = Path(args.out)
     if not out_dir.is_absolute():
         out_dir = REPO_ROOT / out_dir
     out_dir.mkdir(parents=True, exist_ok=True)
 
-    if tag == "windows-x64":
-        asset = out_dir / f"unlucky-launcher-{version}-{tag}.exe"
+    if kind == "exe":
+        asset = out_dir / f"unlucky-launcher-{version}-{slot}.exe"
         shutil.copy2(launcher, asset)
     else:
-        asset = stage_archive(out_dir, tag, version, launcher)
+        asset = stage_archive(out_dir, slot, version, launcher)
 
     sums = write_sums(out_dir, [asset])
     size_mb = asset.stat().st_size / (1024 * 1024)

packaging/release-notes.md

@@ -9,7 +9,9 @@ No WebView, no bundled runtime, no JRE download needed to start the launcher its
 | Platform | Asset | Notes |
 | --- | --- | --- |
 | Windows 10/11 x64 | `unlucky-launcher-{{VERSION}}-windows-x64.exe` | single exe, double-click to run |
+| Windows 11 ARM64 | `unlucky-launcher-{{VERSION}}-windows-arm64.exe` | single exe, runs natively on ARM64 Windows |
 | Linux x64 (X11/Wayland) | `unlucky-launcher-{{VERSION}}-linux-x64.tar.gz` | single binary inside, no installer |
+| Linux arm64 (X11/Wayland) | `unlucky-launcher-{{VERSION}}-linux-arm64.tar.gz` | single binary inside; needs glibc 2.35+ |
 | macOS 12+ Apple Silicon | `unlucky-launcher-{{VERSION}}-macos-arm64.tar.gz` | single binary inside, no installer |
 | macOS 12+ Intel | `unlucky-launcher-{{VERSION}}-macos-x64.tar.gz` | single binary inside, no installer |
 
@@ -22,22 +24,30 @@ with the download on every platform.
 | Platform | Level | Runtime requirements |
 | --- | --- | --- |
 | Windows 10/11 x64 | first class | nothing beyond the OS (UCRT is part of Win10+) |
+| Windows 11 ARM64 | first class (launcher artifact) | nothing extra; launcher runs natively, the game itself runs through the OS x64 emulation layer with an x64 JDK |
 | macOS 12+ (arm64 / x64) | first class | nothing; unsigned build, see Gatekeeper note |
 | Linux x64, X11 | first class | `libxkbcommon`, `fontconfig`, `libGL` (or software renderer), `libxcb` |
 | Linux x64, Wayland | supported | `wayland-client`, `libxkbcommon`, plus the X11 set for XWayland apps |
+| Linux arm64, X11 | first class | glibc 2.35+ (built on `ubuntu-22.04-arm`, same floor as x64), `libxkbcommon`, `fontconfig`, `libGL`, `libxcb` |
+| Linux arm64, Wayland | supported | the above plus `wayland-client` |
 | Windows 8.1/8/7 | unsupported | baseline was raised to Win10 (decision D21) |
 | Android — Termux + X11 | experimental, not promised | CLI only (build from source), GUI unverified; not part of this release matrix |
 
+Both arm64 rows are **formally released slots** (the assets ship in this release and in
+`SHA256SUMS.txt`), not the experimental Termux path: Linux arm64 is built and smoke-tested on a
+native ARM64 runner, Windows ARM64 is cross-built with the same static-CRT gate as x64.
+
 ## Install
 
-**Windows** — put the `.exe` anywhere and run it. Portable data lives next to the exe when a
+**Windows** — put the `.exe` anywhere and run it (pick `-windows-arm64.exe` on ARM64 Windows,
+`-windows-x64.exe` everywhere else). Portable data lives next to the exe when a
 `portable.marker` file is present, otherwise under `%APPDATA%`.
 
 **Linux**
 
 ```bash
-tar -xzf unlucky-launcher-{{VERSION}}-linux-x64.tar.gz
-cd unlucky-launcher-{{VERSION}}-linux-x64
+tar -xzf unlucky-launcher-{{VERSION}}-linux-x64.tar.gz   # use linux-arm64 on aarch64
+cd unlucky-launcher-{{VERSION}}-linux-x64                # ditto
 chmod +x unlucky-launcher && ./unlucky-launcher
 ```