@q1travel/design-system 0.20.0 → 0.22.0

package/.agents/skills/product-design/references/glossary.md

@@ -3,3 +3,31 @@
 用户可见文字与契约里的名词以此为准,跨页 / 表格 / 示例保持一致(`contracts/interface-guidelines.md` §Copy 要求 "consistent nouns")。
 
 **Coverage gap**:统一术语表尚未成形。消费者(如 q1travel-web)正在做「内部黑话清理」,清理产出的中性术语应回流到这里,成为 canonical 词表。在此之前,遇到术语一致性问题记入 `references/coverage-gaps.md`。
+
+## 组件文档页
+
+组件文档页（`contracts/interface-guidelines.md` §Component Documentation Pages）的共享词表。同一概念全库只用左列一个名字；右列的说法不再使用。
+
+### 小节名
+
+| 概念 | 小节名 | 不再使用 |
+|---|---|---|
+| 外观的几种分支 | 变体 | 样式、类型、风格 |
+| 大小档位 | 尺寸 | 大小、规格、小号、大号 |
+| 不可用 | 禁用 | 不可用、禁止 |
+| 校验失败或出错 | 错误 | 失败态、异常、报错态 |
+| 等待中 | 加载中 | 加载态、载入 |
+| 状态由外部持有 | 受控用法 | 受控、状态管理 |
+| 相关组件 | 另请参阅 | 相关组件、延伸阅读 |
+
+### 描述用词
+
+| 用 | 不用 | 说明 |
+|---|---|---|
+| 显示 | 呈现、承载 | 描述组件在界面上出现什么 |
+| 读屏读出的内容 | 可访问名称 | 面向读者的说法；API 表里可保留 `aria-label` 等属性名 |
+| 调用 `onChange` | 回调、输出 | 描述里不写；放到 API 表 |
+
+## 中英混排
+
+以 `contracts/interface-guidelines.md` §Copy 为准：代码标识符用行内 `code` 或 `DocToken`；通用英文译为中文；品牌、产品与组件名以及 Token 保留英文正文。中文与相邻拉丁字母、数字留半角空格，中文句子使用全角逗号、句号、冒号、分号；代码、网址、界面原文引述与源码示例除外。语义判断通过文案审阅完成。

package/contracts/design.dark.md

@@ -8,6 +8,8 @@ source-policy:
   implementation: "Translate references into q1travel tokens and canonical components before production use."
   forbidden: "Reference markup, class names, copied computed styles, and screenshot-only dimensions."
 colors:
+  gray-alpha-100: "rgba(255, 255, 255, 0.08)"
+  gray-alpha-200: "rgba(255, 255, 255, 0.12)"
   primary: "#533afd"
   primary-hover: "#4631d6"
   primary-press: "#342899"
@@ -146,8 +148,8 @@ semantic-colors:
   overlay-scrim: "rgba(2, 6, 23, 0.44)"
   selection-background: "{colors.text-primary}"
   selection-foreground: "{colors.background-100}"
-  focus-ring: "{colors.primary-900}"
-  focus: "{colors.primary-900}"
+  focus-ring: "#ffffff"
+  focus: "#ffffff"
   status-success: "{colors.green-900}"
   status-success-text: "{colors.green-900}"
   status-success-surface: "{colors.green-100}"
@@ -169,62 +171,86 @@ typography:
     fontFamily: Noto Sans SC
     fontSize: 72px
     fontWeight: 500
-    lineHeight: 72px
-    letterSpacing: -0.06em
+    lineHeight: 88px
+    letterSpacing: 0
   heading-64:
     fontFamily: Noto Sans SC
     fontSize: 64px
     fontWeight: 500
-    lineHeight: 68px
-    letterSpacing: -0.06em
+    lineHeight: 80px
+    letterSpacing: 0
   heading-56:
     fontFamily: Noto Sans SC
     fontSize: 56px
     fontWeight: 500
-    lineHeight: 60px
-    letterSpacing: -0.06em
+    lineHeight: 72px
+    letterSpacing: 0
   heading-48:
     fontFamily: Noto Sans SC
     fontSize: 48px
     fontWeight: 500
+    lineHeight: 64px
+    letterSpacing: 0
+  heading-40-strong:
+    fontFamily: Noto Sans SC
+    fontSize: 40px
+    fontWeight: 600
     lineHeight: 52px
-    letterSpacing: -0.06em
+    letterSpacing: 0
   heading-40:
     fontFamily: Noto Sans SC
     fontSize: 40px
     fontWeight: 500
+    lineHeight: 52px
+    letterSpacing: 0
+  heading-32-strong:
+    fontFamily: Noto Sans SC
+    fontSize: 32px
+    fontWeight: 600
     lineHeight: 44px
-    letterSpacing: -0.06em
+    letterSpacing: 0
   heading-32:
     fontFamily: Noto Sans SC
     fontSize: 32px
     fontWeight: 500
-    lineHeight: 38px
-    letterSpacing: -0.04em
+    lineHeight: 44px
+    letterSpacing: 0
+  heading-24-strong:
+    fontFamily: Noto Sans SC
+    fontSize: 24px
+    fontWeight: 600
+    lineHeight: 32px
+    letterSpacing: 0
   heading-24:
     fontFamily: Noto Sans SC
     fontSize: 24px
     fontWeight: 500
     lineHeight: 32px
-    letterSpacing: -0.04em
+    letterSpacing: 0
+  heading-20-strong:
+    fontFamily: Noto Sans SC
+    fontSize: 20px
+    fontWeight: 600
+    lineHeight: 28px
+    letterSpacing: 0
   heading-20:
     fontFamily: Noto Sans SC
     fontSize: 20px
     fontWeight: 500
     lineHeight: 28px
-    letterSpacing: -0.02em
+    letterSpacing: 0
   heading-16:
     fontFamily: Noto Sans SC
     fontSize: 16px
     fontWeight: 500
     lineHeight: 24px
-    letterSpacing: -0.02em
+    letterSpacing: 0
   heading-14:
     fontFamily: Noto Sans SC
     fontSize: 14px
     fontWeight: 500
     lineHeight: 20px
-    letterSpacing: -0.02em
+    letterSpacing: 0
   label-14:
     fontFamily: Noto Sans SC
     fontSize: 14px
@@ -241,13 +267,13 @@ typography:
     fontFamily: Noto Sans SC
     fontSize: 16px
     fontWeight: 400
-    lineHeight: 24px
+    lineHeight: 28px
     letterSpacing: 0
   copy-14:
     fontFamily: Noto Sans SC
     fontSize: 14px
     fontWeight: 400
-    lineHeight: 20px
+    lineHeight: 24px
     letterSpacing: 0
   code-13:
     fontFamily: Geist Mono
@@ -261,12 +287,14 @@ spacing:
   3: 12px
   4: 16px
   6: 24px
+  7: 28px
   8: 32px
   10: 40px
   16: 64px
   24: 96px
   base: 4px
 sizing:
+  touch-target-min: 44px
   control-default: 40px
 rounded:
   xs: 4px
@@ -307,9 +335,9 @@ components:
     height: 40px
   button-secondary:
     backgroundColor: "{semantic-colors.surface-panel}"
-    hoverBackgroundColor: "{semantic-colors.surface-subtle}"
+    hoverBackgroundColor: "{semantic-colors.surface-hover}"
     textColor: "{semantic-colors.text-primary}"
-    borderColor: "{semantic-colors.border-strong}"
+    borderColor: "{semantic-colors.border}"
     typography: "{typography.label-14}"
     rounded: "{rounded.sm}"
     height: 40px
@@ -317,7 +345,7 @@ components:
     backgroundColor: "{semantic-colors.surface-panel}"
     textColor: "{semantic-colors.text-primary}"
     placeholderColor: "{semantic-colors.text-muted}"
-    borderColor: "{semantic-colors.border-strong}"
+    borderColor: "{semantic-colors.border}"
     focusColor: "{semantic-colors.focus-ring}"
     typography: "{typography.label-14}"
     rounded: "{rounded.sm}"
@@ -402,14 +430,18 @@ These components ship in the package. Compose from this list before writing new
 
 `q1-design ls` prints this list from the installed package, and `q1-design doc <name>` prints one component's public API. Use those when the package is installed; use this section when it is not.
 
-**Actions.** Button, ButtonLink, IconButton, SplitButton, LoadMoreButton, ClearButton, CopyButton, Link, Toolbar.
+**Record activity.** Timeline, TimelineItem, Marker, Message, Mention, Composer, Attachment. Timeline uses chronological ol/li with tone dots or Avatar; Marker keeps system events quiet and dates centered. Message supports pending/failed and caller actions; Mention renders caller-owned inline member references using action-text and the selected surface. Composer is a textarea combobox with listbox mentions, Enter sends and Shift+Enter inserts a newline; IME composition never sends or picks. Attachment reuses Progress and named removal. Network, permissions and notifications remain caller-owned.
+
+**Actions.** Button, ButtonLink, IconButton, SplitButton, LoadMoreButton, ClearButton, CopyButton, FilterChip, Link, Toolbar.
 
 - Button carries the action. ButtonLink navigates but reads as a button, for a page-level call to action. Link reads as text, inside a sentence. Substituting one for another makes the page read wrong.
 - SplitButton is a primary action with an adjacent menu whose first entry mirrors it. Do not use it to hide unrelated actions behind a chevron.
+- FilterChip opens a consumer-owned filter picker; undefined means unset, other values mean set. Its 28px pill uses a dashed border-strong outline with CirclePlus when unset, and a solid outline with label, border-token divider, action-text value and ChevronDown when set. The optional leading CircleX clear action is a separate named native button before the picker, with its own Tab stop and shared focus ring.
 - IconButton requires an accessible name. An icon-only control without one is not deliverable.
 
-**Text fields.** FormField, Label, Input, ClearableInput, SearchInput, VerificationCodeInput, Textarea, Select, Fieldset, ErrorMessage.
+**Text fields.** FormField, Label, Input, ClearableInput, SearchInput, InputOTP, Textarea, Select, Fieldset, ErrorMessage.
 
+- InputOTP collects a fixed six-digit code in one joined group by default; `separator` explicitly enables 3+3 groups. VerificationCodeInput and VerificationCodeInputProps remain deprecated aliases for one minor version; migrate to InputOTP and InputOTPProps before their removal in the next minor version. The old `/components/verification-code-input` route redirects to `/components/input-otp`.
 - FormField owns the label, help text, and error slot. Do not assemble those three around a bare Input.
 - Select is for a short, fixed list. Anything searchable, or longer than roughly seven entries, is a Combobox.
 
@@ -419,7 +451,7 @@ These components ship in the package. Compose from this list before writing new
 - 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.
+**Dates and ranges.** Calendar, CalendarGrid, RangeInputs, RangeField, PeriodCombobox, addDays.
 
 **Overlays.** Modal, ModalInset, DestructiveActionModal, Drawer, Sheet, Menu, ContextMenu, DotsMenu, Tooltip, ContextCard, SearchDialog, CommandMenu.
 
@@ -435,7 +467,7 @@ These components ship in the package. Compose from this list before writing new
 - Gauge is one ratio as a ring. Progress is advancement along a task, and takes segment stops.
 - RelativeTimeCard reveals the absolute time behind a relative one. Prefer it to printing both.
 
-**Status and feedback.** Banner, ProjectBanner, Note, ErrorCard, ErrorMessage, EmptyState, Badge, Pill, StatusDot, ToastProvider, useToast, Feedback, Spinner, LoadingDots, Skeleton.
+**Status and feedback.** Banner, ProjectBanner, Note, ErrorCard, ErrorMessage, EmptyState, Badge, Pill, StatusDot, ToastProvider, useToast, Feedback, PageFeedback, Spinner, LoadingDots, Skeleton.
 
 - Banner announces at page scope. Note is an inline aside. ErrorMessage sits against one field. ErrorCard replaces a region that failed to load. Picking the widest one available overstates the problem.
 - Toast is for non-blocking confirmation of something that already happened. It is not where an error the reader must act on belongs.

package/contracts/design.md

@@ -8,6 +8,8 @@ source-policy:
   implementation: "Translate references into q1travel tokens and canonical components before production use."
   forbidden: "Reference markup, class names, copied computed styles, and screenshot-only dimensions."
 colors:
+  gray-alpha-100: "rgba(0, 0, 0, 0.06)"
+  gray-alpha-200: "rgba(0, 0, 0, 0.08)"
   primary: "#533afd"
   primary-hover: "#4434d4"
   primary-press: "#2e2b8c"
@@ -134,7 +136,7 @@ semantic-colors:
   text-on-inverse: "{colors.background-100}"
   surface-media: "#0a0a0a"
   text-on-media: "#ffffff"
-  border: "{colors.gray-400}"
+  border: "{colors.gray-alpha-200}"
   border-strong: "{colors.gray-500}"
   border-active: "{colors.primary-700}"
   border-subtle: "rgba(203, 213, 225, 0.82)"
@@ -146,8 +148,8 @@ semantic-colors:
   overlay-scrim: "rgba(2, 6, 23, 0.44)"
   selection-background: "{colors.text-primary}"
   selection-foreground: "{colors.background-100}"
-  focus-ring: "{colors.primary}"
-  focus: "{colors.primary-700}"
+  focus-ring: "#000000"
+  focus: "#000000"
   status-success: "{colors.green-700}"
   status-success-text: "{colors.green-900}"
   status-success-surface: "{colors.green-100}"
@@ -169,62 +171,86 @@ typography:
     fontFamily: Noto Sans SC
     fontSize: 72px
     fontWeight: 500
-    lineHeight: 72px
-    letterSpacing: -0.06em
+    lineHeight: 88px
+    letterSpacing: 0
   heading-64:
     fontFamily: Noto Sans SC
     fontSize: 64px
     fontWeight: 500
-    lineHeight: 68px
-    letterSpacing: -0.06em
+    lineHeight: 80px
+    letterSpacing: 0
   heading-56:
     fontFamily: Noto Sans SC
     fontSize: 56px
     fontWeight: 500
-    lineHeight: 60px
-    letterSpacing: -0.06em
+    lineHeight: 72px
+    letterSpacing: 0
   heading-48:
     fontFamily: Noto Sans SC
     fontSize: 48px
     fontWeight: 500
+    lineHeight: 64px
+    letterSpacing: 0
+  heading-40-strong:
+    fontFamily: Noto Sans SC
+    fontSize: 40px
+    fontWeight: 600
     lineHeight: 52px
-    letterSpacing: -0.06em
+    letterSpacing: 0
   heading-40:
     fontFamily: Noto Sans SC
     fontSize: 40px
     fontWeight: 500
+    lineHeight: 52px
+    letterSpacing: 0
+  heading-32-strong:
+    fontFamily: Noto Sans SC
+    fontSize: 32px
+    fontWeight: 600
     lineHeight: 44px
-    letterSpacing: -0.06em
+    letterSpacing: 0
   heading-32:
     fontFamily: Noto Sans SC
     fontSize: 32px
     fontWeight: 500
-    lineHeight: 38px
-    letterSpacing: -0.04em
+    lineHeight: 44px
+    letterSpacing: 0
+  heading-24-strong:
+    fontFamily: Noto Sans SC
+    fontSize: 24px
+    fontWeight: 600
+    lineHeight: 32px
+    letterSpacing: 0
   heading-24:
     fontFamily: Noto Sans SC
     fontSize: 24px
     fontWeight: 500
     lineHeight: 32px
-    letterSpacing: -0.04em
+    letterSpacing: 0
+  heading-20-strong:
+    fontFamily: Noto Sans SC
+    fontSize: 20px
+    fontWeight: 600
+    lineHeight: 28px
+    letterSpacing: 0
   heading-20:
     fontFamily: Noto Sans SC
     fontSize: 20px
     fontWeight: 500
     lineHeight: 28px
-    letterSpacing: -0.02em
+    letterSpacing: 0
   heading-16:
     fontFamily: Noto Sans SC
     fontSize: 16px
     fontWeight: 500
     lineHeight: 24px
-    letterSpacing: -0.02em
+    letterSpacing: 0
   heading-14:
     fontFamily: Noto Sans SC
     fontSize: 14px
     fontWeight: 500
     lineHeight: 20px
-    letterSpacing: -0.02em
+    letterSpacing: 0
   label-14:
     fontFamily: Noto Sans SC
     fontSize: 14px
@@ -241,13 +267,13 @@ typography:
     fontFamily: Noto Sans SC
     fontSize: 16px
     fontWeight: 400
-    lineHeight: 24px
+    lineHeight: 28px
     letterSpacing: 0
   copy-14:
     fontFamily: Noto Sans SC
     fontSize: 14px
     fontWeight: 400
-    lineHeight: 20px
+    lineHeight: 24px
     letterSpacing: 0
   code-13:
     fontFamily: Geist Mono
@@ -261,12 +287,14 @@ spacing:
   3: 12px
   4: 16px
   6: 24px
+  7: 28px
   8: 32px
   10: 40px
   16: 64px
   24: 96px
   base: 4px
 sizing:
+  touch-target-min: 44px
   control-default: 40px
 rounded:
   xs: 4px
@@ -307,9 +335,9 @@ components:
     height: 40px
   button-secondary:
     backgroundColor: "{semantic-colors.surface-panel}"
-    hoverBackgroundColor: "{semantic-colors.surface-subtle}"
+    hoverBackgroundColor: "{semantic-colors.surface-hover}"
     textColor: "{semantic-colors.text-primary}"
-    borderColor: "{semantic-colors.border-strong}"
+    borderColor: "{semantic-colors.border}"
     typography: "{typography.label-14}"
     rounded: "{rounded.sm}"
     height: 40px
@@ -317,7 +345,7 @@ components:
     backgroundColor: "{semantic-colors.surface-panel}"
     textColor: "{semantic-colors.text-primary}"
     placeholderColor: "{semantic-colors.text-muted}"
-    borderColor: "{semantic-colors.border-strong}"
+    borderColor: "{semantic-colors.border}"
     focusColor: "{semantic-colors.focus-ring}"
     typography: "{typography.label-14}"
     rounded: "{rounded.sm}"
@@ -402,14 +430,18 @@ These components ship in the package. Compose from this list before writing new
 
 `q1-design ls` prints this list from the installed package, and `q1-design doc <name>` prints one component's public API. Use those when the package is installed; use this section when it is not.
 
-**Actions.** Button, ButtonLink, IconButton, SplitButton, LoadMoreButton, ClearButton, CopyButton, Link, Toolbar.
+**Record activity.** Timeline, TimelineItem, Marker, Message, Mention, Composer, Attachment. Timeline uses chronological ol/li with tone dots or Avatar; Marker keeps system events quiet and dates centered. Message supports pending/failed and caller actions; Mention renders caller-owned inline member references using action-text and the selected surface. Composer is a textarea combobox with listbox mentions, Enter sends and Shift+Enter inserts a newline; IME composition never sends or picks. Attachment reuses Progress and named removal. Network, permissions and notifications remain caller-owned.
+
+**Actions.** Button, ButtonLink, IconButton, SplitButton, LoadMoreButton, ClearButton, CopyButton, FilterChip, Link, Toolbar.
 
 - Button carries the action. ButtonLink navigates but reads as a button, for a page-level call to action. Link reads as text, inside a sentence. Substituting one for another makes the page read wrong.
 - SplitButton is a primary action with an adjacent menu whose first entry mirrors it. Do not use it to hide unrelated actions behind a chevron.
+- FilterChip opens a consumer-owned filter picker; undefined means unset, other values mean set. Its 28px pill uses a dashed border-strong outline with CirclePlus when unset, and a solid outline with label, border-token divider, action-text value and ChevronDown when set. The optional leading CircleX clear action is a separate named native button before the picker, with its own Tab stop and shared focus ring.
 - IconButton requires an accessible name. An icon-only control without one is not deliverable.
 
-**Text fields.** FormField, Label, Input, ClearableInput, SearchInput, VerificationCodeInput, Textarea, Select, Fieldset, ErrorMessage.
+**Text fields.** FormField, Label, Input, ClearableInput, SearchInput, InputOTP, Textarea, Select, Fieldset, ErrorMessage.
 
+- InputOTP collects a fixed six-digit code in one joined group by default; `separator` explicitly enables 3+3 groups. VerificationCodeInput and VerificationCodeInputProps remain deprecated aliases for one minor version; migrate to InputOTP and InputOTPProps before their removal in the next minor version. The old `/components/verification-code-input` route redirects to `/components/input-otp`.
 - FormField owns the label, help text, and error slot. Do not assemble those three around a bare Input.
 - Select is for a short, fixed list. Anything searchable, or longer than roughly seven entries, is a Combobox.
 
@@ -419,7 +451,7 @@ These components ship in the package. Compose from this list before writing new
 - 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.
+**Dates and ranges.** Calendar, CalendarGrid, RangeInputs, RangeField, PeriodCombobox, addDays.
 
 **Overlays.** Modal, ModalInset, DestructiveActionModal, Drawer, Sheet, Menu, ContextMenu, DotsMenu, Tooltip, ContextCard, SearchDialog, CommandMenu.
 
@@ -435,7 +467,7 @@ These components ship in the package. Compose from this list before writing new
 - Gauge is one ratio as a ring. Progress is advancement along a task, and takes segment stops.
 - RelativeTimeCard reveals the absolute time behind a relative one. Prefer it to printing both.
 
-**Status and feedback.** Banner, ProjectBanner, Note, ErrorCard, ErrorMessage, EmptyState, Badge, Pill, StatusDot, ToastProvider, useToast, Feedback, Spinner, LoadingDots, Skeleton.
+**Status and feedback.** Banner, ProjectBanner, Note, ErrorCard, ErrorMessage, EmptyState, Badge, Pill, StatusDot, ToastProvider, useToast, Feedback, PageFeedback, Spinner, LoadingDots, Skeleton.
 
 - Banner announces at page scope. Note is an inline aside. ErrorMessage sits against one field. ErrorCard replaces a region that failed to load. Picking the widest one available overstates the problem.
 - Toast is for non-blocking confirmation of something that already happened. It is not where an error the reader must act on belongs.
@@ -445,7 +477,7 @@ These components ship in the package. Compose from this list before writing new
 **Structure and navigation.** Card, AuthCard, Sidebar, SidebarDrawer, Navigation, NavigationSection, NavigationItem, NavigationGroup, ContextSwitcher, Breadcrumb, CollapsibleBreadcrumb, Tabs, Collapse, CollapseGroup, Separator, Scroller, ScrollerWithButtons, FileTree.
 
 - Card is a surface you have earned, not a default wrapper. Reach for spacing and alignment first.
-- Tabs switch between peer views of the same subject. They are not a way to shorten a page.
+- Tabs switch between peer views of the same subject. They are not a way to shorten a page. Optional `value` / `onValueChange` let the consumer own selection and URL synchronization; `defaultValue` seeds uncontrolled selection. Invalid or disabled values render the first enabled item without notifying. See `implementation-map.md` for selection ownership.
 - ContextSwitcher is the two-level selection model; the consumer owns the state behind it.
 
 **Identity and media.** Avatar, AvatarGroup, Book, Browser, BrowserDots, BrowserControls, BrowserAddress, BrowserTabs, BrowserPlaceholder, Phone, Video, ThemeSwitcher, ProductLockup, Q1travelSymbol.

package/contracts/icon-system.md

@@ -75,4 +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。
+- **光学位移**：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。组件内部另有两处具名、整数像素的局部位移，只作用于本组件：`--q1-product-lockup-optical-y`（品牌符号与竖线对齐产品名，`1px`）与 `--q1-note-icon-optical-y`（Note 图标对齐第一行正文，默认 `3px`、`large` `2px`）。数值由 `check:browser` 的光学 fixture 锁定，见 `contracts/token-naming.md` 的 Optical Tokens。

package/contracts/implementation-map.md

@@ -9,6 +9,8 @@ README owns the repository inventory and generated-file boundary. This file owns
 | Reference intent | q1travel semantic | Canonical surface | Token source | State | Responsive | Accessibility |
 | --- | --- | --- | --- | --- | --- | --- |
 | Bounded documentation frame | Public design-system shell | `AppShell`, `Sidebar`, `Topbar` | `--q1-color-bg-canvas`, `--q1-color-border`, spacing tokens | Route changes reset document scroll | Frame width and sidebar collapse through layout CSS | Landmarks, keyboard search, focus-visible ring |
+| Aligned date-range field | Date-range trigger shares the FieldSize scale | `Calendar`, `RangeField` (`fieldSize`; `size` remains grid-only) | `--q1-control-height-default`, `--q1-space-6`, `--q1-space-8`, `--q1-space-2`, `--q1-touch-target-min` | Draft, apply, clear and popover keyboard behavior preserved; clear/caret centered | Default md40 matches Select/Input; coarse44 matches Select | Named sibling buttons, APG date-picker dialog and focus return |
+| Compact dashboard filters | Consumer-owned filter picker | `FilterChip` | `--q1-space-7` (28px), border-strong, text-secondary, action-text, shared focus | Unset dashed CirclePlus; set solid leading CircleX clear, label, divider, value and ChevronDown | Ellipsis bounds long values; shared TouchTarget preserves coarse 44px targets | Sibling native buttons, clear before picker in Tab order, focus returns to picker |
 | Compact search and command menu | Fast documentation navigation | `CommandMenu`, `Topbar` search trigger | Surface, border, text, focus tokens | Open, active option, escape close | Dialog width clamps on small screens | `role="dialog"`, `aria-modal`, keyboard navigation |
 | Foundation page rhythm | Scannable reference pages | `PageHeader`, `SpecSection`, `SpecTable` | Heading, copy, border, spacing tokens | None beyond links and focus | Tables scroll horizontally when needed | Semantic headings and tables |
 | Introduction tile grid | Entry points into public groups | `IntroTileGrid`, `IntroTile` | Surface, border, text, spacing tokens | Hover, focus | Two columns on desktop, one column on small screens | Tile is a single link with hidden decorative visual |
@@ -26,14 +28,70 @@ README owns the repository inventory and generated-file boundary. This file owns
 - New public tokens use `--q1-*`; existing product `--ds-*` names are legacy migration inputs, not new contract names.
 - Canonical components own repeated structure. Page-local custom structures are allowed only for visual specimens with a narrow purpose.
 - Token references are the design source for production code. Current theme resolved values are clipboard output only.
-- The same public navigation groups remain in the product surface: `基础`, `品牌`, and `组件`.
+- The same public navigation groups remain in the product surface: `基础`, `品牌`, `组件`, and `模式`; `模式` owns compositions across components, starting with `/patterns/admin`.
 - If a capability is missing from a shared component, add the capability to that component before adding another page-local pattern.
 
 ## Documentation Section Ownership
 
 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, 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.
+- **设计 Token** — every Tier B native-semantic control page (Button, Input, Textarea, Select, Checkbox, Radio, Toggle, FilterChip) 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.
+
+## Embedded documentation examples
+
+`DemoBlock` owns one preview and its `ShowCode` footer. `SpecSection` pairs adjacent native
+`.specimen` / `ShowCode` children, including multiple pairs; other previews use explicit
+`DemoBlock` boundaries. Explanation tables and standalone code retain their own structure.
+`ShowCode` opts into `Collapse headingLevel={null}` and `CodeBlock variant="flush"`.
+Collapse keeps its h3 default, keyboard disclosure semantics, focus restoration, and inert
+collapsed panel. A null heading level uses a plain wrapper for an ancillary disclosure;
+it does not enter the document heading outline. CodeBlock keeps its standalone default
+header and outer frame; flush removes that frame and floats copy only when there is no
+filename or language switch. No existing consumer needs an API migration.
+
+Light documentation canvas uses background-200, previews use background-100, and the
+code footer uses bg-subtle. The public light border now uses gray-alpha-200 (black 8%);
+dark borders keep their established value. Consumers with border screenshots should
+refresh them; token names and existing overrides remain valid. Gray-alpha-100/200
+provide theme-relative list-state overlays. Strong heading-40/32/24/20 token roles are
+opt-in 600 weights; existing heading roles keep 500. Space-7 adds the 28px spacing step.
+
+## Component visual subtraction
+
+Destructive Action Modal keeps its typed confirmation gate, error recovery, busy lock,
+and Escape/Cancel dismissal. Optional irreversible copy lives inside the scrollable
+body on status-danger-surface/text tokens; disabled confirmation uses bg-subtle and
+text-muted. There is no duplicate header close control.
+
+Command Menu cycles Tab between its search input and sole Esc keycap close button;
+commands use text without leading arrows and space-8 + space-1 row height. Multi Select
+options use background-only focus feedback; its bulk text action is compact and neutral,
+with no divider. Coarse-pointer targets retain the existing 44px minimum; the compact
+Command Menu close button uses the shared TouchTarget hit region.
+
+Context Switcher identifies the current context with a neutral check and regular-weight
+labels, without selected fill or a stronger selected press layer. File Tree starts with
+no selection and uses only subtle hover fill, retaining tree semantics and visible
+keyboard focus. Folder icons are neutral. Secondary text Button hover changes its
+background while keeping its border static. Public props and token values are unchanged.
+
+## Tabs selection ownership
+
+Owner approved 2026-10-06: `Tabs` accepts optional `value?: string`,
+`defaultValue?: string`, and `onValueChange?: (id: string) => void`. Existing
+consumers need no migration: without these props, selection starts at the first
+enabled item and preserves automatic activation, roving tabindex, and availability
+fallback. `defaultValue` seeds uncontrolled selection once. With `value` defined,
+render derives selection from that value; a missing or disabled ID renders the first
+enabled item without emitting a callback. All-disabled lists select nothing.
+Click, ArrowLeft/ArrowRight, Home, and End notify activation; controlled selection
+changes only when the parent updates `value`. Keyboard navigation follows the
+focused enabled tab while the parent update is pending, and a later value update
+does not pull focus from the activated button. Consumers own URL synchronization.
+
+## Record activity (owner approved 2026-10-06)
+
+Timeline / TimelineItem (ol/li, 8px token dot or Avatar), Marker (quiet actor/time, date separator), Message (default/pending/failed, caller actions) / Mention (inline action-text on selected surface), Composer (Tier A textarea combobox/listbox, IME guard, Enter send / Shift+Enter newline), Attachment (Progress, retry/remove) are public package components. `/patterns/record-activity` composes order facts, Switch, chronological activity and a pinned Composer. Existing tokens only; data, permissions, network and notifications remain caller-owned.

package/contracts/interface-guidelines.md

@@ -24,6 +24,9 @@ Adding a clause therefore means answering two questions before the wording: who
 - [both] MUST use native links for navigation and native buttons for actions.
 - [both] MUST keep visual and hit targets aligned; controls smaller than 24px need a larger interactive area.
 - [both] MUST keep mobile control targets at least 44px where touch is expected.
+- [both] MUST use `--q1-touch-target-min` (44px) for the shared centered invisible child-span hit region of Button (all sizes, including compact consumer overrides and icon-only), CopyButton, Menu/DotsMenu triggers, and Description info/hint buttons only under `(pointer: coarse), (any-pointer: coarse)`. Preserve every existing coarse-pointer visual-size rule. Only axes still below the minimum receive extra hit area; existing 44px targets do not expand outside their visual frame. The region covers the complete border box: canonical Button/CopyButton/Menu/DotsMenu borders are 1px, while Description borders are none. Consumers overriding a control border width must also set its private `--touch-target-border-width` to the actual per-side width (including zero for `border: none`); asymmetric borders need their own hit-region sizing. Focus rings stay on the visual control; child hit-region events activate that native control without replacing its pseudo-elements or overflow rules.
+- [both] MUST leave enough space for expanded targets: dense neighbors must not overlap each other's visual frames. Consumers must reserve the expansion on each side and avoid clipping ancestors; if this is impossible, regroup controls or use larger visual controls. The shared region cannot infer neighbor gaps or escape control/ancestor clipping; clipped compact controls must use a visual size of at least 44px.
+- [both] SHOULD deliberately depart from Geist's measured 24–32px controls without coarse-pointer enlargement: Apple HIG's 44pt guidance and WCAG 2.5.5 motivate q1travel's 44×44 CSS-pixel mobile usability target; pt and CSS pixels are different units.
 - [both] NEVER disable browser zoom.
 - [both] MUST avoid dead zones: if a region looks clickable, the clickable element must cover it.
 - [both] MUST show a loading indicator on in-flight buttons while keeping the original label.
@@ -183,6 +186,12 @@ Theming owns tokens and `color-scheme`; the interaction-contrast rule lives in D
 
 - [both] MUST be public, neutral, and specific.
 - [both] MUST use consistent nouns across pages, navigation, tables, and examples.
+- [both] SHOULD render code identifiers (classes, CSS variables, tokens, props, values, filenames, commands, and code values) with the existing inline `code` or `DocToken` treatment.
+- [both] SHOULD translate generic English terms into Chinese and keep brand, product, and component names, and the term "Token", in plain text.
+- [both] MUST separate Chinese characters from adjacent Latin letters or digits with a half-width space in authored prose; code contents, URLs, literal UI quotations, and code samples are excluded.
+- [both] MUST use full-width `，。：；` immediately after Chinese characters in authored Chinese sentences; code contents, URLs, literal UI quotations, and code samples are excluded.
+- [both] SHOULD use full-width `，。：；` throughout Chinese sentences, including after Latin words or inline code; identifying sentence language across mixed JSX nodes remains an editorial review item.
+- [both] SHOULD follow common Chinese technical-writing practice for mixed-language wording; Microsoft's Chinese localization guidance is a reference example, not a proprietary q1travel rule. Semantic choices and text whose rendered role cannot be reliably inferred remain editorial review items rather than machine-enforced requirements.
 - [both] SHOULD prefer short action-oriented labels.
 - [both] MUST use active voice.
 - [both] MUST use unambiguous action labels (「保存 API Key」, not 「继续」).
@@ -190,6 +199,35 @@ Theming owns tokens and `color-scheme`; the interaction-contrast rule lives in D
 - [both] SHOULD default to positive, problem-solving language, including errors.
 - [both] SHOULD use numerals for counts and keep number/unit formatting consistent.
 - [product] MUST keep currency decimal places consistent within a context (0 or 2, never mixed).
+- [both] MUST address the reader as 「您」, never 「你」.
+- [both] MUST NOT end a button or link label with punctuation (「删除项目」, not 「删除项目？」).
+- [both] MUST keep a Toast title to one short line of at most 15 Chinese characters, excluding interpolated values; details belong in the description or in a Banner.
+- [both] SHOULD write button and link labels as a verb plus a noun (「保存草稿」「添加成员」) and name the action or destination; common single actions (「完成」「关闭」「取消」「添加」「删除」) may stand alone.
+- [both] SHOULD compose an empty state from a title, an explanatory description, and an action. Use 「没有…」 for a no-data title (「没有成员」), without 「还」 or trailing punctuation; a first-use title may guide the reader with 「添加您的第一个…」 (「添加您的第一个产品」), also without trailing punctuation. Write the description as one sentence ending in 「。」 that explains when content will appear (「成员加入后将显示在此处。」), and name the action explicitly (「添加成员」, not 「开始使用」).
+- [both] SHOULD offer 「清除筛选」 instead of a create action when filters hide existing records, and show a load error with a retry instead of an empty state when data failed to load.
+- [both] SHOULD use a compact, centered empty state for an empty section, with a regular-weight title, secondary description, and a dashed token border; omit actions when no immediate action is available.
+- [both] SHOULD resolve data states in the order loading → error → empty → content.
+- [both] SHOULD give every flow a way forward and a way back (「取消」「返回」), and confirm costly or hard-to-reverse actions before running them.
+
+These copy clauses follow the actual Stripe Chinese Dashboard for reader address and empty-state copy: address the reader as 「您」, omit trailing punctuation from empty-state titles, and explain when content will appear in the description.
+
+### Component Naming
+
+- [repo] SHOULD use the Geist component name when Geist has the component; otherwise use the industry name, preferring shadcn/ui, then Radix. Invent a name only when neither has one. Name what the component is, not how it is built.
+- [repo] MUST switch public names directly to the new export without deprecated aliases or old documentation route redirects; record the removal as a breaking change in CHANGELOG.
+
+### Component Documentation Pages
+
+Component pages follow one skeleton so a reader who has used one page can find the same thing on every other. The shape follows the Stripe Apps component reference: one sentence says what the component is for, the fixed sections sit in a fixed order, and only the feature sections in the middle vary by component. Shared terms live in `.agents/skills/product-design/references/glossary.md`.
+
+- [repo] MUST open each component page with one sentence that says what a reader uses the component for. It names no props, no implementation, and no 「输入…输出…」 pairing.
+- [repo] MUST keep the fixed sections in this order: examples first, then feature sections, then 「API」, then 「使用原则」, then 「可访问性」 where the page has one, then 「另请参阅」 as the last section.
+- [repo] MUST end each component page with 「另请参阅」, linking the components a reader is likely to confuse with this one or use beside it.
+- [repo] MUST name a section that covers a shared concept with the glossary's section name (for example 「尺寸」, never 「小号」 or 「大小」).
+- [repo] SHOULD name a component-specific section after the feature it covers, usually the prop it documents (「图标」, 「品牌名」), not after a concept or as a sentence; the explanation goes in the section description.
+- [repo] SHOULD follow the opening sentence with one sentence that separates the component from its nearest neighbour (「和 Button 不同，Badge 只显示、不能点。」).
+
+`scripts/check-shell.mjs` enforces the MUST clauses above on every component page.
 
 ## Agent Integration
 

package/contracts/overlay-shadow-migration.md

@@ -4,6 +4,18 @@ Status: accepted
 
 Decision date: 2026-08-26
 
+## 2026-10-05 所有者批准的直接替换
+
+本批跳过过渡流程，直接在 Token 层替换，不保留旧阴影或兼容档。以下取值取代后文的历史取值及方向性面板例外；后文保留为历史证据，不代表当前下游版本。
+
+- 浅色 popover：1px gray-alpha-200 发丝边 + `0 4px 8px -4px` 黑 4% + `0 16px 24px -8px` 黑 6%。
+- 暗色 popover：1px 白 alpha 发丝边 + 同几何黑 12% / 18%。
+- 浅色 modal：同发丝边 + `0 8px 24px -12px` 黑 12% + `0 32px 72px -12px` 黑 6%。
+- 暗色 modal：同发丝边 + 同几何黑 24% / 18%。
+- Menu、Combobox、Calendar、Multi Select、Context Menu / Card / Switcher、Relative Time Card 删除额外实体边框，由 popover token 统一提供发丝边；Toast 使用同一 token。
+- Drawer / Sheet 使用 modal token，删除组件自持重阴影及重复边框。
+- 名称与消费方式保留；只改本仓，不声明下游已接入。升级后仍需明暗视觉复核；回滚单位仍为完整 token 声明。
+
 关联：q1travel-design-system#140（B2-1）、q1travel-design-system#138（界面准则 · 设计章节）
 
 这份合同冻结 `--q1-shadow-popover` 与 `--q1-shadow-modal` 由单层改为分层的取值、下游影响面与回滚单位。它**不修改 q1travel-web**，不创建下游迁移票，也不声称消费方已完成接入。