@q1travel/design-system 0.14.1 → 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"

package/contracts/overlay-foundation.md

@@ -156,7 +156,7 @@ type OverlayRecord = {
 | --- | --- | --- | --- |
 | Modal | 公开 props、尺寸/布局、关闭策略、文档示例 | portal、stack、focus、blocking lock、统一 Escape/outside ownership | Foundation |
 | DestructiveActionModal | destructive/loading/confirm 语义与提交状态 | 同上；loading 时由 policy 禁止关闭 | Foundation |
-| Sheet | 现有 side、persistent-context 语义；blocking=true、outside pointer=false | 同上；不能让 CSS 注释与 ARIA 语义继续冲突 | Foundation |
+| Sheet | side、persistent-context 语义；blocking=true、outside pointer=false；dismissable 默认 true，false 禁用 Escape 并隐藏内置关闭按钮 | 同上；不能让 CSS 注释与 ARIA 语义继续冲突 | Foundation |
 | Drawer | mobile bottom、gesture、outside/Escape 语义 | 同上；gesture 关闭仍必须服从 top-most 与 loading policy | Foundation |
 
 组件接入不得一次性重写四个组件，也不得在未有单独 contract 的情况下改变公开 DOM、默认 dismissal 或 accessibility tier。
@@ -259,3 +259,7 @@ D7  q1travel-web adoption/migration
 - 宿主每次 open 对应一次登记/释放；改变 blocking 策略应重新登记。idempotent disposer 支持 StrictMode 清理。不同 document 完全隔离。
 
 回归入口：`node --test scripts/check-overlay-coordination.test.mjs`；真实跨 root 的 Escape、焦点、快捷键与滚动锁由 Web consumer 浏览器测试验证。
+
+### Sheet sizing and dismissal
+
+Sheet accepts optional `size: 'sm' | 'md' | 'lg' | 'xl'` for left/right panel widths of 360/480/640/860px, capped by the existing viewport gutters. Omitting size retains 512px. Top/bottom geometry, `title: string`, children, footer, and side remain unchanged. Dismissal policy updates take effect in the same commit as visible close controls, before consumer layout effects. `dismissable=false` retains its blocking coordinator entry, focus trap, inert background, and scroll lock; Escape cannot dismiss it or the underlying host overlay. Outside pointer never closes Sheet. Consumers retain ownership of controlled open and footer actions and restore dismissal when the temporary busy state ends.

package/dist-pkg/design-system.d.ts

@@ -1392,17 +1392,21 @@ export declare function Separator({ orientation, decorative, className, }: {
 
 export declare type SeparatorOrientation = 'horizontal' | 'vertical';
 
-export declare function Sheet({ open, onClose, title, side, children, footer }: {
+export declare function Sheet({ open, onClose, title, side, size, dismissable, children, footer }: {
     open: boolean;
     onClose: () => void;
     title: string;
     side?: SheetSide;
+    size?: SheetSize;
+    dismissable?: boolean;
     children: ReactNode;
     footer?: ReactNode;
 }): ReactNode;
 
 export declare type SheetSide = 'top' | 'right' | 'bottom' | 'left';
 
+export declare type SheetSize = 'sm' | 'md' | 'lg' | 'xl';
+
 export declare function ShowMore({ items, initial, noBorder, initialExpanded, }: {
     items: string[];
     initial?: number;