@qw-ui/tokens 0.3.0-next.40 → 0.3.0-next.43

package/README.md

@@ -1,79 +1,43 @@
 # @qw-ui/tokens
 
-> QW token pipeline：Figma Color variables 是颜色唯一事实源；代码侧校验快照并构建出 CSS / TS 产物。
-
-**层级 L1 · 设计令牌**。qw-ui 全链路样式的单一数据源，所有组件颜色/尺寸只允许引用本包派生出的 **T3 Semantic token（`--qw-sem-*`）**，禁止直写字面量。
-
-## 三层架构
-
-```
-T1 Seed（可选生成参数） ── alias / derive / calibrate ──► T2 Reference
-                                                           │
-                                                           ▼
-                                      T3 Semantic (--qw-sem-*) → Component / Style
-```
-
-T2 是完整机械标尺，可来自 Seed、设计校准、标准常量或外部标准；每条都带 DTCG
-provenance。T3 只引用 T2，组件与业务只碰 T3。
+设计 Token 与主题。Design tokens and theme utilities for qw-ui.
 
 ## 安装
 
+当前开发版本使用 `next`：
+
 ```bash
-pnpm add @qw-ui/tokens
+npm install @qw-ui/tokens@next
 ```
 
-无 peer 依赖。
+包发布于 [公共 npm](https://www.npmjs.com/package/@qw-ui/tokens)。如环境配置了其他镜像，可在安装命令后追加 `--registry=https://registry.npmjs.org/`。
 
 ## 最小示例
 
 ```ts
-// 1. 静态变量（构建期固化，SSR 友好，不随运行时切换）
-import "@qw-ui/tokens/tokens.css";
+import '@qw-ui/tokens/tokens.css';
+import { defaultSeed, derive } from '@qw-ui/tokens';
 
-// 2. 或 live 变量（支持运行时亮暗/主题切换）
-import "@qw-ui/tokens/tokens.live.css";
-
-// 3. TS 侧拿 token 路径类型 / 原始 JSON
-import type { TokenPath } from "@qw-ui/tokens/token-paths";
-import tokens from "@qw-ui/tokens/tokens.json" with { type: "json" };
-```
-
-CSS 里直接用变量：
-
-```css
-.card { color: var(--qw-sem-color-content-primary); background: var(--qw-sem-color-surface-base); }
+const theme = derive(defaultSeed);
+console.log(theme);
 ```
 
-## tokens.css vs tokens.live.css
+## 使用说明
 
-| 产物 | 用途 | 亮暗切换 |
-|---|---|---|
-| `tokens.css` | 默认静态变量，构建期固化 | 需整页换文件 |
-| `tokens.live.css` | 语义变量随 `<html data-qw-mode>` / Provider 解析 | 运行时切换（见下） |
+应用使用 `tokens.css` 提供默认变量；组件消费 `--qw-sem-*` 语义变量。可通过容器的 `data-qw-mode="dark"` 使用暗色主题。`tokens.live.css`、`tailwind.css`、`tokens.json` 等公开资源按项目需求选择，具体入口以 package exports 为准。
 
-**亮暗两种做法**：① 在 `<html>` 上写 `data-qw-mode="dark"`；② React/Vue 用 `QwConfigProvider` 的 `applyMode` / `toggleMode`。两者都只切 T3 解析，不改组件。
+## 兼容性
 
-## 关联包
-
-| 包 | 关系 |
-|---|---|
-| [@qw-ui/react](../react/README.md) / [@qw-ui/vue](../vue/README.md) | 消费 T3 token 渲染组件，需先引本包 CSS |
-| [@qw-ui/theme-editor](../theme-editor/README.md) | 可视化编辑 Seed → 实时预览三层级联 |
-| `@qw-ui/styles-core`（private，不发布） | vanilla-extract 样式事实源，只读本包 T3 token |
-
-设计稿老色值 → T3 映射见 skill `qw-legacy-token-map`。
+CSS 面向 Chrome 123 / iOS Safari 16.4。主题派生 API 可用于 Node 构建工具和浏览器。
 
 ## 版本通道
 
-| 通道 | 安装 | 说明 |
-|---|---|---|
-| `latest`（稳定） | `pnpm add @qw-ui/tokens` | `main` 通道，Release PR review 后发布 |
-| `next`（预发布） | `pnpm add @qw-ui/tokens@next` | `release/next` 通道，高频自增 `x.y.z-next.N` |
-
-9 个公开包 `fixed` 锁步同版本号。npm 发布固定走 `registry.npmjs.org`；内网装依赖走 `registry.anpm.alibaba-inc.com`（tnpm 代理），发布 registry 不要指向内网。流程详见 [development-workflow.md](../../docs/development-workflow.md)。
+- `next`：main 更新并通过检查后自动发布，用于试用当前能力。
+- `latest`：负责人手动发布的正式版本。正式版可用后，使用 `npm install @qw-ui/tokens@latest`；正式版支持范围以该版本 README 为准。
+- 生产项目建议锁定明确版本。配套使用的 `@qw-ui/*` 包应选择同批版本；内部运行时依赖由包管理器安装。
 
-## 仓库 & License
+## 文档与许可证
 
-- 主仓库：<http://gitlab.alibaba-inc.com/qianwen/qw-ui>
-- 问题反馈：<http://gitlab.alibaba-inc.com/qianwen/qw-ui/issues>
-- License：MIT
+- [组件文档与接入指南](https://qw-ui.qianwen.com/)
+- [npm 版本列表](https://www.npmjs.com/package/@qw-ui/tokens?activeTab=versions)
+- MIT，详见包内 `LICENSE`。

package/dist/color-architecture.d.ts

@@ -9,10 +9,18 @@ export type T2AlphaStep = (typeof T2_ALPHA_STEPS)[number];
 export type T2AlphaKey = (typeof T2_ALPHA_KEYS)[number];
 export declare const T2_OKLCH_STEPS: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
 export type T2OklchStep = (typeof T2_OKLCH_STEPS)[number];
+/** RFC0012 approved local standard endpoint; Figma synchronization is pending. */
+export declare const T2_BLACK_CONTRAST_ENDPOINT: {
+    readonly step: "contrast-endpoint";
+    readonly value: "#000000";
+    readonly source: "CSS Color sRGB black mathematical endpoint; specs/rfcs/0012-brand-solid-text-contrast.md";
+    readonly rationale: "The zero sRGB endpoint is a standard constant for on-brand AA text, independent of Seed and existing color scales.";
+};
 export declare const FIGMA_T2_SOLID_SCALE: Record<T1ColorKey, Record<T2OklchStep, string>>;
 /**
- * Figma「Color Token System」T3 语义角色表（60 个，light/dark 均引用 T2 路径）。
- * 与 Figma 节点 22258:49986 逐条对齐；`effect.shadow.*.color` 为复合阴影的颜色
+ * Figma「Color Token System」既有角色及用户批准的本地补充角色。
+ * 既有角色与 Figma 节点 22258:49986 对齐；新角色等待 Figma 同步，不冒充已回流。
+ * light/dark 均引用 T2；`effect.shadow.*.color` 为复合阴影的颜色
  * 分量（对应 Figma 变量 `--qw-sem-effect-shadow-*-color`）。
  */
 export declare const FIGMA_T3_COLOR_ROLES: {
@@ -56,6 +64,10 @@ export declare const FIGMA_T3_COLOR_ROLES: {
         readonly light: "color.gray.50";
         readonly dark: "color.black.900";
     };
+    readonly "content.danger": {
+        readonly light: "color.red.600";
+        readonly dark: "color.red.300";
+    };
     readonly "content.primary": {
         readonly light: "color.black.base";
         readonly dark: "color.white.base";
@@ -96,6 +108,10 @@ export declare const FIGMA_T3_COLOR_ROLES: {
         readonly light: "color.white.base";
         readonly dark: "color.white.base";
     };
+    readonly "content.on-brand": {
+        readonly light: "color.white.base";
+        readonly dark: "color.black.contrast-endpoint";
+    };
     readonly "content.on-warning-subtle": {
         readonly light: "color.yellow.800";
         readonly dark: "color.yellow.200";
@@ -108,6 +124,10 @@ export declare const FIGMA_T3_COLOR_ROLES: {
         readonly light: "color.gray.300";
         readonly dark: "color.gray.600";
     };
+    readonly "border.control": {
+        readonly light: "color.gray.600";
+        readonly dark: "color.gray.base";
+    };
     readonly "border.focus": {
         readonly light: "color.brand.base";
         readonly dark: "color.brand.500";
@@ -169,8 +189,8 @@ export declare const FIGMA_T3_COLOR_ROLES: {
         readonly dark: "color.blue.a20";
     };
     readonly "control-action.danger.default": {
-        readonly light: "color.red.400";
-        readonly dark: "color.red.400";
+        readonly light: "color.red.600";
+        readonly dark: "color.red.600";
     };
     readonly "control-action.danger.subtle": {
         readonly light: "color.red.a10";
@@ -240,6 +260,10 @@ export declare const FIGMA_T3_COLOR_ROLES: {
         readonly light: "color.black.a50";
         readonly dark: "color.black.a50";
     };
+    readonly "overlay.control-on-media": {
+        readonly light: "color.black.a50";
+        readonly dark: "color.white.a40";
+    };
     readonly shadow: {
         readonly light: "color.black.a10";
         readonly dark: "color.black.a50";

package/dist/derive/index.d.ts

@@ -6,7 +6,7 @@ export type { Step, Ramp } from "./oklch.js";
 export type { SemanticMode as Mode } from "./semantic.js";
 export type { ReferenceRecipe, ReferenceTokens, ReferenceBuild, Derivation, ReferenceSourceKind, ShadowLevel, ShadowShape, } from "./reference.js";
 export { buildReference, allReferenceRecipes, evaluateDerivation, seedRefsOf, sourceKindOf, formatDerivation, seedValueAt, RAMP_COLORS, BLACK_ALPHA, WHITE_ALPHA, RADIUS_FACTORS, FONT_SIZE_FACTORS, DURATION_FACTORS, SHADOW_LEVELS, FONT_FAMILY_KEYS, } from "./reference.js";
-export { buildSemanticStructural, buildSemanticColor, semanticRoleEntries, RADIUS_ROLES, CONTROL_HEIGHT_ROLES, ICON_SIZE_ROLES, INSET_STACK_ROLES, Z_INDEX_ROLES, MOTION_DURATION_ROLES, FONT_FAMILY_ROLES, TYPOGRAPHY_ROLES, TYPOGRAPHY_FIELDS, COLOR_ROLES, SHADOW_COMPOSITE_ROLES, } from "./semantic.js";
+export { buildSemanticStructural, buildSemanticColor, semanticRoleEntries, RADIUS_ROLES, CONTROL_HEIGHT_ROLES, ICON_SIZE_ROLES, INSET_STACK_ROLES, Z_INDEX_ROLES, MOTION_DURATION_ROLES, MOTION_EASING_ROLES, SKELETON_SIZE_ROLES, LOADING_SIZE_ROLES, LAYOUT_GAP_ROLES, FONT_FAMILY_ROLES, TYPOGRAPHY_ROLES, TYPOGRAPHY_FIELDS, COLOR_ROLES, SHADOW_COMPOSITE_ROLES, } from "./semantic.js";
 export type { SemanticRoleEntry, ColorRoleRefs, TypographyRole } from "./semantic.js";
 export interface DerivedTokens {
     /** 亮色全量 CSS 变量：--qw-ref-* ∪ --qw-sem-*（light 取值）。 */

package/dist/derive/reference.d.ts

@@ -16,7 +16,8 @@ import type { Seed } from "../schema.js";
  * 颜色层对齐 Figma `Color/qw` 变量集合：
  * - T1 Seed 为 12 个单色种子；
  * - T2 Reference 为每个 seed 的 A5-A100 Alpha 通道、50-900 OKLCH 设计校准实色色阶、
- *   base 引用。T2 Color 不接受零散补色或「色阶 × Alpha」组合。
+ *   base 引用，以及 RFC0012 批准的纯黑 standard-constant 数学端点。
+ *   T2 Color 不接受其它零散补色或「色阶 × Alpha」组合。
  */
 export type ShadowLevel = "sm" | "md" | "lg";
 /**
@@ -104,6 +105,12 @@ export type Derivation =
     kind: "literal";
     value: string | number;
 }
+/** UA-owned CSS environment value; preserved as an expression, never a guessed device length. */
+ | {
+    kind: "cssEnvironment";
+    name: `safe-area-inset-${"top" | "right" | "bottom" | "left"}`;
+    fallback: "0px";
+}
 /** 阴影档位：形状 = shadow.base × 档位比例，颜色 = alphaStep × 档位倍数。 */
  | {
     kind: "shadowLayer";
@@ -181,6 +188,10 @@ export declare const RADIUS_FACTORS: {
 };
 /** 5. 圆角刻度：sm/md/lg/xl 由 radius.base 按系数派生，full 直通独立裁切基准。xl=2×base 对齐治理稿 Radius v2 的 T2 double。 */
 export declare function buildRadiusRecipes(): ReferenceRecipe[];
+/** Existing public placeholder geometry: font-relative text and calibrated media. */
+export declare function buildPlaceholderSizeRecipes(): ReferenceRecipe[];
+/** Loading logo boxes follow the independent existing public size contract. */
+export declare function buildLoadingSizeRecipes(): ReferenceRecipe[];
 /** 6. 控件/图标尺寸：md = base 直通，sm/lg = base ∓ spacing.step × n（控件 ×2、图标 ×1）。 */
 export declare function buildControlIconSizeRecipes(): ReferenceRecipe[];
 /** 描边宽度梯度系数（Figma Stroke v1：Half/Base/Double/Triple = 0.5/1/2/3）。 */

package/dist/derive/semantic.d.ts

@@ -24,6 +24,13 @@ export declare const FOCUS_RING_ROLES: Record<string, string>;
 export declare const INDICATOR_ROLES: Record<string, string>;
 /** 展示类专用尺寸：Avatar 直径三档（Figma 头像 S/M/L）。 */
 export declare const AVATAR_DIAMETER_ROLES: Record<string, string>;
+/** Independent placeholder roles reference T2 directly, never other T3 roles. */
+export declare const SKELETON_SIZE_ROLES: Record<string, string>;
+export declare const MOTION_EASING_ROLES: Record<string, string>;
+export declare const LOADING_SIZE_ROLES: Record<string, string>;
+export declare const LAYOUT_GAP_ROLES: Record<string, string>;
+export declare const SAFE_AREA_INSET_ROLES: Record<string, string>;
+export declare const SAFE_AREA_MINIMUM_ROLES: Record<string, string>;
 export declare const INSET_STACK_ROLES: Record<string, string>;
 export declare const Z_INDEX_ROLES: Record<string, string>;
 export declare const MOTION_DURATION_ROLES: Record<string, string>;