@q1travel/design-system 0.30.12 → 0.30.14

package/README.md

@@ -71,7 +71,7 @@ root.render(
 | --- | --- |
 | `npx q1-design ls` | 列出包内提供的组件、hook 与应用模板 |
 | `npx q1-design doc <组件名>` | 打印组件的公共 API；`doc app-base` 查看应用基础样式模板 |
-| `npx q1-design lint [路径...]` | 按 `Q1-DS-*` 规则检查样式用法，默认扫描 `src` |
+| `npx q1-design lint [路径...]` | 按 `Q1-DS-*` 规则检查样式和组件枚举字面量，默认扫描 `src` |
 | `npx q1-design lint --diff <base-ref>` | 只检查相对 `base-ref` 有改动的文件 |
 | `npx q1-design overrides [路径...]` | 统计对组件外观的 `className` 覆写 |
 | `npx q1-design sync` | 将设计契约与 AI 编码指南同步为项目内的只读缓存 |
@@ -89,7 +89,7 @@ mkdir -p src/styles
 cp .claude/skills/product-design/contracts/app-base.css src/styles/app-base.css
 ```
 
-在应用入口先引入 `@q1travel/design-system/tokens.css`（已引入 `style.css` 时无需重复），再引入 `./styles/app-base.css`。应用可修改该副本或在之后加载覆盖样式；升级并重新 `sync` 后自行审阅模板差异再采纳，CLI 不覆盖应用副本。模板只包含盒模型、页面边距与最小高度、画布文字字体与字体平滑、点按高亮、原生表单字体继承；根容器、读屏工具与组件运动/触控行为由各自所属层管理。
+在应用入口先引入 `@q1travel/design-system/tokens.css`（已引入 `style.css` 时无需重复），再引入 `./styles/app-base.css`。应用可修改该副本或在之后加载覆盖样式；升级并重新 `sync` 后自行审阅模板差异再采纳，CLI 不覆盖应用副本。模板只包含盒模型、页面边距与最小高度、画布文字字体与字体平滑、点按高亮；根容器、读屏工具与组件运动/触控行为由各自所属层管理。组件自带字体继承；应用中的非设计系统原生控件需自行处理字体。已复制旧模板的应用可保留或删除 `button, input, textarea, select { font: inherit; }`，按自身原生控件需求决定。
 
 ## 版本
 

package/bin/lint-component-enums.mjs

@@ -0,0 +1,42 @@
+export const COMPONENT_ENUM_RULE = 'Q1-DS-002';
+
+// Match the CLI's import-based scan; only literal JSX attributes are checked.
+export function lintComponentEnums(source, filename, loadSchema) {
+  const imports = new Map();
+  const importPattern = /import\s*\{([^{}]*?)\}\s*from\s*["']@q1travel\/design-system["']/gs;
+  for (const match of source.matchAll(importPattern)) {
+    for (const part of match[1].split(',')) {
+      if (/^\s*type\s/.test(part)) continue;
+      const [component, local = component] = part.trim().split(/\s+as\s+/);
+      if (/^[A-Z][A-Za-z0-9_]*$/.test(local)) imports.set(local, component);
+    }
+  }
+  for (const match of source.matchAll(/import\s*\*\s*as\s+(\w+)\s*from\s*["']@q1travel\/design-system["']/g)) {
+    imports.set(`${match[1]}.*`, '*');
+  }
+  if (!imports.size) return [];
+  const hits = [];
+  const tagPattern = /<([A-Z][\w.]*)\b((?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'{}])*)>/g;
+  for (const tag of source.matchAll(tagPattern)) {
+    const [namespace, member] = tag[1].split('.');
+    const component = member && imports.has(`${namespace}.*`) ? member : imports.get(tag[1]);
+    if (!component) continue;
+    const attributes = /(?:^|\s)(variant|size)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*(?:"([^"]*)"|'([^']*)')\s*\})/g;
+    for (const attribute of tag[2].matchAll(attributes)) {
+      let value = attribute[2] ?? attribute[3] ?? attribute[4] ?? attribute[5];
+      if (attribute[2] !== undefined || attribute[3] !== undefined) {
+        value = value.replace(/&#(x[\da-f]+|\d+);/gi, (_, code) => String.fromCodePoint(code[0].toLowerCase() === 'x' ? parseInt(code.slice(1), 16) : Number(code)));
+      }
+      const allowed = loadSchema()[component]?.[attribute[1]];
+      if (allowed && !allowed.includes(value)) {
+        const offset = tag.index + tag[0].indexOf(tag[2]) + attribute.index;
+        hits.push({
+          ruleId: COMPONENT_ENUM_RULE,
+          lineNumber: source.slice(0, offset + attribute[0].search(/\S/)).split('\n').length,
+          lineContent: `error ${component}.${attribute[1]}=${JSON.stringify(value)}; 允许值: ${allowed.join(' | ')}`,
+        });
+      }
+    }
+  }
+  return hits;
+}

package/bin/q1-design.mjs

@@ -22,6 +22,8 @@ import { createHash } from 'node:crypto';
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { COMPONENT_ENUM_RULE, lintComponentEnums } from './lint-component-enums.mjs';
+
 const PACKAGE_NAME = '@q1travel/design-system';
 const SKILL_RELATIVE_DIR = '.claude/skills/product-design';
 const MANIFEST_FILE_NAME = '.q1-design-manifest.json';
@@ -644,6 +646,17 @@ const LINT_RULES = [
 function collectLintHits(inputPaths, baseDir) {
   const targetFiles = collectLintTargetFiles(inputPaths, baseDir);
   const hits = [];
+  let enumSchema;
+  const loadEnumSchema = () => {
+    if (!enumSchema) {
+      const relativePath = 'dist-pkg/component-enums.json';
+      const packageRoot = resolveInstalledPackageRoot(baseDir) ?? baseDir;
+      const schemaPath = join(packageRoot, relativePath);
+      if (!existsSync(schemaPath)) throw new Error(`[q1-design] 找不到 ${relativePath}，无法检查组件枚举；请安装 ${PACKAGE_NAME} 或先运行 npm run build:lib。`);
+      enumSchema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+    }
+    return enumSchema;
+  };
 
   for (const absoluteFilePath of targetFiles) {
     const fileContent = readFileSync(absoluteFilePath, 'utf8');
@@ -653,6 +666,14 @@ function collectLintHits(inputPaths, baseDir) {
       isTokens: isTokensPath(absoluteFilePath, baseDir),
     };
 
+    if (!fileFacts.isCssFile && !hasFileDisablePragma(fileContent, COMPONENT_ENUM_RULE)) {
+      const isSuppressed = createSuppressionTracker(COMPONENT_ENUM_RULE);
+      const suppressedLines = fileContent.split('\n').map((line) => isSuppressed(line));
+      for (const hit of lintComponentEnums(fileContent, absoluteFilePath, loadEnumSchema)) {
+        if (!suppressedLines[hit.lineNumber - 1]) hits.push({ ...hit, filePath: relativeFilePath });
+      }
+    }
+
     const activeRules = LINT_RULES.map((rule) => ({
       rule,
       applicable: rule.appliesToFile(fileFacts) && !hasFileDisablePragma(fileContent, rule.ruleId),
@@ -717,7 +738,7 @@ function runLint(inputPaths, consumerRootDir, diffBaseRef) {
 
   for (const hit of hits) {
     console.log(
-      `${hit.ruleId} ${hit.filePath}:${hit.lineNumber} ${truncateLine(hit.lineContent)}`,
+      `${hit.ruleId} ${hit.filePath}:${hit.lineNumber} ${hit.ruleId === COMPONENT_ENUM_RULE ? hit.lineContent : truncateLine(hit.lineContent)}`,
     );
   }
   console.log(`[q1-design] 共 ${hits.length} 处命中`);
@@ -1109,7 +1130,12 @@ if (isDirectRun) {
       }
       args.splice(diffIndex, 2);
     }
-    runLint(args.length > 0 ? args : ['src'], consumerRootDir, diffBaseRef);
+    try {
+      runLint(args.length > 0 ? args : ['src'], consumerRootDir, diffBaseRef);
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
   } else if (subcommand === 'eval') {
     runEval();
   } else if (subcommand === 'overrides') {

package/contracts/app-base.css

@@ -29,10 +29,3 @@ html {
   height: 100%;
   -webkit-tap-highlight-color: transparent;
 }
-
-button,
-input,
-textarea,
-select {
-  font: inherit;
-}

package/contracts/button-api-compatibility.md

@@ -30,6 +30,16 @@ Package-owned semantics are applied after native props. `type`, `className`, `di
 
 Button preserves an explicitly supplied native `aria-busy` when `busy` is false, including during `loading`; `loading` alone still does not add it. This lets consumers announce an external task immediately while controlling visual loading separately. `busy=true` always sets `aria-busy="true"`, even when a consumer passes false. ButtonLink keeps its existing package-owned busy semantics.
 
+## IconButton Attention
+
+`attention?: boolean` is opt-in. Only `attention={true}` adds `data-icon-button-attention="true"` to the existing button. Omitting it or passing false preserves the previous markup and styling without a new class or wrapper.
+
+The first direct child must be an icon or an icon-only container. Subsequent children may include a static Badge. Only that first element rotates, once, using the existing slow duration and in-out easing tokens. The button, Badge, layout, accessible name, native keyboard activation, and focus remain unchanged.
+
+A persistent true value does not replay on rerender, hover, or focus. A committed false state observed by the browser, followed by true, starts another finite cycle. Batched false-to-true updates do not promise replay. No timer or background replay queue is provided.
+
+Under `prefers-reduced-motion: reduce`, no attention animation runs and the static count remains visible. Consumers include the unread count in the accessible name and own count positioning.
+
 ## Loading and Busy States
 
 `loading` and `busy` are intentionally different public states:

package/contracts/design.dark.md

@@ -385,7 +385,7 @@ components:
     backgroundColor: "{semantic-colors.surface-panel}"
     textColor: "{semantic-colors.text-primary}"
     placeholderColor: "{semantic-colors.text-muted}"
-    borderColor: "{semantic-colors.border}"
+    borderColor: "{semantic-colors.border-control}"
     focusColor: "{semantic-colors.focus-ring}"
     typography: "{typography.label-14}"
     rounded: "{rounded.sm}"

package/contracts/design.md

@@ -385,7 +385,7 @@ components:
     backgroundColor: "{semantic-colors.surface-panel}"
     textColor: "{semantic-colors.text-primary}"
     placeholderColor: "{semantic-colors.text-muted}"
-    borderColor: "{semantic-colors.border}"
+    borderColor: "{semantic-colors.border-control}"
     focusColor: "{semantic-colors.focus-ring}"
     typography: "{typography.label-14}"
     rounded: "{rounded.sm}"

package/contracts/implementation-map.md

@@ -112,7 +112,7 @@ Timeline / TimelineItem (ol/li, 8px token dot or Avatar), Marker (quiet actor/ti
 
 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.
+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 with the shared `selection-recipe.css` inset border-strong selection edge (bg-subtle in light, bg-raised in dark); keyboard focus replaces that edge with the 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
 - Native base: `src/components/ui/ControlOption.tsx`; circle-only readonly/warning module: `src/components/ui/CircleCheckbox.tsx`; independent style: `src/styles/checkbox-circle.css`, imported at the top of global.css and included by build-style.mjs. Square defaults remain unchanged.
 - 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.
@@ -150,3 +150,7 @@ The announcement region wraps only the icon, the `q1-sr-only` 「错误：」 pr
 ## Cascader 层级选择
 
 `Cascader`（`src/components/ui/Cascader.tsx`）负责字段及触发器；`cascader/` 的 Types、model、window、Panel 分别负责受控边界、路径与独立选择、测量窗口、关联 listbox 与搜索。复用 Popover/useOverlay、RegionErrorState 和 Spinner；样式来自既有 surface、text、control、space、radius 与 focus token。窄屏同一弹层单列钻取，亮暗继承 anchor。完整约束、可选省略、公开面与回滚见 [Cascader](./cascader.md)。文档入口 `/components/cascader`，不迁移既有选择器。
+
+## ThemeSwitcher selection appearance
+
+Accepted 2026-11-02 (#761): ThemeSwitcher keeps a single outer group border. Options have no border; selection uses `--q1-color-bg-selected-neutral` and primary text, with no inset selection edge. Unselected options keep secondary text and the container background. Light and dark selected and unselected text meet 4.5:1 contrast; the selected background differs from the container. Native labeled radios retain their keyboard behavior, hover changes enabled option text to primary, and keyboard focus uses the shared focus shadow. Public props, class names, DOM structure, exports, and tokens are unchanged.

package/dist-pkg/component-enums.json

@@ -0,0 +1,284 @@
+{
+  "Badge": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "Book": {
+    "variant": [
+      "stripe",
+      "simple"
+    ]
+  },
+  "Browser": {
+    "variant": [
+      "light",
+      "dark"
+    ]
+  },
+  "Button": {
+    "variant": [
+      "primary",
+      "secondary",
+      "ghost",
+      "warning",
+      "danger"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "ButtonLink": {
+    "variant": [
+      "primary",
+      "secondary",
+      "ghost",
+      "warning",
+      "danger"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "CalendarGrid": {
+    "size": [
+      "large",
+      "small"
+    ]
+  },
+  "Checkbox": {
+    "size": [
+      "sm",
+      "md"
+    ]
+  },
+  "CodeBlock": {
+    "variant": [
+      "default",
+      "flush"
+    ]
+  },
+  "Combobox": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "DotsMenu": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "ErrorMessage": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "FilterChip": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "Gauge": {
+    "size": [
+      "xs",
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "IconButton": {
+    "variant": [
+      "primary",
+      "secondary",
+      "ghost",
+      "warning",
+      "danger"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "Input": {
+    "size": [
+      "xs",
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "InputOTP": {
+    "size": [
+      "md",
+      "lg"
+    ]
+  },
+  "Marker": {
+    "variant": [
+      "default",
+      "separator",
+      "unread"
+    ]
+  },
+  "Menu": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "Navigation": {
+    "variant": [
+      "default",
+      "line"
+    ]
+  },
+  "Note": {
+    "size": [
+      "small",
+      "default",
+      "large"
+    ]
+  },
+  "PageFeedback": {
+    "variant": [
+      "rating",
+      "helpful"
+    ]
+  },
+  "Pill": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "ProductLockup": {
+    "size": [
+      "sm",
+      "md"
+    ]
+  },
+  "ProjectBanner": {
+    "variant": [
+      "default",
+      "success",
+      "warning",
+      "error"
+    ]
+  },
+  "RangeField": {
+    "size": [
+      "large",
+      "small"
+    ]
+  },
+  "Select": {
+    "size": [
+      "xs",
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "Sheet": {
+    "size": [
+      "sm",
+      "md",
+      "lg",
+      "xl"
+    ]
+  },
+  "SidebarDrawer": {
+    "variant": [
+      "panel",
+      "plain"
+    ]
+  },
+  "Spinner": {
+    "size": [
+      "sm",
+      "md",
+      "lg",
+      "xl"
+    ]
+  },
+  "SplitButton": {
+    "variant": [
+      "default",
+      "secondary"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "StatusPage": {
+    "size": [
+      "page",
+      "region"
+    ]
+  },
+  "Switch": {
+    "variant": [
+      "segmented",
+      "cards"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "Tabs": {
+    "variant": [
+      "default",
+      "secondary",
+      "line"
+    ]
+  },
+  "Textarea": {
+    "size": [
+      "xs",
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "TextWithCopyButton": {
+    "size": [
+      "default",
+      "small"
+    ]
+  },
+  "Toggle": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "ToggleGroup": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  }
+}

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

@@ -1325,7 +1325,7 @@ export declare type HoverCardProps = {
     className?: string;
 };
 
-export declare function IconButton({ 'aria-label': canonicalAriaLabel, ariaLabel: legacyAriaLabel, 'aria-pressed': ariaPressed, disabled, loading, onClick, onBlur, onKeyDown, onPointerCancel, onPointerDown, onPointerLeave, onPointerUp, onLostPointerCapture, ...rest }: IconButtonProps): JSX.Element;
+export declare function IconButton({ 'aria-label': canonicalAriaLabel, ariaLabel: legacyAriaLabel, 'aria-pressed': ariaPressed, disabled, loading, attention, onClick, onBlur, onKeyDown, onPointerCancel, onPointerDown, onPointerLeave, onPointerUp, onLostPointerCapture, ...rest }: IconButtonProps): JSX.Element;
 
 declare type IconButtonAccessibleName = {
     'aria-label': string;
@@ -1347,6 +1347,7 @@ declare type IconButtonBaseProps = {
     variant?: ButtonVariant;
     size?: ButtonSize;
     circle?: boolean;
+    attention?: boolean;
     loading?: boolean;
     loadingLabel?: string;
     disabled?: boolean;