@q1travel/design-system 0.15.3 → 0.17.0

package/README.md

@@ -12,7 +12,7 @@ q1travel 产品家族的设计权威上游仓，三件事集于一处：`@q1trav
 - Generated mirrors（生成镜像，勿手改）：`public/design.md`、`public/design.dark.md` 由 `scripts/sync-design-contracts.mjs` 从契约源逐字节复制；`public/design.css` 由 `scripts/build-design-css.mjs` 把两份契约 frontmatter 的取值注入 `contracts/design.css` 的类词汇后生成，因而自足、可被独立 HTML 页面直接加载。
 - Runtime tokens：`src/styles/tokens.css`（canonical `--q1-*`，仅 `:root` 与 `:root[data-theme='dark']` 两个扁平 selector）。
 - 发布台账：`contracts/releases/`（仅存于仓库，不进 npm 包）。
-- npm 发布与下游自动更新：[发布操作说明](docs/npm-release.md)。
+- npm 发布与下游自动更新：版本 tag 触发 GitHub Actions OIDC 免令牌发布，详见[发布操作说明](docs/npm-release.md)。
 
 ## Getting Started
 
@@ -35,6 +35,9 @@ npm run dev
 | `npm run check:browser` | 基于 CDP 的浏览器行为契约（含 StrictMode 前置轮） |
 | `npm run check:package-api` | 已构建包的声明与运行时 API + 组件契约 `node --test` 套件 |
 | `npm run check:release-provenance` | 发布台账 vs `CHANGELOG.md`、origin tag 与 npm registry |
+| `npm run check:release-sync` | 发布后 registry 完整性与四仓 Renovate 通知脚本测试 |
+| `npm run release:verify -- <tarball>` | 只校验 workflow tarball 与 npm registry 完整性 |
+| `npm run release:sync -- <tarball>` | 校验 registry 后通知四仓 Renovate；不具备发布能力 |
 | `npm run build:pkg` | 库构建（产物 `dist-pkg/`）+ CSS 拼装 + 包 API 检查（`prepack` 同款） |
 
 本仓没有独立的 test / lint script——规范由 `scripts/` 下的契约门禁脚本守护。

package/contracts/design.dark.md

@@ -120,9 +120,12 @@ semantic-colors:
   action-primary-hover: "{colors.primary-hover}"
   action-primary-press: "{colors.primary-press}"
   action-on-primary: "#ffffff"
+  action-text: "{colors.primary-900}"
   surface-canvas: "{colors.background-100}"
   surface-subtle: "{colors.gray-100}"
   surface-panel: "{colors.background-100}"
+  surface-media: "#0a0a0a"
+  text-on-media: "#ffffff"
   border: "{colors.gray-200}"
   border-strong: "{colors.gray-400}"
   text-primary: "{colors.text-primary}"
@@ -385,8 +388,8 @@ These components ship in the package. Compose from this list before writing new
 
 **Option fields.** ControlOption, Checkbox, Radio, Choicebox, Combobox, MultiSelect, Switch, Toggle, Slider, RangeSlider.
 
-- Switch commits immediately. Checkbox stages a change that a submit applies. Choosing the wrong one misstates when the change takes effect.
-- Toggle selects among mutually exclusive views. It is not a Switch with more entries.
+- Toggle represents one on/off setting and reports a requested change immediately. Checkbox stages a change that a submit applies. Choosing the wrong one misstates when the change takes effect.
+- Switch selects among mutually exclusive views or modes.
 - RangeSlider is two thumbs over one interval, paired with numeric inputs; Slider is a single value.
 
 **Dates and ranges.** CalendarGrid, RangeInputs, RangeField, PeriodCombobox, addDays.

package/contracts/design.md

@@ -120,9 +120,12 @@ semantic-colors:
   action-primary-hover: "{colors.primary-hover}"
   action-primary-press: "{colors.primary-press}"
   action-on-primary: "#ffffff"
+  action-text: "{colors.primary-700}"
   surface-canvas: "{colors.background-100}"
   surface-subtle: "{colors.background-200}"
   surface-panel: "{colors.background-100}"
+  surface-media: "#0a0a0a"
+  text-on-media: "#ffffff"
   border: "{colors.gray-400}"
   border-strong: "{colors.gray-500}"
   text-primary: "{colors.text-primary}"
@@ -385,8 +388,8 @@ These components ship in the package. Compose from this list before writing new
 
 **Option fields.** ControlOption, Checkbox, Radio, Choicebox, Combobox, MultiSelect, Switch, Toggle, Slider, RangeSlider.
 
-- Switch commits immediately. Checkbox stages a change that a submit applies. Choosing the wrong one misstates when the change takes effect.
-- Toggle selects among mutually exclusive views. It is not a Switch with more entries.
+- Toggle represents one on/off setting and reports a requested change immediately. Checkbox stages a change that a submit applies. Choosing the wrong one misstates when the change takes effect.
+- Switch selects among mutually exclusive views or modes.
 - RangeSlider is two thumbs over one interval, paired with numeric inputs; Slider is a single value.
 
 **Dates and ranges.** CalendarGrid, RangeInputs, RangeField, PeriodCombobox, addDays.

package/contracts/implementation-map.md

@@ -33,7 +33,7 @@ README owns the repository inventory and generated-file boundary. This file owns
 
 Two component-page sections are q1travel supersets with no external counterpart, so their scope is defined here rather than inferred page by page.
 
-- **设计 Token** — every Tier B native-semantic control page (Button, Input, Textarea, Select, Checkbox, Radio, Switch) MUST carry this section. Those controls take their whole surface from semantic tokens, so the role/token/usage table is the only place a consumer can see which tokens to override. Tier A and Tier C pages MUST NOT add it by default: their appearance comes mostly from structure, and a token table there restates the global palette without telling the reader anything component-specific. **Tabs is the one recorded exception** — a Tier A component whose surface is likewise entirely token-driven; it keeps its table, and it does not license other Tier A pages to add one.
+- **设计 Token** — every Tier B native-semantic control page (Button, Input, Textarea, Select, Checkbox, Radio, Toggle) MUST carry this section. Those controls take their whole surface from semantic tokens, so the role/token/usage table is the only place a consumer can see which tokens to override. Tier A and Tier C pages MUST NOT add it by default: their appearance comes mostly from structure, and a token table there restates the global palette without telling the reader anything component-specific. **Switch and Tabs are the two recorded exceptions** — these Tier A components are likewise entirely token-driven; they keep their tables, and they do not license other Tier A pages to add one.
 - **API 与行为矩阵** — reserved for composite host components that the consumer assembles while the host owns the state (ContextSwitcher, Navigation, Sidebar). The table exists to state who owns what; a component that owns its own state does not need it.
 
 Rows in these tables reference semantic tokens (`--q1-color-*`, `--q1-shadow-*`, `--q1-radius-*`), not component-private custom properties. Component-private properties driven by props (for example an avatar diameter) are implementation detail and MUST NOT be documented as a consumer-facing token contract.

package/contracts/token-naming.md

@@ -29,6 +29,15 @@ Examples:
 
 Reference color scales use numeric steps from `100` to `1000`.
 
+#### Scale Steps
+
+Non-color reference scales carry their own step rules, so a value that is off the scale shows up as a missing token rather than as a raw number in product CSS.
+
+- **Spacing** — the step number is the pixel value divided by four: `--q1-space-4` is `16px`. Half steps fill the gaps inside the 4px grid where a whole step reads as too loose or too tight: `--q1-space-1-5` (`6px`), `--q1-space-2-5` (`10px`), `--q1-space-3-5` (`14px`). The scale runs `1`, `1-5`, `2`, `2-5`, `3`, `3-5`, `4`, `5`, `6`, `8`, `10`, `16`, `24`; it thins out above `20px` because a large gap is read as layout, not as fine adjustment.
+- **Radius** — `--q1-radius-1` through `--q1-radius-5` (`4`, `6`, `8`, `12`, `16px`), plus `--q1-radius-full` (`9999px`) for a pill. The pill value is deliberately larger than any half-height it can meet: it is a shape, not a measurement, and it does not interpolate with the numbered steps.
+- **Line height** — two families coexist. `--q1-line-height-<role>-<size>` is a pixel line box bound to one font-size step, and typography styles use it. `--q1-line-height-tight` (`1.2`), `-snug` (`1.35`), `-normal` (`1.5`), and `-relaxed` (`1.6`) are unitless and scale with whatever font size they land on; they serve text whose size is not one of the typography steps, such as a body block or a table cell.
+- **Font weight** — `--q1-font-weight-regular` (`400`), `-medium` (`500`), `-semibold` (`600`), `-bold` (`700`). Four steps is the whole scale; a weight between two of them is not a distinction the font stack renders consistently.
+
 ### Motion Tokens
 
 Motion tokens are the single source for transition and animation values. They are split on the only two questions a motion value answers.
@@ -83,6 +92,9 @@ Examples:
 - `--q1-color-action-primary`
 - `--q1-color-status-danger`
 - `--q1-shadow-focus`
+- `--q1-shadow-focus-danger`
+
+`--q1-shadow-focus-danger` is the ring the field family already draws on an invalid control, now named: one step wider and one step lighter than `--q1-shadow-focus`, because red at the same opacity swallows the 1px red border it sits on. Both rings resolve their color through a semantic token, so light and dark need no separate declaration.
 
 ### Component Tokens