@weave-design-system/react 0.1.0

package/src/docs/DesignTokens.mdx

@@ -0,0 +1,235 @@
+{/* @jsxImportSource react */}
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Design Tokens" />
+
+# Design Tokens
+
+All tokens are available as CSS custom properties (via `theme.css`) and as JavaScript constants (via `@weave-ds/react/tokens`).
+
+---
+
+## Colors
+
+Every color has a physical-world reference — clay, linen, moss, honey, charcoal.
+
+### Neutrals
+
+<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(160px, 1fr))', gap: 12, marginTop: 16 }}>
+  <ColorSwatch color="#FAF7F2" name="Background" token="--color-bg" />
+  <ColorSwatch color="#F0EBE3" name="Surface" token="--color-surface" />
+  <ColorSwatch color="#D9D2C7" name="Border" token="--color-border" />
+  <ColorSwatch color="#2C2825" name="Text Primary" token="--color-text-primary" dark />
+  <ColorSwatch color="#6B635A" name="Text Secondary" token="--color-text-secondary" dark />
+  <ColorSwatch color="#FFFFFF" name="White" token="--color-white" border />
+</div>
+
+### Primary (Rust)
+
+<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(160px, 1fr))', gap: 12, marginTop: 16 }}>
+  <ColorSwatch color="#B85C38" name="Rust" token="--color-rust" dark />
+  <ColorSwatch color="#F0D5C5" name="Rust Light" token="--color-rust-light" />
+  <ColorSwatch color="#8E4429" name="Rust Dark" token="--color-rust-dark" dark />
+</div>
+
+### Secondary (Forest)
+
+<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(160px, 1fr))', gap: 12, marginTop: 16 }}>
+  <ColorSwatch color="#3D6B5E" name="Forest" token="--color-forest" dark />
+  <ColorSwatch color="#D4E5DF" name="Forest Light" token="--color-forest-light" />
+</div>
+
+### Semantic
+
+<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(160px, 1fr))', gap: 12, marginTop: 16 }}>
+  <ColorSwatch color="#5E8A6B" name="Success" token="--color-success" dark />
+  <ColorSwatch color="#DDE9E0" name="Success Light" token="--color-success-light" />
+  <ColorSwatch color="#C49A3C" name="Warning" token="--color-warning" dark />
+  <ColorSwatch color="#F5EDD4" name="Warning Light" token="--color-warning-light" />
+  <ColorSwatch color="#B84A3C" name="Error" token="--color-error" dark />
+  <ColorSwatch color="#F3D9D5" name="Error Light" token="--color-error-light" />
+  <ColorSwatch color="#7A8A9A" name="Info" token="--color-info" dark />
+  <ColorSwatch color="#E0E5EA" name="Info Light" token="--color-info-light" />
+</div>
+
+### Delight
+
+<div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(160px, 1fr))', gap: 12, marginTop: 16 }}>
+  <ColorSwatch color="#D4923A" name="Saffron" token="--color-saffron" dark />
+  <ColorSwatch color="#F5E3C8" name="Saffron Light" token="--color-saffron-light" />
+</div>
+
+---
+
+## Typography
+
+Two-tier type system: **Satoshi** (humanist sans-serif) + **JetBrains Mono** (code).
+
+<div style={{ display: 'flex', flexDirection: 'column', gap: 24, marginTop: 16 }}>
+  <TypeSample name="Display" size="40px" lineHeight="48px" weight="700" />
+  <TypeSample name="Heading 1" size="32px" lineHeight="40px" weight="700" />
+  <TypeSample name="Heading 2" size="26px" lineHeight="34px" weight="600" />
+  <TypeSample name="Heading 3" size="22px" lineHeight="30px" weight="600" />
+  <TypeSample name="Body Large" size="18px" lineHeight="28px" weight="400" />
+  <TypeSample name="Body" size="16px" lineHeight="24px" weight="400" />
+  <TypeSample name="Body Small" size="14px" lineHeight="20px" weight="400" />
+  <TypeSample name="Caption" size="12px" lineHeight="16px" weight="500" />
+  <TypeSample name="Code" size="14px" lineHeight="22px" weight="400" mono />
+</div>
+
+---
+
+## Spacing
+
+4px base grid. All spacing derives from `--spacing: 4px`.
+
+<div style={{ display: 'flex', flexDirection: 'column', gap: 8, marginTop: 16 }}>
+  <SpacingSample token="space-1" value="4px" />
+  <SpacingSample token="space-2" value="8px" />
+  <SpacingSample token="space-3" value="12px" />
+  <SpacingSample token="space-4" value="16px" />
+  <SpacingSample token="space-6" value="24px" />
+  <SpacingSample token="space-8" value="32px" />
+  <SpacingSample token="space-12" value="48px" />
+  <SpacingSample token="space-16" value="64px" />
+</div>
+
+---
+
+## Border Radius
+
+<div style={{ display: 'flex', gap: 16, alignItems: 'end', marginTop: 16 }}>
+  <RadiusSample name="sm" value="6px" />
+  <RadiusSample name="md" value="10px" />
+  <RadiusSample name="lg" value="16px" />
+  <RadiusSample name="xl" value="24px" />
+  <RadiusSample name="full" value="9999px" />
+</div>
+
+---
+
+## Elevation
+
+Warm-tinted shadows using `rgba(44, 40, 37, ...)` instead of pure black.
+
+<div style={{ display: 'flex', gap: 24, marginTop: 16 }}>
+  <ElevationSample level={1} shadow="0 1px 3px rgba(44,40,37,0.06)" />
+  <ElevationSample level={2} shadow="0 4px 12px rgba(44,40,37,0.08)" />
+  <ElevationSample level={3} shadow="0 8px 24px rgba(44,40,37,0.12)" />
+  <ElevationSample level={4} shadow="0 16px 48px rgba(44,40,37,0.16)" />
+</div>
+
+---
+
+## Motion
+
+<table style={{ width: '100%', borderCollapse: 'collapse', fontSize: 14 }}>
+  <thead>
+    <tr style={{ borderBottom: '2px solid #D9D2C7', textAlign: 'left' }}>
+      <th style={{ padding: '8px 12px', color: '#6B635A', fontWeight: 600 }}>Token</th>
+      <th style={{ padding: '8px 12px', color: '#6B635A', fontWeight: 600 }}>Value</th>
+      <th style={{ padding: '8px 12px', color: '#6B635A', fontWeight: 600 }}>Usage</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr style={{ borderBottom: '1px solid #D9D2C7' }}>
+      <td style={{ padding: '8px 12px' }}><code>--duration-micro</code></td>
+      <td style={{ padding: '8px 12px' }}>100ms</td>
+      <td style={{ padding: '8px 12px', color: '#6B635A' }}>Hover colors, focus rings</td>
+    </tr>
+    <tr style={{ borderBottom: '1px solid #D9D2C7' }}>
+      <td style={{ padding: '8px 12px' }}><code>--duration-fast</code></td>
+      <td style={{ padding: '8px 12px' }}>200ms</td>
+      <td style={{ padding: '8px 12px', color: '#6B635A' }}>Button presses, toggles</td>
+    </tr>
+    <tr style={{ borderBottom: '1px solid #D9D2C7' }}>
+      <td style={{ padding: '8px 12px' }}><code>--duration-normal</code></td>
+      <td style={{ padding: '8px 12px' }}>350ms</td>
+      <td style={{ padding: '8px 12px', color: '#6B635A' }}>Dropdowns, sidebar toggle</td>
+    </tr>
+    <tr style={{ borderBottom: '1px solid #D9D2C7' }}>
+      <td style={{ padding: '8px 12px' }}><code>--duration-slow</code></td>
+      <td style={{ padding: '8px 12px' }}>500ms</td>
+      <td style={{ padding: '8px 12px', color: '#6B635A' }}>Modals, page transitions</td>
+    </tr>
+    <tr style={{ borderBottom: '1px solid #D9D2C7' }}>
+      <td style={{ padding: '8px 12px' }}><code>--ease-out</code></td>
+      <td style={{ padding: '8px 12px' }}><code>cubic-bezier(0.22, 1, 0.36, 1)</code></td>
+      <td style={{ padding: '8px 12px', color: '#6B635A' }}>Entrances</td>
+    </tr>
+    <tr style={{ borderBottom: '1px solid #D9D2C7' }}>
+      <td style={{ padding: '8px 12px' }}><code>--ease-in</code></td>
+      <td style={{ padding: '8px 12px' }}><code>cubic-bezier(0.55, 0, 1, 0.45)</code></td>
+      <td style={{ padding: '8px 12px', color: '#6B635A' }}>Exits</td>
+    </tr>
+    <tr>
+      <td style={{ padding: '8px 12px' }}><code>--ease-spring</code></td>
+      <td style={{ padding: '8px 12px' }}><code>cubic-bezier(0.34, 1.56, 0.64, 1)</code></td>
+      <td style={{ padding: '8px 12px', color: '#6B635A' }}>Interactive feedback</td>
+    </tr>
+  </tbody>
+</table>
+
+<p style={{ marginTop: 12, fontSize: 14, color: '#6B635A' }}>
+  All durations collapse to <code>0ms</code> when <code>prefers-reduced-motion: reduce</code> is active.
+</p>
+
+---
+
+export function ColorSwatch({ color, name, token, dark, border }) {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+      <div style={{
+        width: '100%', height: 56, borderRadius: 10, backgroundColor: color,
+        border: border ? '1px solid #D9D2C7' : 'none',
+      }} />
+      <span style={{ fontSize: 13, fontWeight: 600, color: '#2C2825' }}>{name}</span>
+      <code style={{ fontSize: 11, color: '#6B635A' }}>{token}</code>
+      <code style={{ fontSize: 11, color: '#6B635A' }}>{color}</code>
+    </div>
+  );
+}
+
+export function TypeSample({ name, size, lineHeight, weight, mono }) {
+  return (
+    <div style={{ display: 'flex', alignItems: 'baseline', gap: 16 }}>
+      <span style={{ width: 100, fontSize: 12, color: '#6B635A', flexShrink: 0 }}>{name}</span>
+      <span style={{
+        fontFamily: mono ? "'JetBrains Mono', monospace" : "'Satoshi', sans-serif",
+        fontSize: size, lineHeight, fontWeight: weight, color: '#2C2825',
+      }}>
+        The quick brown fox
+      </span>
+      <span style={{ fontSize: 11, color: '#6B635A', flexShrink: 0 }}>{size}/{lineHeight}</span>
+    </div>
+  );
+}
+
+export function SpacingSample({ token, value }) {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+      <code style={{ width: 80, fontSize: 11, color: '#6B635A' }}>{token}</code>
+      <div style={{ width: parseInt(value), height: 16, borderRadius: 4, backgroundColor: '#B85C38' }} />
+      <span style={{ fontSize: 11, color: '#6B635A' }}>{value}</span>
+    </div>
+  );
+}
+
+export function RadiusSample({ name, value }) {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 8 }}>
+      <div style={{ width: 56, height: 56, borderRadius: value, backgroundColor: '#F0EBE3', border: '2px solid #D9D2C7' }} />
+      <span style={{ fontSize: 12, fontWeight: 600, color: '#2C2825' }}>{name}</span>
+      <code style={{ fontSize: 11, color: '#6B635A' }}>{value}</code>
+    </div>
+  );
+}
+
+export function ElevationSample({ level, shadow }) {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 8 }}>
+      <div style={{ width: 80, height: 64, borderRadius: 10, backgroundColor: '#F0EBE3', boxShadow: shadow }} />
+      <span style={{ fontSize: 12, fontWeight: 600, color: '#2C2825' }}>elevation-{level}</span>
+    </div>
+  );
+}

package/src/docs/GettingStarted.mdx

@@ -0,0 +1,145 @@
+{/* @jsxImportSource react */}
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Getting Started" />
+
+# Getting Started with Weave
+
+Weave is a human-centered design system for productivity software. Warm over cold. Fluid over rigid. Connected over isolated.
+
+## Installation
+
+```bash
+# npm
+npm install @weave-ds/react
+
+# pnpm
+pnpm add @weave-ds/react
+```
+
+### Peer Dependencies
+
+Weave requires React 18 or 19:
+
+```bash
+npm install react react-dom
+```
+
+## Setup
+
+### 1. Import the theme CSS
+
+Add this import to your app's entry point. This loads all design tokens (colors, typography, spacing, shadows, motion) and Tailwind utilities used by Weave components.
+
+```tsx
+// app.tsx or main.tsx
+import '@weave-ds/react/theme.css';
+```
+
+### 2. Load the fonts
+
+Weave uses [Satoshi](https://www.fontshare.com/fonts/satoshi) as the primary typeface and [JetBrains Mono](https://www.jetbrains.com/lp/mono/) for code. Add these to your HTML `<head>`:
+
+```html
+<link href="https://api.fontshare.com/v2/css?f[]=satoshi@400,500,600,700&display=swap" rel="stylesheet">
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+```
+
+### 3. Use components
+
+```tsx
+import { Button, Card, Badge } from '@weave-ds/react';
+
+function App() {
+  return (
+    <Card className="max-w-md">
+      <Card.Header>
+        <h2>My Project</h2>
+      </Card.Header>
+      <Card.Content>
+        <p>A warm, human-centered interface.</p>
+        <Badge variant="success">Active</Badge>
+      </Card.Content>
+      <Card.Actions>
+        <Button variant="ghost">Cancel</Button>
+        <Button>Save</Button>
+      </Card.Actions>
+    </Card>
+  );
+}
+```
+
+### 4. Toast notifications (optional)
+
+Wrap your app in `ToastProvider` to enable toast notifications:
+
+```tsx
+import { ToastProvider } from '@weave-ds/react';
+
+function App() {
+  return (
+    <ToastProvider>
+      <YourApp />
+    </ToastProvider>
+  );
+}
+```
+
+Then use the `useToast` hook anywhere:
+
+```tsx
+import { useToast, Button } from '@weave-ds/react';
+
+function SaveButton() {
+  const { toast } = useToast();
+  return (
+    <Button onClick={() => toast({ title: 'Saved!', variant: 'success' })}>
+      Save
+    </Button>
+  );
+}
+```
+
+## Tailwind CSS Integration
+
+If your app uses Tailwind CSS v4, add a `@source` directive so Tailwind generates the utility classes used by Weave components:
+
+```css
+/* your app's main CSS file */
+@import "tailwindcss";
+@source "../node_modules/@weave-ds/react/src";
+```
+
+This enables you to extend and override Weave's styles using standard Tailwind utilities.
+
+## Programmatic Token Access
+
+For cases where you need token values in JavaScript (charting libraries, dynamic styles):
+
+```tsx
+import { colors, spacing, radii } from '@weave-ds/react/tokens';
+
+console.log(colors.rust);    // '#B85C38'
+console.log(spacing[6]);     // '24px'
+console.log(radii.lg);       // '16px'
+```
+
+## Design Philosophy
+
+Every decision in Weave traces back to one question: **does this feel human?**
+
+- **Warm Over Cold** — Rounded corners, warm neutrals, earthy accents
+- **Motion Is Meaning** — Purposeful animations that guide attention
+- **Breathing Space** — Generous whitespace, progressive disclosure
+- **Connected, Not Cluttered** — Visual relationships through proximity
+- **Personality in Details** — Satisfying micro-interactions
+
+## Accessibility
+
+All components target **WCAG 2.1 AA** compliance:
+
+- 4.5:1+ contrast ratios on all text
+- Visible focus rings (2px rust outline)
+- Full keyboard navigation
+- ARIA attributes and screen reader support
+- `prefers-reduced-motion` respected automatically

package/src/feedback/alert-banner/AlertBanner.stories.tsx

@@ -0,0 +1,10 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { AlertBanner } from './AlertBanner';
+
+const meta: Meta<typeof AlertBanner> = { title: 'Feedback/AlertBanner', component: AlertBanner, tags: ['autodocs'] };
+export default meta;
+type Story = StoryObj<typeof AlertBanner>;
+
+export const Info: Story = { args: { message: 'A new version is available. Refresh to update.', variant: 'info' } };
+export const Warning: Story = { args: { message: 'Your trial expires in 3 days.', variant: 'warning' } };
+export const Error: Story = { args: { message: 'Failed to save changes. Please try again.', variant: 'error' } };

package/src/feedback/alert-banner/AlertBanner.test.tsx

@@ -0,0 +1,16 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect } from 'vitest';
+import { AlertBanner } from './AlertBanner';
+
+describe('AlertBanner', () => {
+  it('renders message', () => {
+    render(<AlertBanner message="Update available" />);
+    expect(screen.getByRole('alert')).toHaveTextContent('Update available');
+  });
+  it('dismisses on close', async () => {
+    render(<AlertBanner message="Warning" />);
+    await userEvent.click(screen.getByRole('button', { name: 'Dismiss' }));
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+  });
+});

package/src/feedback/alert-banner/AlertBanner.tsx

@@ -0,0 +1,47 @@
+import { useState } from 'react';
+import { Info, AlertTriangle, AlertCircle, X } from 'lucide-react';
+import { cn } from '../../utils/cn';
+
+export type AlertBannerVariant = 'info' | 'warning' | 'error';
+
+export interface AlertBannerProps {
+  message: string;
+  variant?: AlertBannerVariant;
+  dismissible?: boolean;
+  className?: string;
+}
+
+const icons: Record<AlertBannerVariant, React.ReactNode> = {
+  info: <Info size={18} />,
+  warning: <AlertTriangle size={18} />,
+  error: <AlertCircle size={18} />,
+};
+
+const variantStyles: Record<AlertBannerVariant, string> = {
+  info: 'bg-rust-light text-rust-dark',
+  warning: 'bg-warning-light text-warning',
+  error: 'bg-error-light text-error',
+};
+
+export function AlertBanner({ message, variant = 'info', dismissible = true, className }: AlertBannerProps) {
+  const [visible, setVisible] = useState(true);
+  if (!visible) return null;
+
+  return (
+    <div className={cn('flex items-center gap-3 px-4 py-3 rounded-lg', variantStyles[variant], className)} role="alert">
+      <span className="shrink-0">{icons[variant]}</span>
+      <p className="flex-1" style={{ fontSize: 'var(--text-body-sm)', lineHeight: 'var(--leading-body-sm)' }}>{message}</p>
+      {dismissible && (
+        <button
+          type="button"
+          onClick={() => setVisible(false)}
+          className="shrink-0 p-1 rounded hover:bg-black/10 transition-colors"
+          aria-label="Dismiss"
+          style={{ transitionDuration: 'var(--duration-micro)' }}
+        >
+          <X size={14} />
+        </button>
+      )}
+    </div>
+  );
+}

package/src/feedback/alert-banner/index.ts

@@ -0,0 +1,2 @@
+export { AlertBanner } from './AlertBanner';
+export type { AlertBannerProps, AlertBannerVariant } from './AlertBanner';

package/src/feedback/modal/Modal.stories.tsx

@@ -0,0 +1,31 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Modal } from './Modal';
+import { Button } from '../../primitives/button';
+
+const meta: Meta<typeof Modal> = { title: 'Feedback/Modal', component: Modal, tags: ['autodocs'] };
+export default meta;
+type Story = StoryObj<typeof Modal>;
+
+export const Default: Story = {
+  render: () => {
+    const [open, setOpen] = useState(false);
+    return (
+      <>
+        <Button onClick={() => setOpen(true)}>Open Modal</Button>
+        <Modal open={open} onClose={() => setOpen(false)}>
+          <Modal.Header onClose={() => setOpen(false)}>Confirm Action</Modal.Header>
+          <Modal.Body>
+            <p className="text-text-secondary" style={{ fontSize: 'var(--text-body)' }}>
+              Are you sure you want to delete this project? This action cannot be undone.
+            </p>
+          </Modal.Body>
+          <Modal.Footer>
+            <Button variant="ghost" onClick={() => setOpen(false)}>Cancel</Button>
+            <Button variant="destructive" onClick={() => setOpen(false)}>Delete</Button>
+          </Modal.Footer>
+        </Modal>
+      </>
+    );
+  },
+};

package/src/feedback/modal/Modal.test.tsx

@@ -0,0 +1,33 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi } from 'vitest';
+import { Modal } from './Modal';
+
+describe('Modal', () => {
+  it('renders when open', () => {
+    render(<Modal open onClose={() => {}}>Content</Modal>);
+    expect(screen.getByRole('dialog')).toBeInTheDocument();
+  });
+  it('does not render when closed', () => {
+    render(<Modal open={false} onClose={() => {}}>Content</Modal>);
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+  });
+  it('closes on Escape', async () => {
+    const onClose = vi.fn();
+    render(<Modal open onClose={onClose}><button>Focus</button></Modal>);
+    await userEvent.keyboard('{Escape}');
+    expect(onClose).toHaveBeenCalled();
+  });
+  it('renders compound parts', () => {
+    render(
+      <Modal open onClose={() => {}}>
+        <Modal.Header>Title</Modal.Header>
+        <Modal.Body>Body</Modal.Body>
+        <Modal.Footer>Footer</Modal.Footer>
+      </Modal>,
+    );
+    expect(screen.getByText('Title')).toBeInTheDocument();
+    expect(screen.getByText('Body')).toBeInTheDocument();
+    expect(screen.getByText('Footer')).toBeInTheDocument();
+  });
+});

package/src/feedback/modal/Modal.tsx

@@ -0,0 +1,88 @@
+import { forwardRef, useEffect, type ComponentPropsWithoutRef } from 'react';
+import { X } from 'lucide-react';
+import { cn } from '../../utils/cn';
+import { useFocusTrap } from '../../hooks/use-focus-trap';
+
+export interface ModalProps {
+  open: boolean;
+  onClose: () => void;
+  children: React.ReactNode;
+  className?: string;
+}
+
+function ModalRoot({ open, onClose, children, className }: ModalProps) {
+  const containerRef = useFocusTrap<HTMLDivElement>(open);
+
+  useEffect(() => {
+    if (!open) return;
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    document.addEventListener('keydown', handler);
+    return () => document.removeEventListener('keydown', handler);
+  }, [open, onClose]);
+
+  useEffect(() => {
+    if (open) {
+      document.body.style.overflow = 'hidden';
+    }
+    return () => { document.body.style.overflow = ''; };
+  }, [open]);
+
+  if (!open) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
+      <div
+        className="absolute inset-0 bg-text-primary/30 animate-fade-in"
+        onClick={onClose}
+      />
+      <div
+        ref={containerRef}
+        role="dialog"
+        aria-modal="true"
+        className={cn(
+          'relative w-full max-w-lg rounded-xl bg-white shadow-3 overflow-hidden',
+          'animate-scale-in',
+          className,
+        )}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}
+
+const ModalHeader = forwardRef<HTMLDivElement, ComponentPropsWithoutRef<'div'> & { onClose?: () => void }>(
+  ({ className, children, onClose, ...props }, ref) => (
+    <div ref={ref} className={cn('flex items-center justify-between px-6 py-4 border-b border-border', className)} {...props}>
+      <h2 className="text-text-primary font-semibold" style={{ fontSize: 'var(--text-h3)', lineHeight: 'var(--leading-h3)' }}>{children}</h2>
+      {onClose && (
+        <button type="button" onClick={onClose} className="p-1.5 rounded-md text-text-secondary hover:bg-surface transition-colors" aria-label="Close" style={{ transitionDuration: 'var(--duration-micro)' }}>
+          <X size={18} />
+        </button>
+      )}
+    </div>
+  ),
+);
+ModalHeader.displayName = 'Modal.Header';
+
+const ModalBody = forwardRef<HTMLDivElement, ComponentPropsWithoutRef<'div'>>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} className={cn('px-6 py-4', className)} {...props} />
+  ),
+);
+ModalBody.displayName = 'Modal.Body';
+
+const ModalFooter = forwardRef<HTMLDivElement, ComponentPropsWithoutRef<'div'>>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} className={cn('flex justify-end gap-3 px-6 py-4 border-t border-border', className)} {...props} />
+  ),
+);
+ModalFooter.displayName = 'Modal.Footer';
+
+export const Modal = Object.assign(ModalRoot, {
+  Header: ModalHeader,
+  Body: ModalBody,
+  Footer: ModalFooter,
+});

package/src/feedback/modal/index.ts

@@ -0,0 +1,2 @@
+export { Modal } from './Modal';
+export type { ModalProps } from './Modal';

package/src/feedback/skeleton-loader/SkeletonLoader.stories.tsx

@@ -0,0 +1,23 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { SkeletonLoader } from './SkeletonLoader';
+
+const meta: Meta<typeof SkeletonLoader> = { title: 'Feedback/SkeletonLoader', component: SkeletonLoader, tags: ['autodocs'] };
+export default meta;
+type Story = StoryObj<typeof SkeletonLoader>;
+
+export const TextLines: Story = { args: { shape: 'text', lines: 3 } };
+export const AvatarShape: Story = { args: { shape: 'avatar', width: 56, height: 56 } };
+export const ImageShape: Story = { args: { shape: 'image', height: 160 } };
+
+export const CardSkeleton: Story = {
+  render: () => (
+    <div className="max-w-sm rounded-lg bg-surface p-6 shadow-1 flex flex-col gap-4">
+      <div className="flex items-center gap-3">
+        <SkeletonLoader shape="avatar" />
+        <SkeletonLoader shape="text" lines={2} />
+      </div>
+      <SkeletonLoader shape="image" height={120} />
+      <SkeletonLoader shape="text" lines={3} />
+    </div>
+  ),
+};

package/src/feedback/skeleton-loader/SkeletonLoader.test.tsx

@@ -0,0 +1,14 @@
+import { render } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import { SkeletonLoader } from './SkeletonLoader';
+
+describe('SkeletonLoader', () => {
+  it('renders text lines', () => {
+    const { container } = render(<SkeletonLoader shape="text" lines={3} />);
+    expect(container.querySelectorAll('[aria-hidden] > div')).toHaveLength(3);
+  });
+  it('renders avatar shape', () => {
+    const { container } = render(<SkeletonLoader shape="avatar" />);
+    expect(container.firstChild).toHaveAttribute('aria-hidden', 'true');
+  });
+});