@nuxtseo/design-system 0.0.0-stage → 0.1.1

package/shared/contracts/feedback.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod'
+
+/**
+ * Both feedback endpoints are built into the PRO Worker
+ * (`layers/saas/server/api/feedback{,-thumbs}.post.ts`), because the row lands
+ * in the pro D1 `feedback` table, which is also the triage ledger. The site
+ * Worker has no handler and no binding to that database.
+ *
+ * The site's docs rail and free tools still POST these paths from the browser.
+ * That works in production only because `proRoutes()` in
+ * `deploy/cloudflare-env.ts` binds `nuxtseo.com/api/feedback*` to the pro
+ * Worker, so Cloudflare hands the request over at the edge.
+ *
+ * The paths are constants so that coupling is checkable: the site client, the
+ * dev proxy in `apps/site/nuxt.config.ts`, and the route-coverage guard in
+ * `tests/pro-worker-route-coverage.feature.test.ts` all read these. If you
+ * rename an endpoint, the guard fails instead of production 404ing silently.
+ */
+export const FEEDBACK_THUMBS_PATH = '/api/feedback-thumbs'
+export const FEEDBACK_COMMENT_PATH = '/api/feedback'
+
+export interface ThumbsFeedbackResponse {
+  thumbs: 'up' | 'down'
+  stats: {
+    up: number
+    down: number
+  }
+}
+
+export const ThumbsFeedbackSchema = z.object({
+  thumbs: z.enum(['up', 'down']),
+  toolId: z.string().optional(),
+  context: z.record(z.string(), z.unknown()).optional(),
+})
+
+export const CommentFeedbackSchema = z.object({
+  comment: z.string().min(3, 'Must be at least 3 characters'),
+  toolId: z.string().optional(),
+  context: z.record(z.string(), z.unknown()).optional(),
+})
+
+export type CommentFeedbackSchemaOutput = z.output<typeof CommentFeedbackSchema>

package/shared/contracts/index.ts

@@ -0,0 +1 @@
+export * from './feedback'

package/shared/delivery-channels.ts

@@ -0,0 +1,53 @@
+/**
+ * The delivery-channel vocabulary: one place that names each channel and picks
+ * its glyph. Reports, alerts and notification settings all render the same four
+ * channels, and before this each surface re-derived its own label/icon pair, so
+ * "Email + Discord" strings and icon choices drifted per screen.
+ *
+ * Icons are semantic roles from the icon registry and stay MONOCHROME — the
+ * channels are told apart by glyph shape, never by colour (DESIGN.md).
+ */
+
+export const DELIVERY_CHANNEL_KEYS = ['email', 'discord', 'slack', 'webhook'] as const
+
+export type DeliveryChannelKey = typeof DELIVERY_CHANNEL_KEYS[number]
+
+export interface DeliveryChannelMeta {
+  key: DeliveryChannelKey
+  label: string
+  /** Semantic icon role (see `shared/icons/registry.ts`). */
+  icon: string
+}
+
+export const DELIVERY_CHANNELS: Record<DeliveryChannelKey, DeliveryChannelMeta> = {
+  email: { key: 'email', label: 'Email', icon: 'mail' },
+  discord: { key: 'discord', label: 'Discord', icon: 'discord' },
+  slack: { key: 'slack', label: 'Slack', icon: 'slack' },
+  webhook: { key: 'webhook', label: 'Webhook', icon: 'webhook' },
+}
+
+export function deliveryChannelMeta(key: string): DeliveryChannelMeta | null {
+  return DELIVERY_CHANNELS[key as DeliveryChannelKey] ?? null
+}
+
+export function deliveryChannelLabel(key: string): string {
+  return deliveryChannelMeta(key)?.label ?? key
+}
+
+/**
+ * Enabled channels in canonical order, from any record shaped like the stored
+ * `channels` column (`{ email: true, discord: false, … }`).
+ */
+export function enabledDeliveryChannels(
+  channels: Partial<Record<DeliveryChannelKey, unknown>> | null | undefined,
+): DeliveryChannelKey[] {
+  if (!channels)
+    return []
+  return DELIVERY_CHANNEL_KEYS.filter(key => !!channels[key])
+}
+
+/** "Email & Discord" / "No delivery channel" — the prose form of the same set. */
+export function deliveryChannelsSummary(keys: readonly string[], empty = 'No delivery channel'): string {
+  const labels = keys.map(deliveryChannelLabel)
+  return labels.length ? labels.join(' & ') : empty
+}

package/shared/icons/index.ts

@@ -0,0 +1,143 @@
+/**
+ * Public icon API for the design system.
+ *
+ * - `DEFAULT_ICON_SET` — the set an app renders unless its Nuxt config picks
+ *   another with `designSystem.iconSet`. The choice is read once at build time
+ *   (`build/design-system.ts`), so UiIcon, UiButton, and Nuxt UI internals all
+ *   follow it. Preview sets first in the brand-kit `/icons` playground.
+ * - `resolveUiIcon(role, set)` — role → iconify id for `set`, with fallback. Runtime
+ *   code renders roles through `UiIcon` instead, which follows the app's choice.
+ * - Raw `i-*` ids pass straight through, so adoption can be incremental.
+ *
+ * Source scanning is disabled in the layer config. `iconBundleList()` is the
+ * explicit active-set client bundle, so candidate-set literals stay build-only.
+ */
+import type { IconRole, IconSet, RoleMap } from './registry'
+import { ICON_ALIASES, ICON_ROLES, ICON_SETS } from './registry'
+
+export type { IconRole, IconSet, RoleMap } from './registry'
+export { ICON_ALIASES, ICON_ROLES, ICON_SETS } from './registry'
+
+/**
+ * The icon set an app renders when its Nuxt config sets no `designSystem.iconSet`.
+ * Nuxt SEO renders hugeicons. Compare sets first in brand-kit `/icons`.
+ */
+export const DEFAULT_ICON_SET: IconSet = 'hugeicons'
+
+/**
+ * Parse an untrusted icon set name, such as a Nuxt config value, into an
+ * `IconSet`. `undefined` selects `DEFAULT_ICON_SET`.
+ */
+export function parseIconSet(value: unknown): IconSet {
+  if (value === undefined)
+    return DEFAULT_ICON_SET
+  if (typeof value === 'string' && (ICON_SETS as string[]).includes(value))
+    return value as IconSet
+  throw new TypeError(`designSystem.iconSet must be one of ${ICON_SETS.join(', ')}. Received ${JSON.stringify(value)}.`)
+}
+
+/** A curated semantic role or registered synonym. Prefer this for static registries. */
+export type IconAlias = keyof typeof ICON_ALIASES
+export type SemanticUiIcon = IconRole | IconAlias
+
+/**
+ * Component-facing icon input. Runtime provider/flag data can be dynamic, while
+ * literal role names still retain autocomplete through `SemanticUiIcon`.
+ */
+export type RawUiIcon = `i-${string}`
+export type UiIcon = SemanticUiIcon | RawUiIcon | (string & {})
+
+function idFor(role: RoleMap, set: IconSet): string | undefined {
+  if (role.fixed)
+    return role.fixed
+  // active set first, then fall back through the remaining sets in priority order
+  const order = [set, ...ICON_SETS.filter(s => s !== set)]
+  for (const s of order) {
+    const bare = role[s]
+    if (bare)
+      return `i-${s}-${bare}`
+  }
+  return undefined
+}
+
+/** Resolve a semantic role to its iconify id for `set`; pass raw `i-*` strings through. */
+export function resolveUiIcon(icon: UiIcon | undefined, set: IconSet = DEFAULT_ICON_SET): string | undefined {
+  if (!icon)
+    return undefined
+  if (icon.startsWith('i-'))
+    return icon
+  // resolve aliases (synonyms) to their canonical role first
+  const name = (ICON_ALIASES as Record<string, IconRole>)[icon] ?? icon
+  const role = (ICON_ROLES as Record<string, RoleMap>)[name]
+  if (!role)
+    return icon // unknown name: pass through unchanged
+  return idFor(role, set)
+}
+
+/** Map of every role → resolved id for `set`. Used to generate app.config ui.icons. */
+export function iconMapFor(set: IconSet = DEFAULT_ICON_SET): Record<IconRole, string> {
+  const out = {} as Record<IconRole, string>
+  for (const role of Object.keys(ICON_ROLES) as IconRole[])
+    out[role] = idFor(ICON_ROLES[role] as RoleMap, set)!
+  return out
+}
+
+// Collections that contain a hyphen, so `i-<collection>-<name>` can't be split naively.
+const HYPHEN_COLLECTIONS = ['simple-icons', 'svg-spinners', 'circle-flags', 'vscode-icons']
+
+// Brand marks used by UiSourceLogos. Keep these local in every app that extends
+// the design system, so Source identity never depends on Iconify at runtime.
+const SOURCE_LOGO_ICONS = [
+  'logos:google-search-console',
+  'logos:bing',
+  'logos:nuxt-icon',
+  'logos:chrome',
+  'logos:lighthouse',
+  'logos:cloudflare-icon',
+  'logos:vercel-icon',
+  'logos:netlify-icon',
+  'logos:google-analytics',
+  'logos:posthog-icon',
+  'logos:reddit-icon',
+  'logos:x',
+  'logos:ycombinator',
+  'logos:bluesky',
+  'logos:youtube-icon',
+  'logos:github-icon',
+  'simple-icons:plausibleanalytics',
+  'simple-icons:umami',
+] as const
+
+/** `i-lucide-arrow-right` → `lucide:arrow-right` (handles multi-hyphen collections). */
+function toPrefixName(id: string): string {
+  const body = id.replace(/^i-/, '')
+  const coll = HYPHEN_COLLECTIONS.find(c => body.startsWith(`${c}-`))
+  return coll ? `${coll}:${body.slice(coll.length + 1)}` : body.replace('-', ':')
+}
+
+/**
+ * The exact `prefix:name` ids for every role under `set` — feed to @nuxt/icon's
+ * `clientBundle.icons` so the build ships only the active set's resolved icons
+ * (plus the fixed brand/loading marks), never all four candidate sets.
+ */
+export function iconBundleList(set: IconSet = DEFAULT_ICON_SET): string[] {
+  return [...new Set([
+    ...Object.values(iconMapFor(set)).map(toPrefixName),
+    ...SOURCE_LOGO_ICONS,
+  ])]
+}
+
+/**
+ * Role + synonym-alias name → `prefix:name` id, for @nuxt/icon's `aliases` config.
+ * MUST be `prefix:name` (not `i-...`): @nuxt/icon uses an alias's value as the resolved
+ * name verbatim and re-prefixes `i-`, so an `i-` value becomes a broken `i-i-...`.
+ */
+export function iconAliasMap(set: IconSet = DEFAULT_ICON_SET): Record<string, string> {
+  const resolved = iconMapFor(set)
+  const out: Record<string, string> = {}
+  for (const [role, id] of Object.entries(resolved))
+    out[role] = toPrefixName(id)
+  for (const [alias, role] of Object.entries(ICON_ALIASES))
+    out[alias] = toPrefixName(resolved[role as IconRole])
+  return out
+}

package/shared/icons/registry.ts

@@ -0,0 +1,347 @@
+/**
+ * Central, set-swappable icon registry.
+ *
+ * Every icon in the product is referenced by a *semantic role* (`next`, `delete`,
+ * `trending-up`) — never a raw iconify id. Each role maps to a real icon in every
+ * candidate set, so the entire app can be flipped between sets by changing
+ * `designSystem.iconSet` in the Nuxt config. Compare sets visually first in the
+ * brand-kit `/icons` playground.
+ *
+ * Values are the *bare* icon name (no `i-<set>-` prefix); the resolver adds the
+ * prefix for the active set. A role may instead pin a `fixed` full id (used for
+ * brand marks that only live in one set, e.g. `i-simple-icons-github`).
+ *
+ * Naming conventions per set: lucide/carbon use bare names; solar uses the
+ * `-linear` stroke style; hugeicons uses the `-01` variant.
+ */
+
+export type IconSet = 'lucide' | 'carbon' | 'solar' | 'hugeicons'
+
+/** The 4 candidate sets, in fallback priority order when a role lacks the active set. */
+export const ICON_SETS: IconSet[] = ['lucide', 'carbon', 'solar', 'hugeicons']
+
+export type RoleMap = Partial<Record<IconSet, string>> & { fixed?: string }
+
+export const ICON_ROLES = {
+  // ── navigation ─────────────────────────────────────────────
+  'next': { lucide: 'arrow-right', carbon: 'arrow-right', solar: 'arrow-right-linear', hugeicons: 'arrow-right-01' },
+  'back': { lucide: 'arrow-left', carbon: 'arrow-left', solar: 'arrow-left-linear', hugeicons: 'arrow-left-01' },
+  'up': { lucide: 'arrow-up', carbon: 'arrow-up', solar: 'arrow-up-linear', hugeicons: 'arrow-up-01' },
+  'down': { lucide: 'arrow-down', carbon: 'arrow-down', solar: 'arrow-down-linear', hugeicons: 'arrow-down-01' },
+  'external': { lucide: 'external-link', carbon: 'launch', solar: 'arrow-right-up-linear', hugeicons: 'link-square-02' },
+  'expand': { lucide: 'chevron-down', carbon: 'chevron-down', solar: 'alt-arrow-down-linear', hugeicons: 'arrow-down-01' },
+  'collapse': { lucide: 'chevron-up', carbon: 'chevron-up', solar: 'alt-arrow-up-linear', hugeicons: 'arrow-up-01' },
+  'chevron-down': { lucide: 'chevron-down', carbon: 'chevron-down', solar: 'alt-arrow-down-linear', hugeicons: 'arrow-down-01' },
+  'chevron-up': { lucide: 'chevron-up', carbon: 'chevron-up', solar: 'alt-arrow-up-linear', hugeicons: 'arrow-up-01' },
+  'chevron-right': { lucide: 'chevron-right', carbon: 'chevron-right', solar: 'alt-arrow-right-linear', hugeicons: 'arrow-right-01' },
+  'chevron-left': { lucide: 'chevron-left', carbon: 'chevron-left', solar: 'alt-arrow-left-linear', hugeicons: 'arrow-left-01' },
+  'chevrons-up': { lucide: 'chevrons-up', carbon: 'chevron-up', solar: 'double-alt-arrow-up-linear', hugeicons: 'arrow-up-double' },
+  'page-first': { lucide: 'chevrons-left', carbon: 'page-first', solar: 'double-alt-arrow-left-linear', hugeicons: 'arrow-left-double' },
+  'page-last': { lucide: 'chevrons-right', carbon: 'page-last', solar: 'double-alt-arrow-right-linear', hugeicons: 'arrow-right-double' },
+  'menu': { lucide: 'menu', carbon: 'menu', solar: 'hamburger-menu-linear', hugeicons: 'menu-01' },
+  'hash': { lucide: 'hash', carbon: 'hashtag', solar: 'hashtag-linear', hugeicons: 'hashtag' },
+  'home': { lucide: 'house', carbon: 'home', solar: 'home-linear', hugeicons: 'home-01' },
+  'corner-down': { lucide: 'corner-down-right', carbon: 'arrow-down-right', solar: 'arrow-right-down-linear', hugeicons: 'arrow-turn-down' },
+
+  // ── crud / actions ─────────────────────────────────────────
+  'add': { lucide: 'plus', carbon: 'add', solar: 'add-circle-linear', hugeicons: 'add-01' },
+  'close': { lucide: 'x', carbon: 'close', solar: 'close-circle-linear', hugeicons: 'cancel-01' },
+  'delete': { lucide: 'trash-2', carbon: 'trash-can', solar: 'trash-bin-trash-linear', hugeicons: 'delete-02' },
+  'edit': { lucide: 'pencil', carbon: 'edit', solar: 'pen-linear', hugeicons: 'pencil-edit-02' },
+  'copy': { lucide: 'copy', carbon: 'copy', solar: 'copy-linear', hugeicons: 'copy-01' },
+  'check': { lucide: 'check', carbon: 'checkmark', solar: 'check-read-linear', hugeicons: 'tick-02' },
+  'refresh': { lucide: 'rotate-cw', carbon: 'renew', solar: 'refresh-linear', hugeicons: 'reload' },
+  'search': { lucide: 'search', carbon: 'search', solar: 'magnifer-linear', hugeicons: 'search-01' },
+  'download': { lucide: 'download', carbon: 'download', solar: 'download-linear', hugeicons: 'download-01' },
+  'upload': { lucide: 'upload', carbon: 'upload', solar: 'upload-linear', hugeicons: 'upload-01' },
+  'paperclip': { lucide: 'paperclip', carbon: 'attachment', solar: 'paperclip-linear', hugeicons: 'attachment' },
+  'send': { lucide: 'send', carbon: 'send', solar: 'plain-linear', hugeicons: 'sent-02' },
+  'save': { lucide: 'save', carbon: 'save', solar: 'diskette-linear', hugeicons: 'floppy-disk' },
+  'filter': { lucide: 'list-filter', carbon: 'filter', solar: 'filter-linear', hugeicons: 'filter' },
+  'filter-remove': { lucide: 'filter-x', carbon: 'filter-remove', solar: 'filter-broken', hugeicons: 'filter-remove' },
+  'settings': { lucide: 'settings', carbon: 'settings', solar: 'settings-linear', hugeicons: 'settings-01' },
+  'sliders': { lucide: 'sliders-horizontal', carbon: 'settings-adjust', solar: 'tuning-2-linear', hugeicons: 'tools' },
+  'more': { lucide: 'ellipsis-vertical', carbon: 'overflow-menu-vertical', solar: 'menu-dots-linear', hugeicons: 'more-vertical' },
+  'more-horizontal': { lucide: 'ellipsis', carbon: 'overflow-menu-horizontal', solar: 'menu-dots-bold', hugeicons: 'more-horizontal' },
+  'minus': { lucide: 'minus', carbon: 'subtract', solar: 'minus-circle-linear', hugeicons: 'remove-01' },
+  'share': { lucide: 'share-2', carbon: 'share', solar: 'share-linear', hugeicons: 'share-08' },
+  'undo': { lucide: 'undo-2', carbon: 'undo', solar: 'undo-left-linear', hugeicons: 'arrow-turn-backward' },
+  'move': { lucide: 'move', carbon: 'move', hugeicons: 'move' },
+  'grip': { lucide: 'grip-vertical', carbon: 'draggable', solar: 'menu-dots-linear', hugeicons: 'drag-drop-vertical' },
+  'stop': { lucide: 'square', carbon: 'stop', solar: 'stop-linear', hugeicons: 'stop' },
+  'play': { lucide: 'play', carbon: 'play', solar: 'play-linear', hugeicons: 'play' },
+  'pause': { lucide: 'pause', carbon: 'pause', solar: 'pause-linear', hugeicons: 'pause' },
+  'scan': { lucide: 'scan', carbon: 'scan', solar: 'scanner-linear', hugeicons: 'scan-image' },
+  'gamepad': { lucide: 'gamepad-2', carbon: 'game-console', solar: 'gamepad-linear', hugeicons: 'game-controller-03' },
+
+  // ── status / meta ──────────────────────────────────────────
+  'info': { lucide: 'info', carbon: 'information', solar: 'info-circle-linear', hugeicons: 'information-circle' },
+  'note': { lucide: 'info', carbon: 'information', solar: 'info-square-linear', hugeicons: 'information-square' },
+  'tip': { lucide: 'lightbulb', carbon: 'idea', solar: 'lightbulb-linear', hugeicons: 'idea-01' },
+  'warning': { lucide: 'triangle-alert', carbon: 'warning', solar: 'danger-triangle-linear', hugeicons: 'alert-02' },
+  'caution': { lucide: 'circle-alert', carbon: 'warning-alt', solar: 'danger-circle-linear', hugeicons: 'alert-circle' },
+  'success': { lucide: 'circle-check', carbon: 'checkmark-filled', solar: 'check-circle-linear', hugeicons: 'checkmark-circle-02' },
+  'error': { lucide: 'circle-x', carbon: 'close-filled', solar: 'close-circle-linear', hugeicons: 'cancel-circle' },
+  'help': { lucide: 'circle-help', carbon: 'help', solar: 'question-circle-linear', hugeicons: 'help-circle' },
+  'lock': { lucide: 'lock', carbon: 'locked', solar: 'lock-keyhole-linear', hugeicons: 'square-lock-02' },
+  'view': { lucide: 'eye', carbon: 'view', solar: 'eye-linear', hugeicons: 'view' },
+  'hide': { lucide: 'eye-off', carbon: 'view-off', solar: 'eye-closed-linear', hugeicons: 'view-off' },
+  'ai': { lucide: 'sparkles', carbon: 'magic-wand', solar: 'magic-stick-3-linear', hugeicons: 'ai-magic' },
+  'bot': { lucide: 'bot', carbon: 'bot', solar: 'chat-round-line-linear', hugeicons: 'ai-chat-02' },
+  'star': { lucide: 'star', carbon: 'star', solar: 'star-linear', hugeicons: 'star' },
+  'heart': { lucide: 'heart', carbon: 'favorite', solar: 'heart-linear', hugeicons: 'favourite' },
+  'bell': { lucide: 'bell', carbon: 'notification', solar: 'bell-linear', hugeicons: 'notification-01' },
+  'shield': { lucide: 'shield', carbon: 'security', solar: 'shield-linear', hugeicons: 'shield-01' },
+  'shield-check': { lucide: 'shield-check', carbon: 'security', solar: 'shield-check-linear', hugeicons: 'shield-01' },
+  'zap': { lucide: 'zap', carbon: 'lightning', solar: 'bolt-linear', hugeicons: 'flash' },
+  'flag': { lucide: 'flag', carbon: 'flag', solar: 'flag-linear', hugeicons: 'flag-02' },
+  'tag': { lucide: 'tag', carbon: 'tag', solar: 'tag-linear', hugeicons: 'tag-01' },
+  'pin': { lucide: 'pin', carbon: 'pin', solar: 'pin-linear', hugeicons: 'pin' },
+  'bookmark': { lucide: 'bookmark', carbon: 'bookmark', solar: 'bookmark-linear', hugeicons: 'bookmark-01' },
+  'gift': { lucide: 'gift', carbon: 'gift', solar: 'gift-linear', hugeicons: 'gift' },
+  'trophy': { lucide: 'trophy', carbon: 'trophy', solar: 'cup-star-linear', hugeicons: 'champion' },
+  'target': { lucide: 'target', carbon: 'concept', solar: 'target-linear', hugeicons: 'target-02' },
+  // Rivalry / "you vs them" — competitor surfaces. lucide+hugeicons render swords;
+  // carbon/solar have no sword glyph, so they fall back to the rivalry-as-aim stand-in.
+  'versus': { lucide: 'swords', carbon: 'concept', solar: 'target-linear', hugeicons: 'sword-03' },
+  'bug': { lucide: 'bug', carbon: 'debug', solar: 'bug-linear', hugeicons: 'bug-01' },
+  'circle-dash': { lucide: 'circle-dashed', carbon: 'circle-dash', solar: 'record-circle-linear', hugeicons: 'circle' },
+  'loading': { fixed: 'i-svg-spinners-90-ring-with-bg' },
+
+  // ── theme ──────────────────────────────────────────────────
+  'light': { lucide: 'sun', carbon: 'sun', solar: 'sun-linear', hugeicons: 'sun-02' },
+  'dark': { lucide: 'moon', carbon: 'moon', solar: 'moon-linear', hugeicons: 'moon-02' },
+  'system': { lucide: 'monitor', carbon: 'screen', solar: 'monitor-linear', hugeicons: 'computer' },
+
+  // ── objects / domain ───────────────────────────────────────
+  'rocket': { lucide: 'rocket', carbon: 'rocket', solar: 'rocket-linear', hugeicons: 'rocket-01' },
+  'link': { lucide: 'link', carbon: 'link', solar: 'link-linear', hugeicons: 'link-02' },
+  'unlink': { lucide: 'unlink', carbon: 'unlink', solar: 'link-broken-linear', hugeicons: 'unlink-03' },
+  'file': { lucide: 'file-text', carbon: 'document', solar: 'document-text-linear', hugeicons: 'file-01' },
+  'file-search': { lucide: 'file-search', carbon: 'document-view', hugeicons: 'file-search' },
+  'file-check': { lucide: 'file-check', carbon: 'document-tasks', hugeicons: 'file-validation' },
+  'folder': { lucide: 'folder', carbon: 'folder', solar: 'folder-linear', hugeicons: 'folder-01' },
+  'calendar': { lucide: 'calendar', carbon: 'calendar', solar: 'calendar-linear', hugeicons: 'calendar-03' },
+  'clock': { lucide: 'clock', carbon: 'time', solar: 'clock-circle-linear', hugeicons: 'clock-01' },
+  'timer': { lucide: 'timer', carbon: 'timer', solar: 'stopwatch-linear', hugeicons: 'timer-02' },
+  'mail': { lucide: 'mail', carbon: 'email', solar: 'letter-linear', hugeicons: 'mail-01' },
+  'globe': { lucide: 'globe', carbon: 'wikis', solar: 'global-linear', hugeicons: 'global' },
+  'plug': { lucide: 'plug', carbon: 'plug', solar: 'plug-circle-linear', hugeicons: 'plug-01' },
+  'database': { lucide: 'database', carbon: 'data-base', solar: 'database-linear', hugeicons: 'database' },
+  'server': { lucide: 'server', carbon: 'bare-metal-server', solar: 'server-linear', hugeicons: 'database-02' },
+  'cloud': { lucide: 'cloud', carbon: 'cloud', solar: 'cloud-linear', hugeicons: 'cloud' },
+  'key': { lucide: 'key', carbon: 'password', solar: 'key-linear', hugeicons: 'key-01' },
+  'user': { lucide: 'user', carbon: 'user', solar: 'user-linear', hugeicons: 'user' },
+  'users': { lucide: 'users', carbon: 'group', solar: 'users-group-rounded-linear', hugeicons: 'user-group' },
+  'user-plus': { lucide: 'user-plus', carbon: 'user-follow', solar: 'user-plus-linear', hugeicons: 'user-add-01' },
+  'credit-card': { lucide: 'credit-card', carbon: 'purchase', solar: 'card-linear', hugeicons: 'credit-card' },
+  'dollar': { lucide: 'dollar-sign', carbon: 'currency-dollar', solar: 'dollar-linear', hugeicons: 'dollar-01' },
+  'book': { lucide: 'book-open', carbon: 'book', solar: 'book-linear', hugeicons: 'book-02' },
+  'graduation': { lucide: 'graduation-cap', carbon: 'education', solar: 'square-academic-cap-linear', hugeicons: 'mortarboard-02' },
+  'image': { lucide: 'image', carbon: 'image', solar: 'gallery-linear', hugeicons: 'image-01' },
+  'code': { lucide: 'code', carbon: 'code', solar: 'code-linear', hugeicons: 'source-code' },
+  'terminal': { lucide: 'terminal', carbon: 'terminal', solar: 'programming-linear', hugeicons: 'computer-terminal-01' },
+  'command': { lucide: 'command', carbon: 'apps', solar: 'command-linear', hugeicons: 'command' },
+  'layout': { lucide: 'layout-dashboard', carbon: 'dashboard', solar: 'widget-linear', hugeicons: 'dashboard-square-01' },
+  'layers': { lucide: 'layers', carbon: 'layers', solar: 'layers-linear', hugeicons: 'layers-01' },
+  'list': { lucide: 'list', carbon: 'list', solar: 'list-linear', hugeicons: 'task-01' },
+  'table': { lucide: 'table', carbon: 'table', solar: 'widget-linear', hugeicons: 'grid-table' },
+  'grid': { lucide: 'grid-3x3', carbon: 'grid', solar: 'widget-2-linear', hugeicons: 'grid-view' },
+  'map': { lucide: 'map-pin', carbon: 'location', solar: 'map-point-linear', hugeicons: 'location-01' },
+  'wifi': { lucide: 'wifi', carbon: 'wifi', solar: 'wi-fi-router-linear', hugeicons: 'wifi-01' },
+  'monitor': { lucide: 'monitor', carbon: 'screen', solar: 'monitor-linear', hugeicons: 'computer' },
+  'mouse-pointer': { lucide: 'mouse-pointer-click', carbon: 'cursor-1', solar: 'cursor-linear', hugeicons: 'cursor-01' },
+  'gauge': { lucide: 'gauge', carbon: 'meter', solar: 'spedometer-max-linear', hugeicons: 'dashboard-speed-01' },
+  'flask': { lucide: 'flask-conical', carbon: 'chemistry', solar: 'test-tube-linear', hugeicons: 'test-tube-01' },
+  'wand': { lucide: 'wand-sparkles', carbon: 'magic-wand-filled', solar: 'magic-stick-3-linear', hugeicons: 'magic-wand-01' },
+  'git': { lucide: 'git-branch', carbon: 'branch', solar: 'branching-paths-up-linear', hugeicons: 'git-branch' },
+  'version': { lucide: 'git-branch', carbon: 'version', solar: 'branching-paths-up-linear', hugeicons: 'git-branch' },
+  'message': { lucide: 'message-square', carbon: 'chat', solar: 'chat-round-linear', hugeicons: 'message-01' },
+  'phone': { lucide: 'phone', carbon: 'phone', solar: 'phone-linear', hugeicons: 'call' },
+
+  // ── charts / data ──────────────────────────────────────────
+  'chart': { lucide: 'chart-area', carbon: 'chart-area', solar: 'chart-square-linear', hugeicons: 'analytics-01' },
+  'chart-line': { lucide: 'chart-line', carbon: 'chart-line', solar: 'graph-linear', hugeicons: 'analytics-up' },
+  'chart-bar': { lucide: 'chart-column', carbon: 'chart-bar', solar: 'chart-2-linear', hugeicons: 'bar-chart' },
+  'chart-pie': { lucide: 'chart-pie', carbon: 'chart-pie', solar: 'pie-chart-2-linear', hugeicons: 'pie-chart' },
+  'activity': { lucide: 'activity', carbon: 'activity', solar: 'pulse-linear', hugeicons: 'activity-01' },
+  'analytics': { lucide: 'chart-no-axes-combined', carbon: 'analytics', solar: 'chart-linear', hugeicons: 'analytics-01' },
+  'trending-up': { lucide: 'trending-up', carbon: 'growth', solar: 'graph-up-linear', hugeicons: 'analytics-up' },
+  'trending-down': { lucide: 'trending-down', carbon: 'misuse', solar: 'graph-down-linear', hugeicons: 'analytics-down' },
+  'percent': { lucide: 'percent', carbon: 'percentage', solar: 'sale-linear', hugeicons: 'percent' },
+
+  'sort': { lucide: 'chevrons-up-down', carbon: 'arrows-vertical', solar: 'sort-vertical-linear', hugeicons: 'arrow-up-down' },
+  'arrow-up-right': { lucide: 'arrow-up-right', carbon: 'arrow-up-right', solar: 'arrow-right-up-linear', hugeicons: 'arrow-up-right-01' },
+  'arrow-down-right': { lucide: 'arrow-down-right', carbon: 'arrow-down-right', solar: 'arrow-right-down-linear', hugeicons: 'arrow-down-right-01' },
+  'compare': { lucide: 'git-compare', carbon: 'compare', solar: 'transfer-horizontal-linear', hugeicons: 'arrow-data-transfer-horizontal' },
+  'thumbs-up': { lucide: 'thumbs-up', carbon: 'thumbs-up', solar: 'like-linear', hugeicons: 'thumbs-up' },
+  'thumbs-down': { lucide: 'thumbs-down', carbon: 'thumbs-down', solar: 'dislike-linear', hugeicons: 'thumbs-down' },
+
+  // ── more objects / domain ──────────────────────────────────
+  'smartphone': { lucide: 'smartphone', carbon: 'mobile', solar: 'smartphone-linear', hugeicons: 'smart-phone-01' },
+  'unplug': { lucide: 'unplug', carbon: 'connection-signal-off', solar: 'plug-circle-broken', hugeicons: 'plug-socket' },
+  'radar': { lucide: 'radar', carbon: 'radar', solar: 'radar-2-linear', hugeicons: 'radar-01' },
+  'wrench': { lucide: 'wrench', carbon: 'tool-kit', hugeicons: 'wrench-01' },
+  'history': { lucide: 'history', carbon: 'recently-viewed', solar: 'history-linear', hugeicons: 'time-quarter-pass' },
+  'cpu': { lucide: 'cpu', carbon: 'chip', solar: 'cpu-linear', hugeicons: 'cpu' },
+  'puzzle': { lucide: 'puzzle', carbon: 'plug-filled', solar: 'pip-linear', hugeicons: 'puzzle' },
+  'inbox': { lucide: 'inbox', carbon: 'email-new', solar: 'inbox-linear', hugeicons: 'inbox' },
+  'shopping-cart': { lucide: 'shopping-cart', carbon: 'shopping-cart', solar: 'cart-large-2-linear', hugeicons: 'shopping-cart-01' },
+  'hourglass': { lucide: 'hourglass', carbon: 'hourglass', solar: 'hourglass-linear' },
+  'cable': { lucide: 'cable', carbon: 'connect', solar: 'usb-linear', hugeicons: 'cable' },
+  'crown': { lucide: 'crown', solar: 'crown-linear', hugeicons: 'crown' },
+  'cloud-off': { lucide: 'cloud-off', carbon: 'cloud-offline', solar: 'cloud-cross-linear' },
+  'braces': { lucide: 'braces', carbon: 'code', solar: 'code-square-linear', hugeicons: 'source-code-square' },
+  'accessibility': { lucide: 'accessibility', carbon: 'accessibility', solar: 'accessibility-linear' },
+  'video': { lucide: 'video', carbon: 'video', solar: 'videocamera-linear', hugeicons: 'video-01' },
+  'log-out': { lucide: 'log-out', carbon: 'logout', solar: 'logout-2-linear', hugeicons: 'logout-01' },
+  'log-in': { lucide: 'log-in', carbon: 'login', solar: 'login-2-linear', hugeicons: 'login-01' },
+  'list-ordered': { lucide: 'list-ordered', carbon: 'list-numbered', solar: 'list-arrow-down-linear', hugeicons: 'left-to-right-list-number' },
+  'list-checks': { lucide: 'list-checks', carbon: 'task', solar: 'checklist-minimalistic-linear', hugeicons: 'task-done-01' },
+  'folder-plus': { lucide: 'folder-plus', carbon: 'folder-add', solar: 'folder-with-files-linear', hugeicons: 'folder-add' },
+  'briefcase': { lucide: 'briefcase', carbon: 'portfolio', solar: 'case-linear', hugeicons: 'job-search' },
+  'archive': { lucide: 'archive', carbon: 'archive', solar: 'archive-linear', hugeicons: 'archive-02' },
+  'building': { lucide: 'building-2', carbon: 'building', solar: 'buildings-2-linear', hugeicons: 'building-03' },
+  'newspaper': { lucide: 'newspaper', carbon: 'document', solar: 'document-text-linear', hugeicons: 'news' },
+  'megaphone': { lucide: 'megaphone', carbon: 'bullhorn', hugeicons: 'megaphone-01' },
+  'life-buoy': { lucide: 'life-buoy', carbon: 'help', hugeicons: 'help-circle' },
+  'compass': { lucide: 'compass', carbon: 'compass', solar: 'compass-linear', hugeicons: 'navigation-03' },
+  'sprout': { lucide: 'sprout', carbon: 'tree', solar: 'leaf-linear', hugeicons: 'plant-02' },
+  'receipt': { lucide: 'receipt', carbon: 'receipt', solar: 'bill-list-linear', hugeicons: 'invoice-01' },
+  'scale': { lucide: 'scale', carbon: 'scales', solar: 'scale-linear', hugeicons: 'justice-scale-01' },
+  'webhook': { lucide: 'webhook', carbon: 'webhook', solar: 'link-circle-linear', hugeicons: 'api' },
+  'badge': { lucide: 'badge-check', carbon: 'badge', solar: 'medal-ribbon-linear', hugeicons: 'checkmark-badge-01' },
+  'at-sign': { lucide: 'at-sign', carbon: 'at', solar: 'mention-circle-linear', hugeicons: 'at' },
+  'clipboard': { lucide: 'clipboard', carbon: 'document-tasks', solar: 'clipboard-linear', hugeicons: 'clipboard' },
+  'search-x': { lucide: 'search-x', carbon: 'search-locate-mirror', solar: 'minimalistic-magnifer-zoom-out-linear', hugeicons: 'search-remove' },
+  'file-x': { lucide: 'file-x', carbon: 'document-unknown', solar: 'file-corrupted-linear', hugeicons: 'file-not-found' },
+  'calendar-clock': { lucide: 'calendar-clock', carbon: 'calendar-heat-map', solar: 'calendar-date-linear', hugeicons: 'calendar-02' },
+  'video-off': { lucide: 'video-off', carbon: 'video-off', solar: 'videocamera-broken', hugeicons: 'video-off' },
+  'wifi-off': { lucide: 'wifi-off', carbon: 'wifi-off', solar: 'wi-fi-router-minimalistic-linear', hugeicons: 'wifi-disconnected-01' },
+
+  // ── brand ─ stroke-weight (hugeicons) so they sit with the line icons rather
+  // than reading as heavy solid silhouettes. Pinned (fixed) for a consistent brand
+  // family across every active set.
+  // Google defaults to a monochrome G in muted product contexts. `google-color`
+  // is the official multicolor mark for source identity where color is the cue.
+  'google': { fixed: 'i-simple-icons-google' },
+  'google-color': { fixed: 'i-logos-google-icon' },
+  'nuxt': { fixed: 'i-simple-icons-nuxtdotjs' },
+  'github': { fixed: 'i-hugeicons-github' },
+  'discord': { fixed: 'i-hugeicons-discord' },
+  'linkedin': { fixed: 'i-hugeicons-linkedin-01' },
+  'x-twitter': { fixed: 'i-hugeicons-new-twitter' },
+  'facebook': { fixed: 'i-hugeicons-facebook-01' },
+  'slack': { fixed: 'i-hugeicons-slack' },
+} as const satisfies Record<string, RoleMap>
+
+export type IconRole = keyof typeof ICON_ROLES
+
+/**
+ * Alternate names that resolve to a canonical role — synonyms and common
+ * iconify-id variants encountered during migration (e.g. `alert-triangle`,
+ * `loader-2`, `check-circle` all collapse to one role). Keeps the role list
+ * small while letting the codemod map many raw ids onto few roles.
+ */
+export const ICON_ALIASES = {
+  // status synonyms
+  'alert-triangle': 'warning',
+  'octagon-alert': 'warning',
+  'warning-filled': 'warning',
+  'file-warning': 'warning',
+  'alert-circle': 'caution',
+  'circle-alert': 'caution',
+  'check-circle': 'success',
+  'check-circle-2': 'success',
+  'badge-check': 'success',
+  'task-complete': 'success',
+  'checkmark-outline': 'success',
+  'checkmark-filled': 'success',
+  'x-circle': 'error',
+  'close-filled': 'error',
+  'close-outline': 'error',
+  'help-circle': 'help',
+  'file-question': 'help',
+  'message-circle-question': 'help',
+  'shield-alert': 'shield',
+  'shield-check': 'shield-check',
+  // loaders / refresh
+  'loader': 'loading',
+  'loader-2': 'loading',
+  'loader-circle': 'loading',
+  'spinner': 'loading',
+  'renew': 'refresh',
+  'reset': 'refresh',
+  'rotate-cw': 'refresh',
+  'restart': 'refresh',
+  // objects
+  'arrow-right': 'next',
+  'arrow-left': 'back',
+  'external-link': 'external',
+  'link-2': 'link',
+  'bot-message-square': 'bot',
+  'robot': 'bot',
+  'message-circle': 'message',
+  'chat': 'message',
+  'tags': 'tag',
+  'tag-group': 'tag',
+  'globe-2': 'globe',
+  'earth': 'globe',
+  'wikis': 'globe',
+  'cog': 'settings',
+  'cog-6-tooth': 'settings',
+  'magnifying-glass': 'search',
+  'pen': 'edit',
+  'pen-line': 'edit',
+  'pencil': 'edit',
+  'trash': 'delete',
+  'trash-2': 'delete',
+  'document-export': 'download',
+  'file-text': 'file',
+  'code-bracket': 'code',
+  'code-reference': 'code',
+  'xml': 'code',
+  // charts
+  'line-chart': 'chart-line',
+  'bar-chart-3': 'chart-bar',
+  'pie-chart': 'chart-pie',
+  'chart-no-axes-column': 'chart-bar',
+  'trending-up-carbon': 'trending-up',
+  // misc
+  'triangle-alert': 'warning',
+  'clipboard-check': 'list-checks',
+  'clipboard-document-check': 'list-checks',
+  'beaker': 'flask',
+  'swords': 'versus',
+  'crossed-swords': 'versus',
+  'tool-box': 'wrench',
+  'tools': 'wrench',
+  'tool': 'wrench',
+  // bare-name variants that collide with a role's canonical id
+  'map': 'map',
+  'file': 'file',
+  'filter': 'filter',
+  'circle-dot': 'circle-dash',
+  // more synonyms surfaced in migration
+  'key-square': 'key',
+  'key-round': 'key',
+  'shield-off': 'shield',
+  'pause-circle': 'pause',
+  'bell-ring': 'bell',
+  'search-check': 'search',
+  'rocket-launch': 'rocket',
+  'sparkle': 'ai',
+  'sparkle-fill': 'ai',
+  'ai-label': 'ai',
+  'code-duotone': 'code',
+  'books': 'book',
+  'template': 'layout',
+  'blocks': 'grid',
+  // brand logo aliases (carbon `logo-*`, ph duotone, etc.)
+  'logo-x': 'x-twitter',
+  'logo-github': 'github',
+  'logo-discord': 'discord',
+  'logo-linkedin': 'linkedin',
+  'logo-facebook': 'facebook',
+  'logo-slack': 'slack',
+} as const satisfies Record<string, IconRole>