@antfu/design

@antfu/design

A customizable, composable design system for devtools-style Vue apps: a UnoCSS preset (presetAnthonyDesign), a set of Vue primitives, a ground-up design skill, and a color-contrast a11y check. Something in between a component library and shadcn.

Install

pnpm add @antfu/design unocss vue

Quick start

// uno.config.ts
import { presetAnthonyDesign } from '@antfu/design/unocss'
import transformerDirectives from '@unocss/transformer-directives'
import { defineConfig, presetIcons, presetWebFonts, presetWind4 } from 'unocss'

export default defineConfig({
  presets: [
    presetAnthonyDesign({ primary: '#49833E' }),
    presetWind4(), // a base preset is required — bring your own
    presetIcons(),
    presetWebFonts({ fonts: { sans: 'DM Sans', mono: 'DM Mono' } }),
  ],
  // Required — most shipped styles recolor overlays with token `--at-apply`
  // directives; this transformer expands them (and lets you reuse tokens in CSS).
  // (vue-afloat.css is the exception — it themes via vue-afloat's own
  // `--vue-afloat-*` CSS variables and needs no transformer.)
  transformers: [transformerDirectives()],
  // The preset ships no z-index scale (stacking is the app's to own) and blocks
  // plain `z-<number>`. Define the named layers the overlay components use here —
  // these values are yours; tune them to fit your app's stack.
  shortcuts: {
    'z-nav': 'z-[30]',
    'z-dropdown': 'z-[40]',
    'z-tooltip': 'z-[45]',
    'z-toast': 'z-[50]',
    'z-modal-backdrop': 'z-[60]',
    'z-modal-content': 'z-[70]',
    'z-drawer-backdrop': 'z-[80]',
    'z-drawer-content': 'z-[90]',
  },
})

Pair it with @unocss/eslint-plugin for the feedback loop — it surfaces the blocklist hints (e.g. a plain z-50) in your editor and CI instead of silently dropping at build time.

// Components are imported by full path (no barrel) — categorized and prefixed:
import ActionButton from '@antfu/design/components/Action/ActionButton.vue'
import DisplayBadge from '@antfu/design/components/Display/DisplayBadge.vue'
import OverlayModal from '@antfu/design/components/Overlay/OverlayModal.vue'
import '@antfu/design/styles.css' // everything, incl. splitpanes/reka/vue-afloat overrides

styles.css bundles every overlay engine's override. If you don't use them all, cherry-pick instead so unused (splitpanes/reka-ui) CSS never ships:

import '@antfu/design/styles/base.css'
import '@antfu/design/styles/scrollbar.css'
import '@antfu/design/styles/vue-afloat.css' // only if you use tooltips

The package ships raw .ts / .vue source (no bundling) — your build compiles it. No extra content config is needed: UnoCSS's default scan matches .vue/.tsx by extension (its only default exclude is CSS, not node_modules), so the components you import are picked up automatically. If you do set content.pipeline.include, note it replaces the default scan rather than extending it — restate the defaults too, or your own sources stop being generated.

It's a single preset that is not self-contained: it contributes only the antfu design layer (theme tokens, semantic shortcuts, dynamic rules, severity). You compose the base preset, icons, fonts and reset yourself — and add @unocss/transformer-directives (the shipped styles use token --at-apply directives) plus, recommended, @unocss/eslint-plugin for the feedback loop.

Exports

The package is stateless — no dark-mode/clipboard/toast state. Components that vary by scheme take a colorScheme prop; toasts are controlled. Use VueUse directly for state.

Two opt-in helpers reduce the boilerplate without adding global state: provideColorScheme(() => isDark ? 'dark' : 'light') (from @antfu/design/composables/colorScheme) lets scheme-aware components inherit the scheme instead of threading a prop, and useToast() (from @antfu/design/composables/toast) owns a toast queue for FeedbackToasts. Both only read state you own.

Migrating an existing app

If your app predates the design system, adoption is mostly deletion:

• Delete your local token shortcuts. Apps already on the *-base dialect (bg-base, color-base, border-base, op-fade, btn-action, badge-color-*, color-scale-*, …) can drop those hand-rolled uno.config.ts shortcuts blocks — often 20–170 lines — and inherit them from presetAnthonyDesign. Set primary / darkBackground to your existing values (and keep your existing presetWebFonts config as-is — this preset has no opinion on fonts) for a near-zero visual diff.
• Dedupe local utilities into @antfu/design/utils: the duplicated getHashColorFromString / getPluginColor, the byte / duration / time-ago formatters, module-id / path parsing, and semver-range parsing all live there.
• Bump off the legacy presetUno alias. presetUno is the old name for presetWind3; switch to a current base (presetWind4 recommended, or presetWind3) so the semantic shortcuts have utilities to expand into. You still bring your own icons, fonts, and @unocss/reset — the preset bundles none.
• Thread the scheme, not state. The package owns no dark/toast state: pass :color-scheme (or call provideColorScheme() once at the root) and move imperative toast singletons onto a useToast() queue.

Then follow the redesign protocol in the skill (advanced-patterns): map raw colors → tokens, swap raw elements for primitives one family at a time, and run the contrast scan in light + dark after each step.

Embedding in a shadow root

Mounting the components inside a shadow root — a web component, a devtools dock, an injected overlay — is supported, but two things do not cross the boundary on their own:

• The scheme class goes on an ancestor, never on the element you style. The dark variant compiles to a descendant selector (.dark .bg-base), so a node that is .dark doesn't match its own dark rules — the subtree renders light-themed inside a dark host. Toggle dark/light (and color-scheme) on a wrapper — display: contents works, so it costs no layout — and put the surface utilities on its child. :host(.dark) is not an alternative: these are descendant selectors, and they can't reach across the boundary.
• Global CSS can't pierce the boundary — inline the styles. @antfu/design/styles/* (scrollbar, reka-ui animations, vue-afloat, …) must be part of the sheet you inject into the root, alongside the UnoCSS output. They're written with * / unscoped selectors precisely so they work in either place. Add scrollbar-gutter: stable on your own scroll container if you want the gutter reserved.

Portaled content needs no setup. Every component that teleports — the dialogs (OverlayModal, OverlayDrawer, OverlayConfirm), the poppers (FormSelect, FormCombobox, OverlayDropdown, OverlayHoverCard, OverlayContextMenu, LayoutMenubar) and FeedbackToasts — detects the enclosing shadow root and teleports into a container appended to it, which also mirrors the dark/light class of the nearest scheme wrapper so dark-mode tokens keep resolving there. Pass an explicit to (a selector or element) to override the target. The Utilities/ShadowRoot story mounts them all inside a shadow root.

Accessibility

A color-contrast scan (axe-core + Playwright) runs a URL in light and dark mode. Use it programmatically:

import { formatContrastReport, runContrastScan } from '@antfu/design/a11y'

const result = await runContrastScan({ url: 'http://localhost:6006/iframe.html' })
console.log(formatContrastReport(result))

…or run the bundled script with tsx:

tsx node_modules/@antfu/design/a11y/cli.ts http://localhost:6006/iframe.html

Components

Action

Display

Form

Overlay

Layout

Feedback

Full catalog with import paths: core-components.md.

Tokens

Semantic & composite shortcuts

Severity scale

Type sizes

Dynamic

License

MIT © Anthony Fu