antfu-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use this when building interfaces with UnoCSS in any framework (React, Vue, Svelte, Solid, or plain HTML), from dense devtools panels to landing pages. Read core-design-read first to set the direction, then apply the token system plus the polish and anti-slop rules.

当你在任意框架（React、Vue、Svelte、Solid 或纯 HTML）中使用 UnoCSS 构建界面时，无论是密集的开发者工具面板还是落地页，都可以遵循本规范。请先阅读 core-design-read 来明确设计方向，然后应用令牌系统及打磨优化、防草率规则。

Core Rules

核心规则

Use semantic shortcuts (
```
bg-base
```
,
```
border-base
```
,
```
color-active
```
,
```
btn-action
```
) instead of raw utility chains in markup.
Design light and dark mode together. Core tokens must work in both themes.
Name z-index layers (
```
z-top-nav
```
,
```
z-panel-content
```
,
```
z-drawer-content
```
). Do not use raw z values in templates.
Generate class-based utilities only (
```
class="..."
```
). Avoid Attributify syntax in generated code.
Keep icon/status class strings literal so UnoCSS can statically extract them (
```
// @unocss-include
```
when needed).
Use
```
font-mono
```
+
```
tabular-nums
```
for technical values (paths, SHAs, counters, timestamps, percentages).
For long paths and IDs, truncate visually but keep the full value in
```
title
```
.
Read the brief and set the three dials before choosing a look (core-design-read).
Borders for dense or structural surfaces, layered shadows for elevated ones (features-micro-interactions).
Zero em-dash and en-dash characters in any user-facing text (best-practices-anti-slop).

使用语义化快捷方式（
```
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）。
用户可见文本中禁止使用长破折号和短破折号（best-practices-anti-slop）。

Starter shortcuts

初始快捷方式

A minimal semantic core. See core-starter-kit for the full

uno.config.ts

and base styles.

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',
  },
]

一个极简的语义化核心配置。完整的

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',
  },
]

Core References

核心参考

Topic	Description	Reference
Core Principles	Semantic tokens, dark mode parity, z-index naming, class-first output	core-principles
Starter Kit	Copy-paste UnoCSS starter config and base light/dark styles	core-starter-kit
Tokens and Combos	Token families, reusable class combinations, mobile-safe shell tokens	core-tokens-and-combinations
Design Read and Dials	Read the brief, declare a design read, set variance/motion/density dials	core-design-read

主题	描述	参考链接
核心原则	语义化令牌、明暗模式一致性、z-index命名、类优先输出	core-principles
初始套件	可直接复制使用的UnoCSS初始配置及基础明暗样式	core-starter-kit
令牌与组合	令牌体系、可复用类组合、移动端安全外壳令牌	core-tokens-and-combinations
设计准则与调节项	阅读设计说明、明确设计准则、设置差异/动效/密度调节项	core-design-read

Best Practices

最佳实践

Topic	Description	Reference
Strict Rules and Pre-Flight	Do/don't checklist and the consolidated pre-flight	best-practices-strict-rules
Class over Attributify	Why generated code uses class utilities, with conversions	best-practices-class-utilities-over-attributify
Anti-Slop Hygiene	The dash ban and the AI-tell forbidden patterns	best-practices-anti-slop
Bias Correction	Typography, color, layout, and materiality defaults to override	best-practices-bias-correction

主题	描述	参考链接
严格规则与预检查	禁止/允许事项清单及整合式预检查	best-practices-strict-rules
类优先于Attributify	生成代码使用类工具类的原因及转换方法	best-practices-class-utilities-over-attributify
防草率规范	破折号禁用规则及AI识别禁用模式	best-practices-anti-slop
偏差修正	需要覆盖的排版、颜色、布局及材质默认值	best-practices-bias-correction

Features

功能特性

Topic	Description	Reference
Data Presentation	Paths, icons, time, date, numbers, badges, buttons	features-data-presentation
Micro-Interactions	Radius, alignment, shadows, animation, numbers, outlines, hit areas	features-micro-interactions
Floating Vue Overrides	Shared Floating Vue setup and popper styling	features-floating-vue-overrides

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

Advanced

进阶内容

Topic	Description	Reference
Pattern Vocabulary	Named UI patterns to recognize and reach for	advanced-pattern-vocabulary
Redesign Protocol	Detect mode, audit first, preserve IA and SEO	advanced-redesign-protocol

主题	描述	参考链接
模式词汇表	可识别及复用的命名UI模式	advanced-pattern-vocabulary
重设计流程	检测模式、优先审计、保留信息架构及SEO	advanced-redesign-protocol