@q1travel/design-system 0.1.0 → 0.3.0

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

@@ -7,6 +7,7 @@ import { KeyboardEventHandler } from 'react';
 import { MouseEventHandler } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
+import { Ref } from 'react';
 import { RefObject } from 'react';
 import { SelectHTMLAttributes } from 'react';
 import { TextareaHTMLAttributes } from 'react';
@@ -17,13 +18,13 @@ export declare function Avatar({ title, src, letter, glyph, placeholder, icon, i
 
 export declare function AvatarGroup({ members, label, size, limit, overlap, reverse, className, }: {
     members: AvatarMember[];
-    /** 可选整组名；传入则套 role=group 作整组增强，不传则跟 Geist 默认逐个头像标注（读屏念每个成员名）。 */
+    /** 可选整组名；传入则套 role=group 作整组增强，不传则默认逐个头像标注（读屏念每个成员名）。 */
     label?: string;
     /** 成员统一直径；缺省 32。 */
     size?: number;
     /** 显示上限，超出收纳为 +N；非法值（负数/NaN）忽略。 */
     limit?: number;
-    /** 重叠像素；'auto' = 尺寸的 30% 取整（Geist 实测 16→5 / 24→7 / 32→10 / 48→14）；负数按 0 处理。 */
+    /** 重叠像素；'auto' = 尺寸的 30% 取整（例：16→5 / 24→7 / 32→10 / 48→14）；负数按 0 处理。 */
     overlap?: number | 'auto';
     /** 翻转堆叠顺序。 */
     reverse?: boolean;
@@ -43,7 +44,7 @@ export declare type AvatarProps = {
     glyph?: ReactNode;
     /** 加载占位骨架；只用于加载态，不作长期缺省。 */
     placeholder?: boolean;
-    /** 右下角标图标（对标 Geist With custom icon）；纯装饰，语义信息由调用方文字承载。 */
+    /** 右下角标图标；纯装饰，语义信息由调用方文字承载。 */
     icon?: ReactNode;
     /** 角标底色（任意 CSS color，建议用语义 token）；缺省中性灰盘。 */
     iconColor?: string;
@@ -63,7 +64,7 @@ export declare type BadgeProps = {
     subtle?: boolean;
     /** 反转高对比形态；设置后忽略 tone/subtle。 */
     inverted?: boolean;
-    /** 尺寸档 20/24/32（Geist 实测阶梯）。 */
+    /** 尺寸档 20/24/32。 */
     size?: BadgeSize;
     /** 前置图标；纯装饰（组件自动 aria-hidden），宽高随档位 12/14/16 由样式钉死。 */
     icon?: ReactNode;
@@ -88,12 +89,12 @@ export declare type BannerProps = {
     tone?: BannerTone;
     /** 卡条形态的前缀图标；纯装饰（组件自动 aria-hidden）。公告形态与进度形态不渲染图标。 */
     icon?: ReactNode;
-    /** 主操作：公告形态渲染恒深药丸（无 chevron，Geist 同款）；卡条形态渲染描边药丸 + chevron。进度形态忽略 action——任务进行中不挂主跳转，完成后换普通卡条。 */
+    /** 主操作：公告形态渲染恒深药丸（无 chevron）；卡条形态渲染描边药丸 + chevron。进度形态忽略 action——任务进行中不挂主跳转，完成后换普通卡条。 */
     action?: {
         label: string;
         href: string;
     };
-    /** 关闭回调；设置后渲染关闭按钮。公告形态无关闭（跟 Geist）；进度形态渲染在进度头右侧。 */
+    /** 关闭回调；设置后渲染关闭按钮。公告形态无关闭；进度形态渲染在进度头右侧。 */
     onDismiss?: () => void;
     /** 进度形态（自有扩展）：value 为 0–100 的百分比（非法值归 0），label 供读屏。进度恒为卡条形态。 */
     progress?: {
@@ -111,11 +112,11 @@ export declare function Book({ title, variant, color, bandColor, textColor, icon
 export declare type BookProps = {
     /** 封面标题；语义由标题承载，封面其余元素均为装饰。 */
     title: string;
-    /** stripe=顶部色带+下方标签区（Geist 默认）；simple=纯封面、标题置顶。 */
+    /** stripe=顶部色带+下方标签区（默认）；simple=纯封面、标题置顶。 */
     variant?: 'stripe' | 'simple';
-    /** 封面底色；建议传设计 token（var(--q1-color-…)），勿用裸 hex（Geist Best Practices 同款要求）。 */
+    /** 封面底色；建议传设计 token（var(--q1-color-…)），勿用裸 hex。 */
     color?: string;
-    /** stripe 色带颜色；缺省琥珀（Geist 实测默认带色）。 */
+    /** stripe 色带颜色；缺省琥珀。 */
     bandColor?: string;
     /** 标题颜色；自定义封面色时务必保证对比可读。 */
     textColor?: string;
@@ -123,7 +124,7 @@ export declare type BookProps = {
     icon?: ReactNode;
     /** 整幅插画：铺满封面、裁切；标题浮于其上；aria-hidden。 */
     illustration?: ReactNode;
-    /** 细密交叉纹理（自有配方；Geist 的多款纹理样式记 non-goal）。仅用于主视觉，成排书架勿用。 */
+    /** 细密交叉纹理（自有配方）；只提供单一纹理样式，未做多纹理体系（记 non-goal）。仅用于主视觉，成排书架勿用。 */
     textured?: boolean;
     /** 数字按 px；字符串原样透传（如 clamp(...) 做响应式宽度）。内部排版随宽度等比缩放。
      *  width 是唯一尺寸入口：用 style.width 改宽会与内部缩放脱节。 */
@@ -188,7 +189,7 @@ declare type ButtonProps = {
     iconOnly?: boolean;
     /** 圆形——仅用于 icon-only 按钮。与 rounded 互斥（同传时 circle 优先）。 */
     circle?: boolean;
-    /** 药丸形（full radius）+ 柔和抬起阴影（对标 Geist Rounded，营销页/落地页文字 CTA 用）。与 circle 互斥。 */
+    /** 药丸形（full radius）+ 柔和抬起阴影，营销页/落地页文字 CTA 用。与 circle 互斥。 */
     rounded?: boolean;
     loading?: boolean;
     disabled?: boolean;
@@ -205,6 +206,8 @@ declare type ButtonProps = {
     onFocus?: FocusEventHandler<HTMLButtonElement | HTMLAnchorElement>;
     onBlur?: FocusEventHandler<HTMLButtonElement | HTMLAnchorElement>;
     onKeyDown?: KeyboardEventHandler<HTMLButtonElement | HTMLAnchorElement>;
+    /** 渲染为 <button> 或 <a>（取决于是否传 href），供 focus 管理、测量、浮层定位等场景使用。 */
+    ref?: Ref<HTMLButtonElement | HTMLAnchorElement>;
 };
 
 export declare type ButtonSize = 'sm' | 'md' | 'lg';
@@ -245,13 +248,13 @@ declare type CardOwnProps = {
     hover?: boolean;
     /** 次要表面：更弱的底色，与主卡片区分层级。 */
     secondary?: boolean;
-    /** 分段：用分隔线把卡片切成几段（对齐 Geist borderBetween）。 */
+    /** 分段：用分隔线把卡片切成几段。 */
     divided?: boolean;
     /** 分段方向：column 竖排（默认）/ row 横排。与 divided 正交——单传 row 只横向铺开，配 divided 才加分隔线。 */
     direction?: CardDirection;
-    /** 常驻柔和投影（对齐 Geist shadow）：让卡片浮于背景，用于落地/营销卡片。 */
+    /** 常驻柔和投影：让卡片浮于背景，用于落地/营销卡片。 */
     shadow?: boolean;
-    /** 是否带边框，默认 true。传 false 得无框卡片（靠底色/投影表达边界，对齐 Geist border 可选）。 */
+    /** 是否带边框，默认 true。传 false 得无框卡片（靠底色/投影表达边界）。 */
     bordered?: boolean;
     className?: string;
     children: ReactNode;
@@ -345,7 +348,8 @@ export declare function CodeTokens({ tokens }: {
 }): JSX.Element;
 
 export declare function Collapse({ title, defaultOpen, small, children, }: {
-    title: string;
+    /** 固定文案传字符串；随展开/收起切换文案（如"显示代码"/"收起代码"）传函数，入参为当前 open 状态。 */
+    title: string | ((open: boolean) => string);
     defaultOpen?: boolean;
     small?: boolean;
     children: ReactNode;
@@ -404,7 +408,7 @@ declare type CommandMenuProps = {
 };
 
 export declare type CommandMenuSection = {
-    /** 段标题；缺省时该段以无标题分隔线与上文分隔（对标 Geist CommandMenuDivider）。 */
+    /** 段标题；缺省时该段以无标题分隔线与上文分隔。 */
     heading?: string;
     items: CommandMenuItem[];
 };
@@ -548,7 +552,7 @@ export declare type ErrorMessageSize = 'sm' | 'md' | 'lg';
 export declare function Feedback({ label, prompt, placeholder, inline, topics, }: {
     label?: string;
     prompt?: string;
-    /** textarea 占位（对标 Geist Custom Placeholder）：换成更具体的引导，帮助用户知道从哪里说起。 */
+    /** textarea 占位：换成更具体的引导，帮助用户知道从哪里说起。 */
     placeholder?: string;
     inline?: boolean;
     topics?: string[];
@@ -610,11 +614,11 @@ export declare function Input({ id, label, description, error, prefix, suffix, p
     error?: string;
     prefix?: ReactNode;
     suffix?: ReactNode;
-    /** 置 false 去掉前缀的灰块底色与分隔线，变成纯文本/裸图标（对标 Geist prefixStyling）。 */
+    /** 置 false 去掉前缀的灰块底色与分隔线，变成纯文本/裸图标。 */
     prefixStyling?: boolean;
-    /** 置 false 去掉后缀的灰块底色与分隔线（对标 Geist suffixStyling）。 */
+    /** 置 false 去掉后缀的灰块底色与分隔线。 */
     suffixStyling?: boolean;
-    /** 药丸形全圆角外框（对标 Geist rounded，实测 9999px 级 pill 半径）。 */
+    /** 药丸形全圆角外框（9999px 级 pill 半径）。 */
     rounded?: boolean;
     wide?: boolean;
     size?: FieldSize;
@@ -714,8 +718,8 @@ declare type NativeInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'id'
 
 declare type NativeInputProps_2 = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>;
 
-export declare function Note({ type, size, filled, disabled, label, action, children, }: {
-    type?: NoteType;
+export declare function Note({ tone, size, filled, disabled, label, action, children, }: {
+    tone?: NoteTone;
     size?: NoteSize;
     filled?: boolean;
     disabled?: boolean;
@@ -726,7 +730,7 @@ export declare function Note({ type, size, filled, disabled, label, action, chil
 
 declare type NoteSize = 'small' | 'default' | 'large';
 
-declare type NoteType = 'info' | 'success' | 'warning' | 'error' | 'secondary';
+export declare type NoteTone = 'info' | 'success' | 'warning' | 'error' | 'secondary';
 
 declare type PageLink = {
     title: string;
@@ -749,7 +753,7 @@ export declare function Phone({ screenLabel }: {
 
 export declare function Pill({ href, size, icon, title, className, children, ...rest }: PillProps): JSX.Element;
 
-declare type PillProps = {
+export declare type PillProps = {
     href: string;
     size?: BadgeSize;
     /** 前置图标；纯装饰（组件自动 aria-hidden）。 */
@@ -799,7 +803,7 @@ export declare function RangeInputs({ value, withTime, onApply, pinnedTimezone,
     value: RangeValue;
     withTime: boolean;
     onApply: () => void;
-    /** 固定时区（对标 Geist pinnedTimezone）：传入时时区从可选 select 变只读文本、不可切换。 */
+    /** 固定时区：传入时时区从可选 select 变只读文本、不可切换。 */
     pinnedTimezone?: string;
 }): JSX.Element;
 
@@ -914,7 +918,7 @@ export declare function Snippet({ text, prompt, inverted, tone, copyText, onCopy
     prompt?: boolean;
     inverted?: boolean;
     tone?: SnippetTone;
-    /** 显示与复制内容分离（对标 Geist）：传了就复制它，不传复制显示内容。 */
+    /** 显示与复制内容分离：传了就复制它，不传复制显示内容。 */
     copyText?: string;
     /** 复制触发后调用，供外部消费复制事件（如埋点）；不代表剪贴板写入一定成功。 */
     onCopy?: () => void;
@@ -1089,6 +1093,12 @@ export declare function useCopy(): {
     reset: () => void;
 };
 
+export declare function useRadio({ id, ...rest }: {
+    id: string;
+} & NativeInputProps): {
+    component: JSX.Element;
+};
+
 export declare function useToast(): ToastContextValue;
 
 export declare function Video({ controls, loop }: {