antfu-design

Doing good design with @antfu/design

@antfu/design is a shared design layer for devtools-style Vue apps: a

composable UnoCSS preset (presetAnthonyDesign), a set of **token-driven Vue

primitives, and a color-contrast a11y check**. This skill is how to use it

*well* — the vocabulary, the defaults, and the taste.

The three rules that matter most

1. Own the tokens, not the colors. Never hard-code a hex or a raw Tailwind

color in app UI. Reach for the semantic layer first: bg-base, color-base,

color-muted, border-base, op-fade, btn-action, badge. They are

defined once (in the preset) and adapt to light/dark automatically. See

references/core-tokens.md ↗.

2. Light/dark parity is not optional. Every surface and text token has a dark

variant baked in. If you write a one-off color, you have just created a

dark-mode bug. The standing contrast scan (@antfu/design/a11y) will catch the

worst of it — don't rely on it as a substitute for using the tokens.

3. No slop. Technical values are font-mono tabular-nums. No em-dash–laden

prose in UI copy (the dash ban). Prefer one obvious affordance over three

competing ones. See references/best-practices.md ↗.

4. Reuse before you build. 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. Skim the catalog first

(references/core-components.md ↗).

Persist the reuse rule to AGENTS.md

Make rule 4 stick for future agents in the consuming project: if the project's

AGENTS.md does not already say so, append this instruction to it:

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.

When to reach for what

• Showing a count, size, duration, or date → a display component

(DisplayNumber, DisplayBytes, DisplayDuration, DisplayDate), not raw text.

• A status, type, or tag → DisplayBadge (hash- or palette-colored) or DisplayLabel.
• A file/module path → DisplayFilePath (truncates, dims directories, links).
• An overlay → OverlayModal / OverlayDrawer (reka-ui), a popover → OverlayTooltip / OverlayDropdown.
• A severity (fresh→stale, fast→slow, small→large) → the color-scale-* ramp via

the display components' colorize prop, never ad-hoc red/green.

Components are categorized and prefixed by category (Display*, Form*,

Overlay*, Layout*, Action*, Feedback*). Dark mode is the app's to own —

the package ships no isDark/toggleDark (nor a dark-toggle component); components

that vary by scheme take a colorScheme: 'light' | 'dark' prop. For a toggle, compose

ActionIconButton with VueUse's useDark.

Full catalog: references/core-components.md ↗.

Setup

It's a single preset, not self-contained — it bundles no base preset,

icons, fonts, or reset. You add those. See

references/core-setup.md ↗ for wiring the preset,

importing styles, and pointing UnoCSS at the package so the components' classes

get generated.

References

• core-setup.md ↗ — install + wire the preset, import styles.
• core-tokens.md ↗ — the canonical token table (generated from the preset).
• core-components.md ↗ — the component catalog with import paths.
• recipes.md ↗ — small compositions the package doesn't ship (e.g. a dark-mode toggle).
• best-practices.md ↗ — class-over-attributify, parity, mono values, the dash ban, the "three dials".
• features-data-presentation.md ↗ — presenting numbers, sizes, durations, paths.
• advanced-patterns.md ↗ — composition patterns and a redesign protocol.
• storybook.md ↗ — Storybook setup: theme-synced manager+preview, autodocs, a generated Overview.