@antfu/design 0.1.0

package/unocss/shortcuts.ts

@@ -0,0 +1,68 @@
+import type { DynamicShortcut, StaticShortcutMap } from '@unocss/core'
+
+/**
+ * Build the semantic shortcut map. Written **base-agnostic** (uses only
+ * `/opacity` modifiers + hex-with-alpha, never colon-opacity) so it resolves
+ * identically under Wind4, Wind3 and Mini — the `shared-shortcuts.ts` from
+ * `@vitejs/devtools-ui` is the proven template this generalizes.
+ *
+ * `db` is the configurable near-black for dark surfaces.
+ */
+export function buildShortcuts(db: string): (StaticShortcutMap | DynamicShortcut)[] {
+  return [
+    {
+      // ── Text ──────────────────────────────────────────────────────────
+      'color-base': 'color-neutral-800 dark:color-neutral-200',
+      'color-muted': 'color-neutral-600 dark:color-neutral-400',
+      'color-faint': 'color-neutral-500 dark:color-neutral-500',
+      'color-active': 'color-primary-600 dark:color-primary-300',
+
+      // ── Surfaces ──────────────────────────────────────────────────────
+      'bg-base': `bg-white dark:bg-${db}`,
+      'bg-secondary': 'bg-#f5f5f5 dark:bg-#1a1a1a',
+      'bg-active': 'bg-#8881',
+      'bg-hover': 'bg-primary/5',
+      'bg-code': 'bg-gray-500/5',
+      'bg-tooltip': `bg-white/75 dark:bg-${db}/75 backdrop-blur-8`,
+      'bg-gradient-more': `bg-gradient-to-t from-white via-white/80 to-white/0 dark:from-${db} dark:via-${db}/80 dark:to-${db}/0`,
+
+      // ── Borders / rings ───────────────────────────────────────────────
+      'border-base': 'border-#8882',
+      'border-mute': 'border-#8881',
+      'border-active': 'border-primary-600/25 dark:border-primary-400/25',
+      'ring-base': 'ring-#8882',
+
+      // ── Opacity ───────────────────────────────────────────────────────
+      'op-fade': 'op65 dark:op55',
+      'op-mute': 'op30 dark:op25',
+
+      // ── Buttons ───────────────────────────────────────────────────────
+      'btn-action': 'border border-base rounded flex gap-2 items-center px2 py1 op75 hover:op100 hover:bg-active transition disabled:pointer-events-none disabled:op30! outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40',
+      'btn-action-sm': 'btn-action text-sm',
+      '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-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 ────────────────────────────────────────────────────────
+      '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',
+
+      // ── Type sizes (base-agnostic) ────────────────────────────────────
+      'text-micro': 'text-[10px] leading-[1.4]',
+      '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]',
+    },
+  ]
+}

package/utils/color.ts

@@ -0,0 +1,328 @@
+/**
+ * Deterministic string → HSL color utilities.
+ *
+ * Hue-based so the same string always maps to the same hue, with saturation /
+ * lightness chosen to "adapt better contrast in light/dark mode" (the note from
+ * config-inspector's color composable). Pure and framework-agnostic — the
+ * dark-mode flag is an explicit argument so these stay unit-testable without a
+ * DOM. Vue callers pass the scheme flag (e.g. `colorScheme === 'dark'`).
+ *
+ * Color-space manipulation (the OKLCH `labelStyle`) is delegated to colorjs.io.
+ */
+import Color from 'colorjs.io'
+
+/**
+ * Build an `hsla()` string for a given hue, dark-aware.
+ *
+ * Saturation and lightness are chosen per scheme (65%/40% in light mode, 50%/60%
+ * in dark) so the resulting color keeps reasonable contrast against the page.
+ *
+ * @param hue - The hue in degrees (0–360).
+ * @param opacity - The alpha channel, a number or CSS string. Defaults to `1`.
+ * @param dark - Whether to use the dark-mode saturation/lightness. Defaults to `false`.
+ * @returns An `hsla(...)` CSS color string.
+ *
+ * @example
+ * getHsla(180) // → 'hsla(180, 65%, 40%, 1)'
+ * getHsla(180, 0.5) // → 'hsla(180, 65%, 40%, 0.5)'
+ * getHsla(180, 1, true) // → 'hsla(180, 50%, 60%, 1)'
+ */
+export function getHsla(
+  hue: number,
+  opacity: number | string = 1,
+  dark = false,
+): string {
+  const saturation = dark ? 50 : 65
+  const lightness = dark ? 60 : 40
+  return `hsla(${hue}, ${saturation}%, ${lightness}%, ${opacity})`
+}
+
+/**
+ * Map an arbitrary string to a stable hue and return an `hsla()` color.
+ *
+ * Uses a deterministic string hash folded into the 0–360 hue range, so the same
+ * input always yields the same color across runs and machines.
+ *
+ * @param name - The string to derive a hue from.
+ * @param opacity - The alpha channel, a number or CSS string. Defaults to `1`.
+ * @param dark - Whether to use the dark-mode saturation/lightness. Defaults to `false`.
+ * @returns A deterministic `hsla(...)` CSS color string for the input.
+ *
+ * @example
+ * getHashColorFromString('Vite') === getHashColorFromString('Vite') // → true (deterministic)
+ * getHashColorFromString('Vite') !== getHashColorFromString('DevTools') // → true
+ */
+export function getHashColorFromString(
+  name: string,
+  opacity: number | string = 1,
+  dark = false,
+): string {
+  let hash = 0
+  for (let i = 0; i < name.length; i++)
+    hash = name.charCodeAt(i) + ((hash << 5) - hash)
+  const h = ((hash % 360) + 360) % 360
+  return getHsla(h, opacity, dark)
+}
+
+/**
+ * Curated brand hues (in degrees) for well-known ecosystems, so common
+ * package/plugin names get an on-brand color instead of an arbitrary hash.
+ * Overridable by callers via {@link getPluginColor}'s `map` argument.
+ *
+ * @example
+ * defaultBrandHues.vue // → 153
+ * defaultBrandHues.react // → 193
+ */
+export const defaultBrandHues: Record<string, number> = {
+  vue: 153,
+  nuxt: 153,
+  vite: 265,
+  react: 193,
+  preact: 280,
+  solid: 217,
+  svelte: 15,
+  angular: 348,
+  qwik: 265,
+  lit: 210,
+  astro: 270,
+  remix: 220,
+  next: 220,
+  node: 120,
+  deno: 160,
+  bun: 45,
+  npm: 0,
+  pnpm: 35,
+  yarn: 200,
+  ts: 211,
+  typescript: 211,
+  js: 47,
+  javascript: 47,
+  unocss: 190,
+  tailwind: 198,
+  rollup: 12,
+  rolldown: 25,
+  webpack: 200,
+  esbuild: 49,
+  vitest: 120,
+  jest: 340,
+  eslint: 265,
+  prettier: 330,
+  electron: 200,
+  tauri: 200,
+}
+
+export interface LabelStyle {
+  color: string
+  background: string
+  borderColor: string
+}
+
+const labelCache = new Map<string, LabelStyle>()
+
+function oklchToHex(l: number, c: number, h: number): string {
+  return new Color('oklch', [l, c, h]).to('srgb').toGamut({ space: 'srgb' }).toString({ format: 'hex', collapse: false })
+}
+
+/**
+ * Contrast-aware foreground / background / border for a label from a base color,
+ * dark-aware. Uses OKLCH (via colorjs.io) for perceptually even results — the
+ * chroma is clamped so arbitrary inputs never look garish — and caches by
+ * `color|scheme`. (The OKLCH lightness/chroma stops match ghfs's `labelStyle`.)
+ *
+ * @param input - The base color as any CSS color string.
+ * @param dark - Whether to produce the dark-mode variant. Defaults to `false`.
+ * @returns A {@link LabelStyle} with hex `color`, `background` and `borderColor`.
+ *
+ * @example
+ * labelStyle('#d73a4a') // → { color: '#…', background: '#…', borderColor: '#…' } (light)
+ * labelStyle('#d73a4a', true) // → the dark-mode variant
+ */
+export function labelStyle(input: string, dark = false): LabelStyle {
+  const key = `${input}|${dark ? 'd' : 'l'}`
+  const cached = labelCache.get(key)
+  if (cached)
+    return cached
+
+  const [, rawChroma, rawHue] = new Color(input).to('oklch').coords
+  const h = rawHue == null || !Number.isFinite(rawHue) ? 0 : rawHue
+  const c = Math.min(rawChroma == null || !Number.isFinite(rawChroma) ? 0 : rawChroma, 0.18)
+
+  const style: LabelStyle = dark
+    ? {
+        color: oklchToHex(0.80, c, h),
+        background: oklchToHex(0.22, c * 0.5, h),
+        borderColor: oklchToHex(0.38, c * 0.7, h),
+      }
+    : {
+        color: oklchToHex(0.42, c, h),
+        background: oklchToHex(0.94, c * 0.35, h),
+        borderColor: oklchToHex(0.82, c * 0.5, h),
+      }
+
+  labelCache.set(key, style)
+  return style
+}
+
+/**
+ * The plugin prefixes {@link stripPluginPrefix} strips by default. Includes the
+ * common build-tool plugin conventions plus the `vite:`/`rollup:`-style internal
+ * namespace prefixes used by core plugins.
+ */
+export const defaultPluginPrefixes: readonly string[] = [
+  'vite-plugin-',
+  'rollup-plugin-',
+  'webpack-plugin-',
+  'unplugin-',
+  'nuxt-',
+  'eslint-plugin-',
+  'postcss-',
+  'vite:',
+  'rollup:',
+  'rolldown:',
+  'webpack:',
+  '__',
+]
+
+function buildPrefixRe(prefixes: readonly string[]): RegExp {
+  const alt = prefixes.map(p => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')
+  return new RegExp(`^(?:@[^/]+\\/)?(?:${alt})`)
+}
+
+const DEFAULT_PREFIX_RE = buildPrefixRe(defaultPluginPrefixes)
+
+/**
+ * Strip common tool prefixes/scopes to get the meaningful part of a name.
+ *
+ * Removes a recognised plugin prefix (`vite-plugin-`, `rollup-plugin-`,
+ * `unplugin-`, `nuxt-`, `eslint-plugin-`, `postcss-`, the `vite:`/`rollup:`
+ * internal namespaces, …, optionally scoped) and any remaining leading
+ * `@scope/`. Pass a custom prefix list or `RegExp` to override the defaults.
+ *
+ * @param name - The package or plugin name to strip.
+ * @param prefixes - Custom prefix list or anchored `RegExp`. Defaults to {@link defaultPluginPrefixes}.
+ * @returns The meaningful suffix of the name.
+ *
+ * @example
+ * stripPluginPrefix('vite-plugin-inspect') // → 'inspect'
+ * stripPluginPrefix('@antfu/eslint-config') // → 'eslint-config'
+ * stripPluginPrefix('vite:import-analysis') // → 'import-analysis'
+ */
+export function stripPluginPrefix(name: string, prefixes?: readonly string[] | RegExp): string {
+  const re = prefixes == null
+    ? DEFAULT_PREFIX_RE
+    : prefixes instanceof RegExp ? prefixes : buildPrefixRe(prefixes)
+  return name.replace(re, '').replace(/^@[^/]+\//, '')
+}
+
+/**
+ * Color a package/plugin name: brand hue when recognised, deterministic hash
+ * otherwise.
+ *
+ * The name is stripped of plugin prefixes and lower-cased, then matched against
+ * `map` (exact, or as a `key-` / `key.` prefix). On a hit the brand hue is used;
+ * otherwise it falls back to {@link getHashColorFromString} on the original name.
+ *
+ * @param name - The package or plugin name to color.
+ * @param opacity - The alpha channel, a number or CSS string. Defaults to `1`.
+ * @param dark - Whether to use the dark-mode variant. Defaults to `false`.
+ * @param map - Extra brand hues, **merged over** {@link defaultBrandHues} (pass only your additions/overrides).
+ * @returns An `hsla(...)` CSS color string.
+ *
+ * @example
+ * getPluginColor('vue') // → 'hsla(153, 65%, 40%, 1)'
+ * getPluginColor('react') // → 'hsla(193, 65%, 40%, 1)'
+ * getPluginColor('vite-plugin-vue') // → 'hsla(153, 65%, 40%, 1)' (matched by suffix)
+ * getPluginColor('acme', 1, false, { acme: 300 }) // → custom hue merged over the defaults
+ */
+export function getPluginColor(
+  name: string,
+  opacity: number | string = 1,
+  dark = false,
+  map: Record<string, number> = {},
+): string {
+  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)
+  return getHashColorFromString(name, opacity, dark)
+}
+
+// ── Color math (colorjs.io) ───────────────────────────────────────────────
+
+/**
+ * Convert any CSS color to a `#rrggbb[aa]` hex string (gamut-mapped to sRGB).
+ *
+ * @param input - Any CSS color string (hex, `rgb()`, `hsl()`, named, `oklch()`, …).
+ * @returns A sRGB hex string.
+ *
+ * @example
+ * toHex('hsl(0, 100%, 50%)') // → '#ff0000'
+ */
+export function toHex(input: string): string {
+  return new Color(input).to('srgb').toGamut({ space: 'srgb' }).toString({ format: 'hex', collapse: false })
+}
+
+/**
+ * Lighten a color by an OKLCH lightness delta (perceptually even).
+ *
+ * @param input - The base color as any CSS color string.
+ * @param amount - Lightness delta in the 0–1 OKLCH range. Defaults to `0.1`.
+ * @returns The lightened color as a sRGB hex string.
+ *
+ * @example
+ * lighten('#336699', 0.1) // → a lighter blue
+ */
+export function lighten(input: string, amount = 0.1): string {
+  const c = new Color(input).to('oklch')
+  c.l = Math.max(0, Math.min(1, (c.l ?? 0) + amount))
+  return c.to('srgb').toGamut({ space: 'srgb' }).toString({ format: 'hex', collapse: false })
+}
+
+/**
+ * Darken a color by an OKLCH lightness delta (perceptually even).
+ *
+ * @param input - The base color as any CSS color string.
+ * @param amount - Lightness delta in the 0–1 OKLCH range. Defaults to `0.1`.
+ * @returns The darkened color as a sRGB hex string.
+ *
+ * @example
+ * darken('#336699', 0.1) // → a darker blue
+ */
+export function darken(input: string, amount = 0.1): string {
+  return lighten(input, -amount)
+}
+
+/**
+ * Mix two colors in OKLCH space.
+ *
+ * @param a - The first color as any CSS color string.
+ * @param b - The second color as any CSS color string.
+ * @param weight - Weight of `b` in the mix, 0–1. Defaults to `0.5`.
+ * @returns The mixed color as a sRGB hex string.
+ *
+ * @example
+ * mix('#ff0000', '#0000ff') // → a purple midpoint
+ */
+export function mix(a: string, b: string, weight = 0.5): string {
+  return (Color.mix(new Color(a), new Color(b), weight, { space: 'oklch' }) as Color)
+    .to('srgb')
+    .toGamut({ space: 'srgb' })
+    .toString({ format: 'hex', collapse: false })
+}
+
+/**
+ * Set a color's alpha channel, returning an `rgb(...)`/`rgba(...)` string.
+ *
+ * @param input - The base color as any CSS color string.
+ * @param alpha - The alpha channel, 0–1.
+ * @returns The color with the given alpha, as a CSS string.
+ *
+ * @example
+ * withAlpha('#336699', 0.5) // → 'rgb(51 102 153 / 0.5)'
+ */
+export function withAlpha(input: string, alpha: number): string {
+  const c = new Color(input).to('srgb')
+  c.alpha = alpha
+  return c.toString()
+}

package/utils/contrast.ts

@@ -0,0 +1,118 @@
+/**
+ * WCAG contrast helpers — relative luminance and contrast ratio — built on
+ * [colorjs.io](https://colorjs.io) rather than hand-rolled color math, so token
+ * pairs can be asserted in unit tests (e.g. `color-base` on `bg-base` meets AA
+ * in both themes). Complements the runnable axe-core scan in `../a11y`.
+ */
+import Color from 'colorjs.io'
+
+export interface RGB {
+  r: number
+  g: number
+  b: number
+}
+
+function toColor(input: string | RGB): Color {
+  return typeof input === 'string'
+    ? new Color(input)
+    : new Color('srgb', [input.r / 255, input.g / 255, input.b / 255])
+}
+
+/**
+ * Parse any CSS color into `{ r, g, b }` (0–255), via colorjs.io. An already
+ * parsed {@link RGB} is returned unchanged.
+ *
+ * @param input - A CSS color string (hex, `rgb()`, `hsl()`, named, …) or an {@link RGB}.
+ * @returns The color as `{ r, g, b }` with 0–255 channels.
+ *
+ * @example
+ * parseColor('#fff') // → { r: 255, g: 255, b: 255 }
+ * parseColor('#000000') // → { r: 0, g: 0, b: 0 }
+ * parseColor('white') // → { r: 255, g: 255, b: 255 }
+ */
+export function parseColor(input: string | RGB): RGB {
+  if (typeof input !== 'string')
+    return input
+  const [r, g, b] = new Color(input).to('srgb').coords
+  return { r: Math.round((r ?? 0) * 255), g: Math.round((g ?? 0) * 255), b: Math.round((b ?? 0) * 255) }
+}
+
+/**
+ * WCAG relative luminance of a color (0 = black, 1 = white).
+ *
+ * @param color - The color as a CSS string or {@link RGB} object.
+ * @returns The relative luminance in the range 0–1.
+ *
+ * @example
+ * relativeLuminance('#000') // → 0
+ * relativeLuminance('#fff') // → 1
+ */
+export function relativeLuminance(color: string | RGB): number {
+  return toColor(color).luminance
+}
+
+/**
+ * WCAG 2.1 contrast ratio between two colors (1 → 21). Argument order does not
+ * matter.
+ *
+ * @param a - The first color, as a CSS string or {@link RGB} object.
+ * @param b - The second color, as a CSS string or {@link RGB} object.
+ * @returns The contrast ratio, from `1` (identical) up to `21` (black on white).
+ *
+ * @example
+ * Math.round(contrastRatio('#000', '#fff')) // → 21
+ */
+export function contrastRatio(a: string | RGB, b: string | RGB): number {
+  return toColor(a).contrast(toColor(b), 'WCAG21')
+}
+
+export type ContrastLevel = 'AA' | 'AAA'
+
+/**
+ * Whether a ratio satisfies a WCAG level for normal or large text.
+ *
+ * Thresholds are 4.5 (AA) / 7 (AAA) for normal text and 3 (AA) / 4.5 (AAA) for
+ * large text.
+ *
+ * @param ratio - The contrast ratio to test (see {@link contrastRatio}).
+ * @param level - The WCAG conformance level, `'AA'` or `'AAA'`. Defaults to `'AA'`.
+ * @param large - Whether to use the relaxed large-text thresholds. Defaults to `false`.
+ * @returns `true` if the ratio meets or exceeds the threshold.
+ *
+ * @example
+ * meetsContrast(4.5) // → true
+ * meetsContrast(4.49) // → false
+ */
+export function meetsContrast(ratio: number, level: ContrastLevel = 'AA', large = false): boolean {
+  const thresholds = { AA: large ? 3 : 4.5, AAA: large ? 4.5 : 7 }
+  return ratio >= thresholds[level]
+}
+
+export interface ContrastResult {
+  ratio: number
+  AA: boolean
+  AALarge: boolean
+  AAA: boolean
+  AAALarge: boolean
+}
+
+/**
+ * Full contrast report between a foreground and background color.
+ *
+ * @param foreground - The foreground color, as a CSS string or {@link RGB} object.
+ * @param background - The background color, as a CSS string or {@link RGB} object.
+ * @returns A {@link ContrastResult} with the rounded `ratio` and per-level booleans.
+ *
+ * @example
+ * checkContrast('#525252', '#fff').AA // → true
+ */
+export function checkContrast(foreground: string | RGB, background: string | RGB): ContrastResult {
+  const ratio = Math.round(contrastRatio(foreground, background) * 100) / 100
+  return {
+    ratio,
+    AA: meetsContrast(ratio, 'AA'),
+    AALarge: meetsContrast(ratio, 'AA', true),
+    AAA: meetsContrast(ratio, 'AAA'),
+    AAALarge: meetsContrast(ratio, 'AAA', true),
+  }
+}