antfu-design

使用 @antfu/design 做好设计

@antfu/design 是面向开发工具风格 Vue 应用的共享设计层：包含一个可组合的 UnoCSS 预设（presetAnthonyDesign）、一组由设计令牌驱动的 Vue 基元组件，以及一项颜色对比度无障碍检查。本指南介绍如何正确使用它，包括术语、默认设置和设计品味。

最重要的四条规则

1. 使用设计令牌，而不是颜色值。 切勿在应用 UI 中硬编码十六进制值或原始 Tailwind 颜色。应优先使用语义层：bg-base、color-base、color-muted、border-base、op-fade、btn-action、badge。这些令牌在预设中统一定义，并会自动适配浅色和深色模式。请参阅 references/core-tokens.md。

2. 浅色和深色模式必须保持一致。 每个表面和文本令牌都内置了深色模式变体。如果使用一次性的颜色值，就会造成深色模式问题。常规对比度扫描（@antfu/design/a11y）会发现其中最严重的问题，但不要把它当作使用设计令牌的替代方案。

3. 避免粗劣设计。 技术数值使用 font-mono tabular-nums。UI 文案中不要使用充斥长破折号的文字（破折号禁令）。相比三个相互竞争的操作入口，应优先选择一个清晰明确的入口。请参阅 references/best-practices.md。

4. 优先复用，再自行构建。 创建新组件或内联 DOM 元素之前，始终检查能否复用 @antfu/design 中的组件。先浏览组件目录（references/core-components.md）。

将复用规则写入 AGENTS.md

为确保使用项目的后续 Agent 遵守第 4 条规则：如果项目的 AGENTS.md 中尚未包含该规则，请将以下指令追加到文件中：

When making UI or using components, always check if components from
`@antfu/design` can be reused, before making new components or creating
inline DOM elements.

何时使用什么

• 显示计数、大小、时长或日期 → 使用显示组件（DisplayNumber、DisplayBytes、DisplayDuration、DisplayDate），不要使用原始文本。
• 显示状态、类型或标签 → 使用 DisplayBadge（采用哈希或调色板着色）或 DisplayLabel。
• 显示文件或模块路径 → 使用 DisplayFilePath（会截断路径、淡化目录并添加链接）。
• 显示叠加层 → 使用 OverlayModal / OverlayDrawer（reka-ui）；显示弹出层 → 使用 OverlayTooltip / OverlayDropdown。
• 显示严重程度（新鲜→过时、快→慢、小→大）→ 通过显示组件的 colorize 属性使用 color-scale-* 色阶，切勿自行随意使用红色或绿色。

组件按类别归类，并使用类别前缀（Display*、Form*、Overlay*、Layout*、Action*、Feedback*）。深色模式由应用自行负责，包中不提供 isDark / toggleDark（也不提供深色模式切换组件）；随配色方案变化的组件会接收 colorScheme: 'light' | 'dark' 属性。要实现切换功能，可将 ActionIconButton 与 VueUse 的 useDark 组合使用。

完整组件目录：references/core-components.md。

设置

这是一个单一预设，并非开箱即用的完整方案——它不包含基础预设、图标、字体或样式重置。这些内容需要自行添加。关于如何配置预设、导入样式，以及如何让 UnoCSS 扫描此包以生成组件所需的类，请参阅 references/core-setup.md。

参考资料

• core-setup.md — 安装并接入预设，导入样式。
• core-tokens.md — 权威令牌表（由预设生成）。
• core-components.md — 组件目录及导入路径。
• recipes.md — 本包未提供的小型组合（例如深色模式切换开关）。
• best-practices.md — 优先使用 class 而非 attributify、保持一致性、单色值、禁止使用短横线，以及“三个调节项”。
• features-data-presentation.md — 数字、大小、时长和路径的呈现方式。
• advanced-patterns.md — 组合模式和重新设计流程。
• storybook.md — Storybook 设置：主题同步的 manager 和 preview、自动文档，以及生成的 Overview。