@framingui/ui 0.6.2 → 0.6.4

package/README.md

@@ -1,33 +1,21 @@
-# @framingui
+# @framingui/ui
 
-FramingUI Reference Component Library - High-quality, accessible React components with CSS Variables theming.
+> Production-ready React components with CSS Variables theming
 
-## Overview
-
-@framingui provides 20 production-ready components + 13 screen templates built with:
-
-- **Screen Templates (NEW)**: 13 full-page layouts for rapid development
-- **React 19** - Latest React features with Server Components support
-- **TypeScript 5.7+** - Full type safety with strict mode
-- **Radix UI v1.0+** - Accessible headless primitives
-- **CSS Variables** - 3-layer architecture (Atomic → Semantic → Component)
-- **WCAG 2.1 AA** - Fully accessible
+[![npm](https://img.shields.io/npm/v/@framingui/ui)](https://www.npmjs.com/package/@framingui/ui)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
 
 ## Installation
 
 ```bash
-pnpm add @framingui
-# or
-yarn add @framingui
+npm install @framingui/ui
 ```
 
 ## Quick Start
 
-### Import Components
-
 ```tsx
-import { Button, Input, Card } from '@framingui';
-import '@framingui/styles';
+import { Button, Input, Card } from '@framingui/ui';
+import '@framingui/ui/styles';
 
 export default function App() {
   return (
@@ -47,1086 +35,30 @@ export default function App() {
 }
 ```
 
-### CSS Variables Theming
-
-Import the CSS Variables template and customize:
-
-```css
-@import '@framingui/styles';
-
-:root {
-  /* Button Tokens */
-  --button-primary-background: #3b82f6;
-  --button-primary-foreground: white;
-
-  /* Input Tokens */
-  --input-border: #d1d5db;
-  --input-background: white;
-
-  /* Card Tokens */
-  --card-background: white;
-  --card-border: #e5e7eb;
-
-  /* ... customize 100+ other tokens */
-}
-```
-
 ## Components
 
-### Primitive Components (14)
-
-Core UI building blocks with single responsibility:
-
-- **Button** - Interactive button with loading states and variants (default, primary, secondary, destructive, outline, ghost, link)
-- **Input** - Text input with error states and type support (text, email, password, number)
-- **Checkbox** - Checkbox with indeterminate support and form integration
-- **RadioGroup** - Radio button groups with keyboard navigation
-- **Switch** - Toggle switch with checked/unchecked states
-- **Slider** - Range slider with min/max/step configuration
-- **Text** - Polymorphic text component with size variants
-- **Heading** - Hierarchical headings (h1-h6) with level prop
-- **Badge** - Status badges (default, primary, secondary, destructive, outline)
-- **Avatar** - User avatars with image/fallback support
-- **Progress** - Progress bar with value 0-100
-- **Link** - Navigation links (default, muted, underline variants)
-- **Image** - Image component with alt text and optional object-fit
-- **List** - Polymorphic list component (ul/ol)
-
-### Composed Components (6)
-
-Complex components built from primitives:
-
-- **Card** - Card container with header/content/footer structure
-- **Form** - Form with validation context and error handling
-- **Modal** - Dialog/modal overlay with Portal rendering
-- **Dropdown** - Dropdown menu with keyboard navigation
-- **Tabs** - Tabbed navigation with automatic ARIA labels
-- **Table** - Data table with semantic HTML structure
-
----
-
-## Component Examples
-
-### Button
-
-```tsx
-import { Button } from '@framingui';
-
-// Variants
-<Button variant="default">Default</Button>
-<Button variant="primary">Primary</Button>
-<Button variant="secondary">Secondary</Button>
-<Button variant="destructive">Delete</Button>
-<Button variant="outline">Outline</Button>
-<Button variant="ghost">Ghost</Button>
-<Button variant="link">Link</Button>
-
-// Sizes
-<Button size="sm">Small</Button>
-<Button size="md">Medium</Button>
-<Button size="lg">Large</Button>
-
-// States
-<Button loading>Loading...</Button>
-<Button disabled>Disabled</Button>
-```
-
-**Props:**
-
-- `variant`: `"default" | "primary" | "secondary" | "destructive" | "outline" | "ghost" | "link"`
-- `size`: `"sm" | "md" | "lg"`
-- `loading`: `boolean`
-- All native `<button>` props
-
----
-
-### Input
-
-```tsx
-import { Input } from '@framingui';
-
-// Basic usage
-<Input type="text" placeholder="Enter text..." />
-<Input type="email" placeholder="Email address" />
-<Input type="password" placeholder="Password" />
-
-// With error state
-<Input type="text" aria-invalid="true" />
-
-// Disabled
-<Input disabled placeholder="Disabled input" />
-```
-
-**Props:**
-
-- `type`: `"text" | "email" | "password" | "number" | "search" | "tel" | "url"`
-- All native `<input>` props
-
----
-
-### Card
-
-```tsx
-import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@framingui';
-
-<Card>
-  <CardHeader>
-    <CardTitle>Card Title</CardTitle>
-    <CardDescription>Card description or subtitle</CardDescription>
-  </CardHeader>
-  <CardContent>
-    <p>Main content goes here</p>
-  </CardContent>
-  <CardFooter>
-    <Button>Action</Button>
-  </CardFooter>
-</Card>;
-```
-
----
-
-### Form
-
-```tsx
-import { Form, FormField, FormLabel, FormControl, FormDescription, FormMessage } from '@framingui';
-import { Input } from '@framingui';
-
-<Form
-  onSubmit={e => {
-    e.preventDefault(); /* handle submit */
-  }}
->
-  <FormField name="email">
-    <FormLabel htmlFor="email">Email</FormLabel>
-    <FormControl>
-      <Input id="email" type="email" />
-    </FormControl>
-    <FormDescription>We'll never share your email.</FormDescription>
-    <FormMessage name="email">Invalid email address</FormMessage>
-  </FormField>
-</Form>;
-```
-
----
-
-### Modal (Dialog)
-
-```tsx
-import {
-  Modal,
-  ModalTrigger,
-  ModalContent,
-  ModalHeader,
-  ModalTitle,
-  ModalDescription,
-  ModalFooter,
-  ModalClose,
-} from '@framingui';
-import { Button } from '@framingui';
-
-<Modal>
-  <ModalTrigger asChild>
-    <Button>Open Modal</Button>
-  </ModalTrigger>
-  <ModalContent>
-    <ModalHeader>
-      <ModalTitle>Modal Title</ModalTitle>
-      <ModalDescription>Modal description text</ModalDescription>
-    </ModalHeader>
-    <div>Modal body content</div>
-    <ModalFooter>
-      <ModalClose asChild>
-        <Button variant="outline">Cancel</Button>
-      </ModalClose>
-      <Button variant="primary">Confirm</Button>
-    </ModalFooter>
-  </ModalContent>
-</Modal>;
-```
-
----
-
-### Dropdown Menu
-
-```tsx
-import {
-  Dropdown,
-  DropdownTrigger,
-  DropdownContent,
-  DropdownItem,
-  DropdownSeparator,
-} from '@framingui';
-import { Button } from '@framingui';
-
-<Dropdown>
-  <DropdownTrigger asChild>
-    <Button>Open Menu</Button>
-  </DropdownTrigger>
-  <DropdownContent>
-    <DropdownItem onClick={() => console.log('Edit')}>Edit</DropdownItem>
-    <DropdownItem onClick={() => console.log('Duplicate')}>Duplicate</DropdownItem>
-    <DropdownSeparator />
-    <DropdownItem disabled>Disabled Item</DropdownItem>
-    <DropdownItem onClick={() => console.log('Delete')}>Delete</DropdownItem>
-  </DropdownContent>
-</Dropdown>;
-```
-
----
-
-### Tabs
-
-```tsx
-import { Tabs, TabsList, TabsTrigger, TabsContent } from '@framingui';
-
-<Tabs defaultValue="tab1">
-  <TabsList>
-    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
-    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
-    <TabsTrigger value="tab3">Tab 3</TabsTrigger>
-  </TabsList>
-  <TabsContent value="tab1">
-    <p>Content for Tab 1</p>
-  </TabsContent>
-  <TabsContent value="tab2">
-    <p>Content for Tab 2</p>
-  </TabsContent>
-  <TabsContent value="tab3">
-    <p>Content for Tab 3</p>
-  </TabsContent>
-</Tabs>;
-```
-
----
-
-### Checkbox
-
-```tsx
-import { Checkbox } from '@framingui';
-
-// Basic checkbox
-<label>
-  <Checkbox id="terms" />
-  Accept terms and conditions
-</label>
-
-// Indeterminate state
-<Checkbox checked="indeterminate" />
-
-// Disabled
-<Checkbox disabled />
-```
-
-**Props:**
-
-- `checked`: `boolean | "indeterminate"`
-- `onCheckedChange`: `(checked: boolean | "indeterminate") => void`
-- All Radix UI Checkbox props
-
----
-
-### RadioGroup
-
-```tsx
-import { RadioGroup, RadioGroupItem } from '@framingui';
-
-<RadioGroup defaultValue="option1">
-  <div>
-    <RadioGroupItem value="option1" id="opt1" />
-    <label htmlFor="opt1">Option 1</label>
-  </div>
-  <div>
-    <RadioGroupItem value="option2" id="opt2" />
-    <label htmlFor="opt2">Option 2</label>
-  </div>
-  <div>
-    <RadioGroupItem value="option3" id="opt3" />
-    <label htmlFor="opt3">Option 3</label>
-  </div>
-</RadioGroup>;
-```
-
----
-
-### Switch
-
-```tsx
-import { Switch } from '@framingui';
-
-<label>
-  <Switch id="notifications" />
-  Enable notifications
-</label>
-
-<Switch checked onCheckedChange={(checked) => console.log(checked)} />
-```
-
-**Props:**
-
-- `checked`: `boolean`
-- `onCheckedChange`: `(checked: boolean) => void`
-- All Radix UI Switch props
-
----
-
-### Slider
-
-```tsx
-import { Slider } from '@framingui';
-
-// Basic slider
-<label htmlFor="volume" id="volume-label">Volume</label>
-<Slider
-  id="volume"
-  defaultValue={[50]}
-  min={0}
-  max={100}
-  step={1}
-  aria-labelledby="volume-label"
-/>
-
-// Range slider
-<Slider defaultValue={[25, 75]} min={0} max={100} />
-```
-
-**Props:**
-
-- `defaultValue`: `number[]`
-- `min`: `number`
-- `max`: `number`
-- `step`: `number`
-- All Radix UI Slider props
-
----
-
-### Progress
-
-```tsx
-import { Progress } from '@framingui';
-
-<Progress value={50} aria-label="Upload progress" />
-<Progress value={75} aria-label="Loading" />
-<Progress value={100} aria-label="Complete" />
-```
-
-**Props:**
-
-- `value`: `number` (0-100)
-- All Radix UI Progress props
-
----
-
-### Avatar
-
-```tsx
-import { Avatar, AvatarImage, AvatarFallback } from '@framingui';
-
-<Avatar>
-  <AvatarImage src="https://example.com/avatar.jpg" alt="John Doe" />
-  <AvatarFallback>JD</AvatarFallback>
-</Avatar>;
-```
-
----
-
-### Badge
-
-```tsx
-import { Badge } from '@framingui';
-
-<Badge variant="default">Default</Badge>
-<Badge variant="primary">Primary</Badge>
-<Badge variant="secondary">Secondary</Badge>
-<Badge variant="destructive">Error</Badge>
-<Badge variant="outline">Outline</Badge>
-```
-
-**Props:**
-
-- `variant`: `"default" | "primary" | "secondary" | "destructive" | "outline"`
-
----
-
-### Text
-
-```tsx
-import { Text } from '@framingui';
-
-// Sizes
-<Text size="xs">Extra small text</Text>
-<Text size="sm">Small text</Text>
-<Text size="md">Medium text</Text>
-<Text size="lg">Large text</Text>
-
-// Polymorphic rendering
-<Text as="p">Paragraph</Text>
-<Text as="span">Inline text</Text>
-<Text as="div">Block text</Text>
-```
-
-**Props:**
-
-- `as`: `"p" | "span" | "div" | "label"`
-- `size`: `"xs" | "sm" | "md" | "lg"`
-- `variant`: `"default" | "muted"`
-
----
-
-### Heading
-
-```tsx
-import { Heading } from '@framingui';
-
-<Heading level={1}>Heading 1</Heading>
-<Heading level={2}>Heading 2</Heading>
-<Heading level={3}>Heading 3</Heading>
-<Heading level={4}>Heading 4</Heading>
-<Heading level={5}>Heading 5</Heading>
-<Heading level={6}>Heading 6</Heading>
-
-// Sizes
-<Heading level={1} size="sm">Small H1</Heading>
-<Heading level={2} size="lg">Large H2</Heading>
-```
-
-**Props:**
-
-- `level`: `1 | 2 | 3 | 4 | 5 | 6`
-- `size`: `"sm" | "md" | "lg"`
-
----
-
-### Link
-
-```tsx
-import { Link } from '@framingui';
-
-<Link href="/home" variant="default">Default Link</Link>
-<Link href="/about" variant="muted">Muted Link</Link>
-<Link href="/contact" variant="underline">Underlined Link</Link>
-```
-
-**Props:**
-
-- `href`: `string`
-- `variant`: `"default" | "muted" | "underline"`
-- All native `<a>` props
-
----
-
-### List
-
-```tsx
-import { List, ListItem } from '@framingui';
-
-// Unordered list
-<List as="ul">
-  <ListItem>Item 1</ListItem>
-  <ListItem>Item 2</ListItem>
-  <ListItem>Item 3</ListItem>
-</List>
-
-// Ordered list
-<List as="ol">
-  <ListItem>First item</ListItem>
-  <ListItem>Second item</ListItem>
-  <ListItem>Third item</ListItem>
-</List>
-```
-
-**Props:**
-
-- `as`: `"ul" | "ol"`
-
----
-
-### Image
-
-```tsx
-import { Image } from '@framingui';
-
-<Image
-  src="https://example.com/image.jpg"
-  alt="Description of image"
-/>
-
-<Image
-  src="https://example.com/image.jpg"
-  alt="Cover image"
-  className="object-cover w-full h-64"
-/>
-```
-
-**Props:**
-
-- `src`: `string`
-- `alt`: `string` (required for accessibility)
-- All native `<img>` props
-
----
-
-### Table
-
-```tsx
-import {
-  Table,
-  TableHeader,
-  TableBody,
-  TableFooter,
-  TableRow,
-  TableHead,
-  TableCell,
-  TableCaption,
-} from '@framingui';
-
-<Table>
-  <TableCaption>List of users</TableCaption>
-  <TableHeader>
-    <TableRow>
-      <TableHead>Name</TableHead>
-      <TableHead>Email</TableHead>
-      <TableHead>Role</TableHead>
-    </TableRow>
-  </TableHeader>
-  <TableBody>
-    <TableRow>
-      <TableCell>John Doe</TableCell>
-      <TableCell>john@example.com</TableCell>
-      <TableCell>Admin</TableCell>
-    </TableRow>
-    <TableRow>
-      <TableCell>Jane Smith</TableCell>
-      <TableCell>jane@example.com</TableCell>
-      <TableCell>User</TableCell>
-    </TableRow>
-  </TableBody>
-  <TableFooter>
-    <TableRow>
-      <TableCell colSpan={3}>Total: 2 users</TableCell>
-    </TableRow>
-  </TableFooter>
-</Table>;
-```
-
----
-
-## Features
-
-### CSS Variables First
-
-All themeable properties use CSS Variables:
-
-```tsx
-<Button variant="primary">
-  {/* Uses --button-primary-background and --button-primary-foreground */}
-</Button>
-```
-
-### Type-Safe Variants
-
-Powered by class-variance-authority:
-
-```tsx
-<Button variant="secondary" size="lg" loading>
-  Click me
-</Button>
-```
-
-### Accessibility Built-In
-
-- **WCAG 2.1 AA compliant** - All components pass axe-core validation
-- **Proper ARIA attributes** - Screen reader friendly
-- **Keyboard navigation** - Full keyboard support (Tab, Arrow keys, Enter, Escape)
-- **Focus management** - Visible focus indicators and proper focus trapping
-
-### Zero Config Setup
-
-Works out of the box with sensible defaults:
-
-```tsx
-import { Button } from '@framingui';
-
-<Button>Just works</Button>;
-```
-
----
+### Primitives (14)
 
-## Screen Templates (Phase 3)
+Button, Input, Checkbox, Radio, Switch, Slider, Text, Heading, Badge, Avatar, Progress, Link, Image, List
 
-**New in Phase 3**: 13 Screen Templates for rapid full-screen composition.
+### Composed (6)
 
-### Overview
+Card, Form, Modal, Dropdown, Tabs, Table
 
-Screen Templates provide pre-built, theme-aware full-screen layouts that combine multiple components into cohesive user experiences. Each template is registered in a centralized `TemplateRegistry` for easy discovery and reuse.
+## Key Features
 
-**Features:**
+- **WCAG 2.1 AA Compliant**: Fully accessible
+- **CSS Variables**: 3-layer token system (Atomic → Semantic → Component)
+- **Type-Safe**: Full TypeScript support
+- **Zero Config**: Works out of the box
+- **98%+ Test Coverage**: Production-ready quality
 
-- **13 Pre-built Layouts**: Auth (4), Core (3), Feedback (5), Dashboard (1)
-- **Theme-Aware**: Automatically adapts to active theme via CSS Variables
-- **AI-Friendly**: Clear customization boundaries for AI agents
-- **Type-Safe**: Full TypeScript support with ScreenTemplate interface
-- **Responsive**: Desktop, Tablet, Mobile layouts
-
-### Quick Start
-
-```tsx
-import { templateRegistry } from '@framingui/templates';
-
-// Get all templates
-const allTemplates = templateRegistry.getAll(); // 13 templates
-
-// Get by category
-const authTemplates = templateRegistry.getByCategory('auth'); // 4 templates
-
-// Get specific template
-const loginTemplate = templateRegistry.get('auth.login');
-```
-
-### Available Templates (13)
-
-#### Auth Templates (4)
-
-```tsx
-import {
-  LoginTemplate,
-  SignupTemplate,
-  ForgotPasswordTemplate,
-  VerificationTemplate,
-} from '@framingui/templates/auth';
-```
-
-- **LoginTemplate** (`auth.login`) - Centered login card with email/password
-- **SignupTemplate** (`auth.signup`) - Registration form with terms acceptance
-- **ForgotPasswordTemplate** (`auth.forgot-password`) - Password reset flow
-- **VerificationTemplate** (`auth.verification`) - Email verification confirmation
-
-#### Core Templates (3)
-
-```tsx
-import { LandingTemplate, PreferencesTemplate, ProfileTemplate } from '@framingui/templates/core';
-```
-
-- **LandingTemplate** (`home.landing`) - Full-width landing page with CTA
-- **PreferencesTemplate** (`settings.preferences`) - Sidebar settings layout
-- **ProfileTemplate** (`account.profile`) - User profile with avatar editing
-
-#### Feedback Templates (5)
-
-```tsx
-import {
-  LoadingTemplate,
-  ErrorTemplate,
-  EmptyTemplate,
-  ConfirmationTemplate,
-  SuccessTemplate,
-} from '@framingui/templates/feedback';
-```
-
-- **LoadingTemplate** (`feedback.loading`) - Loading skeleton state
-- **ErrorTemplate** (`feedback.error`) - Error state with retry button
-- **EmptyTemplate** (`feedback.empty`) - Empty state with CTA
-- **ConfirmationTemplate** (`feedback.confirmation`) - Dialog confirmation
-- **SuccessTemplate** (`feedback.success`) - Success message with next steps
-
-#### Dashboard Template (1)
-
-```tsx
-import { DashboardTemplate } from '@framingui/templates/dashboard';
-```
-
-- **DashboardTemplate** (`dashboard.overview`) - Dashboard layout with sidebar
-
-### Template Features
-
-- **Type-Safe**: Full TypeScript support with `ScreenTemplate` interface
-- **AI-Friendly**: Clear customization boundaries (`slots`, `texts`, `options`)
-- **Theme-Aware**: CSS Variables for automatic theme adaptation
-- **Responsive**: Breakpoint-based layouts (Desktop 1024px+, Tablet 768-1024px, Mobile <768px)
-- **Accessible**: WCAG 2.1 AA compliance (validation in progress)
-
-### TemplateRegistry API
-
-The `TemplateRegistry` provides centralized template management:
-
-```tsx
-import { templateRegistry } from '@framingui/templates/registry';
-
-// Get all templates
-const allTemplates = templateRegistry.getAll(); // 13 templates
-
-// Get templates by category
-const authTemplates = templateRegistry.getByCategory('auth'); // 4 templates
-
-// Get specific template
-const loginTemplate = templateRegistry.get('auth.login');
-
-// Find by required components
-const formsTemplates = templateRegistry.findByRequiredComponents(['Button', 'Input', 'Form']);
-```
-
-**Design Reference**: All templates follow [Claude.ai Design Philosophy](../../.moai/specs/SPEC-UI-002/reference-guide.md) - clarity, accessibility, universality.
-
-### Phase 3 Status
-
-**Completed (2026-02-01):**
-
-- ✅ Template type system (`ScreenTemplate`, `TemplateRegistry`)
-- ✅ 13 templates implemented (Auth 4, Core 3, Feedback 5, Dashboard 1)
-- ✅ Template registry with category filtering
-- ✅ Storybook stories for all templates
-- ✅ SPEC TAG annotations (TAG-UI002-001 ~ 035)
-- ⚠️ Test coverage: 17.26% (improvement planned)
-
-**Next Steps:**
-
-- Test coverage to 85%+
-- Accessibility validation (axe-core, WCAG 2.1 AA)
-- Additional template variants
-- Template preview gallery in Storybook
-
----
-
-
-## CSS Variables Reference
-
-@framingui uses a 3-layer CSS Variables architecture:
-
-### Layer 1: Atomic Tokens
-
-```css
---color-primary: #3b82f6;
---color-destructive: #ef4444;
---spacing-sm: 0.5rem;
---radius-md: 0.375rem;
-```
-
-### Layer 2: Semantic Tokens
-
-```css
---text-primary: var(--color-primary);
---bg-destructive: var(--color-destructive);
-```
-
-### Layer 3: Component Tokens
-
-**Button Tokens:**
-
-```css
---button-default-background
---button-default-foreground
---button-primary-background
---button-primary-foreground
---button-secondary-background
---button-secondary-foreground
---button-destructive-background
---button-destructive-foreground
---button-outline-border
---button-outline-foreground
---button-ghost-hover-background
---button-link-foreground
---button-disabled-opacity
---button-focus-ring
-```
-
-**Input Tokens:**
-
-```css
---input-background
---input-foreground
---input-border
---input-placeholder
---input-focus-ring
---input-disabled-background
---input-disabled-foreground
-```
-
-**Card Tokens:**
-
-```css
---card-background
---card-foreground
---card-border
-```
+## Documentation
 
-**Modal Tokens:**
-
-```css
---modal-background
---modal-border
---modal-overlay-background
---modal-title-foreground
---modal-description-foreground
-```
-
-**Form Tokens:**
-
-```css
---form-label-foreground
---form-message-destructive
---form-description-foreground
-```
-
-**Other Component Tokens:**
-
-- Badge: `--badge-*-background`, `--badge-*-foreground`, `--badge-*-border`
-- Dropdown: `--dropdown-*-background`, `--dropdown-item-*`
-- Tabs: `--tabs-*-background`, `--tabs-trigger-*`
-- Table: `--table-*-background`, `--table-border`
-- Progress: `--progress-background`, `--progress-indicator-background`
-- Slider: `--slider-track-background`, `--slider-thumb-*`
-- Avatar: `--avatar-background`, `--avatar-foreground`
-
-### Custom Theme Example
-
-```css
-/* dark-theme.css */
-@import '@framingui/styles';
-
-:root {
-  /* Atomic Layer */
-  --color-primary: #60a5fa;
-  --color-background: #1f2937;
-  --color-foreground: #f9fafb;
-
-  /* Button Layer */
-  --button-primary-background: var(--color-primary);
-  --button-primary-foreground: #000000;
-  --button-default-background: #374151;
-  --button-default-foreground: var(--color-foreground);
-
-  /* Input Layer */
-  --input-background: #374151;
-  --input-foreground: var(--color-foreground);
-  --input-border: #4b5563;
-
-  /* Card Layer */
-  --card-background: #374151;
-  --card-foreground: var(--color-foreground);
-  --card-border: #4b5563;
-}
-```
-
----
-
-## Development
-
-### Setup
-
-```bash
-# Clone repository
-git clone https://github.com/your-org/tekton.git
-cd tekton/packages/ui
-
-# Install dependencies (requires pnpm)
-pnpm install
-```
-
-### Scripts
-
-```bash
-# Run tests
-pnpm test
-
-# Run tests with coverage (target: ≥90%)
-pnpm test:coverage
-
-# Run tests in watch mode
-pnpm test:watch
-
-# Type check (TypeScript 5.7+ strict mode)
-pnpm type-check
-
-# Lint (ESLint 9)
-pnpm lint
-
-# Build (outputs to dist/)
-pnpm build
-
-# Clean build artifacts
-pnpm clean
-```
-
-### Project Structure
-
-```
-packages/ui/
-├── src/
-│   ├── primitives/          # 14 primitive components
-│   │   ├── button.tsx
-│   │   ├── input.tsx
-│   │   ├── checkbox.tsx
-│   │   └── ...
-│   ├── components/          # 6 composed components
-│   │   ├── card.tsx
-│   │   ├── form.tsx
-│   │   ├── modal.tsx
-│   │   └── ...
-│   ├── lib/
-│   │   └── utils.ts         # cn() utility
-│   └── index.ts             # Main export
-├── __tests__/
-│   ├── primitives/          # Primitive tests
-│   ├── components/          # Component tests
-│   ├── lib/                 # Utility tests
-│   └── accessibility.test.tsx  # WCAG compliance
-├── vitest.config.ts
-├── tsconfig.json
-└── package.json
-```
-
----
-
-## Testing
-
-All 20 components include comprehensive test coverage:
-
-### Test Coverage (98.93%)
-
-- **Statement Coverage**: 98.93%
-- **Branch Coverage**: 95.52%
-- **Function Coverage**: 100%
-- **Line Coverage**: 98.93%
-
-### Test Categories
-
-**Unit Tests (Vitest + Testing Library)**
-
-- Component rendering
-- Props validation
-- Variant behavior
-- State management
-- Event handling
-
-**Accessibility Tests (vitest-axe)**
-
-- WCAG 2.1 AA compliance
-- ARIA attributes
-- Semantic HTML
-- Color contrast (disabled in jsdom)
-
-**Keyboard Navigation Tests**
-
-- Tab navigation
-- Arrow key navigation (RadioGroup, Tabs, Slider)
-- Enter/Space activation
-- Escape key handling (Modal, Dropdown)
-
-**User Interaction Tests (userEvent)**
-
-- Click events
-- Form submissions
-- Input changes
-- Focus management
-
-### Running Tests
-
-```bash
-# All tests
-pnpm test
-
-# Specific file
-pnpm vitest run __tests__/primitives/button.test.tsx
-
-# Watch mode
-pnpm test:watch
-
-# Coverage report
-pnpm test:coverage
-```
-
----
-
-## Browser Support
-
-- Chrome (latest)
-- Firefox (latest)
-- Safari (latest)
-- Edge (latest)
-
-**Note**: Internet Explorer is not supported.
-
----
-
-## TypeScript Support
-
-All components are fully typed with TypeScript 5.7+:
-
-```tsx
-import { Button, ButtonProps } from '@framingui';
-
-// Type-safe props
-const MyButton: React.FC<ButtonProps> = props => {
-  return <Button {...props} />;
-};
-
-// Type inference
-<Button
-  variant="primary" // ✓ Valid
-  variant="invalid" // ✗ TypeScript error
-  size="lg" // ✓ Valid
-  onClick={e => {
-    // e is typed as MouseEvent<HTMLButtonElement>
-    console.log(e.currentTarget);
-  }}
-/>;
-```
-
----
-
-## Contributing
-
-Contributions are welcome! Please read our contributing guidelines before submitting a PR.
-
-### Development Workflow
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes
-4. Run tests (`pnpm test`)
-5. Run type check (`pnpm type-check`)
-6. Run linter (`pnpm lint`)
-7. Commit changes (`git commit -m 'Add amazing feature'`)
-8. Push to branch (`git push origin feature/amazing-feature`)
-9. Open a Pull Request
-
-### Code Quality Standards
-
-- **Test Coverage**: ≥90% (currently 98.93%)
-- **TypeScript**: Strict mode, no `any` types
-- **Accessibility**: WCAG 2.1 AA compliant
-- **ESLint**: Zero warnings/errors
-- **Documentation**: All public APIs documented
-
----
+- [Component Reference](https://framingui.com/docs/components)
+- [Theming Guide](https://framingui.com/docs/guides/theming)
+- [CSS Variables Reference](https://framingui.com/docs/guides/css-variables)
 
 ## License
 
-MIT License - see [LICENSE](./LICENSE) for details
-
----
-
-## Links
-
-- **Documentation**: [FramingUI Guide](https://github.com/tektoncd/tekton)
-- **Radix UI**: [https://www.radix-ui.com/](https://www.radix-ui.com/)
-- **WCAG 2.1**: [https://www.w3.org/WAI/WCAG21/quickref/](https://www.w3.org/WAI/WCAG21/quickref/)
-- **React 19**: [https://react.dev/](https://react.dev/)
-- **TypeScript**: [https://www.typescriptlang.org/](https://www.typescriptlang.org/)
-
----
-
-## Acknowledgments
-
-Built with:
-
-- [React 19](https://react.dev/) - UI library
-- [Radix UI](https://www.radix-ui.com/) - Accessible primitives
-- [class-variance-authority](https://cva.style/docs) - Variant management
-- [Vitest](https://vitest.dev/) - Testing framework
-- [axe-core](https://github.com/dequelabs/axe-core) - Accessibility testing
-
----
-
-**Version**: 1.0.0
-**Last Updated**: 2026-01-26
-**Maintained by**: Tekton Team
+MIT