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 [blocked].
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 [blocked].
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 [blocked]).

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 creatinginline 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 [blocked].

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 [blocked] for wiring the preset, importing styles, and pointing UnoCSS at the package so the components' classes get generated.

References

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