feat(design): 加 unlucky-design 令牌 crate（M3 色彩/排版/形状/动效/图标）

D26 把视觉基线锁到 Material 3 Expressive，本 crate 是「UI 整体性」的地基：令牌唯一真源，后续 iced 页面只消费不新增。零第三方依赖、零 UI 框架依赖（cargo tree -p unlucky-design --edges normal 只有它自己一行）。 - 色彩：49 个 M3 语义角色 × light/dark，种子色派生 6 条 tone 调色板； tone 轴严格用 CIELAB L*（偏差 ≤1），色相/彩度用 OKLCh 近似 CAM16 并在模块文档里写明口径与已知偏差（不宣称是标准 HCT 动态取色） - 对比度：26 组文字对 × 6 组种子 × 2 模式全部 ≥4.5:1；3 条例外显式登记（Outline 非文字 3:1、OutlineVariant 装饰、SurfaceVariant 是容器色） - 排版：M3 type scale 15 档 + 三平台字体族回退栈（只写族名，不内嵌受限字体） - 形状/高程/动效：Expressive 形状刻度 + shape morph 数据、elevation 级别与 surface container 映射、时长/缓动/弹簧（纯函数可采样） - 图标：24 个从 Slint 版迁移的 SVG path + 4 个新增，IconKind 冻结只可末尾追加；写明 Slint 的 stroke-width 是绝对像素、SVG 是 viewBox 用户单位的语义差异，换算封装成 Icon::stroke_width - 组件档位表：20 个组件的形状/高程/字体/动效一次取全 TODO(M63)：elevation shadow 的 blur/offset/alpha 与四组弹簧参数是占位值，接口先定、数值待玻璃视觉规格表（tower 已通告边界）。
2026-11-01 15:34:04 +08:00
1 parent fef0922073
commit 65ca0ed29a
@@ -0,0 +1,205 @@
+//! 令牌契约测试：从**消费方视角**（只用公开 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_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 name in stack {
+                let lower = name.to_ascii_lowercase();
+                for banned in [".ttf", ".otf", ".ttc", "woff", "file"] {
+                    assert!(
+                        !lower.contains(banned),
+                        "{} 的字体栈出现文件引用 {name}（只允许族名，禁止内嵌受限字体）",
+                        platform.name()
+                    );
+                }
+            }
+        }
+    }
+}
+
+#[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_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() {
+    assert_eq!(Component::ALL.len(), 20);
+    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);
+}
+
+#[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, 0.1);
+    for tone in [20.0_f32, 40.0, 60.0, 80.0] {
+        let color = palette.tone(tone);
+        assert!(
+            (color.lstar() - tone).abs() <= 1.0,
+            "tone {tone} 实际 {}",
+            color.lstar()
+        );
+    }
+}