antfu-design

在任何框架（React、Vue、Svelte、Solid 或纯 HTML）中使用 UnoCSS 构建界面时，都可参考本指南，适用于从密集的开发工具面板到着陆页等场景。先阅读 core-design-read 以确定设计方向，再应用令牌系统以及润色和反臃肿规则。

核心规则

• 在标记中使用语义化快捷类（bg-base、border-base、color-active、btn-action），不要使用原始工具类链。
• 同时设计浅色和深色模式。核心令牌必须同时适用于两种主题。
• 为 z-index 层命名（z-top-nav、z-panel-content、z-drawer-content）。不要在模板中使用原始 z 值。
• 仅生成基于类的工具类（class="..."）。避免在生成的代码中使用 Attributify 语法。
• 将图标和状态类字符串写成字面量，以便 UnoCSS 静态提取（必要时使用 // @unocss-include）。
• 对技术值（路径、SHA、计数器、时间戳、百分比）使用 font-mono 和 tabular-nums。
• 对较长的路径和 ID 进行视觉截断，但要在 title 中保留完整值。
• 阅读需求说明，并在选择外观前设置三个调节项（core-design-read）。
• 密集或结构性表面使用边框，凸起表面使用分层阴影（features-micro-interactions）。
• 面向用户的文本中不得出现破折号字符（em dash 和 en dash）（best-practices-anti-slop）。

入门快捷类

最精简的语义化核心。完整的 uno.config.ts 和基础浅色／深色样式请参见 core-starter-kit。

shortcuts: [
  {
    'color-base': 'color-neutral-800 dark:color-neutral-200',
    'bg-base': 'bg-white dark:bg-#111',
    'bg-secondary': 'bg-#eee dark:bg-#222',
    'border-base': 'border-#8882',

    'bg-active': 'bg-#8881',
    'color-active': 'color-primary-600 dark:color-primary-300',
    'border-active': 'border-primary-600/25 dark:border-primary-400/25',

    'btn-action': 'inline-flex items-center gap-2 rounded border border-base px2 py1 op75 hover:op100 hover:bg-active disabled:pointer-events-none disabled:op30!',
    'op-fade': 'op65 dark:op55',
    'op-mute': 'op30 dark:op25',

    'z-top-nav': 'z-60',
    'z-panel-content': 'z-70',
    'z-drawer-content': 'z-100',
  },
]

核心参考

主题	描述	参考
核心原则	语义化令牌、深色模式一致性、z-index 命名、类优先输出	core-principles
入门工具包	可复制粘贴的 UnoCSS 入门配置和基础浅色／深色样式	core-starter-kit
令牌与组合	令牌系列、可复用的类组合、适用于移动设备的外壳令牌	core-tokens-and-combinations
设计解读与调节项	阅读需求说明、声明设计解读、设置变化度／动效／密度调节项	core-design-read

最佳实践

主题	描述	参考
严格规则与预检	应做／不应做清单及整合后的预检流程	best-practices-strict-rules
优先使用类，而非 Attributify	生成的代码为何使用类工具，以及相应转换方式	best-practices-class-utilities-over-attributify
反臃肿规范	禁用破折号及禁止使用的 AI 痕迹模式	best-practices-anti-slop
偏差校正	需要覆盖的字体排印、颜色、布局和材质默认值	best-practices-bias-correction

功能

主题	描述	参考
数据呈现	路径、图标、时间、日期、数字、徽章、按钮	features-data-presentation
微交互	圆角、对齐、阴影、动画、数字、轮廓、点击区域	features-micro-interactions
Floating Vue 覆盖项	通用 Floating Vue 设置和弹出层样式	features-floating-vue-overrides

高级

主题	描述	参考
模式词汇表	可识别并采用的命名 UI 模式	advanced-pattern-vocabulary
重新设计规范	检测模式、先进行审查、保留 IA 和 SEO	advanced-redesign-protocol