@antfu/design 0.1.0 → 0.2.0

package/README.md

@@ -16,6 +16,7 @@ pnpm add @antfu/design unocss vue
 ```ts
 // 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({
@@ -25,10 +26,29 @@ export default defineConfig({
     presetIcons(),
     presetWebFonts({ fonts: { sans: 'DM Sans', mono: 'DM Mono' } }),
   ],
-  content: { pipeline: { include: [/@antfu\/design/] } },
+  // Required — the shipped styles recolor overlays with token `--at-apply`
+  // directives; this transformer expands them (and lets you reuse tokens in CSS).
+  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`](https://unocss.dev/integrations/eslint)
+> 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.
+
 ```ts
 // Components are imported by full path (no barrel) — categorized and prefixed:
 import ActionButton from '@antfu/design/components/Action/ActionButton.vue'
@@ -38,12 +58,17 @@ import '@antfu/design/styles.css'
 ```
 
 The package ships **raw `.ts` / `.vue` source** (no bundling) — your build
-compiles it. Point UnoCSS at the package so the components' classes are
-generated (`content: { pipeline: { include: [/@antfu\/design/] } }`).
+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.
+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
 
@@ -114,10 +139,18 @@ tsx node_modules/@antfu/design/a11y/cli.ts http://localhost:6006/iframe.html
 | `btn-action-active` | `color-active border-active! bg-active op100!` |
 | `btn-icon` | `w-9 h-9 rounded-full op-fade hover:op100 hover:bg-active transition flex items-center justify-center disabled:pointer-events-none disabled:op30 outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40` |
 | `btn-icon-compact` | `w-6 h-6 rounded op-fade hover:op100 hover:bg-active transition flex items-center justify-center disabled:pointer-events-none disabled:op30 outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40` |
+| `btn-icon-square` | `w-9 h-9 rounded border border-base op-fade hover:op100 hover:bg-active transition flex items-center justify-center disabled:pointer-events-none disabled:op30 outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40` |
 | `btn-primary` | `px3 py1.5 rounded flex gap-2 items-center bg-primary-500 hover:bg-primary-600 text-white transition disabled:op50 disabled:pointer-events-none outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40` |
 | `badge` | `inline-flex items-center gap-1 px-1.5 py-0.5 rounded-md text-xs font-medium leading-none` |
 | `badge-active` | `badge bg-active color-active` |
 | `badge-muted` | `badge bg-#8881 color-muted` |
+| `pad-safe-t` | `pt-[env(safe-area-inset-top)]` |
+| `pad-safe-r` | `pr-[env(safe-area-inset-right)]` |
+| `pad-safe-b` | `pb-[env(safe-area-inset-bottom)]` |
+| `pad-safe-l` | `pl-[env(safe-area-inset-left)]` |
+| `pad-safe-x` | `pad-safe-l pad-safe-r` |
+| `pad-safe-y` | `pad-safe-t pad-safe-b` |
+| `pad-safe` | `pad-safe-x pad-safe-y` |
 
 ### Severity scale
 
@@ -137,19 +170,6 @@ tsx node_modules/@antfu/design/a11y/cli.ts http://localhost:6006/iframe.html
 | `text-mini` | `text-[11px] leading-[1.45]` |
 | `text-compact` | `text-[12px] leading-[1.5]` |
 
-### Named z-index layers
-
-| Token | Expands to |
-|---|---|
-| `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]` |
-
 ### Dynamic
 
 | Token | Expands to |

package/a11y/cli.ts

@@ -27,13 +27,15 @@ function parseArgs(argv: string[]): { options: ContrastScanOptions, help: boolea
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
+    if (arg == null)
+      continue
     if (arg === '-h' || arg === '--help')
       help = true
-    else if (arg === '--mode')
+    else if (arg === '--mode' && argv[i + 1] != null)
       modes.push(argv[++i] as ColorMode)
-    else if (arg === '--exclude')
-      exclude.push(argv[++i])
-    else if (arg === '--key')
+    else if (arg === '--exclude' && argv[i + 1] != null)
+      exclude.push(argv[++i]!)
+    else if (arg === '--key' && argv[i + 1] != null)
       colorSchemeStorageKey = argv[++i]
     else if (arg === '--headed')
       headless = false

package/composables/colorScheme.ts

@@ -2,7 +2,7 @@
  * Opt-in color-scheme context.
  *
  * The package is stateless: most components flip light/dark automatically from
- * the `html.dark` class + `--af-*` tokens, and the handful that compute colors in
+ * the `html.dark` class + the token shortcuts, and the handful that compute colors in
  * JS (badges/labels/proportion bars) take a `colorScheme` prop. Threading that
  * prop everywhere is tedious, so this provides an *opt-in* context: call
  * {@link provideColorScheme} once near the app root (feeding it your own

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@antfu/design",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A customizable, composable design system for devtools-style Vue apps — a UnoCSS preset, Vue primitives, a design skill, and an a11y contrast check",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -46,7 +46,11 @@
   ],
   "peerDependencies": {
     "@axe-core/playwright": "^4.0.0",
+    "@tanstack/vue-virtual": "^3.0.0",
+    "floating-vue": "^5.0.0",
     "playwright": "^1.0.0",
+    "reka-ui": "^2.0.0",
+    "splitpanes": "^4.0.0",
     "unocss": ">=66.0.0",
     "vue": "^3.5.0"
   },
@@ -54,34 +58,48 @@
     "@axe-core/playwright": {
       "optional": true
     },
+    "@tanstack/vue-virtual": {
+      "optional": true
+    },
+    "floating-vue": {
+      "optional": true
+    },
     "playwright": {
       "optional": true
+    },
+    "reka-ui": {
+      "optional": true
+    },
+    "splitpanes": {
+      "optional": true
     }
   },
   "dependencies": {
     "@antfu/utils": "^9.3.0",
     "@iconify-json/catppuccin": "^1.2.17",
-    "@tanstack/vue-virtual": "^3.13.29",
-    "@unocss/core": "^66.7.2",
+    "@unocss/core": ">=66.0.0",
     "@vueuse/core": "^14.3.0",
-    "colorjs.io": "^0.6.1",
-    "floating-vue": "^5.2.2",
-    "reka-ui": "^2.10.0",
-    "splitpanes": "^4.1.2"
+    "colorjs.io": "^0.6.1"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@axe-core/playwright": "^4.12.1",
     "@storybook/vue3-vite": "^10.4.6",
+    "@tanstack/vue-virtual": "^3.13.29",
     "@unocss/preset-icons": "^66.7.2",
     "@unocss/preset-mini": "^66.7.2",
     "@unocss/preset-web-fonts": "^66.7.2",
     "@unocss/preset-wind3": "^66.7.2",
     "@unocss/preset-wind4": "^66.7.2",
+    "@unocss/transformer-directives": "^66.7.2",
     "@vitejs/plugin-vue": "^6.0.7",
     "@vue/test-utils": "^2.4.11",
+    "floating-vue": "^5.2.2",
     "happy-dom": "^20.10.6",
+    "magic-string": "^0.30.21",
     "playwright": "^1.61.1",
+    "reka-ui": "^2.10.0",
+    "splitpanes": "^4.1.2",
     "tsdown": "^0.22.0",
     "tsdown-stale-guard": "^0.1.2",
     "tsnapi": "^0.3.3",

package/skills/antfu-design/references/core-setup.md

@@ -12,6 +12,7 @@ pnpm add @antfu/design unocss
 ```ts
 // 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({
@@ -19,13 +20,19 @@ export default defineConfig({
     presetAnthonyDesign({
       primary: '#49833E', // string | full color-scale object (default antfu green)
       darkBackground: '#111', // near-black for dark surfaces
+      // overrides: { 'bg-base': 'bg-zinc-50 dark:bg-zinc-950' }, // retune any built-in shortcut
     }),
     presetWind4(), // a base preset is REQUIRED — shortcuts expand into its utilities
     presetIcons(),
     presetWebFonts({ fonts: { sans: 'DM Sans', mono: 'DM Mono' } }),
   ],
-  // Generate the components' classes by scanning the installed package:
-  content: { pipeline: { include: [/@antfu\/design/] } },
+  // REQUIRED: the shipped `@antfu/design/styles` recolor third-party overlays with
+  // token `--at-apply` directives — this transformer is what expands them.
+  transformers: [transformerDirectives()],
+  // No `content.pipeline.include` needed: UnoCSS's default scan matches `.vue`/`.tsx`
+  // by extension (its only default exclude is CSS, not `node_modules`), so imported
+  // components are picked up. If you DO set `include`, it REPLACES the default scan —
+  // restate your own sources or they stop generating.
 })
 ```
 
@@ -33,6 +40,64 @@ export default defineConfig({
 > `presetMini`). Without one, the semantic shortcuts have nothing to expand into.
 > The design layer is **one preset** — there are no sub-presets to compose.
 
+> **`@unocss/transformer-directives` is required**, not optional: the design
+> system's own CSS (`base.css`, `floating-vue.css`, `splitpanes.css`) styles
+> surfaces with token directives like `--at-apply: 'bg-base color-base'` instead of
+> hand-duplicated hex values. Without the transformer those rules are dropped and
+> overlays/surfaces lose their theming. It also lets *you* reuse the tokens in your
+> own CSS (`.panel { --at-apply: 'bg-base border border-base'; }`).
+
+## Recommended: the UnoCSS ESLint plugin
+
+Add [`@unocss/eslint-plugin`](https://unocss.dev/integrations/eslint) so the
+guardrails surface as you type instead of silently dropping at build time. It's
+where the blocklist's messages show up — e.g. a plain `z-50` is flagged with the
+"use a named layer" hint — and it keeps class order/duplication tidy. This
+feedback loop is the intended way to work with the design system.
+
+```js
+// eslint.config.js
+import unocss from '@unocss/eslint-plugin'
+
+export default [
+  unocss(),
+]
+```
+
+## z-index layers (you own them)
+
+Stacking is a whole-app concern, so the preset ships **no** z-index scale and
+**blocks plain `z-<number>` / `z-[…]` utilities** (`z-auto` stays allowed) — every
+z-index must flow through a *named* layer you define in your own UnoCSS
+`shortcuts`. The overlay components reference these names; without them, overlays
+have no stacking value. Define them once, alongside the preset, and tune the
+numbers to fit your app:
+
+```ts
+// uno.config.ts (top-level — NOT inside the preset)
+export default defineConfig({
+  presets: [presetAnthonyDesign(), presetWind4()],
+  transformers: [transformerDirectives()],
+  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]',
+  },
+})
+```
+
+These are *reference* values — the only contract is the **ordering** (`z-nav` <
+`z-dropdown` < `z-tooltip` < `z-toast` < `z-modal-backdrop` < `z-modal-content` <
+`z-drawer-backdrop` < `z-drawer-content`) so a modal sits over a dropdown, a drawer
+over a modal. The block lifts each utility *defined in `shortcuts`* — only plain
+z-index written in markup is rejected. Disable the guardrail with
+`presetAnthonyDesign({ blocklists: { plainZIndex: false } })`.
+
 ## Styles
 
 ```ts

package/skills/antfu-design/references/core-tokens.md

@@ -34,10 +34,18 @@ never drift from what the shortcuts actually resolve to.
 | `btn-action-active` | `color-active border-active! bg-active op100!` |
 | `btn-icon` | `w-9 h-9 rounded-full op-fade hover:op100 hover:bg-active transition flex items-center justify-center disabled:pointer-events-none disabled:op30 outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40` |
 | `btn-icon-compact` | `w-6 h-6 rounded op-fade hover:op100 hover:bg-active transition flex items-center justify-center disabled:pointer-events-none disabled:op30 outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40` |
+| `btn-icon-square` | `w-9 h-9 rounded border border-base op-fade hover:op100 hover:bg-active transition flex items-center justify-center disabled:pointer-events-none disabled:op30 outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40` |
 | `btn-primary` | `px3 py1.5 rounded flex gap-2 items-center bg-primary-500 hover:bg-primary-600 text-white transition disabled:op50 disabled:pointer-events-none outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40` |
 | `badge` | `inline-flex items-center gap-1 px-1.5 py-0.5 rounded-md text-xs font-medium leading-none` |
 | `badge-active` | `badge bg-active color-active` |
 | `badge-muted` | `badge bg-#8881 color-muted` |
+| `pad-safe-t` | `pt-[env(safe-area-inset-top)]` |
+| `pad-safe-r` | `pr-[env(safe-area-inset-right)]` |
+| `pad-safe-b` | `pb-[env(safe-area-inset-bottom)]` |
+| `pad-safe-l` | `pl-[env(safe-area-inset-left)]` |
+| `pad-safe-x` | `pad-safe-l pad-safe-r` |
+| `pad-safe-y` | `pad-safe-t pad-safe-b` |
+| `pad-safe` | `pad-safe-x pad-safe-y` |
 
 ### Severity scale
 
@@ -57,19 +65,6 @@ never drift from what the shortcuts actually resolve to.
 | `text-mini` | `text-[11px] leading-[1.45]` |
 | `text-compact` | `text-[12px] leading-[1.5]` |
 
-### Named z-index layers
-
-| Token | Expands to |
-|---|---|
-| `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]` |
-
 ### Dynamic
 
 | Token | Expands to |
@@ -92,9 +87,10 @@ never drift from what the shortcuts actually resolve to.
 - **Severity** `color-scale-{neutral,low,medium,high,critical}` is the one ramp
   for fresh→stale / fast→slow / small→large. Prefer the `colorize` prop on display
   components over using these directly.
-- **Named z-index layers** (`z-nav` < `z-dropdown` < `z-tooltip` < `z-toast` <
-  `z-modal-backdrop` < `z-modal-content` < `z-drawer-backdrop` < `z-drawer-content`)
-  — never raw `z-<n>`.
+- **z-index**: always a named layer (`z-nav`, `z-dropdown`, `z-modal-content`, …),
+  never plain `z-<n>` — the preset blocks plain z-index. The preset ships **no**
+  values; the app defines the named layers in its own `shortcuts`. See
+  [core-setup.md](core-setup.md#z-index-layers-you-own-them).
 - **Theme**: `font-sans` = DM Sans, `font-mono` = DM Mono; extra sizes
   `text-micro` / `text-mini` / `text-compact`; color ramps `primary` (default
   antfu green), `warning`, `success`, `error`.

package/styles/base.css

@@ -1,31 +1,19 @@
 /**
- * Root surface + a small set of CSS custom properties mirroring the token
- * defaults. The overlay-engine override files reference these vars, so they
- * recolor with light/dark automatically and work on plain `import` (without
- * needing UnoCSS to process them).
+ * Root surface + text, applied straight from the design tokens. The `--at-apply`
+ * directives below (and in the other style files) need
+ * `@unocss/transformer-directives` in the consuming app's UnoCSS config (see
+ * Setup) — that's what expands `bg-base` / `color-base` etc., so the surface
+ * follows light/dark with no duplicated set of CSS variables to maintain.
  */
 
 :root {
-  --af-bg-base: #ffffff;
-  --af-bg-secondary: #f5f5f5;
-  --af-color-base: #262626; /* neutral-800 */
-  --af-color-muted: #525252; /* neutral-600 */
-  --af-border-base: rgba(136, 136, 136, 0.13); /* ~#8882 */
-  --af-border-mute: rgba(136, 136, 136, 0.07); /* ~#8881 */
-  --af-tooltip-bg: rgba(255, 255, 255, 0.75);
   color-scheme: light;
 }
 
 html.dark {
-  --af-bg-base: #111111;
-  --af-bg-secondary: #1a1a1a;
-  --af-color-base: #e5e5e5; /* neutral-200 */
-  --af-color-muted: #a3a3a3; /* neutral-400 */
-  --af-tooltip-bg: rgba(17, 17, 17, 0.75);
   color-scheme: dark;
 }
 
 html {
-  background-color: var(--af-bg-base);
-  color: var(--af-color-base);
+  --at-apply: 'bg-base color-base';
 }

package/styles/floating-vue.css

@@ -1,28 +1,25 @@
 /**
- * Recolor floating-vue tooltips/dropdowns to the design tokens. Driven by the
- * `--af-*` custom properties from `base.css` so they follow light/dark.
+ * Recolor floating-vue tooltips/dropdowns to the design tokens via
+ * `@unocss/transformer-directives` (see Setup): `bg-tooltip` carries the
+ * translucent surface + backdrop blur, and `color-base` / `border-base` follow
+ * light/dark automatically.
  */
 
 .v-popper__popper .v-popper__inner {
-  background: var(--af-tooltip-bg);
-  color: var(--af-color-base);
-  border: 1px solid var(--af-border-base);
-  border-radius: 6px;
+  --at-apply: 'bg-tooltip color-base border border-base rounded-md text-xs px-2 py-1';
   box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
-  backdrop-filter: blur(8px);
-  padding: 4px 8px;
-  font-size: 12px;
 }
 
 .v-popper__popper .v-popper__arrow-outer {
-  border-color: var(--af-border-base);
+  --at-apply: 'border-base';
 }
 
 .v-popper__popper .v-popper__arrow-inner {
-  border-color: var(--af-tooltip-bg);
+  /* Matches the `bg-tooltip` fill so the arrow reads as part of the surface. */
+  --at-apply: 'border-white/75 dark:border-[#111]/75';
   visibility: visible;
 }
 
 .v-popper--theme-dropdown .v-popper__inner {
-  padding: 4px;
+  --at-apply: 'p-1';
 }

package/styles/splitpanes.css

@@ -33,15 +33,16 @@
   pointer-events: none;
 }
 
-/* Splitter — recolored to the design tokens. */
+/* Splitter — divider tinted to the neutral border token (see Setup for the
+ * `@unocss/transformer-directives` requirement). */
 .splitpanes__splitter {
   position: relative;
   touch-action: none;
-  background-color: var(--af-border-base);
+  --at-apply: 'bg-#8882';
   transition: background-color 0.2s;
 }
 .splitpanes__splitter:hover {
-  background-color: rgba(136, 136, 136, 0.4);
+  --at-apply: 'bg-#8886';
 }
 .splitpanes--vertical > .splitpanes__splitter {
   min-width: 1px;

package/unocss/blocklist.ts

@@ -0,0 +1,44 @@
+import type { BlocklistRule } from '@unocss/core'
+
+/**
+ * Granular toggle for the preset's blocklists. `true` (default) enables them all,
+ * `false` disables them all, or pass an object to flip individual entries. Kept
+ * open-ended so future guardrails slot in without another option.
+ */
+export type BlocklistsOption = boolean | {
+  /**
+   * Block plain `z-<number>` / `z-[…]` utilities so every z-index flows through a
+   * named, app-owned layer (see Setup). Default `true`.
+   */
+  plainZIndex?: boolean
+}
+
+/**
+ * Matches a plain z-index utility — `z-50`, `z-[70]`, `-z-10`, `z-[var(--x)]` —
+ * but **not** a named layer (`z-modal-content`, `z-nav`) nor the `z-auto` reset.
+ *
+ * The named layers are shortcuts the app defines in its own UnoCSS `shortcuts`
+ * config; their expansion to `z-[70]` happens *inside* the shortcut, which the
+ * blocklist never re-checks. So the layers keep resolving while a plain z-index
+ * written in markup fails to generate — pushing authors to semantic layers.
+ */
+export const RE_PLAIN_Z_INDEX = /^-?z-(?:\d+|\[[^\]]+\])$/
+
+/** Blocklist entry banning plain z-index utilities (see {@link RE_PLAIN_Z_INDEX}). */
+export const plainZIndexBlocklist: BlocklistRule = [
+  RE_PLAIN_Z_INDEX,
+  {
+    message: (selector: string) =>
+      `[@antfu/design] "${selector}" — plain z-index is blocked. Define a named layer in your UnoCSS \`shortcuts\` (e.g. z-modal-content: 'z-[70]') and use that, or pass \`blocklists: { plainZIndex: false }\` to opt out.`,
+  },
+]
+
+/** Resolve the preset's `blocklist` array from the `blocklists` option (default all on). */
+export function buildBlocklist(option: BlocklistsOption = true): BlocklistRule[] {
+  if (option === false)
+    return []
+  const plainZIndex = option === true ? true : option.plainZIndex !== false
+  return [
+    ...(plainZIndex ? [plainZIndexBlocklist] : []),
+  ]
+}

package/unocss/colors.ts

@@ -76,9 +76,20 @@ export const error: ColorRamp = {
   DEFAULT: '#f63d68',
 }
 
-const RAMP_STOPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const
-/** Target OKLCH lightness (0–1) per stop. */
-const RAMP_LIGHTNESS = [0.97, 0.94, 0.87, 0.78, 0.68, 0.58, 0.50, 0.42, 0.35, 0.28, 0.18] as const
+/** Each stop paired with its target OKLCH lightness (0–1). */
+const RAMP_STEPS = [
+  [50, 0.97],
+  [100, 0.94],
+  [200, 0.87],
+  [300, 0.78],
+  [400, 0.68],
+  [500, 0.58],
+  [600, 0.50],
+  [700, 0.42],
+  [800, 0.35],
+  [900, 0.28],
+  [950, 0.18],
+] as const
 
 /**
  * Generate an 11-stop color ramp (`50`..`950` + `DEFAULT`) from a single color,
@@ -97,8 +108,7 @@ export function generateColorRamp(input: string): ColorRamp {
   const [, chroma, rawHue] = new Color(input).to('oklch').coords
   const hue = Number.isFinite(rawHue) ? rawHue : 0
   const ramp: ColorRamp = { DEFAULT: input }
-  RAMP_STOPS.forEach((stop, i) => {
-    const l = RAMP_LIGHTNESS[i]
+  RAMP_STEPS.forEach(([stop, l]) => {
     // Taper chroma at the lightest/darkest stops so they don't look muddy.
     const c = (chroma || 0) * (l > 0.9 || l < 0.25 ? 0.6 : 1)
     ramp[stop] = new Color('oklch', [l, c, hue]).to('srgb').toGamut({ space: 'srgb' }).toString({ format: 'hex' })

package/unocss/index.ts

@@ -1,6 +1,7 @@
 import type { Preset, UserShortcuts } from '@unocss/core'
 import type { PresetAnthonyDesignOptions } from './options'
 import { definePreset, mergeDeep } from '@unocss/core'
+import { buildBlocklist } from './blocklist'
 import { error, resolvePrimary, success, warning } from './colors'
 import { DEFAULT_DARK_BG, DEFAULT_FONTS } from './options'
 import { patternRules } from './patterns'
@@ -26,12 +27,19 @@ function assertOptions(options: PresetAnthonyDesignOptions): void {
  * consumer composes those themselves. The semantic layer is base-agnostic, so it
  * resolves under Wind4, Wind3 or Mini.
  *
+ * It deliberately ships **no z-index scale** — stacking is a whole-app concern.
+ * The overlay components reference named layers (`z-modal-content`, `z-dropdown`,
+ * …); define those in your own UnoCSS `shortcuts` config (see Setup). As a
+ * guardrail the preset blocks plain `z-<number>` utilities so every z-index goes
+ * through a named layer (opt out with `blocklists: { plainZIndex: false }`).
+ *
  * @param options - Theme + dark-surface options (see {@link PresetAnthonyDesignOptions}).
  * @returns A single UnoCSS `Preset`.
  *
  * @example
  * ```ts
  * import { presetAnthonyDesign } from '@antfu/design/unocss'
+ * import transformerDirectives from '@unocss/transformer-directives'
  * import { defineConfig, presetIcons, presetWebFonts, presetWind4 } from 'unocss'
  *
  * export default defineConfig({
@@ -41,6 +49,8 @@ function assertOptions(options: PresetAnthonyDesignOptions): void {
  *     presetIcons(),
  *     presetWebFonts({ fonts: { sans: 'DM Sans', mono: 'DM Mono' } }),
  *   ],
+ *   // Required — expands the token `--at-apply` directives in the shipped styles.
+ *   transformers: [transformerDirectives()],
  * })
  * ```
  */
@@ -71,6 +81,8 @@ export const presetAnthonyDesign = definePreset((options: PresetAnthonyDesignOpt
     ...buildRules(darkBackground),
     ...severityShortcuts,
     ...extend,
+    // Appended last so a same-named entry wins over everything above it.
+    ...(options.overrides ? [options.overrides] : []),
   ]
 
   return {
@@ -78,11 +90,20 @@ export const presetAnthonyDesign = definePreset((options: PresetAnthonyDesignOpt
     extendTheme: theme => mergeDeep(theme as any, themeOverrides as any),
     shortcuts,
     rules: patternRules,
+    // Best-practice guardrails (default all on); see the `blocklists` option.
+    blocklist: buildBlocklist(options.blocklists),
   }
 })
 
 export default presetAnthonyDesign
 
+export {
+  type BlocklistsOption,
+  buildBlocklist,
+  plainZIndexBlocklist,
+  RE_PLAIN_Z_INDEX,
+} from './blocklist'
+
 export {
   type ColorRamp,
   error as errorRamp,

package/unocss/options.ts

@@ -1,4 +1,5 @@
 import type { UserShortcuts } from '@unocss/core'
+import type { BlocklistsOption } from './blocklist'
 import type { ColorRamp } from './colors'
 
 /** Default near-black used for dark surfaces. Overridable via `darkBackground`. */
@@ -28,4 +29,19 @@ export interface PresetAnthonyDesignOptions {
   theme?: Record<string, any>
   /** Extra shortcuts appended after the built-in layer (so they can override it). */
   extendShortcuts?: UserShortcuts
+  /**
+   * Override built-in shortcuts by name. Merged in with the **highest** precedence
+   * (after the built-in layer and `extendShortcuts`), so e.g.
+   * `{ 'bg-base': 'bg-zinc-50 dark:bg-zinc-950' }` redefines what `bg-base` resolves
+   * to. Use this to retune the semantic vocabulary; use `extendShortcuts` to add new
+   * ones.
+   */
+  overrides?: Record<string, string>
+  /**
+   * Best-practice guardrails. Defaults to `true` (all on). Currently the only
+   * entry is `plainZIndex`, which blocks plain `z-<number>` / `z-[…]` utilities so
+   * every z-index goes through a named layer the app defines (see Setup). Pass
+   * `false` to disable all, or `{ plainZIndex: false }` to opt out of one.
+   */
+  blocklists?: BlocklistsOption
 }

package/unocss/shortcuts.ts

@@ -42,6 +42,9 @@ export function buildShortcuts(db: string): (StaticShortcutMap | DynamicShortcut
       'btn-action-active': 'color-active border-active! bg-active op100!',
       'btn-icon': 'w-9 h-9 rounded-full op-fade hover:op100 hover:bg-active transition flex items-center justify-center disabled:pointer-events-none disabled:op30 outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40',
       'btn-icon-compact': 'w-6 h-6 rounded op-fade hover:op100 hover:bg-active transition flex items-center justify-center disabled:pointer-events-none disabled:op30 outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40',
+      // Bordered, square counterpart to the round/borderless `btn-icon` — for
+      // toolbar-style icon buttons that read as a distinct affordance.
+      'btn-icon-square': 'w-9 h-9 rounded border border-base op-fade hover:op100 hover:bg-active transition flex items-center justify-center disabled:pointer-events-none disabled:op30 outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40',
       'btn-primary': 'px3 py1.5 rounded flex gap-2 items-center bg-primary-500 hover:bg-primary-600 text-white transition disabled:op50 disabled:pointer-events-none outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40',
 
       // ── Badges ────────────────────────────────────────────────────────
@@ -54,15 +57,20 @@ export function buildShortcuts(db: string): (StaticShortcutMap | DynamicShortcut
       'text-mini': 'text-[11px] leading-[1.45]',
       'text-compact': 'text-[12px] leading-[1.5]',
 
-      // ── Named z-index layers (ascending) ──────────────────────────────
-      '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]',
+      // ── Safe-area padding (notches / home indicators) ─────────────────
+      'pad-safe-t': 'pt-[env(safe-area-inset-top)]',
+      'pad-safe-r': 'pr-[env(safe-area-inset-right)]',
+      'pad-safe-b': 'pb-[env(safe-area-inset-bottom)]',
+      'pad-safe-l': 'pl-[env(safe-area-inset-left)]',
+      'pad-safe-x': 'pad-safe-l pad-safe-r',
+      'pad-safe-y': 'pad-safe-t pad-safe-b',
+      'pad-safe': 'pad-safe-x pad-safe-y',
+
+      // NOTE: the preset deliberately ships **no** z-index scale. Stacking is a
+      // whole-app concern, so the layer values are the app's to own — it defines
+      // the named layers (`z-modal-content`, `z-dropdown`, …) that the overlay
+      // components reference in its own top-level UnoCSS `shortcuts`. The preset
+      // blocks plain `z-<number>` to keep usage semantic (see `./blocklist`).
     },
   ]
 }

package/utils/color.ts

@@ -243,8 +243,9 @@ export function getPluginColor(
   const hues = map === defaultBrandHues ? defaultBrandHues : { ...defaultBrandHues, ...map }
   const bare = stripPluginPrefix(name).toLowerCase()
   const key = Object.keys(hues).find(k => bare === k || bare.startsWith(`${k}-`) || bare.startsWith(`${k}.`))
-  if (key != null)
-    return getHsla(hues[key], opacity, dark)
+  const hue = key != null ? hues[key] : undefined
+  if (hue != null)
+    return getHsla(hue, opacity, dark)
   return getHashColorFromString(name, opacity, dark)
 }
 

package/utils/format.ts

@@ -47,7 +47,7 @@ export function mapSeverity(value: number, scale: SeverityScale): ColorScaleClas
     if (value <= max)
       return cls
   }
-  return scale[scale.length - 1][1]
+  return scale.at(-1)?.[1] ?? colorScale.neutral
 }
 
 // ── Locale ──────────────────────────────────────────────────────────────────
@@ -159,7 +159,7 @@ export function formatBytes(bytes: number, options: FormatBytesOptions = {}): [s
   if (i === 0)
     return [String(bytes), 'B']
   const value = (bytes / base ** i).toFixed(digits).replace(/\.?0+$/, '')
-  return [value, units[i]]
+  return [value, units[i] ?? 'B']
 }
 
 /**

package/utils/keybinding.ts

@@ -78,8 +78,9 @@ export function parseChord(input: string): ParsedChord {
   let key = ''
   for (const token of tokens) {
     const lower = token.toLowerCase()
-    if (lower in MOD_ALIASES)
-      modifiers.add(MOD_ALIASES[lower])
+    const mod = MOD_ALIASES[lower]
+    if (mod != null)
+      modifiers.add(mod)
     else
       key = KEY_ALIASES[lower] ?? (token.length === 1 ? token.toLowerCase() : token)
   }
@@ -177,7 +178,7 @@ const KEY_GLYPHS: Record<string, string> = {
  * // → ['⌃', 'K'] on macOS, ['Ctrl', 'K'] elsewhere
  */
 export function chordDisplay(chord: ParsedChord): string[] {
-  const mods = chord.modifiers.map(m => isMac ? GLYPHS_MAC[m] : LABELS[m])
+  const mods = chord.modifiers.map(m => (isMac ? GLYPHS_MAC[m] : LABELS[m]) ?? m)
   const key = KEY_GLYPHS[chord.key] ?? (chord.key.length === 1 ? chord.key.toUpperCase() : chord.key)
   return [...mods, key]
 }

package/utils/path.ts

@@ -77,7 +77,7 @@ export interface PnpmPackageInfo {
  */
 export function parsePnpmSegment(segment: string): PnpmPackageInfo | undefined {
   // Strip peer-dependency suffix (`_react@18...`).
-  const base = segment.split('_')[0]
+  const base = segment.split('_')[0] ?? ''
   const at = base.lastIndexOf('@')
   if (at <= 0)
     return undefined
@@ -109,7 +109,7 @@ export function parsePnpmSegment(segment: string): PnpmPackageInfo | undefined {
  */
 export function getPnpmPackageInfoFromPath(path: string): PnpmPackageInfo | undefined {
   const match = normalizeModulePath(path).match(/\.pnpm\/([^/]+)/)
-  if (!match)
+  if (match?.[1] == null)
     return undefined
   return parsePnpmSegment(match[1])
 }
@@ -138,8 +138,10 @@ export function getModuleNameFromPath(path: string): string | undefined {
   if (idx === -1)
     return undefined
   const rest = normalized.slice(idx + 'node_modules/'.length)
-  const segments = rest.split('/')
-  return segments[0].startsWith('@') ? `${segments[0]}/${segments[1]}` : segments[0]
+  const [first, second] = rest.split('/')
+  if (first == null)
+    return undefined
+  return first.startsWith('@') && second != null ? `${first}/${second}` : first
 }
 
 /**

package/utils/semver.ts

@@ -47,9 +47,10 @@ export function compareSemver(a: string, b: string): number {
   const pb = parseVersion(b)
   if (!pa || !pb)
     return 0
-  for (let i = 0; i < 3; i++) {
-    if (pa[i] !== pb[i])
-      return pa[i] < pb[i] ? -1 : 1
+  const core = [[pa[0], pb[0]], [pa[1], pb[1]], [pa[2], pb[2]]] as const
+  for (const [x, y] of core) {
+    if (x !== y)
+      return x < y ? -1 : 1
   }
   // Equal core: a version without prerelease is greater than one with.
   if (pa[3] === pb[3])

package/utils/tree.ts

@@ -24,6 +24,8 @@ export interface ToTreeOptions {
 function flattenChain<T>(node: TreeNode<T>, separator: string): void {
   while (node.children.length === 1 && node.item == null) {
     const child = node.children[0]
+    if (child == null)
+      break
     node.name = `${node.name}${separator}${child.name}`
     node.path = child.path
     node.item = child.item