@od-oneapp/uni-ui 2026.1.1301

package/README.md

@@ -0,0 +1,753 @@
+# @od-oneapp/uni-ui
+
+The core component library for the platform, built with React, Tailwind CSS v4, and Framer Motion.
+
+## AI Chat Hooks
+
+This package now includes enhanced AI chat hooks migrated from the deprecated `@repo/ai` package:
+
+```typescript
+import {
+  AiChatProvider,
+  useAiInput,
+  useBranchNavigation,
+  useMessageActions,
+  type AiChatMessage
+} from "@od-oneapp/uni-ui/hooks/ai-chat";
+```
+
+**Available hooks:**
+
+- `useAiInput` - Enhanced input management with template variables and attachment handling
+- `useBranchNavigation` - Navigate message conversation branches
+- `useMessageActions` - Message editing, deletion, and regeneration
+
+**React 19 Compatible**: Hooks use modern React patterns including `useId`, `useActionState`, and proper cleanup with
+timer managers.
+
+## Modernization Standard: Premium Harmony V2
+
+All components in this package are being modernized to meet the **Premium Harmony V2** standard. This standard focuses
+on tactile feedback, fluid motion, and touch-first ergonomics.
+
+### 1. Touch-First Ergonomics
+
+- **Minimum Hit Targets**: All interactive elements (buttons, links, form controls) MUST have a minimum hit target of
+  **44px**.
+- **Touch Variants**: Atoms like `Button` and `Badge` provide a `size="touch"` variant that guarantees this size while
+  maintaining visual proportionality.
+
+### 2. Micromoments & Tactile Feedback
+
+- **Active Scaling**: Interactive elements should respond to user intent with subtle scaling.
+  - `whileTap={{ scale: 0.98 }}` for buttons and links.
+  - `whileHover={{ scale: 1.01 }}` for cards, list items, and larger interactive blocks.
+- **Spring Physics**: Use high-quality spring physics for all transforms.
+  - **Standard Spring**: `{ type: 'spring', stiffness: 400, damping: 25 }`
+  - **Fluid Spring**: `{ type: 'spring', stiffness: 300, damping: 30 }` (used for larger layout shifts).
+
+### 3. Motion & Transitions
+
+- **Entrance Animations**: Containers should use staggered children entrance.
+- **Dynamic Layouts**: Use `AnimatePresence` for all conditional rendering.
+  - `mode="wait"`: Use for sequential step transitions (e.g., Wizards, Modals).
+  - `mode="popLayout"`: Use for list items to prevent layout jumps during removal.
+  - Omit `mode` for simple overlays.
+- **Height Animations**: Use `motion.div` with `AnimatePresence` for collapsible sections instead of pure CSS
+  transitions to ensure robustness.
+- **Accessibility**: Respect `prefers-reduced-motion` by wrapping animation configurations or using motion's
+  `useReducedMotion` hook.
+  - **WCAG 2.1 Compliance**: Always switch to no-animation or minimal-animation variants (e.g., opacity-only, no
+    stagger) when reduced motion is preferred.
+  ```tsx
+  const prefersReducedMotion = useMediaQuery("(prefers-reduced-motion: reduce)");
+  const containerVariants = prefersReducedMotion
+    ? { initial: {}, animate: {} }
+    : { initial: { opacity: 0 }, animate: { opacity: 1 } };
+  ```
+
+### 4. Technical Requirements
+
+- **Styling**: Tailwind CSS v4 variables (e.g., `text-foreground`, `bg-background`, `border-border/50`).
+- **Composition**: Use the `cn()` utility for merging classes.
+- **Type Safety**: Use `as const` for animation variants to prevent widening types.
+- **React Patterns**: Prefer `useActionState` (or `useFormState` for older react versions), `useTransition`, and
+  `useRef`.
+
+## ⚠️ Breaking Changes & Migration
+
+The following components have updated public APIs to support Premium Harmony V2. These changes primarily involve moving
+to physics-based transitions and standardized touch targets.
+
+### Impacted Components
+
+- `Actions`, `Artifact`, `Branch`, `ChainOfThought`, `ChatInput`, `Checkpoint`, `CodeBlock`, `Confirmation`, `Context`,
+  `Conversation`, `Image`, `InlineCitation`, `Loader`, `Message`, `OpenIn`, `Plan`, `PromptCharCounter`, `PromptInput`,
+  `Queue`, `Reasoning`, `Shimmer`, `Sources`, `Suggestion`, `Task`, `ToolApproval`, `Tool`, `WebPreview`
+
+### Migration Strategy
+
+- **Versioning**: These updates are part of a semver major bump.
+- **Migration Path**: See [MIGRATION.md](./MIGRATION.md) for step-by-step guidance on updating your component usage.
+  Codemods for automated migration are currently under development.
+- **Support Window**: Legacy APIs will be supported via a compatibility layer for 6 months from the release of V2.
+
+---
+
+## 🦾 AI Agent Prompt: Modernize to Premium Harmony V2
+
+Use the following prompt to guide other AI agents in modernizing components to this standard:
+
+````markdown
+**Task**: Modernize the provided component to "Premium Harmony V2" standards with fluid, harmonious animations.
+
+**Context**:
+
+- Project: React 19 / Next.js 16
+- Styling: Tailwind CSS v4 (CSS-first variables with `@theme` directive)
+- Animation: motion (formerly framer-motion) imported from `motion/react`
+- Hooks: `@mantine/hooks` for state management (`useReducedMotion`, `useUncontrolled`, `useFocusWithin`)
+
+---
+
+## 1. Harmonious Motion Philosophy
+
+Create animations that feel connected to surrounding components—not isolated effects.
+
+**Spring Physics (Unified Feel)**:
+
+```tsx
+// Standard spring for micro-interactions (buttons, toggles)
+const SPRING_TACTILE = { type: "spring", stiffness: 400, damping: 25 } as const;
+
+// Fluid spring for layout shifts (cards, panels, accordions)
+const SPRING_FLUID = { type: "spring", stiffness: 300, damping: 30 } as const;
+
+// Gentle spring for large containers (modals, drawers)
+const SPRING_GENTLE = { type: "spring", stiffness: 200, damping: 28 } as const;
+```
+
+**Coordinated Timing**:
+
+- Parent components should complete 80% of their animation before children begin
+- Stagger delays: `0.03s` (fast lists), `0.05s` (standard), `0.08s` (dramatic)
+- Total entrance duration: never exceed 400ms (`count * stagger + duration`)
+
+---
+
+## 2. Responsive & Adaptive Design
+
+**Breakpoint-Aware Animations**:
+
+```tsx
+import { useMediaQuery } from "@mantine/hooks";
+
+const isMobile = useMediaQuery("(max-width: 640px)");
+const isTablet = useMediaQuery("(min-width: 641px) and (max-width: 1024px)");
+
+// Scale down motion intensity on mobile for performance
+const motionIntensity = isMobile ? 0.5 : 1;
+const animationDistance = isMobile ? 10 : 20; // Smaller travel on mobile
+```
+
+**Container Queries** (Tailwind v4):
+
+```tsx
+// Use @container for component-level responsiveness
+<div className="@container">
+  <div className="flex flex-col gap-2 @sm:flex-row @md:gap-4">{/* Adapts to container, not viewport */}</div>
+</div>
+```
+
+---
+
+## 3. Touch vs Desktop Interactions
+
+**Adaptive Tactile Feedback**:
+
+```tsx
+import { useMediaQuery } from "@mantine/hooks";
+
+const hasHover = useMediaQuery("(hover: hover) and (pointer: fine)");
+const isTouch = useMediaQuery("(pointer: coarse)");
+
+// Desktop: subtle hover effects
+// Touch: immediate tap feedback, no hover states
+const interactionProps = hasHover
+  ? {
+      whileHover: { scale: 1.01, backgroundColor: "var(--color-bg-primary_hover)" },
+      whileTap: { scale: 0.98 }
+    }
+  : {
+      whileTap: { scale: 0.96 } // More pronounced on touch
+    };
+```
+
+**Touch Target Standards**:
+
+```tsx
+// Minimum 44x44px for all interactive elements (WCAG 2.5.5)
+className = "min-h-[44px] min-w-[44px]";
+
+// For inline actions, use padding to expand hit area
+className = "relative before:absolute before:-inset-2 before:content-['']";
+```
+
+---
+
+## 4. Pseudo-Element & State Styling
+
+**Modern Pseudo-Element Patterns**:
+
+```tsx
+// Focus ring (keyboard-only)
+className = "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2";
+
+// Hover overlay effect
+className =
+  "relative before:absolute before:inset-0 before:rounded-lg before:bg-foreground/0 before:transition-colors hover:before:bg-foreground/5";
+
+// Active/pressed state
+className = "active:bg-accent/80 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground";
+
+// Disabled state
+className = "disabled:pointer-events-none disabled:opacity-50";
+
+// Selection highlight
+className = "selection:bg-primary/20 selection:text-primary";
+```
+
+**Data Attribute States**:
+
+```tsx
+// For controlled components
+data-state={isOpen ? 'open' : 'closed'}
+data-loading={isLoading || undefined}
+data-pending={isPending || undefined}
+
+// CSS targeting
+className="data-[state=open]:rotate-180 data-[loading=true]:animate-pulse"
+```
+
+---
+
+## 5. Dark/Light Mode Theming
+
+**Semantic Color System**:
+
+```tsx
+// ✅ Use semantic tokens (auto-adapt to theme)
+className = "bg-background text-foreground border-border";
+className = "bg-card text-card-foreground";
+className = "bg-muted text-muted-foreground";
+className = "bg-accent text-accent-foreground";
+className = "bg-destructive text-destructive-foreground";
+
+// ✅ State-aware colors
+className = "bg-success/10 text-success border-success/30";
+className = "bg-warning/10 text-warning border-warning/30";
+className = "bg-error/10 text-error border-error/30";
+
+// ❌ Avoid hardcoded colors
+className = "bg-gray-100 text-gray-900"; // Won't adapt to dark mode
+```
+
+**Theme-Aware Shadows**:
+
+```tsx
+// Shadows that work in both modes
+className = "shadow-sm dark:shadow-none dark:ring-1 dark:ring-border/50";
+
+// Elevated surfaces
+className = "bg-popover shadow-lg dark:shadow-2xl dark:border dark:border-border";
+```
+
+---
+
+## 6. Accessibility-First Animation
+
+**Reduced Motion Support**:
+
+```tsx
+import { useReducedMotion } from "@mantine/hooks";
+
+const reducedMotion = useReducedMotion() ?? false;
+
+// Variant A: Disable animations entirely
+const variants = reducedMotion
+  ? { initial: {}, animate: {}, exit: {} }
+  : {
+      initial: { opacity: 0, y: 20 },
+      animate: { opacity: 1, y: 0 },
+      exit: { opacity: 0, y: -20 }
+    };
+
+// Variant B: Opacity-only fallback (gentler)
+const variants = {
+  initial: { opacity: 0, y: reducedMotion ? 0 : 20 },
+  animate: { opacity: 1, y: 0 },
+  exit: { opacity: 0, y: reducedMotion ? 0 : -20 }
+};
+```
+
+**Focus Management**:
+
+```tsx
+import { useFocusWithin } from '@mantine/hooks';
+
+const { ref, focused } = useFocusWithin();
+
+// Show additional UI when container has focus
+<div ref={ref} className={cn(focused && 'ring-2 ring-ring')}>
+```
+
+---
+
+## 7. Motion Patterns by Component Type
+
+**Lists & Collections**:
+
+```tsx
+<motion.ul variants={containerVariants} initial="hidden" animate="visible">
+  <AnimatePresence mode="popLayout">
+    {items.map((item) => (
+      <motion.li
+        key={item.id}
+        variants={itemVariants}
+        layout
+        exit={{ opacity: 0, scale: 0.95 }}
+        transition={SPRING_FLUID}
+      />
+    ))}
+  </AnimatePresence>
+</motion.ul>
+```
+
+**Modals & Dialogs**:
+
+```tsx
+<AnimatePresence mode="wait">
+  {isOpen && (
+    <>
+      <motion.div
+        className="bg-background/80 fixed inset-0 backdrop-blur-sm"
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        exit={{ opacity: 0 }}
+      />
+      <motion.div
+        className="fixed inset-0 flex items-center justify-center"
+        initial={{ opacity: 0, scale: 0.95 }}
+        animate={{ opacity: 1, scale: 1 }}
+        exit={{ opacity: 0, scale: 0.95 }}
+        transition={SPRING_GENTLE}
+      />
+    </>
+  )}
+</AnimatePresence>
+```
+
+**Collapsible Sections**:
+
+```tsx
+<motion.div
+  initial={false}
+  animate={{ height: isOpen ? "auto" : 0 }}
+  transition={SPRING_FLUID}
+  className="overflow-hidden"
+>
+  <div className="p-4">{content}</div>
+</motion.div>
+```
+
+---
+
+## 8. Variant Authoring with tva/cva
+
+The design system supports type-safe variant authoring. We prefer `tva` (tailwind-variants) for new components, but
+`cva` (class-variance-authority) is also supported.
+
+**tailwind-variants (tva) — Preferred**:
+
+```tsx
+import { tv, type VariantProps } from "tailwind-variants";
+
+const button = tv({
+  base: [
+    "inline-flex items-center justify-center rounded-lg font-medium",
+    "transition-colors focus-visible:outline-none focus-visible:ring-2",
+    "focus-visible:ring-ring focus-visible:ring-offset-2",
+    "disabled:pointer-events-none disabled:opacity-50"
+  ],
+  variants: {
+    variant: {
+      default: "bg-primary text-primary-foreground hover:bg-primary/90",
+      destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+      outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+      secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+      ghost: "hover:bg-accent hover:text-accent-foreground",
+      link: "text-primary underline-offset-4 hover:underline"
+    },
+    size: {
+      default: "h-10 px-4 py-2",
+      sm: "h-9 rounded-md px-3",
+      lg: "h-11 rounded-md px-8",
+      icon: "size-10",
+      touch: "min-h-[44px] min-w-[44px] px-4 py-2" // WCAG touch target
+    },
+    // Responsive variants (tva feature)
+    fullWidth: {
+      true: "w-full",
+      mobile: "w-full sm:w-auto" // Full width on mobile only
+    }
+  },
+  defaultVariants: {
+    variant: "default",
+    size: "default"
+  },
+  // Compound variants for complex state combinations
+  compoundVariants: [
+    {
+      variant: "outline",
+      size: "icon",
+      className: "border-2"
+    }
+  ]
+});
+
+type ButtonVariants = VariantProps<typeof button>;
+
+// Usage
+<button className={button({ variant: "default", size: "touch", fullWidth: "mobile" })}>Click me</button>;
+```
+
+**class-variance-authority (cva) — Legacy Support**:
+
+```tsx
+import { cva, type VariantProps } from "class-variance-authority";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-lg font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80"
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        touch: "min-h-[44px] min-w-[44px] px-4 py-2"
+      }
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default"
+    }
+  }
+);
+```
+
+**Key Differences**:
+
+| Feature               | tva                         | cva           |
+| --------------------- | --------------------------- | ------------- |
+| Responsive variants   | Built-in (`mobile:`, `sm:`) | Manual        |
+| Compound variants     | Cleaner syntax              | Supported     |
+| TypeScript inference  | Better                      | Good          |
+| Tailwind IntelliSense | Full support                | Full support  |
+| Slots (sub-elements)  | Built-in                    | Not supported |
+| Bundle size           | ~3.5kb                      | ~2kb          |
+
+---
+
+## 9. Design Token System
+
+The uni-ui package includes a comprehensive design token system that works across multiple frameworks.
+
+### Available Formats
+
+| Format        | Import                                 | Use Case                            |
+| ------------- | -------------------------------------- | ----------------------------------- |
+| CSS Variables | `@od-oneapp/uni-ui/theme.css`          | Tailwind CSS v4, vanilla CSS        |
+| Mantine CSS   | `@od-oneapp/uni-ui/styles/mantine.css` | Mantine 8 components                |
+| TypeScript    | `@od-oneapp/uni-ui/tokens`             | JS/TS runtime, theme functions      |
+| JSON          | `@od-oneapp/uni-ui/tokens/json`        | Design tools, style dictionaries    |
+| DTCG          | `@od-oneapp/uni-ui/tokens/dtcg`        | Design Token Community Group format |
+
+### CSS Variables (Tailwind CSS v4)
+
+```tsx
+// Import in your app's global CSS or layout
+import "@od-oneapp/uni-ui/theme.css";
+
+// Use semantic tokens in components
+<div className="bg-background text-foreground border-border">
+  <button className="bg-primary text-primary-foreground hover:bg-primary/90">Click me</button>
+</div>;
+```
+
+### Mantine 8 Integration
+
+Full Tailwind color palette available in Mantine with 22 colors × 10 shades = 220 color values.
+
+**Basic Setup (Next.js App Router):**
+
+```tsx
+// app/layout.tsx
+import { ColorSchemeScript, MantineProvider } from "@mantine/core";
+import { createMantineTheme } from "@od-oneapp/uni-ui/tokens";
+import "@mantine/core/styles.css";
+import "@od-oneapp/uni-ui/styles/mantine.css";
+
+const theme = createMantineTheme();
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" data-mantine-color-scheme="light">
+      <head>
+        <ColorSchemeScript defaultColorScheme="auto" />
+      </head>
+      <body>
+        <MantineProvider theme={theme} defaultColorScheme="auto">
+          {children}
+        </MantineProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+**Using Tailwind Colors:**
+
+```tsx
+// All 22 Tailwind colors available as Mantine colors
+<Button color="indigo">Tailwind indigo</Button>
+<Button color="emerald.4">Emerald shade 4</Button>
+<Badge color="rose">Rose badge</Badge>
+
+// With full configuration
+const theme = createMantineTheme({
+  primaryColor: "violet",
+  primaryShade: { light: 6, dark: 8 }, // Different shades for light/dark mode
+  defaultRadius: "md",
+  autoContrast: true, // Auto-calculate text color based on background
+  luminanceThreshold: 0.3, // Threshold for contrast calculation
+  scale: 1, // Scale factor for sizes (useful for accessibility)
+});
+```
+
+**Color Scheme Toggle:**
+
+```tsx
+import { useMantineColorScheme, useComputedColorScheme, ActionIcon } from "@mantine/core";
+import { IconSun, IconMoon } from "@tabler/icons-react";
+
+function ColorSchemeToggle() {
+  const { setColorScheme } = useMantineColorScheme();
+  const computedColorScheme = useComputedColorScheme("light", { getInitialValueInEffect: true });
+
+  return (
+    <ActionIcon
+      onClick={() => setColorScheme(computedColorScheme === "light" ? "dark" : "light")}
+      variant="default"
+      aria-label="Toggle color scheme"
+    >
+      {/* Icons automatically hidden based on color scheme */}
+      <IconSun className="block dark:hidden" />
+      <IconMoon className="hidden dark:block" />
+    </ActionIcon>
+  );
+}
+```
+
+**Available Tailwind Colors:**
+
+- **Neutrals:** slate, gray, zinc, neutral, stone
+- **Warm:** red, orange, amber, yellow
+- **Cool:** lime, green, emerald, teal, cyan, sky, blue
+- **Purple:** indigo, violet, purple, fuchsia
+- **Pink:** pink, rose
+
+**Virtual Colors (Light/Dark Mode Switching):**
+
+```tsx
+import { createMantineTheme, getMantinePaletteColors } from "@od-oneapp/uni-ui/tokens";
+import { virtualColor, createTheme } from "@mantine/core";
+
+const theme = createTheme({
+  ...createMantineTheme(),
+  colors: {
+    ...getMantinePaletteColors(),
+    // Add virtual color that switches based on color scheme
+    primary: virtualColor({
+      name: "primary",
+      light: "indigo", // Use indigo in light mode
+      dark: "violet" // Use violet in dark mode
+    })
+  }
+});
+```
+
+**TypeScript Autocomplete for Colors:**
+
+Create `types/mantine.d.ts` in your app:
+
+```typescript
+import type { MantinePaletteColor } from "@od-oneapp/uni-ui/tokens";
+import type { DefaultMantineColor, MantineColorsTuple } from "@mantine/core";
+
+type ExtendedColors = MantinePaletteColor | DefaultMantineColor;
+
+declare module "@mantine/core" {
+  export interface MantineThemeColorsOverride {
+    colors: Record<ExtendedColors, MantineColorsTuple>;
+  }
+}
+```
+
+**Component Default Props:**
+
+Use `mantineComponentPresets` and `createMantineComponentDefaults` for consistent component styling:
+
+```tsx
+import { createTheme, MantineProvider, Button, TextInput, Modal, Card } from "@mantine/core";
+import { createMantineTheme, createMantineComponentDefaults } from "@od-oneapp/uni-ui/tokens";
+
+// Method 1: Using presets manually
+import { mantineComponentPresets } from "@od-oneapp/uni-ui/tokens";
+
+const theme = createTheme({
+  ...createMantineTheme(),
+  components: {
+    Button: Button.extend({ defaultProps: mantineComponentPresets.Button }),
+    TextInput: TextInput.extend({ defaultProps: mantineComponentPresets.TextInput }),
+    Modal: Modal.extend({ defaultProps: mantineComponentPresets.Modal }),
+    Card: Card.extend({ defaultProps: mantineComponentPresets.Card })
+  }
+});
+
+// Method 2: Using the helper function (auto-applies matching presets)
+const theme2 = createTheme({
+  ...createMantineTheme(),
+  components: createMantineComponentDefaults(
+    { Button, TextInput, Modal, Card }, // Pass components you want to configure
+    { Button: { radius: "xl" } } // Optional overrides
+  )
+});
+```
+
+**Pre-built Component Variants (withProps pattern):**
+
+```tsx
+import { Button, Card } from "@mantine/core";
+import { mantinePrebuiltComponents } from "@od-oneapp/uni-ui/tokens";
+
+// Create pre-configured component variants
+const PrimaryButton = Button.withProps(mantinePrebuiltComponents.PrimaryButton);
+const SecondaryButton = Button.withProps(mantinePrebuiltComponents.SecondaryButton);
+const GhostButton = Button.withProps(mantinePrebuiltComponents.GhostButton);
+const DestructiveButton = Button.withProps(mantinePrebuiltComponents.DestructiveButton);
+const ExternalLink = Button.withProps(mantinePrebuiltComponents.ExternalLinkButton);
+const InteractiveCard = Card.withProps(mantinePrebuiltComponents.InteractiveCard);
+
+// Use in your app
+<PrimaryButton>Save Changes</PrimaryButton>
+<SecondaryButton>Cancel</SecondaryButton>
+<DestructiveButton>Delete Account</DestructiveButton>
+<ExternalLink href="https://example.com">Visit Site</ExternalLink>
+<InteractiveCard onClick={handleClick}>Click me!</InteractiveCard>
+```
+
+**Available Presets:**
+
+- **Buttons:** `PrimaryButton`, `SecondaryButton`, `GhostButton`, `OutlineButton`, `DestructiveButton`,
+  `DestructiveOutlineButton`, `LinkButton`, `ExternalLinkButton`, `CompactButton`, `LargeButton`, `IconButton`
+- **Cards:** `InteractiveCard`, `FlatCard`
+- **Modals:** `CenteredModal`, `FullscreenModal`
+- **Inputs:** `SearchInput`
+
+**Component Defaults Available:**
+
+All major Mantine components have presets: `Button`, `ActionIcon`, `TextInput`, `PasswordInput`, `NumberInput`,
+`Textarea`, `Select`, `MultiSelect`, `Checkbox`, `Radio`, `Switch`, `Slider`, `Alert`, `Notification`, `Badge`, `Modal`,
+`Drawer`, `Popover`, `HoverCard`, `Tooltip`, `Menu`, `Card`, `Paper`, `Accordion`, `Tabs`, `Avatar`, `Image`, `NavLink`,
+`Pagination`, `Table`.
+
+### styled-components Integration
+
+```tsx
+import { ThemeProvider } from "styled-components";
+import { createStyledTheme } from "@od-oneapp/uni-ui/tokens";
+
+<ThemeProvider theme={createStyledTheme("light")}>
+  <App />
+</ThemeProvider>;
+```
+
+### Direct Token Access
+
+```tsx
+import { tokens, tokenValues, cssVars } from "@od-oneapp/uni-ui/tokens";
+
+// Get token metadata
+tokens.colors.light.accent; // { value: '#...', cssVar: '--accent', type: 'color' }
+
+// Get raw values
+tokenValues.colors.light.accent; // '#2563eb'
+
+// Get CSS variable references for inline styles
+cssVars.colors.accent; // 'var(--accent)'
+```
+
+### AI Component Token Constants
+
+For AI-specific components, use the established constants:
+
+```tsx
+import {
+  AI_CONTAINER,
+  AI_FOCUS,
+  AI_HOVER,
+  AI_SPACING,
+  AI_TRANSITION,
+  AI_COLLAPSIBLE,
+} from '../ai-elements.constants';
+
+// Container styles
+className={cn(AI_CONTAINER.card, AI_TRANSITION.colors)}
+
+// Interactive styles
+className={cn(AI_HOVER.bg, AI_FOCUS.ring, AI_TRANSITION.colors)}
+
+// Collapsible content
+className={AI_COLLAPSIBLE.content}
+```
+
+### Token Generation
+
+Tokens are generated from TypeScript source files in `src/tokens/*.ts`:
+
+```bash
+# Generate all token formats
+pnpm tokens:generate
+
+# Watch for changes during development
+pnpm tokens:watch
+```
+
+---
+
+## Quick Reference Checklist
+
+- [ ] **Motion imports**: `import { motion, AnimatePresence } from 'motion/react'`
+- [ ] **Reduced motion**: `useReducedMotion()` from `@mantine/hooks`
+- [ ] **Touch detection**: `useMediaQuery('(pointer: coarse)')`
+- [ ] **Touch targets**: Minimum 44x44px on all interactive elements
+- [ ] **Semantic colors**: No hardcoded color values
+- [ ] **Focus states**: `focus-visible:ring-2` on all interactive elements
+- [ ] **Data attributes**: `data-state`, `data-loading` for CSS hooks
+- [ ] **Spring physics**: Consistent spring configs across related components
+- [ ] **Exit animations**: `AnimatePresence` wrapping conditional renders
+- [ ] **Layout animations**: `layout` prop for position/size changes
+````