@q1travel/design-system 0.15.0 → 0.15.2

package/README.md

@@ -8,7 +8,7 @@ q1travel 产品家族的设计权威上游仓，三件事集于一处：`@q1trav
 
 ## Sources
 
-- Source contracts（设计契约源，canonical）：`contracts/design.md`、`contracts/design.dark.md`、`contracts/token-naming.md`、`contracts/icon-system.md`、`contracts/button-api-compatibility.md`、`contracts/interface-guidelines.md`、`contracts/design-engineering-principles.md`、`contracts/implementation-map.md`、`contracts/overlay-foundation.md`，以及迁移契约 `contracts/status-chip-badge-migration.md`、`contracts/pagination-migration.md`、`contracts/table-migration.md`、`contracts/overlay-shadow-migration.md`。独立 HTML 文档的有界 class 词汇表源为 `contracts/design.css`。
+- Source contracts（设计契约源，canonical）：`contracts/design.md`、`contracts/design.dark.md`、`contracts/token-naming.md`、`contracts/icon-system.md`、`contracts/button-api-compatibility.md`、`contracts/interface-guidelines.md`、`contracts/design-engineering-principles.md`、`contracts/implementation-map.md`、`contracts/overlay-foundation.md`，以及迁移契约 `contracts/context-contrast-migration.md`、`contracts/status-chip-badge-migration.md`、`contracts/pagination-migration.md`、`contracts/table-migration.md`、`contracts/overlay-shadow-migration.md`。独立 HTML 文档的有界 class 词汇表源为 `contracts/design.css`。
 - 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 包）。

package/contracts/context-contrast-migration.md

@@ -0,0 +1,85 @@
+# Context and text contrast migration
+
+## Scope and approval
+
+Issues #246, #245, and #244 share a package ownership boundary. The consumer
+approved implementation on 2026-09-09 after reviewing the source audit and
+correcting the original ramp interpretation. This plan covers the existing
+`text-muted` semantic token, Navigation active text, and the `stacked`
+ContextSwitcher presentation. The consumer accepted the rendered result and authorized commit and release on
+2026-09-11. The target patch release is 0.15.1; the starting consumer version is
+0.15.0. This migration does not include source edits in consuming repositories.
+
+## #246: readable supporting text
+
+The reference ramps keep their existing values. In particular, gray-700 and
+gray-800 are solid-background steps; they intentionally do not flip by theme.
+There is no global monotonic-ramp requirement.
+
+| Semantic token | Before | After | Supported surfaces |
+| --- | --- | --- | --- |
+| Light `--q1-color-text-muted` | gray-700, `#8f8f8f` | `#6b6b6b` | canvas, panel, subtle |
+| Dark `--q1-color-text-muted` | gray-800, `#7d7d7d` | gray-700, `#8f8f8f` | canvas, panel, subtle |
+
+Light supporting text needs its own semantic value between gray-800 and
+gray-900: gray-800 misses normal-text AA, while gray-900 would collapse the
+secondary/muted distinction. Dark supporting text can reuse gray-700. All three
+text levels retain descending contrast on the supported surfaces and meet
+WCAG 2 AA normal-text contrast (4.5:1). Arbitrary consumer surfaces, opacity,
+blending, and disabled styling require their own effective-color checks.
+
+Regenerate `public/design.md`, `public/design.dark.md`, and `public/design.css`
+through `npm run sync:contracts`; runtime and contract values must agree.
+The regression gate checks named text/surface pairs and button-label/solid
+pairs. It must not treat every color as text or accept unsupported color syntax
+silently. Existing browser checks cover composed component colors.
+
+Consumer follow-up after upgrading: q1travel-web PR #998 introduced
+`body.theme-dark .settings-appearance-layout { --text-tertiary: var(--q1-color-gray-700); }`.
+Remove that workaround and resume the normal `--q1-color-text-muted` mapping.
+Recheck the related appearance labels, docs supporting text, raw-color ratchet,
+`check-contrast-contract`, and full Web gates. Other #998 text-secondary
+substitutions should be reviewed individually, not mechanically reverted.
+
+## #245: Navigation active text
+
+Both vertical and horizontal active items, including hover, use the existing
+`--q1-color-primary-900` text-capable step (solution A). The label and decorative
+icon inherit the same foreground. Preserve semibold, transparent resting
+background, neutral hover, focus indication, native activation, and route-owned
+`aria-current`. Do not change the action-primary button background.
+
+This is a package-only CSS change. Web requires no source adjustment. A new
+brand-text semantic token is not introduced in this migration.
+
+## #244: stacked current context
+
+The existing `presentation: { type: 'stacked' }` adopts one consistent visual
+behavior, without new props. Grouped and drilldown keep their presentations.
+
+- A selected `menuitemradio` retains `aria-checked`, with a subtle full-row fill
+  and an inline-start accent rail instead of a trailing check. Pending feedback
+  remains visible. Focus and current-context indicators remain distinguishable.
+- `depth: 1` uses a connector to the preceding depth-0 context within the same
+  group. The last child ends the branch at its center. Search results keep their
+  existing filtering behavior; when the parent is absent, retain indentation
+  without a misleading connector. These decorative lines do not create a Tree
+  widget or alter the menu keyboard model.
+- Hover fades a background layer via opacity using duration-press (120ms).
+  Pointer opening introduces a short, capped list entrance whose last completion
+  is no later than duration-fast (150ms). Search, pending changes, and selection
+  updates do not replay the entrance. Keyboard opening and reduced motion are
+  immediate. Closing unmounts immediately.
+
+Consumer follow-up: upgrade and verify the work-place map with real grouped
+data, sparse/search results, pending/error states, long names, RTL, touch,
+keyboard, and reduced motion. No package-private BEM overrides are required.
+API #538 and #539 remain backend work and are not prerequisites for this change.
+
+## Acceptance and delivery boundary
+
+Require failing-then-passing focused contrast and component assertions, light
+and dark rendered proof, a 390px responsive check, and the full `npm run check`
+on the final source. Keep unrelated baseline failures explicit. Source changes,
+local verification, commit, published version, and consumer adoption are
+separate delivery states.

package/contracts/design.dark.md

@@ -18,7 +18,7 @@ colors:
   background-200: "#000000"
   text-primary: "#ededed"
   text-secondary: "#a0a0a0"
-  text-muted: "#7d7d7d"
+  text-muted: "#8f8f8f"
   brand-preview-light-bg: "#ffffff"
   brand-preview-light-fg: "#171717"
   brand-preview-dark-bg: "#000000"

package/contracts/design.md

@@ -18,7 +18,7 @@ colors:
   background-200: "#fafafa"
   text-primary: "#171717"
   text-secondary: "#4d4d4d"
-  text-muted: "#8f8f8f"
+  text-muted: "#6b6b6b"
   brand-preview-light-bg: "#ffffff"
   brand-preview-light-fg: "#171717"
   brand-preview-dark-bg: "#000000"

package/contracts/icon-system.md

@@ -75,3 +75,4 @@ q1travel 的界面图标**目标是**一套自建的线性图标系统：几何
 - **颜色**：不为图标单独设色，依赖 `currentColor` 跟随文本。
 - **间距**：图标与文本之间保留一致间距，并与文本基线对齐。
 - **一致性**：同一控件组内不混用不同描边或尺寸。
+- **光学位移**：16px 线性图标贴文字标签时，图标框几何居中不等于看起来居中。位移统一消费 `--q1-optical-icon-shift-cjk-label`，通过独立的 `translate` 属性施加，不改 `transform`，因此不会冲掉 chevron 的旋转。取值按字体栈校准：包默认 `--q1-font-sans` 为 `0px`；拉丁首选字体决定行盒、中文回退 PingFang SC 的字体栈（web 当前字体栈）为 `-1px`，由消费方在自己的根上覆盖。纯英文标签会因此偏高约 1–2px，这是 x-height 的物理位置，不再按脚本细分。已接入：Navigation 分组图标、分组 chevron、链接项图标；ContextSwitcher 单行条目图标与动作图标。Button 前后缀默认不位移，消费方在已知全是中文的场景把 `--q1-button-affix-optical-y` 设为该 token。数值由 `check:browser` 的光学 fixture 锁定，见 `contracts/token-naming.md` 的 Optical Tokens。

package/contracts/implementation-map.md

@@ -17,6 +17,7 @@ README owns the repository inventory and generated-file boundary. This file owns
 | Component preview tile | Control density sample | Custom preview composition using component token mappings | Surface, border, action, focus, radius tokens | Button and segment visual states | Flex wrap preserves compact layout | Decorative in intro, real controls documented on component pages |
 | Color rods preview | Color scale summary | Custom preview composition using color scale aliases | `--q1-color-scale-*` aliases | None | Rods distribute across available width | Semantic labels identify the represented scale |
 | Color page reference and semantic tokens | Token reference and theme value copy | `ColorSwatch`, `SemanticColorListItem`, and `SemanticColorDemo` inside `ColorsPage` | `--q1-color-*`, semantic color tokens, and semantic action tokens | Left click copies token, context menu copies resolved value. The focus shadow token shows as an applied focus ring, not a flat color swatch | Ten-step grid and semantic rows adapt to available width | Button labels, semantic rows, live copy feedback |
+| Optical alignment | Aligned-looking media, icons, labels, and column edges | `ContextSwitcher` two-line rows, `Navigation` icons and chevron, `Table` edge columns and actions column, `Badge` label wrapper, `Button` affix | Optical tokens: `--q1-optical-icon-shift-cjk-label`, `--q1-optical-media-first-line-offset`, `--q1-surface-inset-inline`, `--q1-table-edge-padding-inline`, `--q1-button-hang-inline`, `--q1-badge-optical-shift`, `--q1-button-affix-optical-y` | Shifts use standalone `translate`; rotations and layout stay intact | Integer-pixel values only; locked by the `check:browser` optical fixture | Wrapper and class changes add no accessible names or roles |
 | Page footer navigation | Sequential documentation reading | `PageNavigation` | Surface, border, text, spacing tokens | Hover, focus, feedback buttons | Three-column footer collapses with content | Links are named and feedback controls are buttons |
 
 ## Implementation Rules

package/contracts/token-naming.md

@@ -51,6 +51,25 @@ The scale stops at 300ms on purpose. Past that, an interface reads as something
 
 An `infinite` loop's period is not on this scale. A spinner at 1.2s and a skeleton sweep at 1.6s are component rhythms, not responses to input; forcing them into the response scale either breaks them or manufactures single-use tokens.
 
+### Optical Tokens
+
+Optical tokens carry the integer-pixel compensations that make an interface look aligned rather than merely measure aligned. They were introduced in 0.15.2 from the 2026-09-17 optical alignment audit.
+
+Their values hold only for the font stack they were measured with. The package default is calibrated for `--q1-font-sans`; a consumer that overrides the body font stack re-measures and overrides the value on its own root. `check:browser` locks both the package default font stack and the current web font stack with the optical fixture (`/__browser-fixtures__/optical-alignment`): Chinese and mixed samples stay within 1px (plus half a device pixel of quantization), across light and dark themes at DPR 1 and 2.
+
+- `--q1-optical-icon-shift-cjk-label` (`0px`) — vertical shift for a 16px line icon beside a Chinese label. `--q1-font-sans` needs none. The current web stack, whose Latin primary font (Avenir Next) sets the line box while Chinese falls back to PingFang SC, needs `-1px`.
+- `--q1-media-size` (`var(--q1-space-6)`), `--q1-media-first-line-box` (`var(--q1-line-height-label-13)`), and `--q1-optical-media-first-line-offset` (`calc((first-line-box - media-size) / 2)`, `-3px`) — a two-line media row aligns its avatar to the first line's optical center, not to the geometric center of the whole block. The offset resolves once on `:root`, so a surface that changes the media size or first-line box redeclares the offset in the same rule.
+- `--q1-surface-inset-inline` (`var(--q1-space-4)`) — the single content inset that page headers, card content, and table edge columns share as one reference line.
+- `--q1-table-edge-padding-inline` (`var(--q1-surface-inset-inline)`) — outer padding of a table's first and last columns. Inner columns keep `--q1-space-2`.
+- `--q1-button-hang-inline` (`calc(var(--q1-space-3) + 1px)`) — distance from a small button's border edge to its label. Ghost buttons in a table actions column hang by this amount so the label starts on the column line.
+- `--q1-badge-optical-shift` (`0px`) and `--q1-button-affix-optical-y` (`0px`) — opt-in switches for the Badge label and Button affixes. They default to zero because Chinese and Latin labels move in opposite directions; a consumer sets them only where the label script is known.
+
+Rules:
+
+- Values are whole pixels. A compensation never uses a fractional pixel such as `0.5px`.
+- Components apply a shift through the standalone `translate` property, never through `transform`, so an existing `transform: rotate()` keeps working.
+- Where the compensation must change occupied space, use `margin-block-start` with an integer token instead of `translate`.
+
 ### Semantic Tokens
 
 Semantic tokens describe product meaning. Product surfaces should consume these before reaching for reference tokens.