@q1travel/design-system 0.2.0 → 0.3.1

package/contracts/icon-system.md

@@ -0,0 +1,77 @@
+# 图标系统 · Icons
+
+> **状态**：本规范定义图标系统的**目标态**。当前文档站的界面图标仍由 `lucide-react` 渲染（其几何与下方规范一致），并存在若干 `18px` 等迁移前尺寸；迁移到自建工厂 + 注册表是独立排期任务，尚未完成。品牌符号已是自有原生 SVG。
+
+q1travel 的界面图标**目标是**一套自建的线性图标系统：几何参照 Lucide，实现为受控的原生 SVG，不依赖第三方图标库。品牌符号（q1travel 标识）不属于此系统，作为品牌资产单独维护。
+
+本规范是图标系统的**单一真相源**；自建工厂落地时，其代码注释应指回本规范，而非另立编号体系。
+
+---
+
+## 设计规范
+
+所有界面图标共享同一组参数，由图标工厂统一强制，不依赖单个图标自觉遵守。
+
+| 属性 | 值 |
+| --- | --- |
+| 画布 `viewBox` | `0 0 24 24` |
+| 描边宽度 `stroke-width` | `1.8` |
+| 填充 `fill` | `none` |
+| 描边颜色 `stroke` | `currentColor` |
+| 线帽 `stroke-linecap` | `round` |
+| 连接 `stroke-linejoin` | `round` |
+| `aria-hidden` | `true`（装饰默认）|
+| `focusable` | `false` |
+
+- **线性风格**：统一描边、无填充，与 Lucide 图标库一致的线性视觉语言。
+- **`currentColor`**：图标颜色继承当前文本颜色，随主题与组件状态自动适配；**不在图标内写死颜色**。
+
+---
+
+## 尺寸
+
+按所在场景的密度选择，不在区间内随意取值。**默认 16px**（不传 size 时）。现有 `18px` 等实例为迁移前遗留，随自建迁移一并收敛（见顶部状态）。
+
+| 尺寸 | 值 | 场景 |
+| --- | --- | --- |
+| 小 | `16px`（默认）| 按钮内、紧凑控件、导航 |
+| 中 | `20px` | 独立图标、列表项 |
+| 大 | `24px` | 强调、空状态 |
+
+---
+
+## 来源
+
+| 类别 | 方案 |
+| --- | --- |
+| 界面图标 | 几何参照 Lucide，自建原生 SVG；**不引入** `lucide-react` 或任何第三方图标库（目标态，迁移中）|
+| 品牌符号 | q1travel 标识，自有原生 SVG，作为品牌资产单独维护 |
+
+参照 Lucide 几何，是为沿用其成熟、克制的线性视觉；自建实现，是为完全可控、无第三方依赖、可统一治理。
+
+---
+
+## 治理
+
+图标是受控资源，统一遵循以下约束：
+
+- **工厂**：所有图标经统一工厂创建，几何参数、颜色、尺寸与可访问性默认值由工厂强制，而非逐个图标维护。
+- **注册表**：所有图标登记在唯一清单中，记录名称、用途与同义词；语义重复的图标只保留一个（例如「编辑」不并存 edit / pencil / modify）。
+- **单一入口**：界面一律使用图标组件，不在业务代码中内联 `<svg>`。
+- **受控例外（special）**：带额外状态或逻辑、确实无法走工厂的历史图标，登记在注册表的 `special` 字段、单独维护，不作为新增图标的范例。
+- **新增流程**：先登记注册表、补入图标库展示，再投入使用。
+
+---
+
+## 可访问性
+
+- 图标默认 `aria-hidden="true"` 且 `focusable="false"`，视为装饰；语义由相邻文本或调用方的 `aria-label` 承担。
+- 纯图标控件（如图标按钮）必须由调用方提供可访问名称。
+
+---
+
+## 使用
+
+- **颜色**：不为图标单独设色，依赖 `currentColor` 跟随文本。
+- **间距**：图标与文本之间保留一致间距，并与文本基线对齐。
+- **一致性**：同一控件组内不混用不同描边或尺寸。

package/contracts/implementation-map.md

@@ -0,0 +1,29 @@
+# q1travel Design System Implementation Map
+
+This map records how external reference intent is translated into q1travel production code. It is not a screenshot checklist and it is not a source for copied markup or copied styles.
+
+## Directory Shape
+
+README owns the repository inventory and generated-file boundary. This file owns the reference-to-implementation mapping.
+
+| 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 |
+| 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 |
+| Brand lockup preview | q1travel identity specimen | `Q1travelSymbol` with custom lockup composition | Text, border, spacing tokens plus documented lockup variables | None | Asset stage clamps to tile width | Decorative visual is hidden from assistive tech |
+| Icon matrix preview | Icon component density sample | `showcaseIconEntries` rendered with Lucide icons | `currentColor`, text-secondary token | None | Grid clamps inside tile | Icons are decorative in the tile, named on the Icon component page |
+| Component preview tile | Control density sample | Custom preview composition using component token mappings | Surface, border, action, focus, radius tokens | Button and segment visual states | Flex wrap preserves compact layout | Decorative in intro, real controls documented on component pages |
+| Color rods preview | Color scale summary | Custom preview composition using color scale aliases | `--q1-color-scale-*` aliases | None | Rods distribute across available width | Semantic labels identify the represented scale |
+| Color page reference and semantic tokens | Token reference and theme value copy | `ColorSwatch`, `SemanticColorListItem`, and `SemanticColorDemo` inside `ColorsPage` | `--q1-color-*`, semantic color tokens, and semantic action tokens | Left click copies token, context menu copies resolved value. The focus shadow token shows as an applied focus ring, not a flat color swatch | Ten-step grid and semantic rows adapt to available width | Button labels, semantic rows, live copy feedback |
+| Page footer navigation | Sequential documentation reading | `PageNavigation` | Surface, border, text, spacing tokens | Hover, focus, feedback buttons | Three-column footer collapses with content | Links are named and feedback controls are buttons |
+
+## Implementation Rules
+
+- Reference behavior must map to a q1travel semantic before it reaches `src`.
+- 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 `组件`.
+- If a capability is missing from a shared component, add the capability to that component before adding another page-local pattern.

package/contracts/interface-guidelines.md

@@ -0,0 +1,122 @@
+# q1travel Interface Guidelines
+
+These guidelines adapt mature web interface rules into q1travel contracts. They apply to documentation pages, component samples, and future product surfaces that consume this design system. The public localized version is the `/guidelines` page (`src/pages/GuidelinesPage.tsx`); keep both in sync.
+
+## Interactions
+
+- MUST support keyboard operation for every interactive path.
+- MUST show a visible `:focus-visible` state for every focusable element.
+- MUST manage focus for overlays: move focus on open, return it on close, and trap it where the APG pattern requires.
+- MUST use native links for navigation and native buttons for actions.
+- MUST keep visual and hit targets aligned; controls smaller than 24px need a larger interactive area.
+- MUST keep mobile control targets at least 44px where touch is expected.
+- NEVER disable browser zoom.
+- MUST avoid dead zones: if a region looks clickable, the clickable element must cover it.
+- MUST show a loading indicator on in-flight buttons while keeping the original label.
+- SHOULD delay spinners and skeletons by ~150–300ms and keep them visible for ~300–500ms so fast responses do not flicker.
+- SHOULD update the UI optimistically when success is likely, and roll back with an error (or offer Undo) on failure.
+- MUST require confirmation or offer a safe-window Undo for destructive actions.
+- MUST announce async updates (toasts, inline validation) via polite `aria-live`.
+- SHOULD set `overscroll-behavior: contain` inside modals and drawers to prevent scroll chaining.
+- SHOULD delay only the first tooltip in a group; subsequent peers open without delay.
+- SHOULD persist meaningful UI state in the URL when state must survive refresh, sharing, or Back/Forward navigation.
+
+## Forms
+
+- MUST associate every input, textarea, select, checkbox, radio, and switch with a label or accessible name.
+- MUST focus the associated control when its label is clicked; label and control share one generous hit target.
+- MUST allow paste and password-manager behavior unless the field has a documented security reason.
+- MUST validate after input instead of blocking normal typing.
+- MUST show validation near the field and move focus to the first blocking error on submit.
+- MUST keep submit enabled until the request starts; disable and show loading only while the request is in flight.
+- SHOULD submit on Enter when a single text input is focused; in a textarea, ⌘/⌃+Enter submits and Enter inserts a newline.
+- MUST keep mobile input text at 16px or larger.
+- SHOULD use correct `type` and `inputmode` values for better keyboards and validation.
+- SHOULD set `autocomplete` and meaningful `name` values so browser autofill works.
+- MUST trim trailing whitespace introduced by IME or text replacement before validating.
+- SHOULD use placeholders only as examples or patterns, and end placeholder copy with `…`.
+
+## Layout
+
+- MUST align every element intentionally to a grid, edge, baseline, or optical center.
+- MUST prefer CSS grid, flex, and intrinsic sizing over JavaScript measurement.
+- SHOULD balance contrast in icon-and-text lockups by adjusting weight, size, spacing, or color.
+- MUST avoid unwanted internal scrollbars.
+- MUST verify small, laptop, desktop, and wide layouts.
+- SHOULD respect device safe areas (notches, gesture zones) with safe-area variables.
+- SHOULD use semantic layout tokens for repeated frame, rail, topbar, page-header, and specimen proportions.
+- SHOULD allow small optical adjustments when they are named and localized.
+
+## Content And Accessibility
+
+- MUST keep headings hierarchical and provide stable section anchors where deep links exist.
+- MUST keep `<title>` reflecting the current context.
+- MUST provide accessible names for icon-only controls.
+- MUST hide decorative visuals from assistive technology.
+- MUST use redundant status cues; color alone is not enough.
+- MUST mirror final content geometry in skeletons to avoid layout shift when loading completes.
+- MUST design empty, sparse, dense, and error states.
+- MUST offer a next step or recovery path on every screen; no dead ends.
+- MUST keep layouts resilient to short, average, and very long content, especially user-generated content.
+- SHOULD format dates, times, numbers, and currencies for the user's locale.
+- MUST keep technical identifiers, token names, and brand names protected from browser translation with `translate="no"` where appropriate.
+- SHOULD prefer inline help over tooltips.
+- SHOULD use tabular numbers for comparison rows and token tables.
+
+## Accessibility Tiers
+
+Every component is classified into one accessibility tier; the tier sets its bar. The tier is decided by how much keyboard and focus behavior the component must own beyond native semantics. The keyboard model source is always the matching WAI-ARIA APG pattern, not invention — established design systems follow APG too, so "matching a reference" and "following APG" do not conflict.
+
+- **Tier A — composite widgets** (calendar, combobox, menu, modal, drawer, tabs, slider, listbox, tree, …): MUST implement the full keyboard model of the matching APG pattern (roving tabindex; arrow / `Home` / `End` / `PageUp` / `PageDown` as the pattern defines; `Enter` / `Space` activation; `Esc` dismissal that returns focus to the trigger), MUST manage focus on open and close, MUST expose the required ARIA (`role`, `aria-selected` / `aria-expanded` / `aria-controls`, `aria-live` where state changes), MUST document the key map as a「按键 | 行为」keyboard table (`.a11y-keys`) in the page's 可访问性 section, and MUST be locked by a runtime keyboard assertion in `scripts/check-browser.mjs`.
+- **Tier B — native-semantic controls** (button, input, textarea, checkbox, radio, switch, select, links): MUST rely on native elements for keyboard and role, MUST carry an associated label or accessible name, and MUST show a visible `:focus-visible` state through the shared focus token. No custom key handling is expected.
+- **Tier C — display / decorative** (avatar, badge, banner, book, browser, icon, card, skeleton, …): MUST hide purely decorative visuals from assistive technology (`aria-hidden`, non-focusable) and MUST give every icon-only control an accessible name. No keyboard model is required.
+
+Calendar (`src/pages/CalendarPage.tsx`) and Tabs (`src/pages/TabsPage.tsx`) are the Tier A reference implementations to copy.
+
+## Animation
+
+- MUST honor `prefers-reduced-motion`.
+- MUST animate only `opacity` and `transform` unless a documented reason requires otherwise.
+- SHOULD prefer CSS, then the Web Animations API, then JavaScript libraries; avoid main-thread-driven animation.
+- SHOULD choose easing based on what changes (size, distance, trigger).
+- SHOULD keep animations interruptible by user input.
+- SHOULD animate in response to input instead of autoplaying.
+- SHOULD anchor `transform-origin` where the motion physically starts.
+- NEVER use `transition: all`.
+- SHOULD animate only to clarify cause and effect or to reinforce a deliberate state change.
+
+## Theming
+
+- MUST support light and dark themes through tokens, not page-local color constants.
+- MUST set the appropriate `color-scheme` so native controls and scrollbars match the current theme.
+- MUST keep browser theme color aligned with the first paint background.
+- SHOULD give `:hover` / `:active` / `:focus` states more contrast than the rest state.
+- MUST explicitly set native select foreground and background when styling select controls.
+
+## Performance
+
+- MUST prevent layout shift by reserving space for media, fonts, and stable specimens.
+- MUST avoid repeated layout reads and writes during interaction.
+- SHOULD complete POST/PATCH/DELETE requests within 500ms.
+- SHOULD keep controlled input updates cheap and use uncontrolled inputs where appropriate.
+- SHOULD subset CJK fonts and preload critical above-the-fold fonts to avoid flashes and layout shift.
+- SHOULD move long tasks to Web Workers instead of blocking the main thread.
+- SHOULD virtualize long lists before they become a documentation or product performance problem.
+
+## Copy
+
+- MUST be public, neutral, and specific.
+- MUST use consistent nouns across pages, navigation, tables, and examples.
+- SHOULD prefer short action-oriented labels.
+- MUST use active voice.
+- MUST use unambiguous action labels (「保存 API Key」, not 「继续」).
+- MUST make error messages guide the exit: say how to fix it, not only what failed.
+- SHOULD default to positive, problem-solving language, including errors.
+- SHOULD use numerals for counts and keep number/unit formatting consistent.
+- MUST keep currency decimal places consistent within a context (0 or 2, never mixed).
+
+## Agent Integration
+
+- This file is the machine-readable mirror of the public 界面准则 page (`/guidelines`); keep them in sync.
+- `AGENTS.md` at the repository root constrains agent generation and modification behavior.
+- `npm run check` (build + shell contract + browser contract) is the merge gate for any interface change.

package/contracts/token-naming.md

@@ -0,0 +1,82 @@
+# q1travel Token Naming Contract
+
+Status: accepted
+
+This contract defines the token naming standard for q1travel Design System v1. It records the naming decision only; it does not migrate existing `q1travel-web` runtime tokens.
+
+## Decision
+
+New public design-system tokens use the `--q1-*` prefix.
+
+Existing `--ds-*` tokens in product repositories are legacy implementation tokens. They may remain during migration, but they are not the source name for new q1travel Design System contracts, documentation, or component examples.
+
+External reference systems can guide the token layer model and page behavior. Their exact token names, class names, and computed styles are not implementation source.
+
+## Layers
+
+### Reference Tokens
+
+Reference tokens hold source values and scale steps. They are useful for color ramps, spacing scales, radius scales, and typography primitives.
+
+Examples:
+
+- `--q1-color-gray-100`
+- `--q1-color-primary-700`
+- `--q1-color-background-100`
+- `--q1-space-4`
+- `--q1-radius-2`
+- `--q1-font-size-copy-14`
+
+Reference color scales use numeric steps from `100` to `1000`.
+
+### Semantic Tokens
+
+Semantic tokens describe product meaning. Product surfaces should consume these before reaching for reference tokens.
+
+Examples:
+
+- `--q1-color-bg-canvas`
+- `--q1-color-bg-panel`
+- `--q1-color-text-primary`
+- `--q1-color-border`
+- `--q1-color-action-primary`
+- `--q1-color-status-danger`
+- `--q1-shadow-focus`
+
+### Component Tokens
+
+Component tokens are allowed only when a shared component needs a stable public customization surface. Do not create component tokens for one page or one specimen.
+
+Pattern:
+
+- `--q1-<component>-<slot>`
+- `--q1-<component>-<slot>-<state>`
+
+Examples:
+
+- `--q1-button-bg`
+- `--q1-button-bg-hover`
+- `--q1-input-border-focus`
+
+## Usage Rules
+
+- Product code should use semantic tokens first.
+- Documentation color ramps may show and copy reference tokens.
+- Documentation semantic color rows may show and copy semantic tokens.
+- Left-clicking a color token swatch copies the token reference; context menu copies the current theme resolved value for inspection.
+- Raw hex values are contract source values and inspection output, not the preferred product-consumption API.
+- Shadow tokens should be displayed as token references, not as color swatches.
+- Theme-specific values may differ, but token names must stay stable across light and dark themes.
+
+## Migration Rules
+
+- Do not create new public `--ds-*` tokens.
+- Do not rename all product `--ds-*` tokens in a broad sweep.
+- During migration, add explicit aliases only when they reduce risk and point toward the accepted `--q1-*` naming.
+- Treat `--ds-*` tokens in `q1travel-web` as legacy product implementation until a dedicated migration plan lands.
+
+## Non-Goals
+
+- This contract does not publish an npm token package.
+- This contract does not migrate `q1travel-web`.
+- This contract does not require deleting every local or private product CSS variable.

package/{dist → dist-pkg}/design-system.d.ts

@@ -539,7 +539,7 @@ export declare function ErrorCard({ title, message, action }: {
 }): JSX.Element;
 
 export declare function ErrorMessage({ label, size, action, children, }: {
-    /** 可见的粗体标签前缀（如「邮箱错误：」），点明出错对象；缺省不显示（sr-only 前缀恒在）。 */
+    /** 可见的粗体标签前缀（如「邮箱错误：」），点明出错对象；缺省不显示（q1-sr-only 前缀恒在）。 */
     label?: string;
     size?: ErrorMessageSize;
     /** 恢复操作插槽：可安全重试用「重试」按钮，链接式出口放 <a>。 */
@@ -970,7 +970,7 @@ export declare function Switch({ options, ariaLabel, name, defaultValue, onChang
     onChange?: (value: string) => void;
     size?: 'sm' | 'md' | 'lg';
     fullWidth?: boolean;
-    /** 纯图标模式：文字标签仍在，只是视觉隐藏（sr-only），可访问名称不丢失。 */
+    /** 纯图标模式：文字标签仍在，只是视觉隐藏（q1-sr-only），可访问名称不丢失。 */
     iconOnly?: boolean;
 }): JSX.Element | null;