@q1travel/design-system 0.23.0 → 0.24.0

package/contracts/design.dark.md

@@ -442,13 +442,16 @@ These components ship in the package. Compose from this list before writing new
 
 - 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.
+- FilterChip opens a consumer-owned filter picker; undefined means unset, other values mean set. Its default sm 32px 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.
+- FilterOptionPanel is searchable single-select content inside Popover, usually anchored by FilterChip. It owns initial search focus, named combobox/listbox, active-descendant arrow navigation with disabled skipping, loading/error/retry/empty/no-match states, and label/keywords includes filtering. Callers own selection, closing, business ranking and async queries through controlled query/onQueryChange and an injected filter; Escape dismissal and trigger focus return stay with Popover. It does not provide multiselect or an application footer.
 - IconButton requires an accessible name. An icon-only control without one is not deliverable.
 
 **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.
+- `labelHidden` defaults to false. For a single inline field already named by context, it visually hides the real associated label through `q1-sr-only` without reserving a label row or gap; description, visible error, and `aria-describedby` remain unchanged. A label is still required; bare mode rejects `labelHidden`. Input’s existing string `hideLabel` still names the password hide action.
+- FormField positions its visually hidden label and empty live status within its own containing block so an overflowing inline row cannot enlarge the page scroll width.
 - Select is for a short, fixed list. Anything searchable, or longer than roughly seven entries, is a Combobox.
 
 **Option fields.** ControlOption, Checkbox, Radio, Choicebox, Combobox, MultiSelect, Switch, Toggle, ToggleGroup, Slider, RangeSlider.
@@ -463,7 +466,7 @@ Static WCAG stroke contrast against canvas/panel (2026-10-07): light neutral 5.3
 
 
 - Toggle represents one on/off setting and reports a requested change immediately. Square Checkbox stages a form change that a submit applies; circle Checkbox marks task completion through the consumer’s change handler. Choosing the wrong one misstates when the change takes effect.
-- Switch selects among mutually exclusive views or modes.
+- Switch selects among mutually exclusive views or modes; its outer sm / md / lg heights are 32 / 40 / 48px on fine pointers, defaulting to md.
 - ToggleGroup uses pressed buttons for single or multiple choices; arrow keys move focus without selecting. Icon-only items require an accessible name. See `implementation-map.md` for selection ownership.
 - RangeSlider is two thumbs over one interval, paired with numeric inputs; Slider is a single value.
 
@@ -619,3 +622,7 @@ Before delivery, confirm each of these. They are observable; none of them is a m
 In this repository, `npm run check` is the full gate; a partial run is not a pass. In consuming repositories, run their design and token gates before reporting completion.
 
 公开 Foundation 集成：`getOverlayCoordinator` 协调 package 与宿主 overlay 的栈序、inert 与滚动锁；契约见 [Overlay Foundation](./overlay-foundation.md#11-o3-公开-host-协调扩展2026-09-08)。
+
+### 单行控件尺寸
+
+显式 sm / md / lg 的单行控件与 Button 对齐为 32 / 40 / 48px；使用现有 `--q1-space-8`、`--q1-control-height-default` 与 `--q1-space-2`。SearchInput 与 Menu 文字触发器默认 md，FilterChip 默认 sm32，Switch 外框 sm / md / lg 同高 32 / 40 / 48px，默认 md。Calendar 的 size 只控制网格，触发器使用 fieldSize。空或缺省 label 不创建可见标签行，消费方须提供可访问名称。粗指针最小 44px 命中规则保持现有契约。

package/contracts/design.md

@@ -436,19 +436,22 @@ These components ship in the package. Compose from this list before writing new
 
 **Chat messages.** Bubble (incoming/outgoing, optional avatar/name/time, controlled pending/error and retry/actions slots) and MessageScroller (stable keyed items, near-bottom following, streaming growth, prepend anchor preservation, conversationKey reset, named native jump button and separate polite new-message announcements) are public components. They reuse existing tokens and Button; Message and Scroller APIs remain unchanged. Tier B uses native keyboard scrolling and buttons; callers own constrained height, message data, streaming, Markdown, tool cards, history cursors, permissions and network recovery.
 
-**Record activity.** Timeline, TimelineItem, TimelineCollapsedGroup, Marker, Message, Mention, Composer, Attachment. Timeline uses chronological ol/li with tone dots or Avatar; TimelineCollapsedGroup uses a native disclosure for consecutive system events; 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.
+**Record activity.** Timeline, TimelineItem, TimelineCollapsedGroup, Marker, Message, Mention, Composer, Attachment. Timeline uses chronological ol/li with tone dots or Avatar; TimelineCollapsedGroup uses a native disclosure for consecutive system events; 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. Composer also accepts `onMentionQuery(query, {signal})` with 200ms debounce, abort/stale-result rejection, loading/empty/error states and keyboard retry; async lookup takes precedence over static members. Optional `placeholder` and `hint` preserve the input label; member instructions appear only with mention support. Han text may directly precede @, while Unicode word/email interiors do not trigger. Selection inserts text and sets the caret synchronously. 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.
+- FilterChip opens a consumer-owned filter picker; undefined means unset, other values mean set. Its default sm 32px 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.
+- FilterOptionPanel is searchable single-select content inside Popover, usually anchored by FilterChip. It owns initial search focus, named combobox/listbox, active-descendant arrow navigation with disabled skipping, loading/error/retry/empty/no-match states, and label/keywords includes filtering. Callers own selection, closing, business ranking and async queries through controlled query/onQueryChange and an injected filter; Escape dismissal and trigger focus return stay with Popover. It does not provide multiselect or an application footer.
 - IconButton requires an accessible name. An icon-only control without one is not deliverable.
 
 **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.
+- `labelHidden` defaults to false. For a single inline field already named by context, it visually hides the real associated label through `q1-sr-only` without reserving a label row or gap; description, visible error, and `aria-describedby` remain unchanged. A label is still required; bare mode rejects `labelHidden`. Input’s existing string `hideLabel` still names the password hide action.
+- FormField positions its visually hidden label and empty live status within its own containing block so an overflowing inline row cannot enlarge the page scroll width.
 - Select is for a short, fixed list. Anything searchable, or longer than roughly seven entries, is a Combobox.
 
 **Option fields.** ControlOption, Checkbox, Radio, Choicebox, Combobox, MultiSelect, Switch, Toggle, ToggleGroup, Slider, RangeSlider.
@@ -463,7 +466,7 @@ Static WCAG stroke contrast against canvas/panel (2026-10-07): light neutral 5.3
 
 
 - Toggle represents one on/off setting and reports a requested change immediately. Square Checkbox stages a form change that a submit applies; circle Checkbox marks task completion through the consumer’s change handler. Choosing the wrong one misstates when the change takes effect.
-- Switch selects among mutually exclusive views or modes.
+- Switch selects among mutually exclusive views or modes; its outer sm / md / lg heights are 32 / 40 / 48px on fine pointers, defaulting to md.
 - ToggleGroup uses pressed buttons for single or multiple choices; arrow keys move focus without selecting. Icon-only items require an accessible name. See `implementation-map.md` for selection ownership.
 - RangeSlider is two thumbs over one interval, paired with numeric inputs; Slider is a single value.
 
@@ -475,7 +478,7 @@ Static WCAG stroke contrast against canvas/panel (2026-10-07): light neutral 5.3
 - Popover is a named anchored dialog for interactive content; it supports controlled/default open, four-side collision positioning plus controlled anchorRef placement, menu/listbox role focus, width matching, Escape focus return and outside pointer-down dismissal. Keyboard opening moves focus into content; pointer opening retains trigger focus and Tab enters the panel. It is nonmodal by default; opt-in modal locks the background and traps focus. ensurePopoverRoot exposes the same shared Foundation host for consumer-owned sibling portals; dismissExcludeRefs and nested panels preserve parent dismissal boundaries.
 - Modal blocks and demands an answer. Use it for confirmation, not for a long form; a long form belongs in a Drawer or its own route.
 - DestructiveActionModal is the required shape for irreversible actions. Do not rebuild that confirmation from a plain Modal.
-- Sheet slides in from an edge with a focus trap; opt-in `mobileFullscreen` fills narrow viewports with safe-area padding and no outer inset or radius, while default floating spacing remains unchanged; Drawer is the wider panel form. Menu is anchored and flips on collision; ContextMenu and DotsMenu share its keyboard engine.
+- Sheet slides in from an edge with a focus trap; opt-in `mobileFullscreen` fills narrow viewports with safe-area padding and no outer inset or radius, while default floating spacing remains unchanged; Drawer is the wider panel form. Menu is anchored and flips on collision; ContextMenu and DotsMenu share its keyboard engine. DotsMenu accepts contextual `label` (default 更多操作) for trigger and menu, plus `{type:'separator'}` entries using the shared Menu separator; roving focus and typeahead skip separators and disabled items.
 - Tooltip carries a short label for a control. Anything a reader must read to decide belongs in the page or in a ContextCard.
 
 **Data and evidence.** Table, Pagination, DocsPagination, ShowMore, Chart, Gauge, Progress, JsonView, Entity, Description, RelativeTimeCard.
@@ -619,3 +622,7 @@ Before delivery, confirm each of these. They are observable; none of them is a m
 In this repository, `npm run check` is the full gate; a partial run is not a pass. In consuming repositories, run their design and token gates before reporting completion.
 
 公开 Foundation 集成：`getOverlayCoordinator` 协调 package 与宿主 overlay 的栈序、inert 与滚动锁；契约见 [Overlay Foundation](./overlay-foundation.md#11-o3-公开-host-协调扩展2026-09-08)。
+
+### 单行控件尺寸
+
+显式 sm / md / lg 的单行控件与 Button 对齐为 32 / 40 / 48px；使用现有 `--q1-space-8`、`--q1-control-height-default` 与 `--q1-space-2`。SearchInput 与 Menu 文字触发器默认 md，FilterChip 默认 sm32，Switch 外框 sm / md / lg 同高 32 / 40 / 48px，默认 md。Calendar 的 size 只控制网格，触发器使用 fieldSize。空或缺省 label 不创建可见标签行，消费方须提供可访问名称。粗指针最小 44px 命中规则保持现有契约。

package/contracts/implementation-map.md

@@ -15,7 +15,8 @@ README owns the repository inventory and generated-file boundary. This file owns
 | Mobile full-viewport details | Opt-in Sheet mobileFullscreen | `Sheet` | Existing spacing/radius/surface tokens and safe-area env | Default floating inset and overlay lifecycle preserved | Narrow viewport opt-in removes inset/radius and fills viewport | Existing focus trap, Escape and return focus |
 | Hoverable supplemental information | Read-only member or role preview | `HoverCard`, shared anchored overlay foundation | Panel background, popover shadow, radius, spacing and motion tokens | Fine-pointer hover or keyboard focus; configurable 0ms open / 90ms close; card entry cancels close; Escape dismissal; trigger click preserved | Shared collision positioning and portal; coarse/touch hover ignored | Named native trigger, aria-describedby tooltip, no focus transfer or trap, reduced motion |
 | Anchored interactive content | Consumer-owned inline dialog | `Popover`, `ensurePopoverRoot`, `FilterChip`, shared overlay foundation | Panel background, popover shadow, radius, spacing and motion tokens | Controlled/default open or external anchorRef (FilterChip ref forwards to picker); menu/listbox role focus; nested/excluded targets, focusout and anchor visibility dismissal; retained exit animation | Four-side collision plus auto/fixed placement; preferred-height flip, viewport clamp, matchWidth and ancestor scroll; fixed shared portal | Named dialog, expanded/controls wiring, focus return; opt-in modal trap |
-| 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 dashboard filters | Consumer-owned filter picker | `FilterChip` | `--q1-space-8` (default sm32), 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 |
+| Searchable filter choices | Consumer-owned single-select content | `FilterOptionPanel`, `Popover`, `FilterChip` | Existing control, surface, text, radius, spacing and focus tokens | Label/keywords includes or injected filter; controlled query; loading/error/retry/empty/no-match; select callback | Viewport-bound width and scroll list; coarse option height | Named combobox/listbox, initial search focus, aria-activedescendant, disabled skipping; Popover Escape returns to anchor |
 | 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 |
@@ -75,7 +76,7 @@ Command Menu cycles Tab between its search input and sole Esc keycap close butto
 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.
+Command Menu close button uses the shared TouchTarget hit region. DotsMenu accepts contextual `label` (default 更多操作) for trigger and menu, plus `{type:'separator'}` entries using the shared Menu separator; roving focus and typeahead skip separators and disabled items.
 
 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
@@ -99,7 +100,7 @@ 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. TimelineCollapsedGroup uses a native disclosure button with aria-expanded and Enter/Space; callers group runs of consecutive system events (docs example uses three or more). Marker unread uses centered action text; caller places and scrolls to the boundary. Message acknowledgements and its caller-owned actions slot display receipt state. Composer commands share the mention combobox/listbox keyboard model and IME guard; known slash commands invoke onCommand instead of onSubmit. Attachment paste/drop passes File[] to onAttach; legacy clicks remain argument-free. Callers own the file picker and object URLs and revoke previews on removal or unmount. Existing tokens only; data, permissions, network and notifications remain caller-owned.
+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. TimelineCollapsedGroup uses a native disclosure button with aria-expanded and Enter/Space; callers group runs of consecutive system events (docs example uses three or more). Marker unread uses centered action text; caller places and scrolls to the boundary. Message acknowledgements and its caller-owned actions slot display receipt state. Composer also accepts `onMentionQuery(query, {signal})` with 200ms debounce, abort/stale-result rejection, loading/empty/error states and keyboard retry; async lookup takes precedence over static members. Optional `placeholder` and `hint` preserve the input label; member instructions appear only with mention support. Han text may directly precede @, while Unicode word/email interiors do not trigger. Selection inserts text and sets the caret synchronously. Composer commands share the mention combobox/listbox keyboard model and IME guard; known slash commands invoke onCommand instead of onSubmit. Attachment paste/drop passes File[] to onAttach; legacy clicks remain argument-free. Callers own the file picker and object URLs and revoke previews on removal or unmount. Existing tokens only; data, permissions, network and notifications remain caller-owned.
 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.
 
 ## ToggleGroup selection ownership
@@ -126,3 +127,11 @@ The consumer mapping was checked against q1travel-web origin/main: `src/componen
 | conversation switching / new conversation | conversationKey resets follow state, visible anchor and announcement |
 | scroll-to-latest and streaming narration | named jumpLabel button, labelled region, separate polite announcement; caller can pass completed-turn text or empty announcement to silence |
 Keyboard: native viewport Arrow/PageUp/PageDown/Home/End; Tab reaches the viewport and buttons; Enter/Space activates retry or jump. Jump moves focus to the viewport before its button disappears. No custom composite widget keyboard model is introduced.
+
+## Hidden field labels
+
+Owner approved 2026-10-08: additive `labelHidden?: boolean` (default false) keeps a real associated label through `q1-sr-only` while removing its visual row and gap. Input, Textarea, Select, InputOTP and Checkbox/Radio (including circular Checkbox) expose the shell option; bare mode rejects it. SearchInput and Combobox compositions use `FormField labelHidden`, preserving their existing APIs. Calendar/RangeField does not consume FieldShellProps and retains its existing date-trigger behavior. Errors and descriptions remain visible and connected through `aria-describedby`. Input's existing string `hideLabel` remains the password hide-action copy.
+
+`FormField` establishes a relative containing block for hidden labels and empty status regions. Package consumer fixtures enforce label ownership, SSR contracts cover names/messages, and `scripts/lib/check-label-hidden-browser.mjs` checks native labels, visible errors, inline Button alignment and a deterministic 390px scrollable max-content row without page overflow.
+## Control density scale
+Owner approved 2026-10-08: explicitly sized single-line Button, ButtonLink, Input, SearchInput, Select, RangeField trigger, Menu text trigger and FilterChip share sm32 / md40 / lg48 on fine pointers. SearchInput defaults to md and retains native numeric size compatibility; FilterChip defaults to sm32. Menu text triggers default to md40 after the rendered fine-pointer audit confirmed the prior omitted-size trigger measured 38–39px; icon triggers retain their prior behavior. Calendar size remains grid-only; fieldSize controls its trigger. Switch outer sm / md / lg heights align to 32 / 40 / 48px, defaulting to md; coarse-pointer 44px rules remain unchanged. FormField and Select omit empty or absent visible labels; callers supply aria-label, aria-labelledby or a native external label. Select reuses the development-only bare-field accessible-name warning.

package/contracts/interface-guidelines.md

@@ -24,7 +24,7 @@ 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, Description info/hint buttons, and the independent FilterChip picker/clear 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. FilterChip keeps its 28px visual height and existing gaps/margins; its picker and clear hit regions must not overlap. Menu item rows use a real `min-height: var(--q1-touch-target-min)` under the same coarse-pointer query so neighboring rows remain independent. 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 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, Description info/hint buttons, and the independent FilterChip picker/clear 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. FilterChip keeps its default sm32 visual height and existing gaps/margins; its picker and clear hit regions must not overlap. Menu item rows use a real `min-height: var(--q1-touch-target-min)` under the same coarse-pointer query so neighboring rows remain independent. 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.
@@ -209,7 +209,7 @@ Theming owns tokens and `color-scheme`; the interaction-contrast rule lives in D
 - [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.
+These copy clauses keep reader address and empty states consistent with a formal business console: address the reader as 「您」, omit trailing punctuation from empty-state titles, and explain when content will appear in the description.
 
 ### Component Naming
 
@@ -218,7 +218,7 @@ These copy clauses follow the actual Stripe Chinese Dashboard for reader address
 
 ### 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`.
+Component pages follow one skeleton so a reader who has used one page can find the same thing on every other. The shape keeps every page predictable: 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.

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

@@ -426,7 +426,7 @@ declare type CheckboxOnlyProps = {
 };
 
 /** Checkbox 的完整 props。消费方包一层时用它标注，无需知道内部由哪几块组合而成。 */
-export declare type CheckboxProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & CheckboxOnlyProps & {
+export declare type CheckboxProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & FieldLabelVisibilityProps & CheckboxOnlyProps & {
     /** 圆形仅用于任务与清单完成；表单多选保留默认方形。 */
     shape?: 'square' | 'circle';
     /** 仅圆形生效；业务方自行映射优先级。 */
@@ -628,7 +628,7 @@ export declare type CommandMenuSection = {
     items: CommandMenuItem[];
 };
 
-export declare function Composer({ onSubmit, onAttach, attachments, mentions, commands, onCommand, disabled, }: ComposerProps): JSX.Element;
+export declare function Composer({ onSubmit, onAttach, attachments, mentions, onMentionQuery, placeholder, hint, commands, onCommand, disabled, }: ComposerProps): JSX.Element;
 
 export declare type ComposerCommand = ComposerMention & {
     keywords?: string[];
@@ -647,6 +647,9 @@ export declare type ComposerProps = {
     onCommand?: (id: string, argumentText: string) => void;
     attachments?: ReactNode;
     mentions?: ComposerMention[];
+    onMentionQuery?: MentionQuery;
+    placeholder?: string;
+    hint?: ReactNode;
     disabled?: boolean;
 };
 
@@ -798,7 +801,7 @@ export declare type ContextSwitcherSearch = {
     noResults: ContextSwitcherEmptyState;
 };
 
-export declare function ControlOption({ id, label, description, error, indeterminate, ref, type, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, onClick, ...rest }: ControlOptionProps): JSX.Element;
+export declare function ControlOption({ id, label, labelHidden, description, error, indeterminate, ref, type, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, onClick, ...rest }: ControlOptionProps): JSX.Element;
 
 declare type ControlOptionNativeInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'type'>;
 
@@ -810,7 +813,7 @@ declare type ControlOptionOwnProps = {
 };
 
 /** ControlOption 的完整 props（Checkbox / Radio 的共同底座，须显式给 type）。 */
-export declare type ControlOptionProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & CheckboxOnlyProps & {
+export declare type ControlOptionProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & FieldLabelVisibilityProps & CheckboxOnlyProps & {
     type: 'checkbox' | 'radio';
 } & ControlOptionNativeInputProps;
 
@@ -868,14 +871,18 @@ export declare type DocsPaginationProps = {
     next?: DocsPageLink;
 };
 
-export declare function DotsMenu({ entries, size, disabled, align, }: {
+export declare function DotsMenu({ entries, size, disabled, align, label, }: {
     entries: DotsMenuEntry[];
+    label?: string;
     size?: 'sm' | 'md' | 'lg';
     disabled?: boolean;
     align?: 'start' | 'end';
 }): JSX.Element;
 
 export declare type DotsMenuEntry = {
+    type: 'separator';
+} | {
+    type?: 'item';
     label: string;
     disabled?: boolean;
     danger?: boolean;
@@ -967,6 +974,14 @@ declare type FieldBareProps = {
     error?: never;
 };
 
+export declare type FieldLabelVisibilityProps = {
+    label: string;
+    labelHidden?: boolean;
+} | {
+    label?: never;
+    labelHidden?: never;
+};
+
 export declare function Fieldset({ title, subtitle, tone, footerStatus, footerAction, disabled, children, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, }: {
     title?: string;
     subtitle: string;
@@ -1006,6 +1021,8 @@ export declare type FileTreeNode = {
 /** 筛选选择器入口；弹层、筛选值与 expanded 状态归调用方。 */
 export declare const FilterChip: ForwardRefExoticComponent<    {
 label: string;
+/** 可选同高尺寸；默认 sm（32px）胶囊。 */
+size?: ButtonSize;
 /** undefined 表示未设置；0、空字符串和 null 仍是已设置。 */
 value?: ReactNode;
 onClear?: () => void;
@@ -1013,19 +1030,49 @@ onClear?: () => void;
 
 export declare type FilterChipProps = {
     label: string;
+    /** 可选同高尺寸；默认 sm（32px）胶囊。 */
+    size?: ButtonSize;
     /** undefined 表示未设置；0、空字符串和 null 仍是已设置。 */
     value?: ReactNode;
     onClear?: () => void;
 } & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'value'>;
 
-export declare function FormField({ controlId, label, description, error, wide, children, }: {
-    controlId: string;
+export declare type FilterOption = {
+    value: string;
     label: string;
     description?: string;
+    keywords?: string[];
+    disabled?: boolean;
+};
+
+/** 可搜索单选内容；调用方通过 Popover 管理关闭和入口焦点。每次打开时面板自行把焦点放进搜索框，无需向 Popover 传 initialFocus。 */
+export declare function FilterOptionPanel({ options, value, onSelect, label, searchPlaceholder, loading, error, onRetry, emptyText, noMatchText, filter, query: controlledQuery, onQueryChange }: FilterOptionPanelProps): JSX.Element;
+
+export declare type FilterOptionPanelProps = {
+    options: FilterOption[];
+    value?: string;
+    onSelect: (value: string) => void;
+    /** 搜索框与列表的可访问名称。 */
+    label: string;
+    searchPlaceholder?: string;
+    loading?: boolean;
+    error?: ReactNode;
+    onRetry?: () => void;
+    emptyText?: ReactNode;
+    noMatchText?: (query: string) => ReactNode;
+    filter?: (options: FilterOption[], query: string) => FilterOption[];
+    query?: string;
+    onQueryChange?: (query: string) => void;
+};
+
+export declare function FormField({ controlId, label, labelHidden, description, error, wide, children, }: {
+    controlId: string;
+    label?: string;
+    description?: string;
     error?: string;
     wide?: boolean;
     children: ReactNode;
-}): JSX.Element;
+} & FieldLabelVisibilityProps): JSX.Element;
 
 export declare function Gauge({ value, size, showValue, tone, toneDirection, label, indeterminate, }: {
     value?: number;
@@ -1094,7 +1141,7 @@ export declare type IconButtonProps = IconButtonAccessibleName & IconButtonBaseP
     ref?: Ref<HTMLButtonElement>;
 };
 
-export declare function Input({ id, label, description, error, invalid, errorId, ref, prefix, suffix, prefixStyling, suffixStyling, rounded, wide, size, className, revealable, revealed, onRevealedChange, revealLabel, hideLabel, disabled, ...rest }: {
+export declare function Input({ id, label, labelHidden, description, error, invalid, errorId, ref, prefix, suffix, prefixStyling, suffixStyling, rounded, wide, size, className, revealable, revealed, onRevealedChange, revealLabel, hideLabel, disabled, ...rest }: {
     /** 可选：未传时内部 useId 兜底（对齐 Combobox）；显式传入时行为同 0.3.0。 */
     id?: string;
     /** 置 aria-invalid 的业务校验态，不渲染文案；与壳模式 error 并轨（invalid || Boolean(error)）。 */
@@ -1131,9 +1178,9 @@ export declare function Input({ id, label, description, error, invalid, errorId,
     rounded?: boolean;
     wide?: boolean;
     size?: FieldSize;
-} & (FieldShellProps | FieldBareProps) & Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'size' | 'prefix'>): JSX.Element;
+} & (FieldShellProps | FieldBareProps) & FieldLabelVisibilityProps & Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'size' | 'prefix'>): JSX.Element;
 
-export declare function InputOTP({ id, name, value, onValueChange, disabled, readOnly, required, invalid, errorId, size, separator, ref, label, description, error, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': describedBy, }: InputOTPProps): JSX.Element;
+export declare function InputOTP({ id, name, value, onValueChange, disabled, readOnly, required, invalid, errorId, size, separator, ref, label, labelHidden, description, error, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': describedBy, }: InputOTPProps): JSX.Element;
 
 export declare type InputOTPProps = {
     id?: string;
@@ -1151,7 +1198,7 @@ export declare type InputOTPProps = {
     separator?: boolean;
     ref?: Ref<HTMLInputElement>;
     'aria-describedby'?: string;
-} & ((FieldShellProps & {
+} & FieldLabelVisibilityProps & ((FieldShellProps & {
     'aria-label'?: never;
     'aria-labelledby'?: never;
 }) | (FieldBareProps & ({
@@ -1264,8 +1311,14 @@ export declare type MentionProps = {
     children: ReactNode;
 };
 
-export declare function Menu({ label, entries, withChevron, align, triggerContent }: {
+declare type MentionQuery = (query: string, options: {
+    signal: AbortSignal;
+}) => Promise<ComposerMention[]>;
+
+export declare function Menu({ label, entries, withChevron, align, triggerContent, size }: {
     label: string;
+    /** 文字触发器尺寸，默认 md；图标触发器保留原尺寸。 */
+    size?: ButtonSize;
     entries: MenuEntry[];
     withChevron?: boolean;
     align?: 'start' | 'end';
@@ -1709,7 +1762,7 @@ export declare function Q1travelSymbol(props: SVGProps<SVGSVGElement>): JSX.Elem
 export declare function Radio({ ...props }: RadioProps): JSX.Element;
 
 /** Radio 的完整 props。 */
-export declare type RadioProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & ControlOptionNativeInputProps;
+export declare type RadioProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & FieldLabelVisibilityProps & ControlOptionNativeInputProps;
 
 export declare function RangeField(props: CalendarSelectionProps & {
     layout?: PopoverLayout;
@@ -1819,10 +1872,12 @@ export declare type SearchDialogTriggerProps = {
     'aria-controls': string;
 };
 
-export declare function SearchInput({ id, ariaLabel, value: controlledValue, defaultValue, onValueChange, loading, kbdHint, icon, ref, className, disabled, readOnly, autoComplete, spellCheck, onKeyDown: onInputKeyDown, ...inputProps }: SearchInputProps): JSX.Element;
+export declare function SearchInput({ id, size, ariaLabel, value: controlledValue, defaultValue, onValueChange, loading, kbdHint, icon, ref, className, disabled, readOnly, autoComplete, spellCheck, onKeyDown: onInputKeyDown, ...inputProps }: SearchInputProps): JSX.Element;
 
 export declare type SearchInputProps = {
     id: string;
+    /** 与 Button 同高，默认 md；数字保留原生 input 的字符宽度语义。 */
+    size?: ButtonSize | number;
     /** 无可见 label 时的可访问名；与 FormField 或外部 label 组合时留空。 */
     ariaLabel?: string;
     value?: string;
@@ -1835,11 +1890,11 @@ export declare type SearchInputProps = {
     icon?: ReactNode;
     /** React 19 ref-as-prop，指向原生 search input。 */
     ref?: Ref<HTMLInputElement>;
-} & Omit<InputHTMLAttributes<HTMLInputElement>, 'aria-label' | 'defaultValue' | 'id' | 'onChange' | 'ref' | 'type' | 'value'>;
+} & Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'aria-label' | 'defaultValue' | 'id' | 'onChange' | 'ref' | 'type' | 'value'>;
 
-export declare function Select({ id, label, description, error, ref, wide, size, prefix, suffix, className, children, value, defaultValue, multiple, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, ...rest }: {
+export declare function Select({ id, label, labelHidden, description, error, ref, wide, size, prefix, suffix, className, children, value, defaultValue, multiple, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, ...rest }: {
     id: string;
-    label: string;
+    label?: string;
     description?: string;
     error?: string;
     /** 指向原生 select（React 19 ref-as-prop），供表单校验后聚焦等场景。 */
@@ -1847,7 +1902,7 @@ export declare function Select({ id, label, description, error, ref, wide, size,
     wide?: boolean;
     size?: FieldSize;
     prefix?: ReactNode;
-    /** 装饰性后缀图标（aria-hidden），渲染在下拉箭头左侧；跟 prefix 前缀一样不承载信息，可访问名称仍完全来自 label。 */
+    /** 装饰性后缀图标（aria-hidden），渲染在下拉箭头左侧；跟 prefix 前缀一样不承载信息，可访问名称来自可见 label 或消费方提供的 ARIA / 外部 label。 */
     suffix?: ReactNode;
     children: ReactNode;
     /** Select 只接受单一值；多值选择使用 MultiSelect。 */
@@ -1856,7 +1911,7 @@ export declare function Select({ id, label, description, error, ref, wide, size,
     defaultValue?: string | number;
     /** Select 是单选字段；多值选择使用 MultiSelect。 */
     multiple?: never;
-} & Omit<SelectHTMLAttributes<HTMLSelectElement>, 'id' | 'children' | 'size' | 'prefix' | 'multiple' | 'value' | 'defaultValue'>): JSX.Element;
+} & FieldLabelVisibilityProps & Omit<SelectHTMLAttributes<HTMLSelectElement>, 'id' | 'children' | 'size' | 'prefix' | 'multiple' | 'value' | 'defaultValue'>): JSX.Element;
 
 export declare function Separator({ orientation, decorative, className, }: {
     orientation?: SeparatorOrientation;
@@ -2147,7 +2202,7 @@ export declare function Tabs({ tabs, ariaLabel, variant, value, defaultValue, on
     onValueChange?: (id: string) => void;
 }): JSX.Element | null;
 
-export declare function Textarea({ id, label, description, error, invalid, errorId, ref, wide, size, className, maxLength, onInput, ...rest }: TextareaProps): JSX.Element;
+export declare function Textarea({ id, label, labelHidden, description, error, invalid, errorId, ref, wide, size, className, maxLength, onInput, ...rest }: TextareaProps): JSX.Element;
 
 /** Textarea 的完整 props。消费方包一层时用它标注，无需知道内部由哪几块组合而成。 */
 export declare type TextareaProps = {
@@ -2161,7 +2216,7 @@ export declare type TextareaProps = {
     ref?: Ref<HTMLTextAreaElement>;
     wide?: boolean;
     size?: FieldSize;
-} & (FieldShellProps | FieldBareProps) & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'id'>;
+} & (FieldShellProps | FieldBareProps) & FieldLabelVisibilityProps & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'id'>;
 
 export declare function TextWithCopyButton({ text, copyValue, successMessage, size, }: {
     text: string;