@q1travel/design-system 0.28.1 → 0.29.0

package/contracts/implementation-map.md

@@ -105,7 +105,7 @@ Timeline / TimelineItem (ol/li, 8px token dot or Avatar), Marker (quiet actor/ti
 
 ## ToggleGroup selection ownership
 
-Accepted 2026-10-07: public `ToggleGroup` uses the shadcn/Radix name (no corresponding industry-common component). Its `items` API exposes `value`, `label`, optional `icon`, `disabled`, and `ariaLabel`; icon-only items require an icon and `ariaLabel`. `type="single"` accepts string `value` / `defaultValue` and `onValueChange`; `allowEmpty` defaults to false. `type="multiple"` accepts string arrays. Controlled values remain caller-owned; uncontrolled single selection falls back to the first enabled item when its value is absent or unknown and empty selection is disallowed. Disabling an existing selected item retains its pressed state and moves only the tabstop. No existing Switch consumer is migrated.
+Accepted 2026-10-07: public `ToggleGroup` names a group of pressable controls with single or multiple selection. Its `items` API exposes `value`, `label`, optional `icon`, `disabled`, and `ariaLabel`; icon-only items require an icon and `ariaLabel`. `type="single"` accepts string `value` / `defaultValue` and `onValueChange`; `allowEmpty` defaults to false. `type="multiple"` accepts string arrays. Controlled values remain caller-owned; uncontrolled single selection falls back to the first enabled item when its value is absent or unknown and empty selection is disallowed. Disabling an existing selected item retains its pressed state and moves only the tabstop. No existing Switch consumer is migrated.
 
 Native buttons expose `aria-pressed` within `role="group"`. Roving tabindex and Arrow / Home / End move focus without selecting; Enter / Space activate through native clicks. Disabled items are skipped. Button-aligned sm32 / md40 / lg48 sizes use existing tokens, quiet selected background and primary text without a selected ring, shared focus shadow, and the shared coarse-pointer 44px TouchTarget with reserved neighbor space. The Tier A keyboard contract lives on `/components/toggle-group`; Switch retains radio semantics and Tabs retains panel semantics.
 ## Checkbox task completion circle
@@ -113,7 +113,7 @@ Native buttons expose `aria-pressed` within `role="group"`. Roving tabindex and
 - Documentation: `src/pages/CheckboxPage.tsx`, `CheckboxCircleDemo.tsx`, `src/styles/checkbox-circle-specimen.css`; circle completion is restricted to tasks/checklists and row completion treatment stays consumer-owned.
 - Verification: `scripts/check-checkbox-circle-contract.test.mjs`, `scripts/fixtures/checkbox-circle-api-consumer.tsx`, `scripts/lib/checkbox-circle-contrast.mjs`, `scripts/lib/check-checkbox-circle-browser.mjs`. Package gate covers API/default/native markup/readonly semantics/token existence and both-theme contrast; browser gate covers native toggles, focus without preview, readonly, tone fill, reduced motion and coarse hit targets.
 ## Chat messages
-Bubble is separate from Message: chat has optional identity and direction, while Message retains its required author, comment attachments and receipt API unchanged. MessageScroller is separate from Scroller: keyed prepend anchors and message following need ownership of the viewport; the general Scroller API remains unchanged. The shadcn chat reference supplies conversation intent only; quiet chat surfaces map to existing q1travel panel/selected backgrounds, borders, spacing, radii and Button. No reference CSS, motion background or private tokens are shipped.
+Bubble is separate from Message: chat has optional identity and direction, while Message retains its required author, comment attachments and receipt API unchanged. MessageScroller is separate from Scroller: keyed prepend anchors and message following need ownership of the viewport; the general Scroller API remains unchanged. Quiet chat surfaces use existing q1travel panel/selected backgrounds, borders, spacing, radii and Button. No reference CSS, motion background or private tokens are shipped.
 The consumer mapping was checked against downstream chat-style implementations (read-only, no downstream edits).
 | Web capability | Package support / caller boundary |
 | --- | --- |

package/contracts/interface-guidelines.md

@@ -26,7 +26,7 @@ Adding a clause therefore means answering two questions before the wording: who
 - [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 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 NOT ship dense measured 24–32px controls to coarse pointers without 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] SHOULD NOT ship dense measured 24–32px controls to coarse pointers without enlargement: q1travel uses a 44×44 CSS-pixel mobile usability target, informed by WCAG 2.5.5.
 - [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.
@@ -191,7 +191,7 @@ Theming owns tokens and `color-scheme`; the interaction-contrast rule lives in D
 - [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 follow common Chinese technical-writing practice for mixed-language wording. 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 「继续」).
@@ -213,7 +213,7 @@ These copy clauses keep reader address and empty states consistent with a formal
 
 ### Component Naming
 
-- [repo] SHOULD use the industry-common component name when one exists, preferring shadcn/ui, then Radix. Invent a name only when neither has one. Name what the component is, not how it is built.
+- [repo] SHOULD use the industry-common component name when one exists. Invent a name only when no established name fits. 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

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

@@ -1578,7 +1578,7 @@ export declare type MultiSelectProps = {
     preserveSelectionOrder?: boolean;
 };
 
-export declare function Navigation({ className, orientation, ...props }: NavigationProps): JSX.Element;
+export declare function Navigation({ className, orientation, variant, ...props }: NavigationProps): JSX.Element;
 
 export declare function NavigationGroup({ label, icon, expanded, defaultExpanded, onExpandedChange, children, }: NavigationGroupProps): JSX.Element;
 
@@ -1617,6 +1617,8 @@ export declare type NavigationItemProps = NavigationItemAsLink | NavigationItemA
 export declare type NavigationProps = HTMLAttributes<HTMLElement> & {
     'aria-label': string;
     orientation?: 'vertical' | 'horizontal';
+    /** Line styling applies only to horizontal navigation; vertical navigation ignores it. */
+    variant?: 'default' | 'line';
 };
 
 export declare function NavigationSection({ label, action, children, className, ...props }: NavigationSectionProps): JSX.Element;

package/dist-pkg/design-system.js

@@ -5987,16 +5987,17 @@ function cu({
     ) : null
   ] });
 }
-function lu({ className: e, orientation: t = "vertical", ...r }) {
+function lu({ className: e, orientation: t = "vertical", variant: r = "default", ...o }) {
   return /* @__PURE__ */ n(
     "nav",
     {
       className: se(
         "q1-navigation",
         t === "horizontal" && "q1-navigation--horizontal",
+        t === "horizontal" && r === "line" && "q1-navigation--line",
         e
       ),
-      ...r
+      ...o
     }
   );
 }

package/dist-pkg/style.css

@@ -9845,7 +9845,7 @@ button.q1-navigation__item:not(:disabled),
 }
 
 .q1-navigation__item--active {
-  background: var(--q1-color-bg-hover);
+  background: var(--q1-color-gray-alpha-200);
   color: var(--q1-color-text-primary);
   font-weight: var(--q1-font-weight-medium);
 }
@@ -10034,15 +10034,20 @@ a.q1-navigation__item[aria-disabled='true'] {
     background-color var(--q1-duration-press) var(--q1-ease-state);
 }
 
+/* 滚动容器内沿用 Table 的内嵌焦点环，避免四边被 overflow 裁切。 */
+.q1-navigation--horizontal .q1-navigation__item:focus-visible {
+  box-shadow: inset 0 0 0 calc(var(--q1-space-1) / 2) var(--q1-color-focus);
+}
+
 .q1-navigation--horizontal .q1-navigation__item--active {
-  background: var(--q1-color-bg-hover);
+  background: var(--q1-color-gray-alpha-200);
   color: var(--q1-color-text-primary);
 }
 
 @media (hover: hover) and (pointer: fine) {
-  .q1-navigation__item:hover:not(:active):not([aria-disabled='true']):not(:disabled),
+  .q1-navigation__item:hover:not(.q1-navigation__item--active):not(:active):not([aria-disabled='true']):not(:disabled),
   .q1-navigation__group-trigger:hover:not(:active) {
-    background: var(--q1-color-bg-subtle);
+    background: var(--q1-color-bg-hover);
   }
 
   .q1-navigation__item-row:hover .q1-navigation__item-action {
@@ -10053,11 +10058,12 @@ a.q1-navigation__item[aria-disabled='true'] {
 
   .q1-navigation--horizontal .q1-navigation__item:hover:not(:active):not([aria-disabled='true']):not(:disabled) {
     color: var(--q1-color-text-primary);
-    background: var(--q1-color-bg-subtle);
+    background: var(--q1-color-bg-hover);
   }
 
   .q1-navigation--horizontal .q1-navigation__item--active:hover:not(:active):not([aria-disabled='true']):not(:disabled) {
     color: var(--q1-color-text-primary);
+    background: var(--q1-color-gray-alpha-200);
   }
 }
 
@@ -11266,6 +11272,71 @@ a.q1-navigation__item[aria-disabled='true'] {
   display: none;
 }
 
+.q1-navigation--line {
+  --q1-navigation-row-min-height: calc(var(--q1-space-10) + var(--q1-space-1));
+
+  scrollbar-width: none;
+  align-items: stretch;
+  gap: var(--q1-space-6);
+  /* 基线不占布局空间，绘于子项下方；滚动时下划线仍压在同一底边。 */
+  box-shadow: inset 0 calc(var(--q1-space-1) / -4) 0 var(--q1-color-border);
+}
+
+.q1-navigation--line::-webkit-scrollbar {
+  display: none;
+}
+
+.q1-navigation--line .q1-navigation__item {
+  position: relative;
+  border-bottom: calc(var(--q1-space-1) / 2) solid transparent;
+  border-radius: 0;
+  padding: var(--q1-space-3) var(--q1-space-2);
+  background: none;
+  color: var(--q1-color-text-secondary);
+  font-weight: var(--q1-font-weight-regular);
+  transition: color var(--q1-duration-press) var(--q1-ease-state);
+}
+
+/* 焦点环仅纵向收进项内，底边与选中下划线保留一档间距。 */
+.q1-navigation--horizontal.q1-navigation--line .q1-navigation__item:focus-visible {
+  box-shadow: none;
+}
+
+.q1-navigation--line .q1-navigation__item:focus-visible::after {
+  content: '';
+  position: absolute;
+  inset: var(--q1-space-1) 0;
+  border-radius: var(--q1-radius-2);
+  box-shadow: inset 0 0 0 calc(var(--q1-space-1) / 2) var(--q1-color-focus);
+  pointer-events: none;
+}
+
+.q1-navigation--line .q1-navigation__item:is(.q1-navigation__item--active, [aria-current='page']) {
+  border-bottom-color: var(--q1-color-text-primary);
+  color: var(--q1-color-text-primary);
+}
+
+.q1-navigation--line .q1-navigation__item--disabled {
+  color: var(--q1-color-text-muted);
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .q1-navigation--horizontal.q1-navigation--line .q1-navigation__item:hover:not(:active):not([aria-disabled='true']):not(:disabled) {
+    background: none;
+    color: var(--q1-color-text-primary);
+  }
+}
+
+.q1-navigation--line .q1-navigation__item:active:not([aria-disabled='true']):not(:disabled) {
+  background: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .q1-navigation--line .q1-navigation__item {
+    transition: none;
+  }
+}
+
 /* Calendar grid rows, focus treatment, touch targets, and RangeField entrance motion. */
 .calendar__weekdays,
 .calendar__row {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q1travel/design-system",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "description": "React components, design tokens, and interface contracts for q1travel products.",
   "keywords": [
     "react",