@automa8e/ui 0.2.0

package/src/hooks/use-media-query.ts

@@ -0,0 +1,29 @@
+import { useState, useEffect } from 'react'
+
+/**
+ * Returns whether the given media query currently matches.
+ *
+ * @example
+ * const isMobile = useMediaQuery('(max-width: 768px)')
+ * const isDesktop = useMediaQuery('(min-width: 1024px)')
+ */
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState<boolean>(() => {
+    if (typeof window === 'undefined') return false
+    return window.matchMedia(query).matches
+  })
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+
+    const mediaQuery = window.matchMedia(query)
+    const handler = (event: MediaQueryListEvent) => setMatches(event.matches)
+
+    setMatches(mediaQuery.matches)
+    mediaQuery.addEventListener('change', handler)
+
+    return () => mediaQuery.removeEventListener('change', handler)
+  }, [query])
+
+  return matches
+}

package/src/index.ts

@@ -0,0 +1,197 @@
+/**
+ * @automa8e/ui
+ * Production-grade, dark-industrial React component library for the automa8e platform.
+ *
+ * @example
+ * import { Button, StatusBadge, MetricCard } from '@automa8e/ui'
+ * import '@automa8e/ui/styles'
+ */
+
+// ─── Styles (emitted as automa8e-ui.css) ────────────────────────────────────
+import './styles/globals.css'
+
+// ─── Utilities ───────────────────────────────────────────────────────────────
+export { cn } from './lib/utils'
+export { Colors } from './lib/colors'
+export type { ColorKey, ColorValue } from './lib/colors'
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+export type { Size, Intent, Orientation, BaseLayoutProps } from './types/common'
+export type {
+  WorkflowStatus,
+  TaskPriority,
+  TaskStatus,
+  TrendDirection,
+  Metric,
+  WorkflowNodeData,
+  Task,
+  LogEntry,
+} from './types/automation'
+
+// ─── Core UI ─────────────────────────────────────────────────────────────────
+export { Button, buttonVariants } from './components/ui/button'
+export type { ButtonProps } from './components/ui/button'
+
+export { Input } from './components/ui/input'
+export type { InputProps } from './components/ui/input'
+
+export { Textarea } from './components/ui/textarea'
+export type { TextareaProps } from './components/ui/textarea'
+
+export { Label } from './components/ui/label'
+export type { LabelProps } from './components/ui/label'
+
+export { Badge, badgeVariants } from './components/ui/badge'
+export type { BadgeProps } from './components/ui/badge'
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardDescription,
+  CardContent,
+} from './components/ui/card'
+export type { CardProps } from './components/ui/card'
+
+export { Avatar, AvatarImage, AvatarFallback, AvatarGroup } from './components/ui/avatar'
+export type { AvatarProps } from './components/ui/avatar'
+
+export { Separator } from './components/ui/separator'
+export type { SeparatorProps } from './components/ui/separator'
+
+export { Skeleton } from './components/ui/skeleton'
+export type { SkeletonProps } from './components/ui/skeleton'
+
+export { Progress } from './components/ui/progress'
+export type { ProgressProps } from './components/ui/progress'
+
+export { Spinner, spinnerVariants } from './components/ui/spinner'
+export type { SpinnerProps } from './components/ui/spinner'
+
+// ─── Form ────────────────────────────────────────────────────────────────────
+export { Checkbox } from './components/ui/checkbox'
+export type { CheckboxProps } from './components/ui/checkbox'
+
+export { Switch } from './components/ui/switch'
+export type { SwitchProps } from './components/ui/switch'
+
+export {
+  Select,
+  SelectGroup,
+  SelectValue,
+  SelectTrigger,
+  SelectContent,
+  SelectLabel,
+  SelectItem,
+  SelectSeparator,
+  SelectScrollUpButton,
+  SelectScrollDownButton,
+} from './components/ui/select'
+
+// ─── Navigation ──────────────────────────────────────────────────────────────
+export { Tabs, TabsList, TabsTrigger, TabsContent } from './components/ui/tabs'
+export type { TabsListProps, TabsTriggerProps } from './components/ui/tabs'
+
+export {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from './components/ui/accordion'
+
+// ─── Overlay ─────────────────────────────────────────────────────────────────
+export {
+  Dialog,
+  DialogPortal,
+  DialogOverlay,
+  DialogClose,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+  DialogTitle,
+  DialogDescription,
+} from './components/ui/dialog'
+export type { DialogContentProps } from './components/ui/dialog'
+
+export {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuGroup,
+  DropdownMenuPortal,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuRadioGroup,
+} from './components/ui/dropdown-menu'
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from './components/ui/tooltip'
+
+export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor } from './components/ui/popover'
+
+export { Alert, AlertTitle, AlertDescription } from './components/ui/alert'
+export type { AlertProps } from './components/ui/alert'
+
+export {
+  ToastProvider,
+  ToastViewport,
+  Toast,
+  ToastTitle,
+  ToastDescription,
+  ToastClose,
+  ToastAction,
+} from './components/ui/toast'
+export type { ToastProps, ToastActionElement } from './components/ui/toast'
+
+// ─── Data Display ────────────────────────────────────────────────────────────
+export {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption,
+} from './components/ui/table'
+
+export { ScrollArea, ScrollBar } from './components/ui/scroll-area'
+
+// ─── Automation ──────────────────────────────────────────────────────────────
+export { StatusBadge, STATUS_CONFIG } from './components/automation/status-badge'
+export type { StatusBadgeProps } from './components/automation/status-badge'
+
+export { MetricCard, MetricGrid } from './components/automation/metric-card'
+export type { MetricCardProps, MetricGridProps } from './components/automation/metric-card'
+
+export { WorkflowNode, WorkflowPipeline } from './components/automation/workflow-node'
+export type { WorkflowNodeProps, WorkflowPipelineProps } from './components/automation/workflow-node'
+
+export { TaskCard } from './components/automation/task-card'
+export type { TaskCardProps } from './components/automation/task-card'
+
+// ─── Layout ──────────────────────────────────────────────────────────────────
+export { AppShell, PageContent } from './components/layout/app-shell'
+export type { AppShellProps } from './components/layout/app-shell'
+
+export { Sidebar } from './components/layout/sidebar'
+export type { SidebarProps, SidebarNavItem, SidebarSection } from './components/layout/sidebar'
+
+export { Header } from './components/layout/header'
+export type { HeaderProps } from './components/layout/header'
+
+export { PageHeader } from './components/layout/page-header'
+export type { PageHeaderProps } from './components/layout/page-header'
+
+// ─── Hooks ───────────────────────────────────────────────────────────────────
+export { useMediaQuery } from './hooks/use-media-query'
+export { useLocalStorage } from './hooks/use-local-storage'
+export { useDebounce } from './hooks/use-debounce'

package/src/lib/colors.ts

@@ -0,0 +1,102 @@
+/**
+ * Automa8e brand color palette.
+ * Import and use directly in inline styles, or register in your Tailwind config.
+ *
+ * @example
+ * import { Colors } from '@automa8e/ui'
+ * <div style={{ backgroundColor: Colors.primaryBlue }}>...</div>
+ */
+export const Colors = {
+  /** Soft powder blue — page backgrounds, empty states */
+  powderBlue: '#ECF2FA',
+
+  /** Active tab top bar, primary action buttons */
+  primaryBlue: '#3278A0',
+
+  /** Ultra-light gray surface */
+  grays: '#FBFBFC',
+
+  /** Soft border and divider gray */
+  softGrays: '#DDDDDD',
+
+  /** Inactive tab text and border color */
+  primaryGray: '#939598',
+
+  /** Alias for primaryBlue — used in header/nav backgrounds */
+  backgroundBlue: '#3278A0',
+
+  /** Header background blue (slightly lighter) */
+  headerBlue: '#44799E',
+
+  /** Input placeholder and mark highlight */
+  markGray: '#E0E6EE',
+
+  /** Table header background, primary body text */
+  deepBlue: '#4B506D',
+
+  /** Card and panel medium-light background */
+  mediumGray: '#F6F6F6',
+
+  /** Body text on dark backgrounds */
+  blueText: '#4B506D',
+
+  /** Inactive tab separator/shadow */
+  lineGray: '#C7C8CA',
+
+  /** Semi-transparent blue-gray for hover states */
+  grayBlueBackground: '#DFE0EB33',
+
+  /** Solid powder-blue background variant */
+  grayBlueBackground2: '#ECF2FA',
+
+  /** Primary orange — CTAs, highlights, warnings */
+  primaryOrange: '#FC6501',
+
+  /** Success green */
+  success: '#1E791C',
+
+  /** Success state background */
+  successGray: '#EEEFEF',
+
+  /** Deep orange / error red */
+  deepOrange: '#D84132',
+
+  /** Neutral light background */
+  f3Gray: '#F3F3F3',
+
+  /** Soft blue card background */
+  softBlue: '#E7F5FD',
+
+  /** Light page background */
+  lightGrey: '#F0F0F0',
+
+  /** Item and card border separators */
+  itemBorder: '#DFE0EB',
+
+  /** Pure red — danger/error indicators */
+  redDanger: '#ff0000',
+
+  /** Blue line border with opacity */
+  blueLineBorder: 'rgba(68, 121, 158, 0.5)',
+
+  /** Near-black text */
+  darkGray: '#222222',
+
+  /** Bright light gray */
+  brightGray: '#EAEAEA',
+
+  /** Light page background (alt) */
+  lightGray: '#F7F7F7',
+
+  /** Form input and card borders */
+  lightBorder: '#DDDDDD',
+
+  /** Bright accent blue */
+  babyBlue: '#0F67B1',
+} as const
+
+/** TypeScript type for any Colors key */
+export type ColorKey = keyof typeof Colors
+
+/** TypeScript type for any Colors value */
+export type ColorValue = typeof Colors[ColorKey]

package/src/lib/utils.ts

@@ -0,0 +1,10 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/**
+ * Merges Tailwind CSS class names with conflict resolution.
+ * Combines clsx (conditional classes) with tailwind-merge (deduplication).
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/src/styles/globals.css

@@ -0,0 +1,230 @@
+/* ── Google Fonts ─────────────────────────────────────────────── */
+@import url('https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700;1,9..40,400&family=IBM+Plex+Mono:wght@300;400;500;600&family=Syne:wght@400;500;600;700;800&display=swap');
+
+/* ── Design tokens ────────────────────────────────────────────── */
+:root {
+  /* ── Light mode (default, shadcn convention) ── */
+  --radius: 0.5rem;
+
+  --background:             oklch(0.99 0 0);
+  --foreground:             oklch(0.18 0.02 255);
+  --card:                   oklch(1.00 0 0);
+  --card-foreground:        oklch(0.18 0.02 255);
+  --popover:                oklch(1.00 0 0);
+  --popover-foreground:     oklch(0.18 0.02 255);
+  --primary:                oklch(0.70 0.18 52);
+  --primary-foreground:     oklch(0.99 0 0);
+  --secondary:              oklch(0.94 0.01 255);
+  --secondary-foreground:   oklch(0.22 0.02 255);
+  --muted:                  oklch(0.94 0.01 255);
+  --muted-foreground:       oklch(0.52 0.01 255);
+  --accent:                 oklch(0.94 0.01 255);
+  --accent-foreground:      oklch(0.22 0.02 255);
+  --destructive:            oklch(0.58 0.22 25);
+  --destructive-foreground: oklch(0.99 0 0);
+  --success:                oklch(0.60 0.18 145);
+  --success-foreground:     oklch(0.99 0 0);
+  --warning:                oklch(0.82 0.16 84);
+  --warning-foreground:     oklch(0.18 0.02 255);
+  --info:                   oklch(0.65 0.16 220);
+  --info-foreground:        oklch(0.99 0 0);
+  --border:                 oklch(0.88 0.01 255);
+  --input:                  oklch(0.88 0.01 255);
+  --ring:                   oklch(0.70 0.18 52);
+
+  /* sidebar */
+  --sidebar:                        oklch(0.96 0.005 255);
+  --sidebar-foreground:             oklch(0.18 0.02 255);
+  --sidebar-primary:                oklch(0.70 0.18 52);
+  --sidebar-primary-foreground:     oklch(0.99 0 0);
+  --sidebar-accent:                 oklch(0.92 0.01 255);
+  --sidebar-accent-foreground:      oklch(0.22 0.02 255);
+  --sidebar-border:                 oklch(0.88 0.01 255);
+  --sidebar-ring:                   oklch(0.70 0.18 52);
+
+  /* workflow status */
+  --workflow-running:   oklch(0.70 0.18 52);
+  --workflow-completed: oklch(0.60 0.18 145);
+  --workflow-failed:    oklch(0.58 0.22 25);
+  --workflow-pending:   oklch(0.52 0.01 255);
+  --workflow-paused:    oklch(0.82 0.16 84);
+  --workflow-cancelled: oklch(0.38 0.01 255);
+
+  /* charts */
+  --chart-1: oklch(0.70 0.18 52);
+  --chart-2: oklch(0.65 0.16 220);
+  --chart-3: oklch(0.60 0.18 145);
+  --chart-4: oklch(0.82 0.16 84);
+  --chart-5: oklch(0.58 0.22 25);
+}
+
+.dark {
+  /* ── Dark mode (automa8e default brand experience) ── */
+  --background:             oklch(0.14 0.02 255);
+  --foreground:             oklch(0.92 0.01 255);
+  --card:                   oklch(0.17 0.02 255);
+  --card-foreground:        oklch(0.92 0.01 255);
+  --popover:                oklch(0.17 0.02 255);
+  --popover-foreground:     oklch(0.92 0.01 255);
+  --primary:                oklch(0.72 0.18 52);
+  --primary-foreground:     oklch(0.14 0.02 255);
+  --secondary:              oklch(0.24 0.02 255);
+  --secondary-foreground:   oklch(0.92 0.01 255);
+  --muted:                  oklch(0.22 0.02 255);
+  --muted-foreground:       oklch(0.54 0.01 255);
+  --accent:                 oklch(0.24 0.02 255);
+  --accent-foreground:      oklch(0.92 0.01 255);
+  --destructive:            oklch(0.60 0.22 25);
+  --destructive-foreground: oklch(0.92 0.01 255);
+  --success:                oklch(0.62 0.18 145);
+  --success-foreground:     oklch(0.92 0.01 255);
+  --warning:                oklch(0.82 0.16 84);
+  --warning-foreground:     oklch(0.14 0.02 255);
+  --info:                   oklch(0.67 0.16 220);
+  --info-foreground:        oklch(0.92 0.01 255);
+  --border:                 oklch(0.26 0.02 255);
+  --input:                  oklch(0.26 0.02 255);
+  --ring:                   oklch(0.72 0.18 52);
+
+  --sidebar:                        oklch(0.17 0.02 255);
+  --sidebar-foreground:             oklch(0.92 0.01 255);
+  --sidebar-primary:                oklch(0.72 0.18 52);
+  --sidebar-primary-foreground:     oklch(0.14 0.02 255);
+  --sidebar-accent:                 oklch(0.22 0.02 255);
+  --sidebar-accent-foreground:      oklch(0.92 0.01 255);
+  --sidebar-border:                 oklch(0.26 0.02 255);
+  --sidebar-ring:                   oklch(0.72 0.18 52);
+
+  --workflow-running:   oklch(0.72 0.18 52);
+  --workflow-completed: oklch(0.62 0.18 145);
+  --workflow-failed:    oklch(0.60 0.22 25);
+  --workflow-pending:   oklch(0.54 0.01 255);
+  --workflow-paused:    oklch(0.82 0.16 84);
+  --workflow-cancelled: oklch(0.38 0.01 255);
+
+  --chart-1: oklch(0.72 0.18 52);
+  --chart-2: oklch(0.67 0.16 220);
+  --chart-3: oklch(0.62 0.18 145);
+  --chart-4: oklch(0.82 0.16 84);
+  --chart-5: oklch(0.60 0.22 25);
+}
+
+/* ── Tailwind v4 theme mapping ────────────────────────────────── */
+@theme inline {
+  /* radius */
+  --radius: 0.5rem;
+  --radius-sm:  calc(var(--radius) - 4px);
+  --radius-md:  calc(var(--radius) - 2px);
+  --radius-lg:  var(--radius);
+  --radius-xl:  calc(var(--radius) + 4px);
+
+  /* color tokens */
+  --color-background:             var(--background);
+  --color-foreground:             var(--foreground);
+  --color-card:                   var(--card);
+  --color-card-foreground:        var(--card-foreground);
+  --color-popover:                var(--popover);
+  --color-popover-foreground:     var(--popover-foreground);
+  --color-primary:                var(--primary);
+  --color-primary-foreground:     var(--primary-foreground);
+  --color-secondary:              var(--secondary);
+  --color-secondary-foreground:   var(--secondary-foreground);
+  --color-muted:                  var(--muted);
+  --color-muted-foreground:       var(--muted-foreground);
+  --color-accent:                 var(--accent);
+  --color-accent-foreground:      var(--accent-foreground);
+  --color-destructive:            var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-success:                var(--success);
+  --color-success-foreground:     var(--success-foreground);
+  --color-warning:                var(--warning);
+  --color-warning-foreground:     var(--warning-foreground);
+  --color-info:                   var(--info);
+  --color-info-foreground:        var(--info-foreground);
+  --color-border:                 var(--border);
+  --color-input:                  var(--input);
+  --color-ring:                   var(--ring);
+  --color-sidebar:                var(--sidebar);
+  --color-sidebar-foreground:     var(--sidebar-foreground);
+  --color-sidebar-primary:        var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent:         var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border:         var(--sidebar-border);
+  --color-sidebar-ring:           var(--sidebar-ring);
+  --color-workflow-running:       var(--workflow-running);
+  --color-workflow-completed:     var(--workflow-completed);
+  --color-workflow-failed:        var(--workflow-failed);
+  --color-workflow-pending:       var(--workflow-pending);
+  --color-workflow-paused:        var(--workflow-paused);
+  --color-workflow-cancelled:     var(--workflow-cancelled);
+  --color-chart-1:                var(--chart-1);
+  --color-chart-2:                var(--chart-2);
+  --color-chart-3:                var(--chart-3);
+  --color-chart-4:                var(--chart-4);
+  --color-chart-5:                var(--chart-5);
+
+  /* brand palette — static hex values, not theme-switchable */
+  --color-brand-primary-blue:   #3278A0;
+  --color-brand-header-blue:    #44799E;
+  --color-brand-deep-blue:      #4B506D;
+  --color-brand-baby-blue:      #0F67B1;
+  --color-brand-soft-blue:      #E7F5FD;
+  --color-brand-powder-blue:    #ECF2FA;
+  --color-brand-primary-orange: #FC6501;
+  --color-brand-deep-orange:    #D84132;
+  --color-brand-success-green:  #1E791C;
+  --color-brand-red-danger:     #ff0000;
+  --color-brand-primary-gray:   #939598;
+  --color-brand-dark-gray:      #222222;
+  --color-brand-item-border:    #DFE0EB;
+  --color-brand-line-gray:      #C7C8CA;
+  --color-brand-mark-gray:      #E0E6EE;
+
+  /* typography */
+  --font-sans:    "DM Sans", sans-serif;
+  --font-mono:    "IBM Plex Mono", monospace;
+  --font-display: "Syne", sans-serif;
+}
+
+/* ── Keyframes ────────────────────────────────────────────────── */
+@keyframes accordion-down {
+  from { height: 0 }
+  to   { height: var(--radix-accordion-content-height) }
+}
+@keyframes accordion-up {
+  from { height: var(--radix-accordion-content-height) }
+  to   { height: 0 }
+}
+@keyframes fade-in {
+  from { opacity: 0; transform: translateY(4px) }
+  to   { opacity: 1; transform: translateY(0) }
+}
+@keyframes slide-in-right {
+  from { transform: translateX(100%); opacity: 0 }
+  to   { transform: translateX(0);    opacity: 1 }
+}
+@keyframes workflow-pulse {
+  0%, 100% { opacity: 1;   box-shadow: 0 0  8px color-mix(in oklch, var(--workflow-running) 50%, transparent) }
+  50%       { opacity: 0.6; box-shadow: 0 0 20px color-mix(in oklch, var(--workflow-running) 80%, transparent) }
+}
+@keyframes shimmer {
+  0%   { background-position: -200% 0 }
+  100% { background-position:  200% 0 }
+}
+@keyframes spin-slow {
+  from { transform: rotate(0deg) }
+  to   { transform: rotate(360deg) }
+}
+
+/* ── Base layer ───────────────────────────────────────────────── */
+@layer base {
+  * { border-color: var(--color-border); }
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+}

package/src/types/automation.ts

@@ -0,0 +1,74 @@
+/**
+ * Automation domain types for the automa8e platform.
+ */
+
+/** All possible states a workflow or automation run can be in. */
+export type WorkflowStatus =
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'pending'
+  | 'paused'
+  | 'cancelled'
+  | 'idle'
+  | 'scheduled'
+
+/** Task priority levels. */
+export type TaskPriority = 'critical' | 'high' | 'medium' | 'low'
+
+/** Task execution status. */
+export type TaskStatus = 'running' | 'completed' | 'failed' | 'pending' | 'skipped' | 'cancelled'
+
+/** Metric trend direction. */
+export type TrendDirection = 'up' | 'down' | 'flat'
+
+/** Represents a single metric to display in a MetricCard. */
+export interface Metric {
+  label: string
+  value: string | number
+  unit?: string
+  previousValue?: string | number
+  trend?: TrendDirection
+  trendPercent?: number
+  description?: string
+}
+
+/** Represents a workflow node in a pipeline visualization. */
+export interface WorkflowNodeData {
+  id: string
+  label: string
+  type: 'trigger' | 'action' | 'condition' | 'delay' | 'output'
+  status: WorkflowStatus
+  description?: string
+  executedAt?: Date | string
+  duration?: number /** milliseconds */
+  error?: string
+}
+
+/** Represents a single task in a task list. */
+export interface Task {
+  id: string
+  title: string
+  description?: string
+  status: TaskStatus
+  priority: TaskPriority
+  assignee?: {
+    name: string
+    avatarUrl?: string
+    initials?: string
+  }
+  tags?: string[]
+  dueAt?: Date | string
+  createdAt?: Date | string
+  completedAt?: Date | string
+}
+
+/** Represents a log entry for the automation log viewer. */
+export interface LogEntry {
+  id: string
+  level: 'info' | 'warn' | 'error' | 'debug' | 'success'
+  message: string
+  timestamp: Date | string
+  source?: string
+  meta?: Record<string, unknown>
+}

package/src/types/common.ts

@@ -0,0 +1,48 @@
+import type { ComponentPropsWithoutRef, ElementRef, HTMLAttributes } from 'react'
+
+/**
+ * Utility to make certain keys of a type required.
+ */
+export type RequiredKeys<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>
+
+/**
+ * Utility to extract the ref type from a component.
+ */
+export type ComponentRef<T extends React.ElementType> = ElementRef<T>
+
+/**
+ * Utility to extract props from a component.
+ */
+export type ComponentProps<T extends React.ElementType> = ComponentPropsWithoutRef<T>
+
+/**
+ * Common size variants used across components.
+ */
+export type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+
+/**
+ * Common intent/color variants for semantic meaning.
+ */
+export type Intent = 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'destructive' | 'info'
+
+/**
+ * Common orientation.
+ */
+export type Orientation = 'horizontal' | 'vertical'
+
+/**
+ * Polymorphic component ref helper.
+ */
+export type PolymorphicRef<C extends React.ElementType> = React.ComponentPropsWithRef<C>['ref']
+
+/**
+ * Base props for all layout components.
+ */
+export interface BaseLayoutProps extends HTMLAttributes<HTMLDivElement> {
+  children?: React.ReactNode
+  className?: string
+}
+
+// Re-export React for convenience
+import type React from 'react'
+export type { React }