@q1travel/design-system 0.15.0 → 0.15.1

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"