@q1travel/design-system 0.15.1 → 0.15.3

package/contracts/context-contrast-migration.md

@@ -76,6 +76,22 @@ 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.
 
+## #255: stacked hierarchy without decorative lines
+
+Supersedes the two decorative rules accepted under #244; the rest of that
+section stands. The consumer reviewed the rendered 320px popup on 2026-09-17 and
+found the connector lines and the accent rail restating what the layout already
+carries.
+
+- Nesting is expressed by indentation only. A `depth: 1` context indents one
+  step (16px) from its parent's inline padding, in every presentation. The
+  connector lines are removed; `aria-describedby` still names the visible
+  parent, so the parent relationship survives for assistive technology.
+- A selected `menuitemradio` keeps `aria-checked`, the subtle full-row fill and
+  its rounded corners, and gains the trailing check already used by grouped and
+  drilldown. The inline-start accent rail is removed. Hover remains a background
+  layer; `:focus-visible` keeps its own focus shadow and is not a decoration.
+
 ## Acceptance and delivery boundary
 
 Require failing-then-passing focused contrast and component assertions, light

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.