@windforge/ui 0.1.0

package/src/components/text.tsx

@@ -0,0 +1,109 @@
+import * as React from 'react'
+import { Slot } from '@radix-ui/react-slot'
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from '../lib/utils'
+import type { NoStyle } from '../lib/types'
+
+/**
+ * Text — the typography primitive (our `Typography`). Size, weight, tone and
+ * alignment are a closed token vocabulary; nothing renders off-scale. Renders a
+ * `<p>` by default; use `asChild` for the right semantic element:
+ *
+ *   <Text size="3xl" weight="bold" asChild><h1>Title</h1></Text>
+ *   <Text tone="muted">Body copy</Text>
+ *   <Text span weight="medium">inline label</Text>   // inline <span>, not a block <p>
+ *   <Text variant="inline-code">defaultOpen</Text>   // inline <code> within prose
+ */
+const text = cva('', {
+  variants: {
+    size: {
+      sm: 'text-sm', base: 'text-base', lg: 'text-lg', xl: 'text-xl',
+      '2xl': 'text-2xl', '3xl': 'text-3xl', '4xl': 'text-4xl', '5xl': 'text-5xl', '6xl': 'text-6xl',
+    },
+    weight: {
+      light: 'font-light', regular: 'font-normal', medium: 'font-medium', semibold: 'font-semibold', bold: 'font-bold',
+    },
+    tone: {
+      default:  'text-primary',
+      muted:    'text-secondary',
+      subtle:   'text-tertiary',
+      disabled: 'text-disabled',
+      inverse:  'text-inverse',
+      brand:    'text-brand',
+      link:     'text-link',
+      // A brand→secondary gradient clipped to the glyphs — for hero/display type.
+      gradient: 'bg-gradient-to-r from-brand to-brand-secondary bg-clip-text text-transparent',
+    },
+    align:    { left: 'text-left', center: 'text-center', right: 'text-right' },
+    truncate: { true: 'truncate', false: '' },
+    mono:     { true: 'font-mono', false: '' },
+    // `variant="inline-code"` renders a <code> element styled as inline code:
+    // monospace, a subtle fill, em-sized so it scales with the surrounding text.
+    // Listed last so its text-size wins; no horizontal padding so it hugs the text.
+    variant: {
+      'inline-code': 'rounded border border-subtle bg-surface-inset py-0.5 font-mono text-[0.875em] text-primary',
+    },
+  },
+  defaultVariants: { size: 'base', tone: 'default' },
+})
+
+export interface TextProps extends NoStyle<React.HTMLAttributes<HTMLElement>>, VariantProps<typeof text> {
+  asChild?: boolean
+  /** Render inline as a `<span>` instead of a block `<p>` — for labels, chips and text inside flex rows. */
+  span?: boolean
+}
+
+export const Text = React.forwardRef<HTMLElement, TextProps>(
+  ({ asChild, span, size, weight, tone, align, truncate, mono, variant, ...props }, ref) => {
+    const Comp: React.ElementType = asChild ? Slot : span ? 'span' : variant === 'inline-code' ? 'code' : 'p'
+    return (
+      <Comp
+        ref={ref as React.Ref<HTMLParagraphElement>}
+        className={cn(text({ size, weight, tone, align, truncate, mono, variant }))}
+        {...props}
+      />
+    )
+  },
+)
+Text.displayName = 'Text'
+
+/**
+ * Headings — semantic `H1`–`H6` components. Each picks the right element and a
+ * sensible default size; override `size`/`weight`/`tone` to decouple visual
+ * scale from document outline.
+ *
+ *   <H1>Page title</H1>
+ *   <H3 size="lg">Section</H3>
+ */
+export interface HeadingProps
+  extends NoStyle<React.HTMLAttributes<HTMLHeadingElement>>,
+    Pick<VariantProps<typeof text>, 'size' | 'weight' | 'tone' | 'align' | 'truncate'> {}
+
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6
+const HEADING_SIZE: Record<HeadingLevel, NonNullable<VariantProps<typeof text>['size']>> = {
+  1: '3xl', 2: '2xl', 3: 'xl', 4: 'lg', 5: 'base', 6: 'sm',
+}
+
+function createHeading(level: HeadingLevel) {
+  const Tag = `h${level}` as const
+  const Component = React.forwardRef<HTMLHeadingElement, HeadingProps>(
+    ({ size, weight = 'bold', tone, align, truncate, ...props }, ref) => (
+      <Tag
+        ref={ref}
+        className={cn(text({ size: size ?? HEADING_SIZE[level], weight, tone, align, truncate }), 'tracking-tight')}
+        {...props}
+      />
+    ),
+  )
+  Component.displayName = `H${level}`
+  return Component
+}
+
+export const H1 = createHeading(1)
+export const H2 = createHeading(2)
+export const H3 = createHeading(3)
+export const H4 = createHeading(4)
+export const H5 = createHeading(5)
+export const H6 = createHeading(6)
+
+export { text as textVariants }

package/src/components/textarea.tsx

@@ -0,0 +1,27 @@
+import * as React from 'react'
+import { cn } from '../lib/utils'
+import type { NoStyle } from '../lib/types'
+import { focusRingField } from '../lib/recipes'
+
+export interface TextareaProps extends NoStyle<React.TextareaHTMLAttributes<HTMLTextAreaElement>> {
+  /** Error state — red control outline + aria-invalid. Usually set for you by FormField. */
+  invalid?: boolean
+}
+
+export const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+  ({ invalid, ...props }, ref) => (
+    <textarea
+      ref={ref}
+      aria-invalid={invalid || undefined}
+      className={cn(
+        'flex min-h-20 w-full rounded-lg border border-strong bg-surface px-3 py-2 text-sm text-primary',
+        'transition-colors placeholder:text-tertiary',
+        focusRingField,
+        'disabled:cursor-not-allowed disabled:opacity-50',
+        invalid && 'border-error focus-visible:border-error',
+      )}
+      {...props}
+    />
+  ),
+)
+Textarea.displayName = 'Textarea'

package/src/components/toast.tsx

@@ -0,0 +1,107 @@
+import * as React from 'react'
+import { createPortal } from 'react-dom'
+import { CheckCircle2, XCircle, AlertTriangle, Info, X } from 'lucide-react'
+import { cn } from '../lib/utils'
+import { focusRingInset } from '../lib/recipes'
+
+/**
+ * Toast / Snackbar — a transient message. Call `toast({...})` from anywhere
+ * (event handlers, effects, outside React), and render `<Toaster />` once near
+ * the app root. Text stays the normal foreground; only the icon carries the
+ * status hue (matching Alert).
+ */
+export type ToastVariant = 'neutral' | 'success' | 'error' | 'warning' | 'info'
+
+export interface ToastOptions {
+  title?: React.ReactNode
+  description?: React.ReactNode
+  variant?: ToastVariant
+  duration?: number
+  action?: React.ReactNode
+}
+interface ToastRecord extends ToastOptions {
+  id: number
+}
+
+// ── tiny external store (callable outside React) ────────────────────────────────
+let toasts: ToastRecord[] = []
+const listeners = new Set<() => void>()
+const emit = () => listeners.forEach((listener) => listener())
+let nextId = 0
+
+export function toast(options: ToastOptions): number {
+  const id = nextId++
+  const duration = options.duration ?? 5000
+  toasts = [...toasts, { variant: 'neutral', ...options, duration, id }]
+  emit()
+  if (duration > 0) window.setTimeout(() => dismissToast(id), duration)
+  return id
+}
+export function dismissToast(id: number) {
+  toasts = toasts.filter((existing) => existing.id !== id)
+  emit()
+}
+
+function useToasts() {
+  return React.useSyncExternalStore(
+    (onStoreChange) => {
+      listeners.add(onStoreChange)
+      return () => listeners.delete(onStoreChange)
+    },
+    () => toasts,
+    () => toasts,
+  )
+}
+
+const ICONS: Record<ToastVariant, React.ReactNode | null> = {
+  neutral: null,
+  success: <CheckCircle2 className="text-success" />,
+  error: <XCircle className="text-error" />,
+  warning: <AlertTriangle className="text-warning" />,
+  info: <Info className="text-info" />,
+}
+
+function ToastItem({ toast }: { toast: ToastRecord }) {
+  // Urgent variants interrupt the screen reader; the rest announce politely.
+  const urgent = toast.variant === 'error' || toast.variant === 'warning'
+  return (
+    <li
+      role={urgent ? 'alert' : 'status'}
+      aria-live={urgent ? 'assertive' : 'polite'}
+      className="pointer-events-auto flex w-80 gap-3 rounded-xl border border-border bg-surface p-4 text-primary shadow-lg animate-scale-in [&_svg]:size-5 [&_svg]:shrink-0"
+    >
+      {toast.variant && toast.variant !== 'neutral' && <span className="mt-0.5">{ICONS[toast.variant]}</span>}
+      <div className="min-w-0 flex-1">
+        {toast.title && <div className="font-semibold leading-snug">{toast.title}</div>}
+        {toast.description && <div className="text-sm text-primary">{toast.description}</div>}
+        {toast.action && <div className="mt-2">{toast.action}</div>}
+      </div>
+      <button
+        type="button"
+        aria-label="Dismiss"
+        onClick={() => dismissToast(toast.id)}
+        className={cn('-mr-1 -mt-1 h-fit rounded-md p-1 text-secondary opacity-70 transition-opacity hover:opacity-100', focusRingInset)}
+      >
+        <X className="h-4 w-4" />
+      </button>
+    </li>
+  )
+}
+
+const emptySubscribe = () => () => {}
+
+export function Toaster() {
+  const activeToasts = useToasts()
+  // Hydration gate: false on the server snapshot, true once on the client — no
+  // mismatch, and no Effect needed to flip a `mounted` flag.
+  const mounted = React.useSyncExternalStore(emptySubscribe, () => true, () => false)
+  if (!mounted) return null
+  return createPortal(
+    <ol className="pointer-events-none fixed bottom-4 right-4 z-[100] flex w-80 flex-col gap-2">
+      {activeToasts.map((toast) => (
+        <ToastItem key={toast.id} toast={toast} />
+      ))}
+    </ol>,
+    document.body,
+  )
+}

package/src/components/toggle-button.tsx

@@ -0,0 +1,103 @@
+import * as React from 'react'
+import { cva } from 'class-variance-authority'
+import { cn } from '../lib/utils'
+import type { NoStyle } from '../lib/types'
+import { focusRingInset } from '../lib/recipes'
+
+/**
+ * ToggleButtonGroup / ToggleButton — a segmented control. `type="single"` keeps
+ * one value selected; `type="multiple"` keeps an array. Controlled via
+ * `value`/`onValueChange`. Buttons share edges like a ButtonGroup.
+ */
+type SingleProps = {
+  type?: 'single'
+  value: string | null
+  onValueChange: (value: string | null) => void
+}
+type MultipleProps = {
+  type: 'multiple'
+  value: string[]
+  onValueChange: (value: string[]) => void
+}
+export type ToggleButtonGroupProps = (SingleProps | MultipleProps) &
+  NoStyle<Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'>>
+
+interface ToggleGroupValue {
+  isSelected: (itemValue: string) => boolean
+  toggle: (itemValue: string) => void
+}
+const ToggleGroupContext = React.createContext<ToggleGroupValue | null>(null)
+
+export function ToggleButtonGroup({
+  type = 'single', value, onValueChange, children, ...props
+}: ToggleButtonGroupProps) {
+  const contextValue = React.useMemo<ToggleGroupValue>(() => {
+    if (type === 'multiple') {
+      const values = (value as string[]) ?? []
+      return {
+        isSelected: (itemValue) => values.includes(itemValue),
+        toggle: (itemValue) =>
+          (onValueChange as MultipleProps['onValueChange'])(
+            values.includes(itemValue) ? values.filter((existing) => existing !== itemValue) : [...values, itemValue],
+          ),
+      }
+    }
+    return {
+      isSelected: (itemValue) => value === itemValue,
+      toggle: (itemValue) => (onValueChange as SingleProps['onValueChange'])(value === itemValue ? null : itemValue),
+    }
+  }, [type, value, onValueChange])
+
+  return (
+    <ToggleGroupContext.Provider value={contextValue}>
+      <div
+        role="group"
+        className={cn(
+          'inline-flex isolate',
+          '[&>*]:rounded-none [&>*:first-child]:rounded-l-lg [&>*:last-child]:rounded-r-lg [&>*:not(:first-child)]:-ml-px',
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    </ToggleGroupContext.Provider>
+  )
+}
+
+const toggleButton = cva(
+  'inline-flex h-10 items-center justify-center gap-2 border border-strong px-4 text-sm font-medium transition-colors ' +
+    'disabled:opacity-50 disabled:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 ' + focusRingInset,
+  {
+    variants: {
+      selected: {
+        true:  'z-10 bg-surface-inverse text-inverse border-transparent',
+        false: 'bg-surface text-secondary hover:bg-surface-subtle hover:text-primary',
+      },
+    },
+  },
+)
+
+export interface ToggleButtonProps extends NoStyle<React.ButtonHTMLAttributes<HTMLButtonElement>> {
+  value: string
+}
+
+export const ToggleButton = React.forwardRef<HTMLButtonElement, ToggleButtonProps>(
+  ({ value, onClick, ...props }, ref) => {
+    const group = React.useContext(ToggleGroupContext)
+    const selected = group?.isSelected(value) ?? false
+    return (
+      <button
+        ref={ref}
+        type="button"
+        aria-pressed={selected}
+        className={cn(toggleButton({ selected }))}
+        onClick={(event) => {
+          group?.toggle(value)
+          onClick?.(event)
+        }}
+        {...props}
+      />
+    )
+  },
+)
+ToggleButton.displayName = 'ToggleButton'

package/src/components/tooltip.tsx

@@ -0,0 +1,26 @@
+import * as React from 'react'
+import * as TooltipPrimitive from '@radix-ui/react-tooltip'
+import { cn } from '../lib/utils'
+import type { NoStyle } from '../lib/types'
+
+export const TooltipProvider = TooltipPrimitive.Provider
+export const Tooltip = TooltipPrimitive.Root
+export const TooltipTrigger = TooltipPrimitive.Trigger
+
+export const TooltipContent = React.forwardRef<
+  React.ElementRef<typeof TooltipPrimitive.Content>,
+  NoStyle<React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>>
+>(({ sideOffset = 6, ...props }, ref) => (
+  <TooltipPrimitive.Portal>
+    <TooltipPrimitive.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      className={cn(
+        'z-50 overflow-hidden rounded-md bg-surface-inverse px-2.5 py-1.5 text-sm font-medium text-inverse shadow-md',
+        'animate-scale-in',
+      )}
+      {...props}
+    />
+  </TooltipPrimitive.Portal>
+))
+TooltipContent.displayName = TooltipPrimitive.Content.displayName

package/src/icons/forge-icon.tsx

@@ -0,0 +1,55 @@
+import * as React from 'react'
+import { cn } from '../lib/utils'
+
+/**
+ * The Windforge brand mark — a hammer ("forge") fused with a wind swirl.
+ * Plain SVG (no MUI SvgIcon dependency): sized by `className` (default 1.5rem),
+ * renders the brand purple gradient. The gradient id is per-instance (useId) so
+ * many marks on one page stay collision-free.
+ */
+const WINDFORGE_PATH =
+  'M403.1,144.03 403.39,140.32 401.1,134.61 349.97,85.76 345.97,84.05 340.26,84.62 328.27,95.47 324.84,95.47 283.14,58.34 270,52.06 262,52.63 252.86,57.77 200.02,115.75 196.59,122.04 199.44,131.75 261.71,190.02 256,202.02 236.01,230.58 236.29,232.58 260.28,236.01 290.56,242.86 327.69,257.14 351.69,273.14 390.53,310.27 394.53,311.98 399.67,311.41 403.39,308.27 455.37,248.86 461.09,236.86 461.09,229.44 456.52,219.72 394.82,160.88 394.82,157.46 403.1,144.03Z M138.03,155.46 150.6,154.89 159.74,157.17 180.31,169.74 177.16,161.45 169.74,150.03 156.31,137.75 143.17,130.89 130.04,127.46 110.61,127.46 95.76,131.46 78.62,141.17 66.34,153.46 56.06,171.17 50.91,192.3 50.91,204.3 53.77,219.72 57.77,230.58 66.34,244.86 86.05,263.43 102.61,272.57 115.18,277.14 148.89,283.42 183.73,284.56 246.57,279.99 272.85,280.56 295.13,283.42 316.27,288.56 334.55,295.42 355.69,306.27 372.82,318.27 373.68,317.41 351.12,293.7 339.69,283.99 320.84,271.42 297.99,260.57 257.43,249.14 167.17,236.58 139.75,228.01 124.89,219.44 115.47,210.01 111.47,203.16 108.61,193.45 109.18,180.88 113.75,170.02 120.89,162.31 131.18,156.6 138.03,155.46Z M277.42,296.56 276.28,294.28 248.29,293.13 182.59,297.13 88.62,402.53 84.05,412.24 83.48,424.81 85.76,432.24 92.05,442.52 102.04,451.95 116.32,458.8 129.46,459.94 143.75,454.23 277.42,296.56Z'
+
+export interface ForgeIconProps extends React.SVGProps<SVGSVGElement> {}
+
+export const ForgeIcon = React.forwardRef<SVGSVGElement, ForgeIconProps>(
+  ({ className, ...props }, ref) => {
+    const gradId = `forge-${React.useId().replace(/:/g, '')}`
+    return (
+      <svg
+        ref={ref}
+        viewBox="0 0 512 512"
+        role="img"
+        aria-label="Windforge"
+        className={cn('h-6 w-6', className)}
+        {...props}
+      >
+        <defs>
+          <linearGradient id={gradId} x1="0" y1="1" x2="1" y2="0">
+            <stop offset="0" stopColor="var(--wf-color-brand-primary-active)" />
+            <stop offset="1" stopColor="var(--wf-color-brand-secondary)" />
+          </linearGradient>
+        </defs>
+        <path fill={`url(#${gradId})`} fillRule="evenodd" d={WINDFORGE_PATH} />
+      </svg>
+    )
+  },
+)
+ForgeIcon.displayName = 'ForgeIcon'
+
+export interface WindforgeLogoProps {
+  className?: string
+  /** Hide the wordmark, show only the mark. */
+  markOnly?: boolean
+}
+
+export function WindforgeLogo({ className, markOnly = false }: WindforgeLogoProps) {
+  return (
+    <span className={cn('inline-flex items-center gap-2.5', className)}>
+      <ForgeIcon className="h-8 w-8 drop-shadow-sm" />
+      {!markOnly && (
+        <span className="text-base font-bold tracking-tight text-primary leading-none">WindForge</span>
+      )}
+    </span>
+  )
+}

package/src/icons/icon-set.ts

@@ -0,0 +1,60 @@
+import {
+  // arrows & chevrons
+  ArrowUp, ArrowDown, ArrowLeft, ArrowRight, ArrowUpRight, ChevronUp, ChevronDown,
+  ChevronLeft, ChevronRight, ChevronsUpDown, ChevronsLeft, ChevronsRight, CornerDownLeft,
+  // navigation & layout
+  Menu, MoreHorizontal, MoreVertical, Home, Search, LayoutDashboard, LayoutGrid,
+  PanelLeft, PanelRight, PanelTop, Map, MapPin, Globe, ExternalLink, Link, Filter,
+  // actions
+  Plus, Minus, X, Check, Copy, ClipboardCheck, Pencil, Trash2, Save, Download, Upload,
+  Share2, RefreshCw, RotateCw, Settings, SlidersHorizontal, Send, Eye, EyeOff, Maximize2,
+  // status & feedback
+  Info, AlertTriangle, AlertCircle, CheckCircle2, XCircle, HelpCircle, Ban, ShieldCheck,
+  Shield, Bell, BellRing, BellOff, LoaderCircle, Star, Heart, Bookmark, Flag, ThumbsUp,
+  // files & data
+  File, FileText, Folder, FolderOpen, Image, Paperclip, Inbox, Archive, Package, Box,
+  Boxes, Database, Server, Cloud, Calendar, Clock,
+  // communication
+  Mail, MessageSquare, MessageCircle, Phone, AtSign, Hash, Megaphone, Rss,
+  // media
+  Play, Pause, SkipForward, SkipBack, Volume2, VolumeX, Mic, MicOff, Camera, Video, Music,
+  // text & formatting
+  Bold, Italic, Underline, AlignLeft, AlignCenter, AlignRight, AlignJustify, List,
+  ListOrdered, ListChecks, Type, Code2, Quote,
+  // people & commerce
+  User, Users, UserPlus, CircleUser, LogIn, LogOut, CreditCard, ShoppingCart, DollarSign,
+  Wallet, Gift, Briefcase, Building2,
+  // toggles & shapes
+  ToggleLeft, ToggleRight, Circle, CircleDot, CircleDashed, Square, CheckSquare, Shapes, Tag,
+  // theming & system
+  Palette, SwatchBook, Sun, Moon, MonitorSmartphone, Sparkles, Rocket, Zap, Layers, Ruler,
+  Gauge, Accessibility, Lock, Unlock, Bot, Terminal, GitBranch, TrendingUp, Activity,
+  type LucideIcon,
+} from 'lucide-react'
+
+/**
+ * COMMONLY-USED LUCIDE ICONS — a reference selection, grouped by purpose.
+ *
+ * lucide-react is the design system's supported icon library; consumers import
+ * icons directly from it. These are NOT re-exported as Windforge icons — this
+ * map just powers a browsable, on-brand subset on the Iconography page (the ones
+ * the system actually uses plus the obvious gaps), with an escape hatch to the
+ * full library for the long tail. Object-shorthand keys keep each entry's name in
+ * sync with its component, and the explicit imports keep this list tree-shakeable.
+ */
+export const commonIconGroups: { label: string; icons: Record<string, LucideIcon> }[] = [
+  { label: 'Arrows & chevrons', icons: { ArrowUp, ArrowDown, ArrowLeft, ArrowRight, ArrowUpRight, ChevronUp, ChevronDown, ChevronLeft, ChevronRight, ChevronsUpDown, ChevronsLeft, ChevronsRight, CornerDownLeft } },
+  { label: 'Navigation & layout', icons: { Menu, MoreHorizontal, MoreVertical, Home, Search, LayoutDashboard, LayoutGrid, PanelLeft, PanelRight, PanelTop, Map, MapPin, Globe, ExternalLink, Link, Filter } },
+  { label: 'Actions', icons: { Plus, Minus, X, Check, Copy, ClipboardCheck, Pencil, Trash2, Save, Download, Upload, Share2, RefreshCw, RotateCw, Settings, SlidersHorizontal, Send, Eye, EyeOff, Maximize2 } },
+  { label: 'Status & feedback', icons: { Info, AlertTriangle, AlertCircle, CheckCircle2, XCircle, HelpCircle, Ban, ShieldCheck, Shield, Bell, BellRing, BellOff, LoaderCircle, Star, Heart, Bookmark, Flag, ThumbsUp } },
+  { label: 'Files & data', icons: { File, FileText, Folder, FolderOpen, Image, Paperclip, Inbox, Archive, Package, Box, Boxes, Database, Server, Cloud, Calendar, Clock } },
+  { label: 'Communication', icons: { Mail, MessageSquare, MessageCircle, Phone, AtSign, Hash, Megaphone, Rss } },
+  { label: 'Media', icons: { Play, Pause, SkipForward, SkipBack, Volume2, VolumeX, Mic, MicOff, Camera, Video, Music } },
+  { label: 'Text & formatting', icons: { Bold, Italic, Underline, AlignLeft, AlignCenter, AlignRight, AlignJustify, List, ListOrdered, ListChecks, Type, Code2, Quote } },
+  { label: 'People & commerce', icons: { User, Users, UserPlus, CircleUser, LogIn, LogOut, CreditCard, ShoppingCart, DollarSign, Wallet, Gift, Briefcase, Building2 } },
+  { label: 'Toggles & shapes', icons: { ToggleLeft, ToggleRight, Circle, CircleDot, CircleDashed, Square, CheckSquare, Shapes, Tag } },
+  { label: 'Theming & system', icons: { Palette, SwatchBook, Sun, Moon, MonitorSmartphone, Sparkles, Rocket, Zap, Layers, Ruler, Gauge, Accessibility, Lock, Unlock, Bot, Terminal, GitBranch, TrendingUp, Activity } },
+]
+
+/** The flat name → component map across all groups. */
+export const commonIcons: Record<string, LucideIcon> = Object.assign({}, ...commonIconGroups.map((g) => g.icons))

package/src/icons/svg-icon.tsx

@@ -0,0 +1,43 @@
+import * as React from 'react'
+
+export interface SVGIconProps extends React.SVGProps<SVGSVGElement> {
+  /** SVG viewBox — defaults to the 24×24 grid lucide draws on, so custom icons
+   *  line up with the rest of the set. */
+  viewBox?: string
+  /** Accessible label. Omit for a purely decorative icon (rendered aria-hidden). */
+  label?: string
+}
+
+/**
+ * SVGIcon — render a custom icon with the same conventions as the supported
+ * lucide set: a 24×24 viewBox, 2px round strokes painted in `currentColor`, and
+ * sizing through h-/w- utilities. Pass the shape as children; override `stroke`,
+ * `fill`, or `strokeWidth` for a filled or heavier glyph.
+ *
+ *   <SVGIcon label="Spark" className="h-5 w-5 text-brand">
+ *     <path d="M12 2 4 7v10l8 5 8-5V7z" />
+ *   </SVGIcon>
+ */
+export const SVGIcon = React.forwardRef<SVGSVGElement, SVGIconProps>(
+  ({ viewBox = '0 0 24 24', label, children, ...props }, ref) => (
+    <svg
+      ref={ref}
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox={viewBox}
+      width={24}
+      height={24}
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      role={label ? 'img' : undefined}
+      aria-label={label}
+      aria-hidden={label ? undefined : true}
+      {...props}
+    >
+      {children}
+    </svg>
+  ),
+)
+SVGIcon.displayName = 'SVGIcon'

package/src/index.ts

@@ -0,0 +1,80 @@
+/**
+ * @windforge/ui — the single import surface.
+ *
+ * Re-exports every component, layout, the brand mark, the `cn` helper, and the
+ * full @windforge/tokens surface (wf* constants, brandVars/brandRamp, source maps).
+ * Consumers import from here and nowhere else.
+ */
+
+// ── catalog (machine-readable component registry) ──
+export * from './catalog'
+
+// ── utilities ──
+export { cn } from './lib/utils'
+export { useMediaQuery } from './lib/use-media-query'
+export * from './lib/recipes'
+
+// ── primitives ──
+export * from './components/button'
+export * from './components/button-group'
+export * from './components/toggle-button'
+export * from './components/badge'
+export * from './components/chip'
+export * from './components/text'
+export * from './components/link'
+export * from './components/card'
+export * from './components/input'
+export * from './components/textarea'
+export * from './components/label'
+export * from './components/form-field'
+export * from './components/separator'
+export * from './components/skeleton'
+export * from './components/code-block'
+export * from './components/alert'
+export * from './components/layout'
+
+// ── interactive (Radix-backed) ──
+export * from './components/switch'
+export * from './components/checkbox'
+export * from './components/radio-group'
+export * from './components/tabs'
+export * from './components/tooltip'
+export * from './components/select'
+export * from './components/autocomplete'
+export * from './components/modal'
+export * from './components/dialog'
+export * from './components/pagination'
+export * from './components/stepper'
+export * from './components/toast'
+export * from './components/accordion'
+export * from './components/avatar'
+export * from './components/progress'
+export * from './components/slider'
+export * from './components/popover'
+export * from './components/dropdown-menu'
+export * from './components/table'
+export * from './components/data-table'
+export * from './components/breadcrumb'
+export * from './components/sheet'
+export * from './components/multi-select'
+export * from './components/command'
+export * from './components/calendar'
+export * from './components/date-picker'
+export * from './components/chart'
+
+// ── brand & icons ──
+// lucide-react is the supported icon library (imported directly by consumers).
+// `commonIcons`/`commonIconGroups` are a reference selection for the docs gallery;
+// `SVGIcon` wraps a custom SVG in the same conventions.
+export * from './icons/forge-icon'
+export * from './icons/svg-icon'
+export { commonIcons, commonIconGroups } from './icons/icon-set'
+
+// ── layouts ──
+export * from './layouts/theme-provider'
+export * from './layouts/app-shell'
+export * from './layouts/side-nav'
+export * from './layouts/app-bar'
+
+// ── tokens (single token surface) ──
+export * from '@windforge/tokens'