# Introduction

> Gaudi is a curated React design system for blogs and applications, with shared foundations, rich components and reusable interface patterns.

Gaudi brings reusable React components, design foundations and practical interface patterns into one coherent system. It began with a blog and grew to support application interfaces: forms, data views, navigation, dialogs, dashboards and complete workflows, alongside rich editorial and MDX experiences.

The package is `@gaudi/design-system`; the source lives at [ahmadassaf/design-system](https://github.com/ahmadassaf/design-system).

## How this site is built

Every component, block, chart, chat and hook page is **generated from the design system's own metadata** (its `ai/components.json`, the pattern coverage manifest and the owner fixtures), so the docs cannot drift from the code. Each example renders the real fixture in an isolated frame, and its **Code** tab shows the same copyable source as Storybook, rewritten to public `@gaudi/design-system/...` imports.

- [Installation](https://design.gaudi.site/docs/getting-started): Add the package, the stylesheet and the Next.js config.
- [Foundations](https://design.gaudi.site/docs/foundations): Colours and tokens, typography, icons, accessibility and states.
- [Theming](https://design.gaudi.site/docs/theming): Eight presets, the theme contract and StyleGlide/tweakcn/shadcn import.
- [AI & agents](https://design.gaudi.site/docs/ai): llms.txt, the agent skill, the MCP server and the registry.
- [Components](https://design.gaudi.site/docs/components): Controls, inputs, overlays, data display, feedback and navigation.
- [Blocks](https://design.gaudi.site/docs/blocks): App shells, auth, dashboards, forms, scheduling, settings and more.

## What belongs in Gaudi

- **Foundations:** shared tokens, typography, colours, icons, motion and accessibility conventions.
- **Components:** reusable controls and compositions, with variants and interaction states for real product use.
- **Patterns and blocks:** application shells, settings, onboarding, collections and editorial page sections.
- **Publishing:** post components, reading layouts and MDX primitives for blogs and other content experiences.

Source: https://design.gaudi.site/docs (Markdown with example code: https://design.gaudi.site/docs.md)

---

# Installation

> Install @gaudi/design-system and render your first component.

## Install the package

Install the package from its GitHub repository, then import it as `@gaudi/design-system`.

```sh
pnpm add github:ahmadassaf/design-system
```

React, React DOM, Next.js, `next-themes` and Tailwind CSS are shared framework **peers**; Gaudi installs its own implementation libraries. Install the optional peers only for the features that need them:

```sh
pnpm add recharts        # Charts (@gaudi/design-system/charts)
pnpm add @xyflow/react   # Flow (@gaudi/design-system/core/Flow + flow.css)
```

## Use a component

```jsx
import { Avatar, Button, Dialog } from '@gaudi/design-system';
import '@gaudi/design-system/global.css';
```

For route-level code that imports one or two components, prefer **leaf entries** so bundlers do not traverse the full barrel:

```jsx
import Button from '@gaudi/design-system/core/Button';
import Dialog from '@gaudi/design-system/core/Dialog';
```

Only the explicit entries in the package `exports` are public: owner paths such as `/core/Button`, `/chat/ChatInput` and `/hooks/state/use-controllable-state`.

## Next steps

- [Set up with Next.js](https://design.gaudi.site/docs/getting-started/nextjs): transpilePackages, the stylesheet and the theme script.
- [Tailwind preset](https://design.gaudi.site/docs/getting-started/tailwind): Use Gaudi's tokens in your own utilities.
- [styles.css](https://design.gaudi.site/docs/getting-started/styles): global.css versus styles.css, themes.css and flow.css.
- [Fonts](https://design.gaudi.site/docs/getting-started/fonts): Gaudi never downloads fonts; wire next/font or @fontsource.

Source: https://design.gaudi.site/docs/getting-started (Markdown with example code: https://design.gaudi.site/docs/getting-started.md)

---

# Setup with Next.js

> Configure the App Router for Gaudi's React source, stylesheet and themes.

Gaudi ships **React source (JSX)** for a JSX-aware bundler and Tailwind CSS v4 processing, so Next.js must transpile it.

## 1. Transpile the package

```js title="next.config.mjs"
export default {
  transpilePackages: ['@gaudi/design-system']
};
```

## 2. Load the stylesheet once

```jsx title="app/layout.jsx"
import '@gaudi/design-system/global.css';
```

`global.css` loads Tailwind v4, Gaudi's tokens, foundations and component CSS, and scans the package source. If your app owns its Tailwind entry, use [styles.css](https://design.gaudi.site/docs/getting-started/styles) instead.

## 3. Add themes (optional)

Render the no-flash script in `<head>` and wrap the app in `ThemeProvider` from a client component:

```jsx title="app/layout.jsx"
import { getThemeScript } from '@gaudi/design-system/themes';
import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html lang='en' suppressHydrationWarning>
      <head><script dangerouslySetInnerHTML={{ __html: getThemeScript() }} /></head>
      <body><Providers>{children}</Providers></body>
    </html>
  );
}
```

```jsx title="app/providers.jsx"
'use client';
import { ThemeProvider } from '@gaudi/design-system/themes';

export const Providers = ({ children }) => <ThemeProvider defaultMode='system'>{children}</ThemeProvider>;
```

Apps that keep `next-themes` for light/dark pass `enableMode={false}` to `ThemeProvider` and `getThemeScript`. See the [theming guide](https://design.gaudi.site/docs/theming/guide).

## Site configuration

Site-aware components (navigation, footer, command launcher) read metadata from `SiteConfigProvider`; `LayoutContainer` wires it up. Gaudi never imports data from the consuming app.

```jsx
import { SiteConfigProvider } from '@gaudi/design-system/context';

<SiteConfigProvider metadata={siteMetadata} navigation={navigationMetadata}>
  <App />
</SiteConfigProvider>
```

> **Note:** This documentation site is itself a Next.js App Router app built this way: Gaudi's ThemeProvider, AppShell, Tabs, CodeBlock, Command and Button render its chrome.

Source: https://design.gaudi.site/docs/getting-started/nextjs (Markdown with example code: https://design.gaudi.site/docs/getting-started/nextjs.md)

---

# Tailwind preset

> Use Gaudi's colours, radii, typography and prose theme in your own Tailwind utilities.

Tailwind v4 loads Gaudi's configuration through `global.css`, so most apps need nothing else. For a JavaScript config, use the preset and the two plugins from the package:

```js title="tailwind.config.js"
const designSystemPreset = require('@gaudi/design-system/tailwind-preset');
const addVariablesColors = require('@gaudi/design-system/tailwind/addVariablesColors');
const tailwindGrid = require('@gaudi/design-system/tailwind/tailwindGrid');

module.exports = {
  content: [
    './app/**/*.{js,jsx,ts,tsx,mdx}',
    './node_modules/@gaudi/design-system/src/**/*.{js,jsx,mdx}'
  ],
  plugins: [addVariablesColors, tailwindGrid],
  presets: [designSystemPreset]
};
```

With a CSS-first Tailwind v4 entry, point `@config` at the package config and add the package source:

```css title="app/globals.css"
@import 'tailwindcss';
@custom-variant dark (&:where(.dark, .dark *));
@config '../node_modules/@gaudi/design-system/src/tailwind/config.js';
@source '../node_modules/@gaudi/design-system/src';
@import '@gaudi/design-system/styles.css';
```

Use the **semantic utilities** (`bg-surface`, `text-text-muted`, `border-border`, `bg-accent`, `text-danger`…) built from the token names, never raw hex or palette shades for UI state. See [Colours & tokens](https://design.gaudi.site/docs/foundations/colours).

Source: https://design.gaudi.site/docs/getting-started/tailwind (Markdown with example code: https://design.gaudi.site/docs/getting-started/tailwind.md)

---

# styles.css

> Which stylesheet to import, and how corner radius and density are configured.

| Import | When |
| --- | --- |
| `@gaudi/design-system/global.css` | Apps without their own Tailwind entry: loads Tailwind v4, Gaudi tokens, foundations and component CSS, and scans the package source. |
| `@gaudi/design-system/styles.css` | Apps that own their Tailwind entry: import after `@import "tailwindcss";` and add `@source` for the package. |
| `@gaudi/design-system/themes.css` | Every theme preset, switched with `data-theme` (optional when you use `ThemeProvider`). |
| `@gaudi/design-system/flow.css` | Only with the Flow component. |

`src/styles.css` aggregates shared foundations and owner-local component styles; `src/global.css` adds Tailwind and application body defaults. CSS token definitions are authoritative; `tokens.json` is the JavaScript/preset projection.

## Corner radius

Elements use a soft 4px radius. Set `--ds-radius` on the root after importing the stylesheet to change every corner without rebuilding CSS:

```css
:root {
  --ds-radius: 4px; /* 0px for square corners */
}
```

## Density

Inner padding, gaps and control heights scale with `--ds-space-scale` (default `1`):

```css
:root {
  --ds-space-scale: 0.875; /* compact */
}
```

Density: Inner padding, gaps and control heights scale with --ds-space-scale (default 1). Prefer gap-* over space-x/y-*. Component CSS uses calc(var(--ds-space-scale, 1) * <length>).

| Scale | `--ds-space-scale` |
| --- | --- |
| tight | 0.75 |
| compact | 0.875 |
| default | 1 |
| relaxed | 1.25 |
| spacious | 1.5 |

Radius: All corners use --ds-radius (configurable down to 0px). Circles only for intrinsic shapes. Default `4px` via `--ds-radius`.

Source: https://design.gaudi.site/docs/getting-started/styles (Markdown with example code: https://design.gaudi.site/docs/getting-started/styles.md)

---

# Fonts

> Gaudi never downloads fonts; load them with next/font or @fontsource and put them first in the stack.

Theme font stacks name an open-source family first and fall back to system faces. `@fontsource/<family>` registers the real family name, so the stack picks it up automatically.

`next/font` generates its own family name: expose it as a CSS variable and put it first in the theme's stack, as the default theme does with `--font-space-inter`.

```jsx title="app/layout.jsx"
import { Fraunces, Source_Sans_3 } from 'next/font/google';

const serif = Fraunces({ subsets: ['latin'], variable: '--font-fraunces' });
const sans = Source_Sans_3({ subsets: ['latin'], variable: '--font-source-sans' });

// <html lang='en' className={`${serif.variable} ${sans.variable}`} suppressHydrationWarning>
```

```css title="app/globals.css"
/* after the Gaudi stylesheets */
[data-theme='folio'] {
  --ds-font-sans: var(--font-source-sans), ui-sans-serif, system-ui, sans-serif;
  --ds-font-heading: var(--font-fraunces), ui-serif, Georgia, serif;
}
```

Curated pairs are exported as `FONT_PAIRS` from `@gaudi/design-system/themes`. See [Typography](https://design.gaudi.site/docs/foundations/typography) for the default stacks.

Source: https://design.gaudi.site/docs/getting-started/fonts (Markdown with example code: https://design.gaudi.site/docs/getting-started/fonts.md)

---

# Foundations

> Tokens, typography, icons, motion, accessibility and state conventions shared by every Gaudi owner.

Gaudi preserves a clear hierarchy, compact controls, neutral surfaces, restrained elevation and functional blue accents. Article reading stays comfortable and application layouts stay efficient, in both light and dark themes.

- [Colours & tokens](https://design.gaudi.site/docs/foundations/colours): Semantic colour tokens, charts, radius, density and motion.
- [Typography](https://design.gaudi.site/docs/foundations/typography): Font stacks, the type scale and prose.
- [Icons](https://design.gaudi.site/docs/foundations/icons): The icon registry behind ``.
- [Accessibility](https://design.gaudi.site/docs/foundations/accessibility): Semantics, focus, keyboard, motion, RTL and responsive checks.
- [States](https://design.gaudi.site/docs/foundations/states): Loading, empty, error, disabled and read-only states.

Source: https://design.gaudi.site/docs/foundations (Markdown with example code: https://design.gaudi.site/docs/foundations.md)

---

# Colours & tokens

> The semantic --ds-* contract. Every swatch below reads the live theme, so switch presets or modes to compare.

Runtime CSS (`src/tokens/tokens.css`) is the token authority; `tokens.json` is the supported JavaScript/preset projection exported from `@gaudi/design-system/tokens`.

```js
import tokens from '@gaudi/design-system/tokens';
```

## Colour

Use semantic Tailwind utilities (bg-*, text-*, border-*, ring-*) built from these names, never raw hex or palette shades for UI state. Status colours always pair with text or an icon.

Semantic colour utilities (`bg-*`, `text-*`, `border-*`, CSS variables `--ds-color-*`): `accent`, `accent-dark`, `accent-foreground`, `accent-muted`, `accent-subtle`, `attention`, `attention-border`, `attention-foreground`, `attention-muted`, `attention-subtle`, `background`, `border`, `border-dark`, `border-muted`, `danger`, `danger-border`, `danger-foreground`, `danger-muted`, `danger-subtle`, `dark`, `discovery`, `discovery-border`, `discovery-foreground`, `discovery-muted`, `discovery-subtle`, `foreground`, `info`, `info-border`, `info-foreground`, `info-muted`, `info-subtle`, `success`, `success-border`, `success-foreground`, `success-muted`, `success-subtle`, `surface`, `surface-dark`, `surface-muted`, `surface-raised`, `text`, `text-inverse`, `text-muted`, `text-subtle`, `ui-accent`, `ui-accent-foreground`, `ui-attention-ink`, `ui-background`, `ui-border`, `ui-card`, `ui-card-foreground`, `ui-chart-1`, `ui-chart-2`, `ui-chart-3`, `ui-chart-4`, `ui-chart-5`, `ui-danger-ink`, `ui-destructive`, `ui-destructive-foreground`, `ui-discovery-ink`, `ui-focus`, `ui-focus-foreground`, `ui-focus-ink`, `ui-foreground`, `ui-info-ink`, `ui-input`, `ui-invert`, `ui-invert-foreground`, `ui-muted`, `ui-muted-foreground`, `ui-popover`, `ui-popover-foreground`, `ui-primary`, `ui-primary-foreground`, `ui-primary-strong`, `ui-ring`, `ui-secondary`, `ui-secondary-foreground`, `ui-sidebar`, `ui-sidebar-accent`, `ui-sidebar-accent-foreground`, `ui-sidebar-border`, `ui-sidebar-foreground`, `ui-sidebar-primary`, `ui-sidebar-primary-foreground`, `ui-sidebar-ring`, `ui-success-ink`, `ui-warning-ink`, `warning`, `warning-border`, `warning-foreground`, `warning-muted`, `warning-subtle`.

Never use colour as the only status cue: status colours always pair with text or an icon.

## Radius and density

Density: Inner padding, gaps and control heights scale with --ds-space-scale (default 1). Prefer gap-* over space-x/y-*. Component CSS uses calc(var(--ds-space-scale, 1) * <length>).

| Scale | `--ds-space-scale` |
| --- | --- |
| tight | 0.75 |
| compact | 0.875 |
| default | 1 |
| relaxed | 1.25 |
| spacious | 1.5 |

Radius: All corners use --ds-radius (configurable down to 0px). Circles only for intrinsic shapes. Default `4px` via `--ds-radius`.

## Motion

Durations and easings respect `prefers-reduced-motion`.

| Token | Value |
| --- | --- |
| duration feedback | `120ms` |
| duration focal | `560ms` |
| duration overlay | `320ms` |
| duration state | `180ms` |
| ease in | `cubic-bezier(0.7, 0, 0.84, 0)` |
| ease out | `cubic-bezier(0.16, 1, 0.3, 1)` |
| ease standard | `cubic-bezier(0.2, 0, 0, 1)` |

Source: https://design.gaudi.site/docs/foundations/colours (Markdown with example code: https://design.gaudi.site/docs/foundations/colours.md)

---

# Typography

> Font stacks, line heights and the prose scale used by articles and docs.

| Family | Stack |
| --- | --- |
| mono | `JetBrains Mono, Menlo, Monaco, monospace` |
| sans | `var(--font-space-inter, 'Inter Variable'), Inter Variable, system-ui, sans-serif` |

| Line height | Value |
| --- | --- |
| body | 1.6 |
| prose | 1.7 |
| tight | 1.15 |

## Prose

Long-form content uses the `.prose` class from Gaudi's typography foundation: comfortable measure, a {'1.7'} line height and heading rhythm tuned for articles. This page is rendered inside `.prose`.

Use `Typography` and `typographyVariants` from the package root for headings, labels and descriptions in application UI, and the [fonts guide](https://design.gaudi.site/docs/getting-started/fonts) to load real families.

Source: https://design.gaudi.site/docs/foundations/typography (Markdown with example code: https://design.gaudi.site/docs/foundations/typography.md)

---

# Icons

> The icon registry behind Icon, plus brand marks and animated icons.

```jsx
import { Icon } from '@gaudi/design-system';

<Icon name='Info' size='md' color='primary' label='More information' />
```

Pass `label` when the icon carries meaning and `decorative` otherwise. Sizes: `xs`, `sm`, `md`, `lg`, `xl`, `2xl` or a number. Brand marks are separate entries such as `@gaudi/design-system/icons/brands/github`.

## Registry

456 registry icon names for `<Icon name='…' />`: `Accessibility`, `Activity`, `AlertCircle`, `AlertTriangle`, `AlignCenter`, `AlignLeft`, `AlignRight`, `Apple`, `AppWindow`, `Archive`, `ArrowDown`, `ArrowDownCircle`, `ArrowDownIcon`, `ArrowDownToLine`, `ArrowLeft`, `ArrowLeftFromLine`, `ArrowLeftRight`, `ArrowLeftToLine`, `ArrowLongLeftIcon`, `ArrowLongRightIcon`, `ArrowRight`, `ArrowRightFromLine`, `ArrowRightOnRectangleIcon`, `ArrowRightToLine`, `ArrowUp`, `ArrowUpCircle`, `ArrowUpDown`, `ArrowUpIcon`, `ArrowUpRight`, `ArrowUpToLine`, `AtSign`, `AudioLines`, `Award`, `BadgeCheck`, `Ban`, `Banknote`, `BarChart`, `BarChart2`, `BarChart3`, `Battery`, `Bell`, `BellOff`, `Bluetooth`, `Bold`, `Book`, `Bookmark`, `BookmarkCheck`, `BookOpen`, `BookOpenIcon`, `BookText`, `BookUser`, `Bot`, `Boxes`, `Braces`, `Brain`, `Briefcase`, `BriefcaseBusiness`, `Bug`, `Building`, `Building2`, `Cable`, `Calculator`, `Calendar`, `CalendarCheck`, `CalendarClock`, `CalendarDays`, `CalendarDaysIcon`, `CalendarOutline`, `CalendarRange`, `CalendarSearch`, `CardSim`, `ChartArea`, `ChartBar`, `ChartLine`, `ChartNoAxesColumnDecreasing`, `ChatBubbleLeftRightIcon`, `Check`, `CheckCheck`, `CheckCircle`, `CheckIcon`, `CheckSquare`, `ChessKnight`, `ChevronDown`, `ChevronDownIcon`, `ChevronFirst`, `ChevronLast`, `ChevronLeft`, `ChevronRight`, `ChevronRightIcon`, `ChevronsLeft`, `ChevronsRight`, `ChevronsUpDown`, `ChevronUp`, `Circle`, `CircleAlert`, `CircleCheck`, `CircleDashed`, `CircleDollarSign`, `CircleDot`, `CircleHelp`, `CircleMinus`, `CirclePause`, `CirclePlus`, `CircleUserRound`, `CircleX`, `Clipboard`, `ClipboardList`, `Clock`, `Clock3`, `ClockIcon`, `CloudDownload`, `CloudOff`, `CloudSun`, `CloudUpload`, `Code`, `Code2`, `CodeBracketIcon`, `Codepen`, `Coffee`, `Coins`, `Columns2`, `Columns3`, `Combine`, `Command`, `Compass`, `Copy`, `CopyIcon`, `CornerDownLeft`, `CornerDownRight`, `CornerUpLeft`, `CornerUpRight`, `Cpu`, `CreditCard`, `css`, `Cubes`, `Database`, `Distribution`, `docker`, `DollarSign`, `Download`, `EllipsisVertical`, `EnvelopeIcon`, `ExclamationTriangleIcon`, `ExternalLink`, `ExternalLinkOutline`, `Eye`, `EyeOff`, `FaceIdError`, `file`, `File`, `FileArchive`, `FileCheck`, `FileCode`, `FileImage`, `FileJson`, `FileSearch`, `FileSignature`, `FileSpreadsheet`, `FileText`, `FileType2`, `Filter`, `Fingerprint`, `FingerPrintIcon`, `FingerprintPattern`, `Flag`, `Flame`, `FlaskConical`, `FlipHorizontal`, `FlipVertical`, `folder`, `Folder`, `folder-open`, `FolderGit2`, `FolderOpen`, `FolderPlus`, `Fork`, `Funnel`, `Gaudi`, `Gauge`, `git`, `GitBranch`, `GitCompareArrows`, `GitFork`, `github`, `Github`, `GitMerge`, `GitPullRequest`, `GitPullRequestArrow`, `Globe`, `Google`, `GoogleCloud`, `GraduationCap`, `Grid`, `Grid2x2`, `Grid3X3`, `GripHorizontal`, `GripVertical`, `Hand`, `Handshake`, `HandshakeLine`, `Hash`, `Headphones`, `Heart`, `HeartPulse`, `HelpCircle`, `History`, `Home`, `HomeIcon`, `Hourglass`, `House`, `html`, `IdCard`, `IdentificationIcon`, `Image`, `Inbox`, `IndentDecrease`, `IndentIncrease`, `Info`, `InformationCircleIcon`, `Italic`, `javascript`, `json`, `Kanban`, `Key`, `Keyboard`, `KeyRound`, `KeySquare`, `LandPlot`, `Laptop`, `Layers`, `Layout`, `LayoutDashboard`, `LayoutGrid`, `LayoutTemplate`, `Library`, `LifeBuoy`, `Lightbulb`, `LightBulbIcon`, `LightbulbOff`, `LineChart`, `Link`, `Link2`, `Link2Off`, `linkedin`, `Linkedin`, `LinkIcon`, `LinkSlashIcon`, `List`, `ListChecks`, `ListFilter`, `ListFilterPlus`, `ListMusic`, `ListPlus`, `ListTodo`, `ListTree`, `Loader2`, `LoaderCircle`, `LocateFixed`, `Lock`, `LogOut`, `Magnet`, `MagnifyingGlassIcon`, `mail`, `Mail`, `MailOutline`, `Map`, `MapPin`, `MapPinCheckInside`, `MapPinned`, `markdown`, `Maximize`, `Maximize2`, `medium`, `Medium`, `Megaphone`, `Memory`, `Menu`, `Merge`, `MessageCircle`, `MessageSquare`, `MessageSquareMore`, `MessageSquareReply`, `Mic`, `Microsoft`, `Minimize`, `Minimize2`, `Minus`, `MinusIcon`, `Monitor`, `MonitorSmartphone`, `Moon`, `MoonFill`, `MoreHorizontal`, `MoreVertical`, `MousePointer2`, `Music`, `Network`, `NewspaperIcon`, `node`, `Package`, `Palette`, `PanelLeft`, `PanelLeftClose`, `PanelLeftOpen`, `PanelRightOpen`, `Panels`, `Paperclip`, `Pause`, `PauseCircle`, `Paypal`, `Pencil`, `PencilSparkles`, `PenSquare`, `PenTool`, `Percent`, `Phone`, `PhoneCall`, `PhotoIcon`, `PictureInPicture2`, `PieChart`, `Pin`, `PinOff`, `Pipette`, `Plane`, `Play`, `Plus`, `PlusIcon`, `Podcast`, `Presentation`, `Printer`, `Prisma`, `Puzzle`, `python`, `QrCode`, `Quote`, `Radio`, `RadioTower`, `react`, `Receipt`, `RectangleGroupIcon`, `RectangleStackIcon`, `Redo`, `RefreshCw`, `Repeat`, `Repeat2`, `Reply`, `Robot`, `Rocket`, `RotateCcw`, `RotateCw`, `Route`, `Save`, `Scale`, `Scan`, `ScanSearch`, `Scissors`, `Search`, `SearchCheck`, `Send`, `Server`, `Settings`, `Settings2`, `Share2`, `Shield`, `ShieldAlert`, `ShieldCheck`, `ShieldQuestionMark`, `Ship`, `ShoppingBag`, `ShoppingCart`, `Signal`, `Signpost`, `Siren`, `SkipBack`, `SkipForward`, `SlidersHorizontal`, `Smartphone`, `Smile`, `Sparkles`, `Split`, `Sprout`, `Square`, `Square3Stack3DIcon`, `SquareActivity`, `SquareCheck`, `SquareDashedMousePointer`, `SquarePen`, `SquareTerminal`, `SquareUser`, `Star`, `Store`, `Strikethrough`, `Sun`, `SunFill`, `Table`, `Tablet`, `Tag`, `TagIcon`, `Tags`, `Target`, `Terminal`, `TestTube2`, `ThumbsDown`, `ThumbsUp`, `Timer`, `TowerControl`, `Trash`, `Trash2`, `TrendingDown`, `TrendingUp`, `TriangleAlert`, `Trophy`, `Truck`, `twitter`, `Twitter`, `Type`, `typescript`, `Underline`, `Undo`, `Ungroup`, `Unlink`, `Upload`, `User`, `UserCheck`, `UserGroupIcon`, `UserMinus`, `UserPlus`, `UserRound`, `UserRoundCheck`, `UserRoundCog`, `UserRoundX`, `Users`, `UsersRound`, `Video`, `VideoOff`, `Volume2`, `VolumeOff`, `VolumeX`, `VscFile`, `VscFolder`, `VscFolderOpened`, `Wallet`, `WalletCards`, `Warning`, `Waypoints`, `Webhook`, `Wifi`, `Workflow`, `Wrench`, `X`, `XCircle`, `youtube`, `Youtube`, `Zap`, `ZoomIn`, `ZoomOut`.

Source: https://design.gaudi.site/docs/foundations/icons (Markdown with example code: https://design.gaudi.site/docs/foundations/icons.md)

---

# Accessibility

> The accessibility, keyboard, motion, RTL and responsive conventions every owner follows.

Each component page lists its own accessibility contract under **Accessibility**. These conventions apply across the system.

## Semantics and names

- Use semantic elements, visible labels, associated errors and meaningful accessible names.
- Name every navigation and complementary region; keep a skip link and a main landmark in app shells.
- Never use colour as the only status cue; pair status colours with text or an icon.

## Keyboard and focus

- Every interaction is keyboard reachable, with a visible focus ring from the `focus` token.
- Shortcuts respect editable fields and IME composition (see [useHotkey](https://design.gaudi.site/docs/hooks/use-hotkey)).
- Overlays trap focus and return it to a surviving, meaningful target when they close.
- Keys and DOM identity stay stable through selection, filtering and responsive changes, preserving focus and scroll position.

## Motion

Animations respect `prefers-reduced-motion` and forced colours ([usePrefersReducedMotion](https://design.gaudi.site/docs/hooks/use-prefers-reduced-motion)). Initial docs loads never steal focus or scroll the page.

## Right-to-left

Components use logical properties (`inline-start`, `inline-end`), so they mirror under `dir='rtl'`. Wrap RTL regions in `DirectionProvider` so Radix-based parts follow:

```jsx
import { DirectionProvider } from '@gaudi/design-system/core/Direction';

<DirectionProvider dir='rtl'><div dir='rtl'>{controls}</div></DirectionProvider>
```

Every example on this site has an **RTL** toggle in its toolbar.

## Responsive checks

Build for narrow containers as well as wide pages: let labels and actions wrap, keep full-width elements aligned, and contain deliberately scrollable charts, tables and boards within their own regions. Verify narrow phones, common phones, tablets, laptops and wide desktops (for example 320–360, 390, 768, 1280 and 1600px) in light and dark. Every example here has phone/tablet/desktop width toggles.

## Contrast

Every theme preset passes WCAG AA pairs in both modes (`checkContrast`); the `contrast` preset goes further with 7:1 body text. See the [theming guide](https://design.gaudi.site/docs/theming/guide#contrast).

Source: https://design.gaudi.site/docs/foundations/accessibility (Markdown with example code: https://design.gaudi.site/docs/foundations/accessibility.md)

---

# States & recovery

> Loading, empty, error, disabled and read-only states, and how components recover.

Interactive owners document their states alongside their examples. Shared conventions:

- **Loading:** compose Core [Skeleton](https://design.gaudi.site/docs/components/skeleton) and [Loader](https://design.gaudi.site/docs/components/loader); placeholder layouts are decorative and hidden from assistive technology.
- **Empty:** use [EmptyState](https://design.gaudi.site/docs/components/empty-state) with a clear next action.
- **Errors:** associate messages with their field ([Field](https://design.gaudi.site/docs/components/field)); use [Banner](https://design.gaudi.site/docs/components/banner) and [Toast](https://design.gaudi.site/docs/components/toast) for page-level feedback.
- **Disabled and read-only:** respect changes immediately, keep read-only values focusable and copyable.
- **Controlled values stay authoritative:** compose host callbacks and honour cancellation where the contract allows it.
- **Async work:** clean up listeners, timers and pending work, and prevent stale results from affecting a different request or an unmounted view.

Gaudi owns presentation, semantics, keyboard/focus behaviour and local interaction state. Applications own business rules, permissions, persistence and service requests; mocked uploads, messages and saves in examples never connect to real services.

Source: https://design.gaudi.site/docs/foundations/states (Markdown with example code: https://design.gaudi.site/docs/foundations/states.md)

---

# Theming

> One semantic contract, eight WCAG AA presets, a runtime provider and lossless import/export.

A theme overrides the semantic `--ds-*` contract (surfaces, text, borders, accent, focus, status, charts, sidebar and shadows for light and dark, plus fonts, radius and density). Every other token derives from it, so components need no theme-specific code.

```jsx
// Static: every preset, switched by an attribute
import '@gaudi/design-system/themes.css';
// <html data-theme='folio' className='dark'>

// Next.js App Router: no-flash script in app/layout.jsx, provider in a client component
import { getThemeScript, ThemeProvider, useTheme } from '@gaudi/design-system/themes';
// <head><script dangerouslySetInnerHTML={{ __html: getThemeScript() }} /></head>
// <ThemeProvider defaultMode='system'>{children}</ThemeProvider>
// const { theme, setTheme, mode, setMode } = useTheme();
```

## Presets

Try them live: each card is a nested `data-theme` scope; **Use** applies the preset to the whole site (the header picker does the same).

Theme presets: `contrast`, `ember`, `folio`, `gaudi`, `graphite`, `grove`, `midnight`, `pastel`.

**Bring any [StyleGlide](https://www.styleglide.ai/themes), [tweakcn](https://tweakcn.com) or [shadcn/ui](https://ui.shadcn.com/themes) theme:** the contract follows the shadcn CSS-variable convention, so their themes import as-is on the [Themes page](https://design.gaudi.site/themes), with `gaudi-ds theme import`, or through the `import_theme` MCP tool.

- [Theming guide](https://design.gaudi.site/docs/theming/guide): The full contract, runtime API, fonts, import/export and contrast.
- [Themes page](https://design.gaudi.site/themes): Gallery plus a paste-in importer and exporter.
- [Theme Studio](https://design.gaudi.site/docs/theming/studio): Edit, generate, check and export themes in Storybook.

Source: https://design.gaudi.site/docs/theming (Markdown with example code: https://design.gaudi.site/docs/theming.md)

---

# Theming guide

> The theme contract, runtime API, Next.js setup, fonts, import/export and contrast, rendered from the design system THEMING.md.

> Rendered from [src/tokens/THEMING.md](https://github.com/ahmadassaf/design-system/blob/main/src/tokens/THEMING.md) at build time.

A Gaudi theme overrides a fixed set of semantic `--ds-*` tokens (the **theme contract**) for light and dark. Every other token in `tokens.css` either aliases a contract token or is derived from one, so components never need theme-specific code. Themes are JSON (`themes/theme.schema.json`), compiled to CSS scoped by `[data-theme="<id>"]`, and interchangeable with [shadcn/ui](https://ui.shadcn.com/themes), [tweakcn](https://tweakcn.com) and [StyleGlide](https://www.styleglide.ai/themes) themes. **Bring any StyleGlide, tweakcn or shadcn theme:** paste its CSS into Theme Studio or run `gaudi-ds theme import`, and it applies as-is.

The default theme, `gaudi`, is extracted programmatically from `tokens.css`; applying it changes nothing. Source of truth for the contract: `src/themes/contract.js`.

## Contract (134 values)

Per mode (`light`, `dark`): 58 colours + 6 shadows. Shared: 4 font families, radius and density.

| Group | Tokens (`--ds-color-<token>`) | shadcn equivalent |
| --- | --- | --- |
| Surfaces | `surface`, `surface-muted`, `surface-raised` | background, muted, card/popover |
| Text | `text`, `text-muted`, `text-subtle`, `text-inverse` | foreground, muted-foreground |
| Borders | `border`, `border-muted` | border, input |
| Accent | `accent`, `accent-dark`, `accent-foreground`, `accent-muted`, `accent-subtle` | primary, primary-foreground, secondary, accent |
| Focus | `focus`, `focus-foreground` | ring |
| Status (×6) | `success`, `warning`, `danger`, `discovery`, `info`, `attention`, each with `-foreground`, `-muted`, `-subtle`, `-border` | destructive (+ success/warning/info when present) |
| Charts | `chart-1` … `chart-8` | chart-1 … chart-5 |
| Sidebar | `sidebar`, `sidebar-foreground`, `sidebar-accent`, `sidebar-border` | sidebar-* |

| Shared / per-mode value | Variable | Theme JSON |
| --- | --- | --- |
| Shadows (per mode) | `--ds-shadow-card`, `-card-hover`, `-floating`, `-popover`, `-launcher`, `-table` | `shadows.light`, `shadows.dark` |
| Fonts | `--ds-font-sans`, `--ds-font-serif`, `--ds-font-mono`, `--ds-font-heading` | `fonts` |
| Radius | `--ds-radius` (every corner token follows it) | `radius` |
| Density | `--ds-space-scale` | `spacing` (0.5–2, default 1) |
| Letter-spacing | body `letter-spacing` | `tracking` (optional) |

`focus`, `focus-foreground` and the `sidebar*` tokens default to `discovery`, `discovery-foreground`, `surface-muted`, `text`, `accent-subtle` and `border`; `--ds-font-heading` defaults to the sans stack.

### Derived tokens

- **Aliases** (`--ds-color-table-*`, `--ds-color-mermaid-*`, `--ds-radius-*`, `--radius-*` and the shadcn bridge `--background`, `--primary`, …) are re-declared inside themed scopes, so a nested `data-theme` element (a preview card) resolves them against its own values.
- **Recomputed for non-default themes**: chart cursor/grid/neutrals, sequential and heatmap ramps (from the accent and `chart-3`, with contrast-picked inks), positive/negative (`success`/`danger`), launcher, popover, citation, caption, scrollbar and aurora colours.
- Unchanged: code-block chrome and the diverging chart ramp.

### Contrast

Every preset passes these WCAG AA pairs in both modes (`checkContrast`, `gaudi-ds theme check`): 4.5:1 for `text`/`text-muted`/`text-subtle` on the surfaces, `text` on `accent-subtle`/`accent-muted`/status `-muted`, `surface` on `text`, `accent-foreground` on `accent`/`accent-dark`, `accent` on surfaces, `focus-foreground` on `focus`, each status on the surface and its `-subtle`, each `-foreground` on its status, and the sidebar pairs; 3:1 for `focus` and `chart-1…8` on the surface. Borders are decorative and not checked. The `contrast` preset goes further, with 7:1 body text.

`checkContrast(theme)` returns `{ pass, checked, failures, results }` (each result: `mode`, `fg`, `bg`, `min`, `ratio`, `pass`). The auto-fix, `repairContrast(theme)` (also `importTheme(input, { repair: true })` and `gaudi-ds theme import --fix`), nudges failing pairs by the smallest lightness change (tints first, then foregrounds); `generateTheme` and `randomTheme` run it on their output.

## Presets

`gaudi` (default), `folio` (warm editorial serif), `graphite` (cool minimal mono, square, flat), `contrast` (7:1 text), `pastel` (soft, rounded), `midnight` (dark-first indigo), `grove` (nature), `ember` (vivid orange). JSON in `themes/presets/`, registry items in `public/r/theme-<id>.json`. Regenerate with `pnpm themes:build` (recipes in `scripts/themes/presets.mjs`; `pnpm themes:check` in CI).

## Applying a theme

**Static.** Import `@gaudi/design-system/themes.css` (every preset) and set `data-theme="<id>"` on `<html>`. Dark values apply with `.dark` on the themed element or an ancestor (or on a descendant); `.light` on a themed element opts out of an ancestor's `.dark`.

**Runtime (Next.js app router).**

```jsx
// app/layout.jsx (server component)
import { getThemeScript } from '@gaudi/design-system/themes';
import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html lang='en' suppressHydrationWarning>
      <head><script dangerouslySetInnerHTML={{ __html: getThemeScript() }} /></head>
      <body><Providers>{children}</Providers></body>
    </html>
  );
}

// app/providers.jsx
'use client';
import { ThemeProvider } from '@gaudi/design-system/themes';
export const Providers = ({ children }) => <ThemeProvider defaultMode='system'>{children}</ThemeProvider>;

// A settings picker
const { theme, themes, setTheme, mode, setMode, resolvedMode, applyCustomTheme } = useTheme();
```

`ThemeProvider` props: `themes` (default: presets), `defaultTheme` (`'gaudi'`), `defaultMode` (`'system'`), `storageKey` (`'gaudi-theme'`), `storage` (Web Storage-shaped `{ getItem, setItem, removeItem }`, default `localStorageAdapter`; `null` disables persistence), `enableMode` (`true`), `attribute` (`'data-theme'`), `darkClass` (`'dark'`), `nonce`, `onThemeChange(id)`. It injects the active non-default theme's CSS (so `themes.css` is optional) and stores it for `getThemeScript`, which applies `data-theme`, that CSS and `.dark` before first paint. Server and first client renders use the defaults; the stored choice is read after mount.

`useTheme()` returns `{ theme, themes, mode, resolvedMode, setTheme(id), setMode('light' | 'dark' | 'system'), applyCustomTheme(themeJson) }`; outside a provider it returns the defaults with no-op setters.

Apps that already manage light/dark with `next-themes` (Gaudi's `ThemeSwitch`, `Commander` and `LayoutContainer` use it) keep it and pass `enableMode={false}` to `ThemeProvider` and `getThemeScript({ enableMode: false })`.

```jsx
// app/providers.jsx: next-themes owns light/dark, Gaudi owns the theme
'use client';
import { ThemeProvider as ModeProvider } from 'next-themes';
import { ThemeProvider } from '@gaudi/design-system/themes';

export const Providers = ({ children }) => (
  <ModeProvider attribute='class' defaultTheme='system' enableSystem>
    <ThemeProvider enableMode={false}>{children}</ThemeProvider>
  </ModeProvider>
);
// app/layout.jsx: <script dangerouslySetInnerHTML={{ __html: getThemeScript({ enableMode: false }) }} />
```

Invalid saved custom themes and theme IDs that are no longer available fall back to `defaultTheme`. The provider reuses the same validation as theme imports.

`applyTheme(themeJson, { document?, nonce?, attribute?, darkClass? })` compiles and injects a theme anywhere (returns `{ css, remove }`). `compileTheme(theme, { attribute?, darkClass? })` returns the CSS string using the same selectors as the provider; `listThemes()` and `getThemePreset(id)` support pickers. A custom dark class controls theme tokens; applications must also configure their CSS dark variants to use that class.

### Fonts

Gaudi never downloads fonts. Theme font stacks name an open-source family first and fall back to system faces. `@fontsource/<family>` registers the real family name, so the stack picks it up automatically. `next/font` (`next/font/google` or `next/font/local`) generates its own family name: expose it as a CSS variable and put it first in the theme's stack, as the default theme does with `--font-space-inter`. Curated pairs: `FONT_PAIRS` in `@gaudi/design-system/themes`.

```jsx
// app/layout.jsx
import { Fraunces, Source_Sans_3 } from 'next/font/google';
const serif = Fraunces({ subsets: ['latin'], variable: '--font-fraunces' });
const sans = Source_Sans_3({ subsets: ['latin'], variable: '--font-source-sans' });
// <html lang='en' className={`${serif.variable} ${sans.variable}`} suppressHydrationWarning>
```

```css
/* app/globals.css, after the Gaudi stylesheets */
[data-theme='folio'] {
  --ds-font-sans: var(--font-source-sans), ui-sans-serif, system-ui, sans-serif;
  --ds-font-heading: var(--font-fraunces), ui-serif, Georgia, serif;
}
```

## Import and export

`importTheme(input, { id?, name?, repair? })` accepts shadcn/tweakcn/StyleGlide CSS (`:root`/`.dark`, optionally inside `@layer base`; OKLCH, HSL, bare v3 HSL triplets, hex or rgb; `var()` references are resolved), a shadcn registry item (`cssVars.theme/light/dark`) or Gaudi theme JSON, and returns `{ theme, report, warnings, format }`. Mapped values are kept verbatim; missing tokens are derived (status families from conventional hues, tints from their base, `chart-6…8` by hue rotation, `text-subtle` contrast-solved). `repair: true` nudges failing pairs (tints move first, then foregrounds, by the smallest lightness change).

| shadcn variable | Gaudi token |
| --- | --- |
| `--background` / `--foreground` | `surface` / `text` |
| `--card` (also exported as `--popover`) | `surface-raised` |
| `--muted` / `--muted-foreground` | `surface-muted` / `text-muted` |
| `--primary` / `--primary-foreground` | `accent` / `accent-foreground` |
| `--secondary` | `accent-muted` |
| `--accent` | `accent-subtle` |
| `--destructive` / `--destructive-foreground` | `danger` / `danger-foreground` |
| `--success`, `--warning`, `--info` (+ `-foreground`) | matching status tokens |
| `--border` (also exported as `--input`) | `border` |
| `--ring` | `focus` |
| `--chart-1` … `--chart-5` | `chart-1` … `chart-5` |
| `--sidebar` (or `--sidebar-background`), `--sidebar-foreground`, `--sidebar-accent`, `--sidebar-border` | `sidebar*` |
| `--radius` | `radius` |
| `--font-sans`, `--font-serif`, `--font-mono` | `fonts` (heading = sans) |
| `--shadow-sm`, `-xs`, `-md`, `-lg`, `-xl`, `-2xl` | `card`, `table`, `floating`, `card-hover`, `popover`, `launcher` |
| `--spacing` (rem ÷ 0.25) / `--tracking-normal` | `spacing` / `tracking` |

`*-foreground` variables for card, popover, secondary, accent and sidebar are written by the exporter (as `text` or `sidebar-foreground`) and ignored on import.

`exportTheme(theme, format)`: `json`, `css` (scoped Gaudi CSS), `shadcn` (`:root`/`.dark` + `@theme inline`) or `registry` (a `registry:theme` item with `cssVars`; `meta.gaudiTheme` keeps the lossless Gaudi JSON).

### CLI and MCP

```sh
gaudi-ds theme list
gaudi-ds theme import ./tweakcn.css --id ocean --out themes/ [--fix]
gaudi-ds theme export folio --format shadcn|css|registry|json [--out file]
gaudi-ds theme check ./themes/ocean.json --verbose
gaudi-ds theme generate --brand '#0e7490' --secondary '#f59e0b' --id teal --out themes/
```

MCP tools: `list_themes`, `get_theme`, `import_theme` (returns theme JSON and the contrast report), `export_theme`.

## Generating

`generateTheme({ brand, secondary?, seed?, ... })` turns one or two seed colours into a full OKLCH palette for both modes (accent kept on the brand hue and moved only in lightness until it passes; status roles keep conventional hues; neutrals tinted towards the brand), with fonts, radius and shadows. `randomTheme(seed)` produces a harmonious random theme. Both are deterministic and offline. The Storybook **Theming / Theme Studio** page puts the gallery, editor, generator, contrast report and import/export together.

## Credits

Gaudi does not reinvent theme authoring. The theme contract follows the [shadcn/ui](https://ui.shadcn.com/themes) CSS-variable convention (`--background`, `--primary`, `--chart-1`, …), so any theme made in [StyleGlide](https://www.styleglide.ai/themes), [tweakcn](https://tweakcn.com) or the [shadcn/ui theme editor](https://ui.shadcn.com/themes) can be imported as-is; we encourage designing themes there. Theme Studio is inspired by those tools. No code was copied from them; their names are used only to describe compatibility.

Source: https://design.gaudi.site/docs/theming/guide (Markdown with example code: https://design.gaudi.site/docs/theming/guide.md)

---

# Presets

> gaudi, folio, graphite, contrast, pastel, midnight, grove and ember, each passing WCAG AA in both modes.

| Preset | Character |
| --- | --- |
| `gaudi` | The default, extracted from `tokens.css`; applying it changes nothing. |
| `folio` | Warm editorial serif. |
| `graphite` | Cool minimal mono, square and flat. |
| `contrast` | 7:1 body text. |
| `pastel` | Soft and rounded. |
| `midnight` | Dark-first indigo. |
| `grove` | Nature. |
| `ember` | Vivid orange. |

Theme presets: `contrast`, `ember`, `folio`, `gaudi`, `graphite`, `grove`, `midnight`, `pastel`.

Presets are JSON in `themes/presets/` and shadcn registry items named `theme-<id>`. The CLI lists, checks and exports them:

```sh
gaudi-ds theme list
gaudi-ds theme export folio --format shadcn
```

Source: https://design.gaudi.site/docs/theming/presets (Markdown with example code: https://design.gaudi.site/docs/theming/presets.md)

---

# Theme Studio

> The Storybook page that puts the gallery, editor, generator, contrast report and import/export together.

Theme Studio lives in the design system's Storybook (**Theming / Theme Studio**). It edits every contract token, generates palettes from one or two brand colours (`generateTheme`, `randomTheme`), shows the contrast report and imports or exports themes in every format.

- [Open Theme Studio](https://storybook.gaudi.site/index.html?path=/story/theming-theme-studio--studio): Runs with the design system's Storybook (`pnpm storybook`, port 6006 locally).
- [Import and export here](https://design.gaudi.site/themes): The Themes page offers the importer and exporter without Storybook.

> **Note:** The Storybook URL is configurable with `NEXT_PUBLIC_STORYBOOK_URL` once Storybook is hosted.

Theme Studio is inspired by [StyleGlide](https://www.styleglide.ai/themes), [tweakcn](https://tweakcn.com) and the [shadcn/ui theme editor](https://ui.shadcn.com/themes).

Source: https://design.gaudi.site/docs/theming/studio (Markdown with example code: https://design.gaudi.site/docs/theming/studio.md)

---

# AI & agents

> Machine-readable docs, an agent skill, a local MCP server and a copy-in registry, all generated from the sources of truth.

Gaudi ships everything an agent needs to use it correctly, generated from the same sources as the components (owner docs, READMEs, the story catalogue, the coverage manifest, tokens, the icon registry and the package exports), so it cannot drift.

| Piece | Where | Ships in the npm package |
| --- | --- | --- |
| Metadata | `ai/components.json`, `blocks.json`, `tokens.json`, `icons.json`, `setup.json`, `exports.json` | yes |
| LLM docs | `llms.txt`, `llms-full.txt`, `docs/llm/<id>.md` | `llms*.txt` yes |
| Agent skill | `skills/gaudi-design-system/SKILL.md` | yes |
| CLI / MCP | `bin/gaudi-ds.mjs`, `cli/` | yes |
| Registry | `registry.json`, `public/r/<name>.json` | repository only until hosted |

- [llms.txt](https://design.gaudi.site/docs/ai/llms-txt): The index for language models, also served by this site.
- [Agent skill](https://design.gaudi.site/docs/ai/skill): Install the skill for Claude, Cursor, Codex, Windsurf, VS Code or OpenCode.
- [MCP server](https://design.gaudi.site/docs/ai/mcp): A local stdio server over the shipped metadata.
- [Registry](https://design.gaudi.site/docs/ai/registry): Copy-in blocks and patterns for the shadcn CLI.

This setup is inspired by [reui](https://reui.io) ([agent skills](https://reui.io/docs/agent-skills), [MCP](https://reui.io/docs/mcp), [registry](https://reui.io/docs/registry), [llms.txt](https://reui.io/llms.txt)) and builds on the [llms.txt proposal](https://llmstxt.org), the [shadcn registry spec](https://ui.shadcn.com/docs/registry) and the [Model Context Protocol](https://modelcontextprotocol.io).

Source: https://design.gaudi.site/docs/ai (Markdown with example code: https://design.gaudi.site/docs/ai.md)

---

# llms.txt

> A package summary, setup and an index of every docs page as Markdown, for language models.

`llms.txt` follows the [llms.txt convention](https://llmstxt.org): the design system's summary and setup (install, imports, CSS, preset), then every docs page in sidebar order, each linking to its Markdown version.

- [/llms.txt](https://design.gaudi.site/llms.txt): the index.
- [/llms-full.txt](https://design.gaudi.site/llms-full.txt): every page concatenated (API tables, usage, accessibility and notes; example code stays on each page's own Markdown).
- `/docs/<page>.md`: any page as Markdown, for example [/docs.md](https://design.gaudi.site/docs.md). Requests for a docs URL with `Accept: text/markdown` get the same Markdown.

Every page also has **Copy Markdown** and **Open in ChatGPT / Claude** actions. Links are absolute once `NEXT_PUBLIC_SITE_URL` is set for the docs host.

```sh
curl -s https://<docs-host>/llms.txt
curl -s -H 'Accept: text/markdown' https://<docs-host>/docs/components/button
```

Source: https://design.gaudi.site/docs/ai/llms-txt (Markdown with example code: https://design.gaudi.site/docs/ai/llms-txt.md)

---

# Agent skill

> Install the Gaudi skill into your coding agent's rules or skills folder.

```sh
npx @gaudi/design-system skills install --agent claude   # default
npx @gaudi/design-system skills install --agent all --dir ../my-app
npx @gaudi/design-system skills list
```

| Agent | Installed to |
| --- | --- |
| `claude` | `.claude/skills/gaudi-design-system/SKILL.md` and `references/` |
| `cursor` | `.cursor/rules/gaudi-design-system.mdc` (auto-attached for JS/TS/MDX) |
| `codex`, `opencode` | a managed section in `AGENTS.md` |
| `windsurf` | `.windsurf/rules/gaudi-design-system.md` |
| `vscode` | `.github/instructions/gaudi-design-system.instructions.md` |

Re-running is idempotent. Before publishing, run the same commands with `node /path/to/design-system/bin/gaudi-ds.mjs` in place of `npx @gaudi/design-system`.

Source: https://design.gaudi.site/docs/ai/skill (Markdown with example code: https://design.gaudi.site/docs/ai/skill.md)

---

# MCP server

> A local stdio Model Context Protocol server that reads the shipped metadata, with no network access.

Tools: `search`, `list_components`, `get_component`, `get_examples`, `list_blocks`, `get_block`, `get_tokens`, `get_install_command`, `validate_usage`, `get_agent_skill`, `get_project_setup`, plus theme tools `list_themes`, `get_theme`, `import_theme` and `export_theme`; prompt: `build`.

```sh
claude mcp add gaudi-ds -- npx -y @gaudi/design-system mcp
# before publishing (local checkout):
claude mcp add gaudi-ds -- node "/path/to/design-system/bin/gaudi-ds.mjs" mcp
```

Cursor (`.cursor/mcp.json`) and Windsurf:

```json
{ "mcpServers": { "gaudi-ds": { "command": "npx", "args": ["-y", "@gaudi/design-system", "mcp"] } } }
```

VS Code (`.vscode/mcp.json`):

```json
{ "servers": { "gaudi-ds": { "type": "stdio", "command": "npx", "args": ["-y", "@gaudi/design-system", "mcp"] } } }
```

The full client list (Codex, OpenCode) is in the [AI reference](https://design.gaudi.site/docs/ai/reference#mcp-server).

Source: https://design.gaudi.site/docs/ai/mcp (Markdown with example code: https://design.gaudi.site/docs/ai/mcp.md)

---

# Registry

> A shadcn-compatible registry of blocks and patterns whose components stay package imports.

The registry covers the curated examples: page-level **blocks** (`registry:block`: app shells, sidebars, screens, dashboards, forms, scheduling, stat cards, chat) and component **patterns** (`registry:example`). Each item's file is the owner fixture rewritten to public imports, exactly the source shown in every **Code** tab on this site, so it imports from `@gaudi/design-system` instead of copying components.

Add the namespace to `components.json`:

```json
{ "registries": { "@gaudi": "https://design.gaudi.site/r/{name}.json" } }
```

Then add any item by name, or by its full URL:

```sh
npx shadcn@latest add @gaudi/screens-account-settings
npx shadcn@latest add https://design.gaudi.site/r/screens-account-settings.json
```

Install the package first (`pnpm add github:ahmadassaf/design-system`). Some items reference demo assets (`/avatars/…`, `static/images/…`); supply your own. Copied compositions keep the [third-party notice](https://github.com/ahmadassaf/design-system#third-party-notices).

Source: https://design.gaudi.site/docs/ai/registry (Markdown with example code: https://design.gaudi.site/docs/ai/registry.md)

---

# AI reference

> llms.txt, the agent skill installer, the MCP server and the copy-in registry, rendered from the design system README.

> Rendered from the [README "AI & agents" section](https://github.com/ahmadassaf/design-system#ai--agents) at build time.

Gaudi ships machine-readable docs, an agent skill, a local MCP server and a copy-in block registry. All of it is generated from the sources of truth (owner `stories/docs/*.docs.js`, READMEs, the story catalogue, `coverage.json`, `public-names.json`, tokens, the icon registry and `package.json` exports) so it cannot drift from the components.

| Piece | Where | Ships in npm package |
| --- | --- | --- |
| Metadata | `ai/components.json`, `blocks.json`, `tokens.json`, `icons.json`, `setup.json`, `exports.json` | yes |
| LLM docs | `llms.txt` (index), `llms-full.txt` (every page), `docs/llm/<id>.md` (one page per component/hook) | `llms*.txt` yes; `docs/llm` repo only (package excludes `docs/`) |
| Agent skill | `skills/gaudi-design-system/SKILL.md` + generated `references/catalogue.md` | yes |
| CLI / MCP | `bin/gaudi-ds.mjs`, `cli/` | yes |
| Registry | `registry.json`, `public/r/<name>.json` | no (about 5 MB; repo only until hosted) |

This setup is inspired by [reui](https://reui.io): its [agent skills](https://reui.io/docs/agent-skills), [MCP server](https://reui.io/docs/mcp), [registry](https://reui.io/docs/registry) and [llms.txt](https://reui.io/llms.txt). It also builds on the [llms.txt proposal](https://llmstxt.org), the [shadcn registry spec](https://ui.shadcn.com/docs/registry) and the [Model Context Protocol](https://modelcontextprotocol.io) with its official [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk). See [credits](https://github.com/ahmadassaf/design-system#credits--acknowledgements).

Regenerate after changing components, docs, stories or tokens. `pnpm catalogue:sync` now also runs `pnpm ai:build`; the registry is separate:

```sh
pnpm ai:build            # ai/, docs/llm/, llms.txt, llms-full.txt, skill catalogue
pnpm ai:check            # fails when any generated file is stale
pnpm registry:build      # registry.json + public/r/*.json (--check to verify)
pnpm registry:validate   # official shadcn schemas; installs shadcn into node_modules/.cache on first use
pnpm test:ai             # search/validate unit tests, skill installer, MCP stdio smoke test
```

## llms.txt

`llms.txt` follows the llms.txt convention: package summary, install/import/CSS/preset setup, then Foundations, components by category (each linking to `docs/llm/<id>.md`), Blocks & patterns, MCP & skills, and Registry. Links are repository-relative until a docs host is chosen. `llms-full.txt` concatenates every page (API table, usage, accessibility, notes, examples and the owner README).

## Agent skill

```sh
npx @gaudi/design-system skills install --agent claude   # default
npx @gaudi/design-system skills install --agent all --dir ../my-app
npx @gaudi/design-system skills list
```

| Agent | Installed to |
| --- | --- |
| `claude` | `.claude/skills/gaudi-design-system/SKILL.md` and `references/` |
| `cursor` | `.cursor/rules/gaudi-design-system.mdc` (auto-attached for JS/TS/MDX) |
| `codex`, `opencode` | a managed section in `AGENTS.md` (between `gaudi-design-system:start/end` markers) |
| `windsurf` | `.windsurf/rules/gaudi-design-system.md` (`trigger: model_decision`) |
| `vscode` | `.github/instructions/gaudi-design-system.instructions.md` (Copilot, `applyTo` JS/TS/MDX) |

Re-running is idempotent: unchanged files are reported as such and the AGENTS.md section is replaced in place. Before publishing, run the same commands with `node /path/to/design-system/bin/gaudi-ds.mjs` in place of `npx @gaudi/design-system`.

## MCP server

A local stdio server reads the shipped `ai/` metadata (no network). Tools: `search`, `list_components`, `get_component`, `get_examples`, `list_blocks`, `get_block`, `get_tokens`, `get_install_command`, `validate_usage`, `get_agent_skill`, `get_project_setup`; prompt: `build`.

```sh
claude mcp add gaudi-ds -- npx -y @gaudi/design-system mcp
# before publishing (local checkout):
claude mcp add gaudi-ds -- node "/path/to/design-system/bin/gaudi-ds.mjs" mcp
```

Cursor (`.cursor/mcp.json`) and Windsurf (`~/.codeium/windsurf/mcp_config.json`):

```json
{ "mcpServers": { "gaudi-ds": { "command": "npx", "args": ["-y", "@gaudi/design-system", "mcp"] } } }
```

VS Code (`.vscode/mcp.json`):

```json
{ "servers": { "gaudi-ds": { "type": "stdio", "command": "npx", "args": ["-y", "@gaudi/design-system", "mcp"] } } }
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.gaudi-ds]
command = "npx"
args = ["-y", "@gaudi/design-system", "mcp"]
```

OpenCode (`opencode.json`): `{ "mcp": { "gaudi-ds": { "type": "local", "command": ["npx", "-y", "@gaudi/design-system", "mcp"] } } }`. For any client, `node /path/to/design-system/bin/gaudi-ds.mjs` runs the same server from a repository checkout in place of `npx -y @gaudi/design-system`. `get_block` returns block source when `public/r` exists (a repository checkout); otherwise it returns the install command.

## Registry (blocks & patterns)

`pnpm registry:build` emits a shadcn-compatible registry for the curated examples in `coverage.json`: page-level blocks (`registry:block`: app shells, sidebars, screens, dashboards, forms, scheduling, stat cards, chat) and component patterns (`registry:example`). Each item's file is the owner fixture rewritten by the Storybook `publicSource` helper, so it imports components from `@gaudi/design-system` (declared as a dependency) instead of copying them. `registry.json` is generated; do not edit it by hand, and do not use `shadcn build` (it would copy the fixtures' relative imports).

The registry is served from https://design.gaudi.site/r. Consumers add the namespace to their `components.json`:

```json
{ "registries": { "@gaudi": "https://design.gaudi.site/r/{name}.json" } }
```

```sh
npx shadcn@latest add @gaudi/screens-account-settings
npx shadcn@latest add https://design.gaudi.site/r/screens-account-settings.json
```

Install the package from GitHub first (`pnpm add github:ahmadassaf/design-system`), or build the registry with `GAUDI_PACKAGE_SPEC=github:ahmadassaf/design-system pnpm registry:build` so items declare that spec. Some items reference demo assets (`/avatars/…`, `static/images/…`) listed in their `docs`/`meta.assets`; supply your own. Copied compositions keep the [third-party notice](https://github.com/ahmadassaf/design-system#third-party-notices).

Source: https://design.gaudi.site/docs/ai/reference (Markdown with example code: https://design.gaudi.site/docs/ai/reference.md)

---

# Components

> Controls, inputs, overlays, data display, feedback and navigation primitives.

76 pages · 355 live examples, generated from the design system metadata.

## Layout & Containers

- [Accordion](https://design.gaudi.site/docs/components/accordion): Rich disclosure for FAQs, settings, member directories, nested help, and guided setup. Eleven patterns use Gaudi tokens, icons, avatars, cards, and pills.
- [Carousel](https://design.gaudi.site/docs/components/carousel): Carousel renders standard feature slides and editorial card rails.
- [Direction](https://design.gaudi.site/docs/components/direction): Scopes text direction for Gaudi controls that need directional keyboard and placement behavior.
- [Resizable](https://design.gaudi.site/docs/components/resizable): Resizable panes with accessible separators and bounded panel sizes.
- [ScrollArea](https://design.gaudi.site/docs/components/scroll-area): Contained scrolling with themed scrollbars and optional smooth wheel motion for article reading.
- [Sortable](https://design.gaudi.site/docs/components/sortable): Reorder lists and grids with drag handles, keyboard controls and cancellation.

## Basics

- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio): Keep media at a stable aspect ratio as its container resizes.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups. The existing Avatar API and curated patterns share the same image and fallback primitives.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Checkbox](https://design.gaudi.site/docs/components/checkbox): Checkbox renders a token-styled binary control.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Icon](https://design.gaudi.site/docs/components/icon): Static and interactive artwork from Gaudi’s centralized icon registry. AnimatedIcon adds opt-in motion with shared size and color tokens, a searchable catalogue, and host-controlled activation.
- [ImageGallery](https://design.gaudi.site/docs/components/image-gallery): A responsive masonry or grid collection with an accessible image viewer. A one-item collection is a full-width, click-to-expand image.
- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [Kbd](https://design.gaudi.site/docs/components/kbd): Kbd renders keyboard keys and multi-key shortcuts.
- [Link](https://design.gaudi.site/docs/components/link): Link centralizes navigation semantics for internal, anchor, and external links.
- [Loader](https://design.gaudi.site/docs/components/loader): An accessible loading indicator with arcs, dots, expanding rings, and an indeterminate bar. Loader replaces the former Spinner component and story.
- [Map](https://design.gaudi.site/docs/components/map): An interactive geographic map with selectable markers, route lines, and camera controls. Powered by MapLibre; applications supply their own style, geography, and prepared data.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Pointer](https://design.gaudi.site/docs/components/pointer): A pointer effect scoped to its container, with direct, spring and lazy tracking, hover feedback, and native input fallbacks.
- [Progress](https://design.gaudi.site/docs/components/progress): Determinate and indeterminate progress with a readable task label.
- [RadioGroup](https://design.gaudi.site/docs/components/radio-group): Choose one option using native radio controls or selectable cards.
- [ReadingIndicator](https://design.gaudi.site/docs/components/reading-indicator): Reading progress as a classic top bar, a vertical ruler with a moving percentage, or a movable circular meter.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [Separator](https://design.gaudi.site/docs/components/separator): Separate related content with a horizontal or vertical rule.
- [Slider](https://design.gaudi.site/docs/components/slider): Adjust one value or a range with pointer and keyboard input.
- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.
- [Tabs](https://design.gaudi.site/docs/components/tabs): Switch between related panels with keyboard-accessible tab controls.
- [Textarea](https://design.gaudi.site/docs/components/textarea): Multiline text entry that composes with the same labels and errors as Input.
- [TextHighlight](https://design.gaudi.site/docs/components/text-highlight): TextHighlight emphasizes short inline phrases inside prose.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Tooltip](https://design.gaudi.site/docs/components/tooltip): Brief contextual help attached to an independently labelled control.
- [VideoPlayer](https://design.gaudi.site/docs/components/video-player): A native video player with a complete toolbar, an elastic minimal timeline, and a poster that opens a focused viewing dialog.

## Messaging

- [Attachment](https://design.gaudi.site/docs/components/attachment): File attachments with metadata, previews, actions and upload states.

## Feedback & States

- [Banner](https://design.gaudi.site/docs/components/banner): Banner renders a compact announcement strip.
- [EmptyState](https://design.gaudi.site/docs/components/empty-state): Explain empty collections, unavailable results and the next useful action.
- [Skeleton](https://design.gaudi.site/docs/components/skeleton): Skeleton renders non-semantic loading placeholders on the theme border token, so blocks read clearly in light and dark themes. Shimmer is the text counterpart: a highlight that sweeps across a label such as Thinking… while work is in progress.

## Navigation

- [Breadcrumb](https://design.gaudi.site/docs/components/breadcrumb): Breadcrumb renders hierarchical page trails for navigation context.
- [FloatingMenu](https://design.gaudi.site/docs/components/floating-menu): A compact, inverted pill of destinations that floats over the page once the reader scrolls away from the header, with an optional Back to top button. LayoutContainer renders it for the site; pass targetRef and position sticky to use it inside a scroll container.
- [NavigationMenu](https://design.gaudi.site/docs/components/navigation-menu): NavigationMenu renders grouped site navigation with dropdown panels for categories, sections, and related destinations.
- [Pagination](https://design.gaudi.site/docs/components/pagination): Pagination renders blog-style previous/status/next navigation. Hovering or focusing the center status reveals direct page shortcuts.
- [Scrollspy](https://design.gaudi.site/docs/components/scrollspy): Track the visible section and navigate a long document using anchor links.
- [Stepper](https://design.gaudi.site/docs/components/stepper): Show progress through a sequence of labelled steps.
- [Tree](https://design.gaudi.site/docs/components/tree): Browse hierarchical content with expansion, selection, checkboxes and drag feedback.

## Advanced Inputs

- [Calendar](https://design.gaudi.site/docs/components/calendar): Date selection for single dates, ranges, bookings and localized calendars.
- [Cascader](https://design.gaudi.site/docs/components/cascader): Select items from hierarchical data using drill-down, columns, search and multiple selection.
- [ColorPicker](https://design.gaudi.site/docs/components/color-picker): An inline color canvas with hue, opacity, an eyedropper, and HEX/RGB/HSL/CSS editors.
- [FileUpload](https://design.gaudi.site/docs/components/file-upload): Choose or drop attachments with validation, upload progress and recovery actions.
- [InputOtp](https://design.gaudi.site/docs/components/input-otp): One-time code entry with grouped slots, paste support and completion feedback.
- [NumberField](https://design.gaudi.site/docs/components/number-field): Numeric entry with increment buttons, bounds, locale formatting and scrubbing.
- [PhoneInput](https://design.gaudi.site/docs/components/phone-input): International phone entry with country selection and formatted numbers.
- [Questionnaire](https://design.gaudi.site/docs/components/questionnaire): A sequence of form questions with selection, validation and progress.
- [Rating](https://design.gaudi.site/docs/components/rating): Display a rating or let people select a score using labelled stars.
- [SignaturePad](https://design.gaudi.site/docs/components/signature-pad): A composable signature input with pressure-aware SVG ink, undo and redo, native forms, saved previews, and image or JSON export.

## Data Display

- [CodeBlock](https://design.gaudi.site/docs/components/code-block): CodeBlock renders syntax-highlighted source with an optional header, copy button, line numbers, highlighted and focused lines, diffs, folding and line selection.
- [DataTable](https://design.gaudi.site/docs/components/data-table): DataTable is a TanStack table with a compact data anatomy: shared headers that preserve label casing, hairline rows, synced column and row hover, a tinted wash for selected rows, and declarative column alignment, width and pinning. It adds search with a live count, single or multi-column sorting, selection with bulk actions, expandable rows, row action menus, pinned rows, grouped bands, a totals footer, sticky headers, automatic virtualization, pagination or load-more, CSV export, and loading, refreshing, empty and error states. Sorting, selection, expansion and pinning work controlled or uncontrolled.
- [FilterBar](https://design.gaudi.site/docs/components/filter-bar): A collection toolbar: search with a live result count, a Filters popover of facets with counts, and removable Field: Value chips. The host owns matching and persistence.
- [Item](https://design.gaudi.site/docs/components/item): Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.
- [SchemaDisplay](https://design.gaudi.site/docs/components/schema-display): Read an API endpoint or a JSON Schema: method badge, path with highlighted parameters, and request and response schemas as an expandable property tree.
- [Terminal](https://design.gaudi.site/docs/components/terminal): Terminal renders mac-style shell examples with typed commands and structured output lines.
- [Timeline](https://design.gaudi.site/docs/components/timeline): Display dated activity and milestones with readable descriptions and optional actions.

## Overlays & Menus

- [Commander](https://design.gaudi.site/docs/components/commander): Commander provides the site command palette with host-supplied destinations for navigation, content search, and theme actions.
- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [Popover](https://design.gaudi.site/docs/components/popover): Popover renders compact positioned supporting content next to its trigger.
- [Sheet](https://design.gaudi.site/docs/components/sheet): A panel that slides in from an edge over a dimmed page, for side tasks such as settings, details, comments, notifications or an assistant, without leaving the current screen.
- [Toast](https://design.gaudi.site/docs/components/toast): Transient feedback for completed actions, errors and recoverable background work.

## Media & Previews

- [Embed](https://design.gaudi.site/docs/components/embed): The shared preview vocabulary for messages and content: one switch that hands each piece of content to its owner. Links go to LinkPreview, code to CodeBlock, generated pages to WebPreview; images and videos default to a LinkPreview card until you pass a renderer.
- [LinkPreview](https://design.gaudi.site/docs/components/link-preview): A link enriched with what the destination is. One normaliser, normalizeLinkPreview, turns the app's preview payload into a kind (repository, video, article, social post, docs, Wikipedia, package, image, file, internal post or website) and the rich fields that kind earns; three variants present it.
- [WebPreview](https://design.gaudi.site/docs/components/web-preview): A framed browser for a live or generated page: back, forward and reload, an editable address bar, open in a new tab, device widths, a sandboxed iframe with a loading state, an optional console, and a link preview card when a site refuses framing.

## Planning

- [EventCalendar](https://design.gaudi.site/docs/components/event-calendar): Schedule events across day, week, month, agenda and resource views.
- [Flow](https://design.gaudi.site/docs/components/flow): A node-and-edge canvas for workflows, pipelines, agent trees and driver maps, themed with Gaudi tokens and built on React Flow.
- [Gantt](https://design.gaudi.site/docs/components/gantt): A timeline board for scheduled work, dependencies and resource planning.
- [Kanban](https://design.gaudi.site/docs/components/kanban): Move work items between columns while retaining an accessible move action.

Source: https://design.gaudi.site/docs/components (Markdown with example code: https://design.gaudi.site/docs/components.md)

---

# AspectRatio

> Keep media at a stable aspect ratio as its container resizes.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/AspectRatio` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/AspectRatio/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-aspectratio--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { AspectRatio } from '@gaudi/design-system/core/AspectRatio';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/aspect-ratio-common-ratios.json`.

## Usage

```jsx
import { AspectRatio } from '@gaudi/design-system/core/AspectRatio';

<AspectRatio ratio={16 / 9}>
  <img src={cover.src} alt={cover.alt} className='h-full w-full object-cover' />
</AspectRatio>
```

## Examples

### Common ratios

Registry: `npx shadcn@latest add https://design.gaudi.site/r/aspect-ratio-common-ratios.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ratio` | `number` | `1` | no | Width divided by height; use 16 / 9 for landscape media. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Supply alternative text for images and accessible names for embedded media.

## Related

- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Checkbox](https://design.gaudi.site/docs/components/checkbox): Checkbox renders a token-styled binary control.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.

Source: https://design.gaudi.site/docs/components/aspect-ratio (Markdown with example code: https://design.gaudi.site/docs/components/aspect-ratio.md)

---

# Avatar

> Profile images, resilient initials, presence, verification, account menus and collaborator groups.

The existing Avatar API and curated patterns share the same image and fallback primitives.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Avatar` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Avatar/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-avatar--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Avatar } from '@gaudi/design-system/core/Avatar';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/avatar-account-menu.json`.

## Usage

```jsx
import { Avatar } from '@gaudi/design-system';

<Avatar name='Mei Castellanos' src='/avatars/person-20.svg' shape='circle' indicator={{ label: 'Online', tone: 'success' }} />
```

## Examples

### Account dropdown menu

Registry: `npx shadcn@latest add https://design.gaudi.site/r/avatar-account-menu.json`

### Rings and activity

Registry: `npx shadcn@latest add https://design.gaudi.site/r/avatar-activity-rings.json`

### Empty state

Registry: `npx shadcn@latest add https://design.gaudi.site/r/avatar-empty-state.json`

### Groups

Registry: `npx shadcn@latest add https://design.gaudi.site/r/avatar-groups.json`

### Hover groups with tooltips

Registry: `npx shadcn@latest add https://design.gaudi.site/r/avatar-hover-groups.json`

### Inside buttons

Registry: `npx shadcn@latest add https://design.gaudi.site/r/avatar-in-buttons.json`

### Sizes, shapes and fallbacks

Registry: `npx shadcn@latest add https://design.gaudi.site/r/avatar-sizes-fallbacks.json`

### Social proof

Registry: `npx shadcn@latest add https://design.gaudi.site/r/avatar-social-proof.json`

### Status and icon badges

Registry: `npx shadcn@latest add https://design.gaudi.site/r/avatar-status-badges.json`

### User details and badge

Registry: `npx shadcn@latest add https://design.gaudi.site/r/avatar-user-details.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `src` | `string` | — | no | Remote, local or data image source; failed and pending images show the fallback. |
| `name / label` | `string` | — | no | Name generates Unicode initials; label preserves explicit legacy initials. |
| `alt` | `string` | — | no | Accessible identity override; an empty string is decorative. |
| `fallback` | `ReactNode \| boolean` | `initials` | no | Custom artwork or text; true shows the guest silhouette. |
| `size` | `2xs \| xs \| sm \| md \| lg \| xl` | `md` | no | Six sizes; existing xs through lg dimensions are preserved. |
| `shape` | `circle \| square \| tile` | `square` | no | Identity crop and background treatment. |
| `surface` | `solid \| tinted \| plain \| bare` | `solid` | no | Identity crop and background treatment. |
| `indicator` | `{ label, tone?, icon?, position? }` | — | no | Host-provided presence or verification; positions follow reading direction. |
| `imageProps` | `object` | — | no | Image attributes and per-layer appearance. |
| `imageClassName` | `string` | — | no | Image attributes and per-layer appearance. |
| `fallbackClassName` | `string` | — | no | Image attributes and per-layer appearance. |
| `tone` | `gray \| neutral \| blue \| teal \| green \| amber \| yellow \| red \| rose \| indigo` | `gray` | no | Fallback colour family. |
| `grayscale` | `boolean` | `false` | no | Desaturates the image. |
| `onLoadingStatusChange` | `(status) => void` | — | no | Receives loading, loaded or error; source changes recover automatically. |
| `AvatarGroup` (sub-component) | `avatars, max, size, shape, label, renderAvatar, renderOverflow` | — | no | Accepts data-driven identities or existing compound children. |

### Variants

- `size`: `2xs`, `xs`, `sm`, `md`, `lg`, `xl`
- `shape`: `circle`, `square`, `tile`
- `surface`: `solid`, `tinted`, `plain`, `bare`
- `tone`: `gray`, `neutral`, `blue`, `teal`, `green`, `amber`, `yellow`, `red`, `rose`, `indigo`

## Accessibility

A named Avatar exposes one image label, including host-provided presence. Use alt="" beside visible identity text. Wrap interactive avatars in Button, Tooltip or DropdownMenu; status badges never infer presence from image loading.

## Related

- [Profile](https://design.gaudi.site/docs/blocks/profile): Account and organisation pages for an application: profile details, organisation members and permissions, billing and usage, referrals, and connected mailboxes.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [Tooltip](https://design.gaudi.site/docs/components/tooltip): Brief contextual help attached to an independently labelled control.
- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [Image](https://design.gaudi.site/docs/mdx/image): Image renders editorial MDX images with caption, dark-mode source, fallback source, and click-to-open modal behavior.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.

Source: https://design.gaudi.site/docs/components/avatar (Markdown with example code: https://design.gaudi.site/docs/components/avatar.md)

---

# Button

> Button renders the Gaudi action and link-button variants.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Button` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Button/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-button--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Button from '@gaudi/design-system/core/Button';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/button-async-success.json`.

## Usage

```jsx
import { Button } from '@gaudi/design-system';

<Button variant='solid' tone='accent' size='md'>Read article</Button>
```

## Examples

### Async loading and success

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-async-success.json`

### Avatar and two-line content

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-avatar-two-line.json`

### Copy with feedback

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-copy-feedback.json`

### Counts, badges and shortcuts

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-counts-shortcuts.json`

### Icons, loading and links

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-icons-loading.json`

### Social sign-in

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-social-sign-in.json`

### Toggling icon and label

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-toggling-label.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | — | no | Visible button label or content. |
| `variant` | `solid \| soft \| outline \| ghost \| subtle` | `solid` | no | Reusable visual treatment. |
| `size` | `xs \| sm \| md \| lg \| icon \| icon-xs \| icon-sm \| icon-lg` | `md` | no | Compact heights: xs 24px, sm 28px, md/default 32px, lg 36px. Icon sizes match their text-button counterparts. Use matching sizes for controls in the same row. |
| `tone` | `accent \| neutral \| success \| warning \| danger \| attention \| discovery \| info` | `accent (solid, subtle); neutral (soft, outline, ghost)` | no | Semantic meaning for the action. Quiet variants default to neutral so screens do not turn blue. Legacy hue names remain supported as compatibility aliases. |
| `radius` | `sm \| md \| lg \| full` | `md` | no | Legacy aliases use the global --ds-radius setting (4px by default); none stays square where supported. |
| `href` | `string` | — | no | Renders an internal Next link or safe external anchor. |
| `disabled` | `boolean` | `false` | no | Disables native buttons and removes disabled links from the tab order. |
| `className` | `string` | — | no | Root class override. |

### Variants

- `variant`: `solid`, `soft`, `outline`, `ghost`, `subtle`
- `size`: `xs`, `sm`, `md`, `lg`, `icon`, `icon-xs`, `icon-sm`, `icon-lg`
- `tone`: `accent`, `neutral`, `success`, `warning`, `danger`, `attention`, `discovery`, `info`
- `radius`: `sm`, `md`, `lg`, `full`

## Accessibility

Button renders native buttons for actions and links for navigation. Disabled link variants are removed from tab order.

## Related

- [Link](https://design.gaudi.site/docs/components/link): Link centralizes navigation semantics for internal, anchor, and external links.
- [Icon](https://design.gaudi.site/docs/components/icon): Static and interactive artwork from Gaudi’s centralized icon registry.
- [Tooltip](https://design.gaudi.site/docs/components/tooltip): Brief contextual help attached to an independently labelled control.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Loader](https://design.gaudi.site/docs/components/loader): An accessible loading indicator with arcs, dots, expanding rings, and an indeterminate bar.
- [Kbd](https://design.gaudi.site/docs/components/kbd): Kbd renders keyboard keys and multi-key shortcuts.

Source: https://design.gaudi.site/docs/components/button (Markdown with example code: https://design.gaudi.site/docs/components/button.md)

---

# ButtonGroup

> Group related actions with joined borders and consistent sizing.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/ButtonGroup` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/ButtonGroup/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-buttongroup--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ButtonGroup } from '@gaudi/design-system/core/ButtonGroup';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/button-group-collection-toolbar.json`.

## Usage

```jsx
import Button from '@gaudi/design-system/core/Button';
import { ButtonGroup } from '@gaudi/design-system/core/ButtonGroup';

<ButtonGroup aria-label='Document actions'>
  <Button onClick={save}>Save</Button>
  <Button variant='outline' onClick={exportDocument}>Export</Button>
</ButtonGroup>
```

## Examples

### Collection toolbar

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-group-collection-toolbar.json`

### Counts and labels

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-group-counts-labels.json`

### Editor header

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-group-editor-header.json`

### Inputs and selects

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-group-inputs-selects.json`

### Segmented choices

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-group-segmented.json`

### Split buttons

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-group-split-buttons.json`

### Steppers and pagination

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-group-steppers-pagination.json`

### Toolbars

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-group-toolbars.json`

### Vertical groups

Registry: `npx shadcn@latest add https://design.gaudi.site/r/button-group-vertical.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `orientation` | `horizontal \| vertical` | `horizontal` | no | Arrangement and accessible orientation of the group. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |
| `ButtonGroupSeparator.orientation` | `horizontal \| vertical` | `vertical` | no | Direction of a divider between actions. |

### Variants

- `orientation`: `horizontal`, `vertical`

## Accessibility

Buttons retain independent names and focus targets. Use ToggleGroup when the actions represent a selection.

## Related

- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Direction](https://design.gaudi.site/docs/components/direction): Scopes text direction for Gaudi controls that need directional keyboard and placement behavior.
- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [Tooltip](https://design.gaudi.site/docs/components/tooltip): Brief contextual help attached to an independently labelled control.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.

Source: https://design.gaudi.site/docs/components/button-group (Markdown with example code: https://design.gaudi.site/docs/components/button-group.md)

---

# Card

> Card frames reusable content with title, subtitle, and optional children.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Card` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Card/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-card--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Card from '@gaudi/design-system/core/Card';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/card-billing-usage.json`.

## Usage

```jsx
import { Card } from '@gaudi/design-system';

<Card title='Building with tokens' subtitle='Cards frame reusable content.' />
```

## Examples

### Usage meters that expand

Registry: `npx shadcn@latest add https://design.gaudi.site/r/card-billing-usage.json`

### Deployment status

Registry: `npx shadcn@latest add https://design.gaudi.site/r/card-deployment-status.json`

### Header badge and actions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/card-header-actions.json`

### Link cards

Registry: `npx shadcn@latest add https://design.gaudi.site/r/card-link-cards.json`

### Login form

Registry: `npx shadcn@latest add https://design.gaudi.site/r/card-login-form.json`

### Media cards

Registry: `npx shadcn@latest add https://design.gaudi.site/r/card-media.json`

### Sections and dividers

Registry: `npx shadcn@latest add https://design.gaudi.site/r/card-sections.json`

### Stat with trend and menu

Registry: `npx shadcn@latest add https://design.gaudi.site/r/card-stat-trend.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `title` | `ReactNode` | — | no | Optional card heading. |
| `titleLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | no | Semantic level for the optional card heading. |
| `subtitle` | `ReactNode` | — | no | Supporting description under the title. |
| `children` | `ReactNode` | — | no | Body content, actions, or nested composition. |
| `variant` | `elevated \| outline \| soft \| flat` | `elevated` | no | Container surface treatment. |
| `padding` | `none \| sm \| md \| lg` | `md` | no | Internal spacing. |
| `radius` | `none \| sm \| md \| lg` | `md` | no | Legacy aliases use the global --ds-radius setting (4px by default); none stays square where supported. |
| `interactive` | `boolean` | `false` | no | Adds hover elevation for cards containing a real link or button. |
| `className` | `string` | — | no | Root class override. |
| `classNames` | `{ root, body, title, subtitle }` | — | no | Slot-level class overrides. |

### Variants

- `titleLevel`: `2`, `3`, `4`, `5`, `6`
- `variant`: `elevated`, `outline`, `soft`, `flat`
- `padding`: `none`, `sm`, `md`, `lg`
- `radius`: `none`, `sm`, `md`, `lg`

## Accessibility

Card is a structural container. Put links or buttons inside it rather than making the whole card a fake control.

## Related

- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [Accordion](https://design.gaudi.site/docs/components/accordion): Rich disclosure for FAQs, settings, member directories, nested help, and guided setup.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.

Source: https://design.gaudi.site/docs/components/card (Markdown with example code: https://design.gaudi.site/docs/components/card.md)

---

# Checkbox

> Checkbox renders a token-styled binary control.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Checkbox` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Checkbox/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-checkbox--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Checkbox from '@gaudi/design-system/core/Checkbox';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/checkbox-corner-cards.json`.

## Usage

```jsx
import { Checkbox } from '@gaudi/design-system';

<Checkbox label='Include drafts' defaultChecked />
```

## Examples

### Corner-check cards

Registry: `npx shadcn@latest add https://design.gaudi.site/r/checkbox-corner-cards.json`

### Groups

Registry: `npx shadcn@latest add https://design.gaudi.site/r/checkbox-groups.json`

### Label extras and styles

Registry: `npx shadcn@latest add https://design.gaudi.site/r/checkbox-label-extras.json`

### Nested group

Registry: `npx shadcn@latest add https://design.gaudi.site/r/checkbox-nested-group.json`

### Row cards

Registry: `npx shadcn@latest add https://design.gaudi.site/r/checkbox-row-cards.json`

### States

Registry: `npx shadcn@latest add https://design.gaudi.site/r/checkbox-states.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | `generated id` | no | Connects the button control to its visible label. |
| `label` | `ReactNode` | — | no | Visible label text. |
| `checked` | `boolean` | — | no | Controlled checked state. |
| `defaultChecked` | `boolean` | `false` | no | Initial checked state for uncontrolled usage. |
| `disabled` | `boolean` | `false` | no | Prevents changes and lowers visual emphasis. |
| `onCheckedChange` | `(checked) => void` | — | no | Called with the next checked state. |
| `className` | `string` | — | no | Root class override. |

## Accessibility

Checkbox exposes role checkbox, aria-checked, disabled state, and a visible label when provided.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Tooltip](https://design.gaudi.site/docs/components/tooltip): Brief contextual help attached to an independently labelled control.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Separator](https://design.gaudi.site/docs/components/separator): Separate related content with a horizontal or vertical rule.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.

Source: https://design.gaudi.site/docs/components/checkbox (Markdown with example code: https://design.gaudi.site/docs/components/checkbox.md)

---

# Field

> Field composes form label, description, error, and input building blocks.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Field` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Field/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-field--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Field } from '@gaudi/design-system/core/Field';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/field-controls.json`.

## Usage

```jsx
import { Field, FieldDescription, EmailInput, FieldLabel } from '@gaudi/design-system';

<Field>
  <FieldLabel htmlFor='email'>Email</FieldLabel>
  <EmailInput id='email' />
  <FieldDescription>Used for article updates only.</FieldDescription>
</Field>
```

## Examples

### Controls in fields

Registry: `npx shadcn@latest add https://design.gaudi.site/r/field-controls.json`

### Validation errors

Registry: `npx shadcn@latest add https://design.gaudi.site/r/field-errors.json`

### Fieldsets of choices

Registry: `npx shadcn@latest add https://design.gaudi.site/r/field-fieldsets.json`

### Fields that reflow by width

Registry: `npx shadcn@latest add https://design.gaudi.site/r/field-responsive.json`

### Preferences form that checks itself

Registry: `npx shadcn@latest add https://design.gaudi.site/r/field-settings-validation.json`

### Label accessories

Registry: `npx shadcn@latest add https://design.gaudi.site/r/label-accessories.json`

### Inline edit

Registry: `npx shadcn@latest add https://design.gaudi.site/r/label-inline-edit.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `caretMode` | `native \| smooth` | `provider / smooth` | no | FieldInput overrides the nearest InputConfigProvider. Native editing stays intact. |
| `children` | `ReactNode` | — | no | Composes label, input, description, and error slots or supplies slot text. |
| `htmlFor` | `string` | — | no | Connects the visible label to the input id. |
| `id` | `string` | — | no | Input id paired with FieldLabel htmlFor. |
| `type` | `string` | `text` | no | Native input type. |
| `name` | `string` | — | no | Native input name for form submission. |
| `value` | `string` | — | no | Controlled input value. |
| `defaultValue` | `string` | — | no | Initial uncontrolled input value. |
| `placeholder` | `string` | — | no | Native input placeholder. |
| `required` | `boolean` | `false` | no | Marks the input as required. |
| `invalid` | `boolean` | `true when a FieldError is rendered` | no | Forces aria-invalid and the error border on FieldInput. |
| `disabled` | `boolean` | `false` | no | Disables the input. |
| `onChange` | `(event) => void` | — | no | Native input change handler. |
| `className` | `string` | — | no | Class override on each Field slot. |

### Variants

- `caretMode`: `native`, `smooth`

## Accessibility

Field keeps label, input, description, and error markup colocated so form controls can be wired with id/htmlFor.

## Related

- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [InputOtp](https://design.gaudi.site/docs/components/input-otp): One-time code entry with grouped slots, paste support and completion feedback.
- [Tooltip](https://design.gaudi.site/docs/components/tooltip): Brief contextual help attached to an independently labelled control.
- [Checkbox](https://design.gaudi.site/docs/components/checkbox): Checkbox renders a token-styled binary control.
- [RadioGroup](https://design.gaudi.site/docs/components/radio-group): Choose one option using native radio controls or selectable cards.

Source: https://design.gaudi.site/docs/components/field (Markdown with example code: https://design.gaudi.site/docs/components/field.md)

---

# Icon

> Static and interactive artwork from Gaudi’s centralized icon registry.

AnimatedIcon adds opt-in motion with shared size and color tokens, a searchable catalogue, and host-controlled activation.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Icon` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Icon/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-icon--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Icon from '@gaudi/design-system/core/Icon';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/icon-stack-in-context.json`.

## Usage

```jsx
import { Icon } from '@gaudi/design-system';

<Icon name='Info' label='More information' color='primary' size='lg' />
```

## Examples

### In an empty state and list row

Registry: `npx shadcn@latest add https://design.gaudi.site/r/icon-stack-in-context.json`

### Sizes, colors and badge

Registry: `npx shadcn@latest add https://design.gaudi.site/r/icon-stack-sizes-badge.json`

### In a card, list row and empty state

Registry: `npx shadcn@latest add https://design.gaudi.site/r/icon-tile-in-context.json`

### Tones

Registry: `npx shadcn@latest add https://design.gaudi.site/r/icon-tile-tones.json`

### Variants, sizes and shapes

Registry: `npx shadcn@latest add https://design.gaudi.site/r/icon-tile-variants.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | `registry icon name` | — | no | Renders an icon from the Gaudi registry. |
| `kind` | `github \| linkedin \| twitter \| youtube \| mail \| ...` | — | no | Compatibility alias for social/link icon use. |
| `href` | `string` | — | no | Renders the icon as a safe link when provided. |
| `label` | `string` | — | no | Accessible label for informative icons and icon links. |
| `decorative` | `boolean` | `false` | no | Hides the SVG from assistive technology when the icon is visual only. |
| `size` | `xs \| sm \| md \| lg \| xl \| 2xl \| number` | `md` | no | Controls icon dimensions. |
| `color` | `neutral \| muted \| primary \| info \| success \| warning \| danger \| attention \| blue \| teal \| green \| amber \| yellow \| red \| rose \| dim` | `currentColor` | no | Token color shortcut. |
| `strokeWidth` | `number` | `icon default` | no | Adjusts line icon stroke width. Filled brand icons such as Github ignore it. |
| `active` | `boolean (AnimatedIcon)` | `false` | no | Starts motion when the host is active and visible. Reduced motion and hidden documents keep the resting artwork. |
| `className` | `string` | — | no | Root class override. |

### Variants

- `kind`: `github`, `linkedin`, `twitter`, `youtube`, `mail`, `...`
- `color`: `neutral`, `muted`, `primary`, `info`, `success`, `warning`, `danger`, `attention`, `blue`, `teal`, `green`, `amber`, `yellow`, `red`, `rose`, `dim`

## Accessibility

Decorative icons are hidden from assistive technology. Informative or icon-only links need a readable label.

## Related

- [EmptyState](https://design.gaudi.site/docs/components/empty-state): Explain empty collections, unavailable results and the next useful action.
- [Item](https://design.gaudi.site/docs/components/item): Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.

Source: https://design.gaudi.site/docs/components/icon (Markdown with example code: https://design.gaudi.site/docs/components/icon.md)

---

# ImageGallery

> A responsive masonry or grid collection with an accessible image viewer.

A one-item collection is a full-width, click-to-expand image.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/ImageGallery` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/ImageGallery/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-imagegallery--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ImageGallery } from '@gaudi/design-system/core/ImageGallery';
```

## Usage

```jsx
import { ImageGallery } from '@gaudi/design-system/core/ImageGallery';

<ImageGallery images={[{ id: 'lavender', src: '/static/images/art/0.svg', alt: 'Lavender gradient artwork', caption: 'A study in lavender and light', width: 1200, height: 675 }]} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-imagegallery--playground)
- [Single expandable image](https://storybook.gaudi.site/index.html?path=/story/core-imagegallery--single)
- [Controlled grid](https://storybook.gaudi.site/index.html?path=/story/core-imagegallery--controlled)
- [Empty & unavailable images](https://storybook.gaudi.site/index.html?path=/story/core-imagegallery--recovery)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `images` | `Array<{ id, src, alt, caption?, thumbnailSrc?, width?, height? }>` | `[]` | no | Prepared images with unique, stable string IDs. src is the full image; thumbnailSrc optionally supplies a smaller preview. width and height reserve the thumbnail aspect ratio; a different ratio crops the preview. The viewer always contains the full image. |
| `label` | `string` | `Image gallery` | no | Accessible name of the gallery region. |
| `layout` | `masonry \| grid` | `masonry` | no | Masonry keeps each thumbnail ratio and reads down each column. Grid reads across rows and crops thumbnails to 4:3. |
| `columns` | `{ mobile?, tablet?, desktop? }` | `{ mobile: 1, tablet: 2, desktop: 3 }` | no | Positive integer column counts at gallery widths below 640px, from 640px, and from 1024px. A single image always occupies one full-width column. |
| `showCaptions` | `boolean` | `true` | no | Shows captions below thumbnails. The viewer always shows the active caption or alternative text. |
| `selectedId` | `string \| null` | `uncontrolled` | no | Controls or initializes the viewer selection. null closes it; selecting a thumbnail, navigating, swiping, and closing request a change. Controlled hosts remain authoritative. An ID absent from images closes the viewer. |
| `defaultSelectedId` | `string \| null` | `null` | no | Controls or initializes the viewer selection. null closes it; selecting a thumbnail, navigating, swiping, and closing request a change. Controlled hosts remain authoritative. An ID absent from images closes the viewer. |
| `onSelectedIdChange` | `(id) => void` | — | no | Controls or initializes the viewer selection. null closes it; selecting a thumbnail, navigating, swiping, and closing request a change. Controlled hosts remain authoritative. An ID absent from images closes the viewer. |
| `disabled` | `boolean` | `false` | no | Disables thumbnail activation and hides the viewer while true, retaining the selection. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `layout`: `masonry`, `grid`

## Accessibility

Thumbnails are named buttons. Enter or Space opens the viewer. Arrow keys move between images (respecting direction), Home and End select the first and last images, and Escape closes. Touch supports swiping and browser pinch zoom. Dialog contains focus and restores the opener, or the gallery region if that opener was removed or disabled. Reduced motion removes animated slide movement.

## Notes

- Provide useful alt text; captions add visible context. Offscreen slides are hidden from assistive technology. Navigation stops at either end and disappears for a single image.
- Images load lazily, with the selected full image loaded eagerly. Failed sources show an accessible placeholder; replace thumbnailSrc (or src when no thumbnail is supplied) to recover a preview, and src to recover the full image. Empty collections show an explicit empty state.
- Use one image in images for an expandable article figure. No separate single-image wrapper is needed. Existing MDX/Image and MDX/ImageModal share the same viewer while preserving their APIs.
- The Shadix UI gallery informed the masonry and expansion behavior. The implementation uses Gaudi Dialog, Carousel, Button and Icon; it does not load remote demo resources.

## Related

- [Navigation](https://design.gaudi.site/docs/blocks/navigation): The site header block: brand, primary NavigationMenu with a two-block Blog panel (categories beside recent posts) or a Categories panel on the supplied blog route, search, theme switch, and a phone sheet below lg.
- [Image](https://design.gaudi.site/docs/mdx/image): Image renders editorial MDX images with caption, dark-mode source, fallback source, and click-to-open modal behavior.
- [ImageModal](https://design.gaudi.site/docs/mdx/image-modal): A focused view of an article image with a caption and dismiss action.
- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Carousel](https://design.gaudi.site/docs/components/carousel): Carousel renders standard feature slides and editorial card rails.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.

Source: https://design.gaudi.site/docs/components/image-gallery (Markdown with example code: https://design.gaudi.site/docs/components/image-gallery.md)

---

# Input

> Text, search, numeric and date inputs with prefix and suffix slots.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Input` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Input/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-input--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Input from '@gaudi/design-system/core/Input';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/input-group-addons.json`.

## Usage

```jsx
import Input, { EmailInput } from '@gaudi/design-system/core/Input';

<>
  <Input aria-label='Project name' value={name} onChange={event => setName(event.target.value)} />
  <EmailInput aria-label='Email address' name='email' required />
</>
```

## Examples

### Addon placement

Registry: `npx shadcn@latest add https://design.gaudi.site/r/input-group-addons.json`

### AI prompt inputs

Registry: `npx shadcn@latest add https://design.gaudi.site/r/input-group-ai-prompts.json`

### Multi-field composer

Registry: `npx shadcn@latest add https://design.gaudi.site/r/input-group-composer.json`

### Dropdown selectors

Registry: `npx shadcn@latest add https://design.gaudi.site/r/input-group-dropdowns.json`

### Hints and states

Registry: `npx shadcn@latest add https://design.gaudi.site/r/input-group-hints-states.json`

### Inline actions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/input-group-inline-actions.json`

### Search with filters

Registry: `npx shadcn@latest add https://design.gaudi.site/r/input-group-search-filters.json`

### Labels and messages

Registry: `npx shadcn@latest add https://design.gaudi.site/r/input-labels-messages.json`

### Password with strength meter

Registry: `npx shadcn@latest add https://design.gaudi.site/r/input-password-strength.json`

### Style variants

Registry: `npx shadcn@latest add https://design.gaudi.site/r/input-style-variants.json`

### Input types

Registry: `npx shadcn@latest add https://design.gaudi.site/r/input-types.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `caretMode` | `native \| smooth` | `provider / smooth` | no | Overrides InputConfigProvider for this field. Smooth mode animates the collapsed caret while supported native text controls retain their editing behavior. |
| `type` | `text \| email \| search \| url \| tel \| password \| number \| date` | `text` | no | Native input type. Use EmailInput for addresses and NumberField for numeric values to retain the default smooth caret. |
| `prefix / suffix` | `ReactNode` | — | no | Content before or after the native control. |
| `placeholder` | `string` | — | no | Example value; never a replacement for a label. |
| `required / disabled` | `boolean` | `false` | no | Native form constraint and availability. |
| `invalid` | `boolean` | — | no | Marks the underlying FieldInput as invalid. |
| `inputClassName` | `string` | — | no | Classes on the input itself. |
| `className` | `string` | — | no | Additional classes on the outer element. |
| `Native input props / ref` (pass-through) | `InputHTMLAttributes<HTMLInputElement>` | — | no | Forwards value, defaultValue, onChange, disabled, required, name, autocomplete and ARIA attributes to the input. |

### Variants

- `caretMode`: `native`, `smooth`

## Accessibility

Compose Field, FieldLabel, FieldDescription and FieldError. Keep labels visible and connect errors to their control.

## Notes

- EmailInput is a named export from the Input entry. It composes Input with a text editor, an email keyboard hint, email autocomplete and single-address pattern validation, so it supports smooth caret mode.
- EmailInput fixes type=text and inputMode=email; multiple addresses are unsupported. An additional pattern narrows the allowed addresses. Invalid author patterns are ignored while email validation remains active.
- EmailInput keeps raw text (spaces are invalid), reports patternMismatch instead of typeMismatch, and leaves custom error copy to FieldError/onInvalid. required, minLength/maxLength, name, form, value/defaultValue, refs and event handlers reach the native editor.
- Smooth caret is enabled by default. Use EmailInput for addresses and NumberField for numeric values throughout forms and examples; reserve native email/number types for documented semantic exceptions. Provider and per-field caretMode=native overrides remain available.

## Related

- [NumberField](https://design.gaudi.site/docs/components/number-field): Numeric entry with increment buttons, bounds, locale formatting and scrubbing.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [Popover](https://design.gaudi.site/docs/components/popover): Popover renders compact positioned supporting content next to its trigger.
- [Tooltip](https://design.gaudi.site/docs/components/tooltip): Brief contextual help attached to an independently labelled control.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.

Source: https://design.gaudi.site/docs/components/input (Markdown with example code: https://design.gaudi.site/docs/components/input.md)

---

# Kbd

> Kbd renders keyboard keys and multi-key shortcuts.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Kbd` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Kbd/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-kbd--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Kbd from '@gaudi/design-system/core/Kbd';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/kbd-in-controls.json`.

## Usage

```jsx
import { Kbd } from '@gaudi/design-system';

<Kbd keys='command,shift,k' size='sm' variant='raised' />
```

## Examples

### Shortcuts in controls

Registry: `npx shadcn@latest add https://design.gaudi.site/r/kbd-in-controls.json`

### Keys, groups and icons

Registry: `npx shadcn@latest add https://design.gaudi.site/r/kbd-keys-groups.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | — | no | Single visible key when keys is not provided. |
| `keys` | `string \| string[]` | — | no | Shortcut list such as "command,shift,k". |
| `size` | `xs \| sm \| md \| lg` | `md` | no | Controls key dimensions and text size. |
| `variant` | `raised \| outline \| flat` | `raised` | no | Visual keycap treatment. |
| `className` | `string` | — | no | Root class override. |

### Variants

- `size`: `xs`, `sm`, `md`, `lg`
- `variant`: `raised`, `outline`, `flat`

## Accessibility

Keyboard shortcuts expose readable aria-label text such as Command plus K while keeping visual symbols compact.

## Related

- [Tooltip](https://design.gaudi.site/docs/components/tooltip): Brief contextual help attached to an independently labelled control.
- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio): Keep media at a stable aspect ratio as its container resizes.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.

Source: https://design.gaudi.site/docs/components/kbd (Markdown with example code: https://design.gaudi.site/docs/components/kbd.md)

---

# Link

> Link centralizes navigation semantics for internal, anchor, and external links.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Link` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Link/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-link--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Link from '@gaudi/design-system/core/Link';
```

## Usage

```jsx
import { Link } from '@gaudi/design-system';

<Link href='/blog' variant='inline' tone='blue'>Read the blog</Link>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-link--playground)
- [Link Types](https://storybook.gaudi.site/index.html?path=/story/core-link--link-types)
- [Variants and tones](https://storybook.gaudi.site/index.html?path=/story/core-link--variants)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | — | no | Visible link label. |
| `href` | `internal \| anchor \| external URL` | — | no | Internal routes use Next Link; anchors and external URLs use native anchors. |
| `prefetch` | `boolean` | `true` | no | Next.js prefetch behavior for internal links. |
| `variant` | `inline \| muted \| nav \| bare` | `inline` | no | Text link style: inline takes tone, muted is secondary gray, nav is strong gray turning blue on hover, bare inherits the parent color. |
| `tone` | `accent \| attention \| danger \| discovery \| info \| neutral \| success \| warning` | `neutral` | no | Color family of the inline variant. Default is black/gray and turns blue on hover. muted, nav, and bare have fixed colors and ignore tone. |
| `className` | `string` | — | no | Root class override. |

### Variants

- `variant`: `inline`, `muted`, `nav`, `bare`
- `tone`: `accent`, `attention`, `danger`, `discovery`, `info`, `neutral`, `success`, `warning`

## Accessibility

Link renders Next links for internal URLs, anchors for fragments, and safe external anchors with noopener noreferrer.

## Related

- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio): Keep media at a stable aspect ratio as its container resizes.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Checkbox](https://design.gaudi.site/docs/components/checkbox): Checkbox renders a token-styled binary control.

Source: https://design.gaudi.site/docs/components/link (Markdown with example code: https://design.gaudi.site/docs/components/link.md)

---

# Loader

> An accessible loading indicator with arcs, dots, expanding rings, and an indeterminate bar.

Loader replaces the former Spinner component and story.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Loader` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Loader/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-loader--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Loader } from '@gaudi/design-system/core/Loader';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/loader-inline-controls.json`.

## Usage

```jsx
import { Loader } from '@gaudi/design-system/core/Loader';

<Loader variant='three-dots' size='md' label='Loading articles' />
```

## Examples

### In buttons, badges and inputs

Registry: `npx shadcn@latest add https://design.gaudi.site/r/loader-inline-controls.json`

### Inline status

Registry: `npx shadcn@latest add https://design.gaudi.site/r/loader-inline-status.json`

### Overlays and empty states

Registry: `npx shadcn@latest add https://design.gaudi.site/r/loader-overlays.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `variant` | `arc \| dual-arc \| bar \| beat \| bounce \| circle-dots \| clip \| puff \| three-dots \| triangle \| two-dots` | `arc` | no | Selects the motion and shape. Every variant represents an unknown wait; use Progress when completion can be measured. |
| `size` | `xs \| sm \| md \| lg` | `md` | no | 12, 16, 20, or 32px tall. The bar is three times as wide; other variants are square. Shapes keep these dimensions across spacing presets. |
| `label` | `string` | `Loading` | no | Accessible status label describing the operation. A visible label belongs beside the indicator. |
| `LoaderRoot` (sub-component) | `component` | `currentColor, sm` | no | Composition primitive with the same variants and sizing. Inherits text color and accepts aria-label rather than label. Loader adds the accent color and md default. |
| `loaderVariants` | `string[]` | — | no | Supported variant names for controls or a variant picker. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `variant`: `arc`, `dual-arc`, `bar`, `beat`, `bounce`, `circle-dots`, `clip`, `puff`, `three-dots`, `triangle`, `two-dots`
- `size`: `xs`, `sm`, `md`, `lg`

## Accessibility

Each loader exposes role="status" and a readable label. Motion is decorative to that status. With reduced motion, rotation, travel, scaling and bouncing stop; the whole indicator breathes slowly in place. For an already-labelled button or busy region, use aria-hidden="true" to avoid duplicate announcements.

## Notes

- Use className="text-current" to inherit surrounding text, or a semantic tone such as text-text-muted. Explicit size utility classes can override the dimensions. Keep the bar at its natural 3:1 ratio.
- All animation is CSS and SVG; there are no timers or browser-only rendering dependencies. Unmount the loader when the operation finishes. Loading state, cancellation, progress and recovery belong to the host.
- Import Loader from the root, core, or core/Loader entry. Spinner, SpinnerRoot and core/Spinner have been renamed to Loader, LoaderRoot and core/Loader; update existing imports.
- The Shadix UI loader reference informed the variant family. Geometry and motion are implemented locally using Gaudi colors, density and motion conventions.

## Related

- [Progress](https://design.gaudi.site/docs/components/progress): Determinate and indeterminate progress with a readable task label.
- [EmptyState](https://design.gaudi.site/docs/components/empty-state): Explain empty collections, unavailable results and the next useful action.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator): What the assistant is doing: idle, thinking, streaming, tool, done or error.

Source: https://design.gaudi.site/docs/components/loader (Markdown with example code: https://design.gaudi.site/docs/components/loader.md)

---

# Map

> An interactive geographic map with selectable markers, route lines, and camera controls.

Powered by MapLibre; applications supply their own style, geography, and prepared data.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Map` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Map/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-map--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Map } from '@gaudi/design-system/core/Map';
```

## Usage

```jsx
'use client';

import { useState } from 'react';
import { Map } from '@gaudi/design-system/core/Map';

const meeting = {
  id: 'meeting',
  coordinates: [-73.983, 40.7535],
  label: 'Bryant Park meeting point'
};

// Pass the host application's MapLibre style object or URL as mapStyle.
// Load @gaudi/design-system/styles.css once in the application's stylesheet entry.
export function MeetingMap({ mapStyle }) {
  const [selectedId, setSelectedId] = useState(null);

  return (
    <div>
      <Map
        label='Meeting location'
        mapStyle={mapStyle}
        initialViewState={{ center: meeting.coordinates, zoom: 15 }}
        markers={[meeting]}
        selectedMarkerId={selectedId}
        onMarkerClick={setSelectedId}
        style={{ height: '24rem' }}
      />
      <p>Bryant Park, 42nd Street and Sixth Avenue, New York.</p>
      {selectedId === meeting.id && (
        <p role='status'>Meet at the Sixth Avenue entrance.</p>
      )}
    </div>
  );
}
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-map--playground)
- [Single location](https://storybook.gaudi.site/index.html?path=/story/core-map--location)
- [Unavailable map & recovery](https://storybook.gaudi.site/index.html?path=/story/core-map--recovery)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `mapStyle` | `MapLibre StyleSpecification \| string` | `required` | no | A stable style object or an application-configured style URL. Gaudi has no built-in map service, access token, geocoding, or routing endpoint. Memoize object styles. Changing the style preserves the camera. |
| `initialViewState` | `{ center: [longitude, latitude], zoom?, bearing?, pitch? }` | `{ center: [0, 0], zoom: 2 }` | no | Initial camera. Later changes use ref.flyTo, ref.fitBounds, or ref.reset. Coordinates always use longitude before latitude. |
| `markers` | `Array<{ id, coordinates, label, tone?, icon?, badge? }>` | `[]` | no | Stable unique IDs, [longitude, latitude] coordinates, and an accessible label. tone uses Button tones, icon is a React slot, and badge is optional visible metadata; include its meaning in label. |
| `selectedMarkerId` | `string \| number` | — | no | Controlled selection. Pointer and keyboard activation request a selection; the host chooses whether to accept it. Selection does not move the camera. |
| `onMarkerClick` | `(id) => void` | — | no | Controlled selection. Pointer and keyboard activation request a selection; the host chooses whether to accept it. Selection does not move the camera. |
| `routes` | `Array<{ id, coordinates, color?, width?, dashed? }>` | `[]` | no | Prepared line strings (at least two coordinates each). The app supplies color and status meaning. Defaults: blue, 3px, solid. Preserve attribution in your map style. |
| `label` | `string` | `Map` | no | Accessible name for the map region and keyboard canvas. |
| `controls` | `boolean` | `true` | no | Shows reset, zoom in, and zoom out controls when interactive. |
| `interactive` | `boolean` | `true` | no | Enables camera gestures and keyboard navigation. False disables those and hides camera controls; marker buttons remain selectable. |
| `scrollZoom` | `boolean` | `false` | no | Enables wheel zoom. Off by default so a map embedded in a page does not trap page scrolling. |
| `minZoom` | `number` | `0` | no | Camera zoom bounds. Changes clamp the current view without replacing the map. |
| `maxZoom` | `number` | `20` | no | Camera zoom bounds. Changes clamp the current view without replacing the map. |
| `onViewStateChange` | `(view) => void` | — | no | Camera movement completion, map readiness, and renderer/style/source errors. view includes center, zoom, bearing, and pitch. onViewStateChange reports state; it is not a controlled camera prop. |
| `onLoad` | `(view) => void` | — | no | Camera movement completion, map readiness, and renderer/style/source errors. view includes center, zoom, bearing, and pitch. onViewStateChange reports state; it is not a controlled camera prop. |
| `onError` | `(error) => void` | — | no | Camera movement completion, map readiness, and renderer/style/source errors. view includes center, zoom, bearing, and pitch. onViewStateChange reports state; it is not a controlled camera prop. |
| `ref` | `{ flyTo(view), fitBounds(bounds, options?), reset(), getViewState() }` | — | no | Imperative camera access after readiness. fitBounds accepts southwest/northeast coordinate pairs and optional MapLibre fit options. Camera motion honors reduced motion. getViewState returns null before mount. |
| `labels` | `{ loading?, unavailable?, retry?, zoomIn?, zoomOut?, reset? }` | `English labels` | no | Localized state and control text. |
| `children` | `ReactNode` | — | no | Bottom-left overlay content and custom unavailable-state content. Retry remains available. Keep overlay content concise and provide a textual alternative for important geographic information. |
| `fallback` | `ReactNode` | `location buttons` | no | Bottom-left overlay content and custom unavailable-state content. Retry remains available. Keep overlay content concise and provide a textual alternative for important geographic information. |
| `style` | `CSSProperties` | — | no | Container styling, including height (default 32rem). The map follows its container size. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

The named region contains a focusable map canvas: arrows pan, plus/minus zoom. Marker buttons and controls work with Enter/Space and show focus. Selected markers expose aria-pressed. Browser touch gestures and reduced motion are supported. Geographic canvas content itself is not a screen-reader equivalent: provide a linked list or textual route summary, as the tracking example does.

## Notes

- Use an app-owned basemap and preserve the provider’s attribution. Style URLs, tiles, sprites, and glyphs are only requested when configured by the host. For local demos, the bundled NYC geometry and system fonts need no external services.
- The tracking story is a composition of Map, Button, Input, Select, Icon, and Pill. Vehicles and journeys are fictional, stored locally, and do not imply live tracking, traffic, or route calculation.
- Keep markers and route IDs stable. Updating coordinates moves the existing marker and preserves its button identity. Resource failures show a recoverable state with a list fallback; WebGL support is required to draw the map.

## Related

- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [Icon](https://design.gaudi.site/docs/components/icon): Static and interactive artwork from Gaudi’s centralized icon registry.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Pointer](https://design.gaudi.site/docs/components/pointer): A pointer effect scoped to its container, with direct, spring and lazy tracking, hover feedback, and native input fallbacks.

Source: https://design.gaudi.site/docs/components/map (Markdown with example code: https://design.gaudi.site/docs/components/map.md)

---

# Pill

> Pill renders compact category and status labels.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Pill` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Pill/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-pill--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Pill from '@gaudi/design-system/core/Pill';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/badge-icons-avatars.json`.

## Usage

```jsx
import { Pill } from '@gaudi/design-system';

<Pill tone='blue' variant='solid' size='sm'>Engineering</Pill>
```

## Examples

### Icons, dots, avatars and images

Registry: `npx shadcn@latest add https://design.gaudi.site/r/badge-icons-avatars.json`

### Removable filters and links

Registry: `npx shadcn@latest add https://design.gaudi.site/r/badge-removable-filters.json`

### Sizes, counts and labels

Registry: `npx shadcn@latest add https://design.gaudi.site/r/badge-sizes-counts.json`

### Variants

Registry: `npx shadcn@latest add https://design.gaudi.site/r/badge-variants.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | — | no | Visible category, status, or tag label. |
| `size` | `xs \| sm \| md \| lg` | `md` | no | Controls padding and text size. |
| `tone` | `gray \| neutral \| blue \| teal \| green \| amber \| yellow \| red \| rose \| indigo` | `blue` | no | Semantic tone alias mapped through Gaudi tokens rather than raw palette utilities. |
| `variant` | `solid \| soft \| outline \| ghost \| subtle` | `solid` | no | Visual treatment. |
| `radius` | `sm \| md \| full` | `sm` | no | Legacy aliases use the global --ds-radius setting (4px by default); none stays square where supported. |
| `href` | `string` | — | no | Renders the pill as a navigation link. |
| `icon` | `ReactNode` | — | no | Decorative leading icon. |
| `pulse` | `boolean` | `false` | no | Adds a pulsing status dot. |
| `className` | `string` | — | no | Root class override. |

### Variants

- `size`: `xs`, `sm`, `md`, `lg`
- `tone`: `gray`, `neutral`, `blue`, `teal`, `green`, `amber`, `yellow`, `red`, `rose`, `indigo`
- `variant`: `solid`, `soft`, `outline`, `ghost`, `subtle`
- `radius`: `sm`, `md`, `full`

## Accessibility

Pill includes visible text so status or category meaning is not color-only.

## Related

- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio): Keep media at a stable aspect ratio as its container resizes.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Checkbox](https://design.gaudi.site/docs/components/checkbox): Checkbox renders a token-styled binary control.

Source: https://design.gaudi.site/docs/components/pill (Markdown with example code: https://design.gaudi.site/docs/components/pill.md)

---

# Pointer

> A pointer effect scoped to its container, with direct, spring and lazy tracking, hover feedback, and native input fallbacks.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Pointer` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Pointer/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-pointer--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Pointer } from '@gaudi/design-system/core/Pointer';
```

## Usage

```jsx
import { Pointer, Button } from '@gaudi/design-system';

<Pointer variant='frame' tracking='lazy' className='min-h-80 p-8'>
  <Button>Explore work</Button>
</Pointer>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-pointer--playground)
- [Direct, spring and lazy](https://storybook.gaudi.site/index.html?path=/story/core-pointer--tracking)
- [Contextual labels](https://storybook.gaudi.site/index.html?path=/story/core-pointer--labels)
- [Inputs and native fallbacks](https://storybook.gaudi.site/index.html?path=/story/core-pointer--native-fallbacks)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `variant` | `dot \| ring \| frame \| label` | `frame` | no | Follower appearance. Ring and frame keep a precise dot at the actual pointer; label places a hint beside it. |
| `tracking` | `direct \| spring \| lazy` | `lazy` | no | Immediate movement, a responsive spring, or a slower trailing frame. |
| `tone` | `neutral \| accent` | `neutral` | no | Theme-aware foreground or accent color. |
| `label` | `string` | `Explore` | no | Default label for the label variant. A descendant data-pointer-label overrides it while hovered. |
| `hideCursor` | `boolean` | `true` | no | Hides the native cursor only while the effect is active inside this container. |
| `disabled` | `boolean` | `false` | no | Turns off the decorative effect. Descendant controls stay usable. |
| `data-pointer-native` | `HTML attribute on descendants` | — | no | Opt any subtree into the native cursor, for example selectable article text. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `variant`: `dot`, `ring`, `frame`, `label`
- `tracking`: `direct`, `spring`, `lazy`
- `tone`: `neutral`, `accent`

## Accessibility

The overlay is aria-hidden and never captures pointer events. Touch, pen, reduced motion, editable fields, keyboard use, and disabled effects retain the native cursor. Give every action its normal visible label; pointer text is supplementary. No global cursor styles are changed.

## Related

- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio): Keep media at a stable aspect ratio as its container resizes.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Checkbox](https://design.gaudi.site/docs/components/checkbox): Checkbox renders a token-styled binary control.

Source: https://design.gaudi.site/docs/components/pointer (Markdown with example code: https://design.gaudi.site/docs/components/pointer.md)

---

# Progress

> Determinate and indeterminate progress with a readable task label.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Progress` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Progress/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-progress--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Progress from '@gaudi/design-system/core/Progress';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/progress-multi-step.json`.

## Usage

```jsx
import Progress from '@gaudi/design-system/core/Progress';

<Progress value={completed} max={total} label='Upload progress' />
```

## Examples

### Multi-step

Registry: `npx shadcn@latest add https://design.gaudi.site/r/progress-multi-step.json`

### Sizes and colors

Registry: `npx shadcn@latest add https://design.gaudi.site/r/progress-sizes-colors.json`

### Status messages

Registry: `npx shadcn@latest add https://design.gaudi.site/r/progress-status-messages.json`

### File upload list

Registry: `npx shadcn@latest add https://design.gaudi.site/r/progress-upload-list.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | — | no | Accessible name of the progress indicator. |
| `value` | `number` | — | no | Completed amount; omit for indeterminate progress. |
| `max` | `number` | `100` | no | Total amount. |
| `valueText` | `string` | — | no | Human-readable progress such as 3 of 8 files. |
| `tone` | `accent \| success \| warning \| danger` | `accent` | no | Status color. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `tone`: `accent`, `success`, `warning`, `danger`

## Accessibility

Provide a task label and meaningful value text. Avoid announcing every small progress update.

## Related

- [Item](https://design.gaudi.site/docs/components/item): Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.
- [Slider](https://design.gaudi.site/docs/components/slider): Adjust one value or a range with pointer and keyboard input.
- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio): Keep media at a stable aspect ratio as its container resizes.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.

Source: https://design.gaudi.site/docs/components/progress (Markdown with example code: https://design.gaudi.site/docs/components/progress.md)

---

# RadioGroup

> Choose one option using native radio controls or selectable cards.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/RadioGroup` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/RadioGroup/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-radiogroup--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import RadioGroup from '@gaudi/design-system/core/RadioGroup';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/radio-group-corner-cards.json`.

## Usage

```jsx
import RadioGroup from '@gaudi/design-system/core/RadioGroup';

<RadioGroup label='Delivery frequency' value={frequency} onValueChange={setFrequency}
  options={[{ value: 'daily', label: 'Daily' }, { value: 'weekly', label: 'Weekly' }]} />
```

## Examples

### Corner-radio cards

Registry: `npx shadcn@latest add https://design.gaudi.site/r/radio-group-corner-cards.json`

### Fieldset, descriptions and states

Registry: `npx shadcn@latest add https://design.gaudi.site/r/radio-group-fieldset-states.json`

### Framed lists

Registry: `npx shadcn@latest add https://design.gaudi.site/r/radio-group-framed-lists.json`

### Label extras and layouts

Registry: `npx shadcn@latest add https://design.gaudi.site/r/radio-group-label-extras.json`

### Row cards

Registry: `npx shadcn@latest add https://design.gaudi.site/r/radio-group-row-cards.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label / description` | `ReactNode` | — | no | Legend and supporting instructions. |
| `options` | `Array<{ value, label, description?, disabled? }>` | `[]` | no | Mutually exclusive choices. |
| `value / defaultValue / onValueChange` | `string / function` | — | no | Controlled or initial selected value. |
| `name` | `string` | `Generated ID` | no | Shared form field name. |
| `disabled / required` | `boolean` | — | no | Native form constraints. |
| `variant` | `list \| cards` | `list` | no | Choice layout. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `variant`: `list`, `cards`

## Accessibility

Native radios provide Arrow-key navigation and form submission. Keep the legend and option labels descriptive.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Tooltip](https://design.gaudi.site/docs/components/tooltip): Brief contextual help attached to an independently labelled control.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Separator](https://design.gaudi.site/docs/components/separator): Separate related content with a horizontal or vertical rule.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.

Source: https://design.gaudi.site/docs/components/radio-group (Markdown with example code: https://design.gaudi.site/docs/components/radio-group.md)

---

# ReadingIndicator

> Reading progress as a classic top bar, a vertical ruler with a moving percentage, or a movable circular meter.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/ReadingIndicator` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/ReadingIndicator/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-readingindicator--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ReadingIndicator } from '@gaudi/design-system/core/ReadingIndicator';
```

## Usage

```jsx
import { ReadingIndicator } from '@gaudi/design-system/core/ReadingIndicator';

// Render once near the page root.
<ReadingIndicator />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-readingindicator--playground)
- [Bar, ruler and ring](https://storybook.gaudi.site/index.html?path=/story/core-readingindicator--styles)
- [Article range](https://storybook.gaudi.site/index.html?path=/story/core-readingindicator--article)
- [Top of page](https://storybook.gaudi.site/index.html?path=/story/core-readingindicator--page)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `variant` | `bar \| ruler \| ring` | `bar` | no | A thin horizontal bar, a vertical tick scale, or a compact circular meter. |
| `position` | `fixed \| absolute \| inline` | `fixed` | no | Fixed to the viewport, anchored inside a positioned parent, or placed in normal layout. Bar sits at the top; ruler at the end edge; ring at the bottom end. |
| `targetRef` | `Ref<HTMLElement>` | `window` | no | Ref to a scrolling element or a Gaudi ScrollArea root. Omit to track the document. |
| `contentRef` | `Ref<HTMLElement>` | `whole scroll range` | no | Optional article inside the scroll target. Starts when its top reaches the viewport top; finishes when its bottom comes into view. |
| `value` | `number (0–100)` | `automatic` | no | Supply an external reading percentage to bypass scroll tracking. Clamped to 0–100; non-finite values become 0. |
| `tone` | `accent \| neutral` | `accent` | no | Accent or foreground marks, adapted to the current theme. |
| `showValue` | `boolean` | `false for bar; true otherwise` | no | Shows the percentage next to the indicator. |
| `label` | `string` | `Reading progress` | no | Accessible name for the progressbar. aria-labelledby can name it from an existing heading. |
| `draggable` | `boolean` | `false` | no | Adds a movement handle to a fixed or absolute ring. Arrow keys move it; Home or Escape resets it. |
| `dragBoundsRef` | `Ref<HTMLElement>` | `viewport` | no | Constrains the movable ring to this container. Set it for a ring positioned inside a panel. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `variant`: `bar`, `ruler`, `ring`
- `position`: `fixed`, `absolute`, `inline`
- `tone`: `accent`, `neutral`

## Accessibility

Exposes a named progressbar without live announcements on every scroll. The indicator does not capture scrolling or text selection; only the optional ring handle receives input. Reduced motion removes the number transition. Progress measures scroll position, not comprehension.

## Notes

- Resizes and content growth are measured automatically. A non-scrollable document is complete (100%); an unresolved target starts at 0%.
- Reserve a side gutter for the ruler and room for the ring so they do not cover reading text. Set style.top to place a fixed bar below a site header. For a top bar with no extra configuration, render <ReadingIndicator /> once in the page.
- The ruler and ring are independently implemented interpretations of the Skiper UI scroll progress references; no remote assets or registry code are loaded.

## Related

- [Progress](https://design.gaudi.site/docs/components/progress): Determinate and indeterminate progress with a readable task label.
- [ScrollArea](https://design.gaudi.site/docs/components/scroll-area): Contained scrolling with themed scrollbars and optional smooth wheel motion for article reading.
- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio): Keep media at a stable aspect ratio as its container resizes.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.

Source: https://design.gaudi.site/docs/components/reading-indicator (Markdown with example code: https://design.gaudi.site/docs/components/reading-indicator.md)

---

# Select

> Select renders a styled option picker with searchable combobox behavior and multi-select support.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Select` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Select/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-select--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Select from '@gaudi/design-system/core/Select';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/autocomplete-async-search.json`.

## Usage

```jsx
import { Select } from '@gaudi/design-system';

<Select
  searchable
  multiple
  placeholder='Choose topics'
  options={[
    { label: 'Design systems', value: 'design-systems' },
    { label: 'Knowledge graphs', value: 'knowledge-graphs' },
  ]}
/>
```

## Examples

### Async search results

Registry: `npx shadcn@latest add https://design.gaudi.site/r/autocomplete-async-search.json`

### Autocomplete in a form

Registry: `npx shadcn@latest add https://design.gaudi.site/r/autocomplete-in-form.json`

### Input options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/autocomplete-input-options.json`

### Grouped people search

Registry: `npx shadcn@latest add https://design.gaudi.site/r/autocomplete-people-search.json`

### Date presets with a custom picker

Registry: `npx shadcn@latest add https://design.gaudi.site/r/combobox-date-presets.json`

### Grouped options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/combobox-grouped.json`

### Combobox inside a dialog

Registry: `npx shadcn@latest add https://design.gaudi.site/r/combobox-in-dialog.json`

### Combobox in a form

Registry: `npx shadcn@latest add https://design.gaudi.site/r/combobox-in-form.json`

### Input options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/combobox-input-options.json`

### Member tags

Registry: `npx shadcn@latest add https://design.gaudi.site/r/combobox-member-tags.json`

### Multiple selection with chips

Registry: `npx shadcn@latest add https://design.gaudi.site/r/combobox-multiple-chips.json`

### Property pickers

Registry: `npx shadcn@latest add https://design.gaudi.site/r/combobox-property-pickers.json`

### Native select fields

Registry: `npx shadcn@latest add https://design.gaudi.site/r/native-select-fields.json`

### Clearable select

Registry: `npx shadcn@latest add https://design.gaudi.site/r/select-clearable.json`

### Options with descriptions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/select-descriptions.json`

### Form fields and states

Registry: `npx shadcn@latest add https://design.gaudi.site/r/select-form-states.json`

### Grouped options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/select-grouped.json`

### Select inside a dialog

Registry: `npx shadcn@latest add https://design.gaudi.site/r/select-in-dialog.json`

### Rich option content

Registry: `npx shadcn@latest add https://design.gaudi.site/r/select-rich-options.json`

### Select in a toolbar

Registry: `npx shadcn@latest add https://design.gaudi.site/r/select-toolbar.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options` | `Array<{ label, value, disabled }>` | `[]` | no | Selectable options. Option children are also normalized when options is empty. |
| `value` | `string \| string[]` | — | no | Controlled selected value. Arrays are used for multiple mode. |
| `defaultValue` | `string \| string[]` | — | no | Initial uncontrolled selected value. |
| `onValueChange` | `(value, option) => void` | — | no | Called when selection changes. |
| `multiple` | `boolean` | `false` | no | Allows selecting more than one option. |
| `searchable` | `boolean` | `false` | no | Shows a search field inside the popup and filters options. |
| `placeholder` | `string` | `Select option` | no | Trigger placeholder when nothing is selected. |
| `searchPlaceholder` | `string` | `Search options...` | no | Search input placeholder. |
| `emptyText` | `string` | `No options found.` | no | Empty result text. |
| `defaultOpen` | `boolean` | `false` | no | Initial open state for demos or controlled-looking examples. |
| `disabled` | `boolean` | `false` | no | Disables the trigger. |
| `invalid` | `boolean` | `false` | no | Applies aria-invalid and error styling. |
| `name` | `string` | — | no | Renders hidden form inputs for selected values. |
| `aria-label` | `string` | — | no | Accessible label for icon-only or unlabeled select controls. |
| `children` | `ReactNode` | — | no | Option children normalized when options is empty. |
| `className` | `string` | — | no | Root class override. |
| `classNames` | `{ root, trigger, value, placeholder, chevron, popup, search, option, check, empty }` | — | no | Slot-level class overrides. |

## Accessibility

Select uses a native button trigger, listbox semantics, aria-expanded, aria-selected, aria-multiselectable for multi-select, and keyboard support for Arrow keys, Enter, Space, Home, End, and Escape.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Item](https://design.gaudi.site/docs/components/item): Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.
- [Toast](https://design.gaudi.site/docs/components/toast): Transient feedback for completed actions, errors and recoverable background work.
- [Banner](https://design.gaudi.site/docs/components/banner): Banner renders a compact announcement strip.

Source: https://design.gaudi.site/docs/components/select (Markdown with example code: https://design.gaudi.site/docs/components/select.md)

---

# Separator

> Separate related content with a horizontal or vertical rule.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Separator` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Separator/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-separator--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Separator } from '@gaudi/design-system/core/Separator';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/separator-horizontal.json`.

## Usage

```jsx
import { Separator } from '@gaudi/design-system/core/Separator';

<Separator orientation='horizontal' />
```

## Examples

### Horizontal rules

Registry: `npx shadcn@latest add https://design.gaudi.site/r/separator-horizontal.json`

### Text label

Registry: `npx shadcn@latest add https://design.gaudi.site/r/separator-text-label.json`

### Vertical rules

Registry: `npx shadcn@latest add https://design.gaudi.site/r/separator-vertical.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `orientation` | `horizontal \| vertical` | `horizontal` | no | Direction of the rule. |
| `decorative` | `boolean` | `true` | no | Keep visual-only separators out of the accessibility tree. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `orientation`: `horizontal`, `vertical`

## Accessibility

Set decorative={false} only when the separator conveys meaningful structure.

## Related

- [Direction](https://design.gaudi.site/docs/components/direction): Scopes text direction for Gaudi controls that need directional keyboard and placement behavior.
- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio): Keep media at a stable aspect ratio as its container resizes.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.

Source: https://design.gaudi.site/docs/components/separator (Markdown with example code: https://design.gaudi.site/docs/components/separator.md)

---

# Slider

> Adjust one value or a range with pointer and keyboard input.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Slider` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Slider/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-slider--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Slider } from '@gaudi/design-system/core/Slider';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/slider-number-sync.json`.

## Usage

```jsx
import { Slider } from '@gaudi/design-system/core/Slider';

<Slider aria-label='Volume' value={volume} onValueChange={setVolume} min={0} max={100} />
```

## Examples

### Paired with a number field

Registry: `npx shadcn@latest add https://design.gaudi.site/r/slider-number-sync.json`

### Custom readouts

Registry: `npx shadcn@latest add https://design.gaudi.site/r/slider-readouts.json`

### Scale labels and ticks

Registry: `npx shadcn@latest add https://design.gaudi.site/r/slider-scale-ticks.json`

### Thumbs and states

Registry: `npx shadcn@latest add https://design.gaudi.site/r/slider-thumbs-states.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `getValueText` | `(value, index) => string` | — | no | Text a thumb announces instead of the number, such as a level name; use it with a controlled value. |
| `value / defaultValue` | `number[]` | — | no | Controlled or initial thumb positions. |
| `onValueChange / onValueCommit` | `(values: number[]) => void` | — | no | Continuous updates or the committed selection. |
| `min / max` | `number` | `0 / 100` | no | Allowed range. |
| `step` | `number` | `1` | no | Keyboard and pointer increment. |
| `orientation` | `horizontal \| vertical` | `horizontal` | no | Control orientation. |
| `disabled` | `boolean` | `false` | no | Prevent adjustment. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `orientation`: `horizontal`, `vertical`

## Accessibility

Label every thumb and provide a readable value. Use range examples when the two endpoints have different meanings.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [NumberField](https://design.gaudi.site/docs/components/number-field): Numeric entry with increment buttons, bounds, locale formatting and scrubbing.
- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio): Keep media at a stable aspect ratio as its container resizes.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.

Source: https://design.gaudi.site/docs/components/slider (Markdown with example code: https://design.gaudi.site/docs/components/slider.md)

---

# Switch

> Switch renders a token-styled boolean preference control.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Switch` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Switch/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-switch--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Switch from '@gaudi/design-system/core/Switch';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/switch-card-grid.json`.

## Usage

```jsx
import { Switch } from '@gaudi/design-system';

<Switch label='Email notifications' defaultChecked />
```

## Examples

### Card grid with descriptions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/switch-card-grid.json`

### Colours and destructive settings

Registry: `npx shadcn@latest add https://design.gaudi.site/r/switch-colours-destructive.json`

### Labels and states

Registry: `npx shadcn@latest add https://design.gaudi.site/r/switch-labels-states.json`

### Settings panel

Registry: `npx shadcn@latest add https://design.gaudi.site/r/switch-settings-panel.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | `generated id` | no | Connects the switch to its visible label. |
| `label` | `ReactNode` | — | no | Visible label text. |
| `checked` | `boolean` | — | no | Controlled checked state. |
| `defaultChecked` | `boolean` | `false` | no | Initial checked state for uncontrolled usage. |
| `size` | `sm \| md \| lg` | `md` | no | Controls track, thumb, and label scale. |
| `disabled` | `boolean` | `false` | no | Prevents changes and lowers visual emphasis. |
| `onCheckedChange` | `(checked) => void` | — | no | Called with the next checked state. |
| `className` | `string` | — | no | Root class override. |

### Variants

- `size`: `sm`, `md`, `lg`

## Accessibility

Switch exposes role switch, aria-checked, disabled state, and a visible label when provided.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Tooltip](https://design.gaudi.site/docs/components/tooltip): Brief contextual help attached to an independently labelled control.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Separator](https://design.gaudi.site/docs/components/separator): Separate related content with a horizontal or vertical rule.

Source: https://design.gaudi.site/docs/components/switch (Markdown with example code: https://design.gaudi.site/docs/components/switch.md)

---

# Tabs

> Switch between related panels with keyboard-accessible tab controls.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Tabs` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Tabs/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-tabs--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Tabs } from '@gaudi/design-system/core/Tabs';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/tabs-badge-counts.json`.

## Usage

```jsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@gaudi/design-system/core/Tabs';

<Tabs defaultValue='overview'>
  <TabsList aria-label='Project'><TabsTrigger value='overview'>Overview</TabsTrigger><TabsTrigger value='activity'>Activity</TabsTrigger></TabsList>
  <TabsContent value='overview'>{overview}</TabsContent>
  <TabsContent value='activity'>{activity}</TabsContent>
</Tabs>
```

## Examples

### Badge counts

Registry: `npx shadcn@latest add https://design.gaudi.site/r/tabs-badge-counts.json`

### Period switch

Registry: `npx shadcn@latest add https://design.gaudi.site/r/tabs-period-switch.json`

### Settings form tabs

Registry: `npx shadcn@latest add https://design.gaudi.site/r/tabs-settings-form.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value / defaultValue / onValueChange` | `string / function` | — | no | Controlled or initial active tab. |
| `orientation` | `horizontal \| vertical` | `horizontal` | no | Visual layout and keyboard direction. |
| `activationMode` | `automatic \| manual` | `automatic` | no | Whether focus also activates a tab. |
| `TabsList.variant` | `underline \| outline \| type` | `underline` | no | How the active tab is marked: a short underline, a fine outline, or weight alone. default and line still map to underline. |
| `TabsList.tone` | `neutral \| accent \| info \| success \| warning \| danger \| discovery \| attention` | `neutral` | no | Colour of the underline or outline marker; neutral follows the text colour. |
| `TabsTrigger.value / TabsContent.value` | `string` | `Required` | no | Matching identity for the trigger and panel. |
| `TabsTrigger.disabled` | `boolean` | `false` | no | Exclude an unavailable tab from navigation. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `orientation`: `horizontal`, `vertical`
- `activationMode`: `automatic`, `manual`

## Accessibility

Radix associates tabs and panels. Label the tab list; use manual activation when loading panels is expensive.

## Related

- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.

Source: https://design.gaudi.site/docs/components/tabs (Markdown with example code: https://design.gaudi.site/docs/components/tabs.md)

---

# Textarea

> Multiline text entry that composes with the same labels and errors as Input.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Textarea` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Textarea/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-textarea--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Textarea from '@gaudi/design-system/core/Textarea';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/textarea-auto-resize.json`.

## Usage

```jsx
import Textarea from '@gaudi/design-system/core/Textarea';

<Textarea aria-label='Message' value={message} onChange={event => setMessage(event.target.value)} rows={4} />
```

## Examples

### Growing note field with a counter

Registry: `npx shadcn@latest add https://design.gaudi.site/r/textarea-auto-resize.json`

### Field states

Registry: `npx shadcn@latest add https://design.gaudi.site/r/textarea-field-states.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `caretMode` | `native \| smooth` | `provider / smooth` | no | Overrides InputConfigProvider for this field. Smooth mode animates the collapsed caret while supported native text controls retain their editing behavior. |
| `rows` | `number` | `4` | no | Initial visible line count. |
| `placeholder` | `string` | — | no | Example value; never a replacement for a label. |
| `Native textarea props / ref` (pass-through) | `TextareaHTMLAttributes<HTMLTextAreaElement>` | — | no | Value, change callback, name, placeholder, limits, disabled, required and ARIA attributes. |
| `invalid` | `boolean` | — | no | Expose invalid state through FieldTextarea. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `caretMode`: `native`, `smooth`

## Accessibility

Use FieldLabel and FieldError. Preserve entered text after a validation or submission failure.

## Related

- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio): Keep media at a stable aspect ratio as its container resizes.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.

Source: https://design.gaudi.site/docs/components/textarea (Markdown with example code: https://design.gaudi.site/docs/components/textarea.md)

---

# TextHighlight

> TextHighlight emphasizes short inline phrases inside prose.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/TextHighlight` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/TextHighlight/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-texthighlight--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { TextHighlight } from '@gaudi/design-system/core/TextHighlight';
```

## Usage

```jsx
import { TextHighlight } from '@gaudi/design-system';

<p>Design systems make <TextHighlight>consistency visible</TextHighlight>.</p>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-texthighlight--playground)
- [Tones](https://storybook.gaudi.site/index.html?path=/story/core-texthighlight--tones)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | — | no | Inline text to emphasize. |
| `variant` | `marker \| soft \| underline` | `marker` | no | Highlight treatment. |
| `tone` | `gray \| neutral \| blue \| teal \| green \| amber \| yellow \| red \| rose \| indigo` | `blue` | no | Color family. |
| `animate` | `boolean` | `true` | no | Enables the marker draw animation. |
| `className` | `string` | — | no | Root class override. |

### Variants

- `variant`: `marker`, `soft`, `underline`
- `tone`: `gray`, `neutral`, `blue`, `teal`, `green`, `amber`, `yellow`, `red`, `rose`, `indigo`

## Accessibility

TextHighlight is inline text emphasis. It must keep the original text readable and must not be the only way meaning is conveyed.

## Related

- [Highlight](https://design.gaudi.site/docs/mdx/highlight): Inline emphasis within article text.
- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio): Keep media at a stable aspect ratio as its container resizes.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.

Source: https://design.gaudi.site/docs/components/text-highlight (Markdown with example code: https://design.gaudi.site/docs/components/text-highlight.md)

---

# ToggleGroup

> Single or multiple pressed choices for view modes and compact formatting controls.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/ToggleGroup` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/ToggleGroup/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-togglegroup--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import ToggleGroup from '@gaudi/design-system/core/ToggleGroup';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/toggle-group-filters.json`.

## Usage

```jsx
import ToggleGroup from '@gaudi/design-system/core/ToggleGroup';

<ToggleGroup type='single' label='Display' value={view} onValueChange={setView}
  options={[{ value: 'list', label: 'List' }, { value: 'grid', label: 'Grid' }]} />
```

## Examples

### Filters

Registry: `npx shadcn@latest add https://design.gaudi.site/r/toggle-group-filters.json`

### Icon and label switchers

Registry: `npx shadcn@latest add https://design.gaudi.site/r/toggle-group-switchers.json`

### Group variants, spacing, sizes and orientation

Registry: `npx shadcn@latest add https://design.gaudi.site/r/toggle-group-variants.json`

### Toggle that swaps icon and label

Registry: `npx shadcn@latest add https://design.gaudi.site/r/toggle-icon-label-swap.json`

### Reactions and counts

Registry: `npx shadcn@latest add https://design.gaudi.site/r/toggle-reactions.json`

### Toggle variants, sizes and states

Registry: `npx shadcn@latest add https://design.gaudi.site/r/toggle-variants.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | — | no | Accessible name of the group. |
| `options` | `Array<{ value, label, disabled? }>` | `[]` | no | Available choices. |
| `type` | `single \| multiple` | `single` | no | Selection model. |
| `variant` | `outline \| default` | `outline` | no | Attached outline items by default; spacing separates them. |
| `size` | `sm \| default \| lg` | `default` | no | Attached outline items by default; spacing separates them. |
| `spacing` | `number` | `0` | no | Attached outline items by default; spacing separates them. |
| `value / defaultValue / onValueChange` | `string \| string[] / function` | — | no | Controlled or initial selection matching type. |
| `disabled / loop` | `boolean` | `false / true` | no | Group availability and keyboard wrapping. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `type`: `single`, `multiple`
- `variant`: `outline`, `default`
- `size`: `sm`, `default`, `lg`

## Accessibility

Each item communicates its pressed state. Choose radio controls when a form requires exactly one persistent choice.

## Related

- [Tooltip](https://design.gaudi.site/docs/components/tooltip): Brief contextual help attached to an independently labelled control.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio): Keep media at a stable aspect ratio as its container resizes.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.

Source: https://design.gaudi.site/docs/components/toggle-group (Markdown with example code: https://design.gaudi.site/docs/components/toggle-group.md)

---

# Tooltip

> Brief contextual help attached to an independently labelled control.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/Tooltip` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Tooltip/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-tooltip--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Tooltip from '@gaudi/design-system/core/Tooltip';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/tooltip-disabled-button.json`.

## Usage

```jsx
import Tooltip from '@gaudi/design-system/core/Tooltip';
import Button from '@gaudi/design-system/core/Button';

<Tooltip content='Copy link'><Button aria-label='Copy link' onClick={copyLink}>Copy</Button></Tooltip>
```

## Examples

### Disabled button

Registry: `npx shadcn@latest add https://design.gaudi.site/r/tooltip-disabled-button.json`

### People

Registry: `npx shadcn@latest add https://design.gaudi.site/r/tooltip-people.json`

### Sides

Registry: `npx shadcn@latest add https://design.gaudi.site/r/tooltip-sides.json`

### Status and metadata

Registry: `npx shadcn@latest add https://design.gaudi.site/r/tooltip-status-metadata.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactElement` | `Required` | no | Single focusable, ref-forwarding trigger. |
| `content` | `ReactNode` | — | no | Supporting tooltip text. |
| `side` | `top \| right \| bottom \| left` | `top` | no | Preferred placement; collision handling may adjust it. |
| `delayDuration` | `number` | `300` | no | Hover delay in milliseconds. |
| `open / defaultOpen / onOpenChange` | `boolean / function` | `uncontrolled` | no | Controlled or initial visibility. |

### Variants

- `side`: `top`, `right`, `bottom`, `left`

## Accessibility

Tooltips open on focus and hover, dismiss with Escape and do not replace the control’s accessible name. Use Popover for interactive content.

## Related

- [Popover](https://design.gaudi.site/docs/components/popover): Popover renders compact positioned supporting content next to its trigger.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.

Source: https://design.gaudi.site/docs/components/tooltip (Markdown with example code: https://design.gaudi.site/docs/components/tooltip.md)

---

# VideoPlayer

> A native video player with a complete toolbar, an elastic minimal timeline, and a poster that opens a focused viewing dialog.

- Category: Core · Basics
- Import: `@gaudi/design-system/core/VideoPlayer` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/VideoPlayer/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-videoplayer--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { VideoPlayer } from '@gaudi/design-system/core/VideoPlayer';
```

## Usage

```jsx
import { VideoPlayer } from '@gaudi/design-system/core/VideoPlayer';

<VideoPlayer src='/media/film.webm' poster='/media/film.webp' title='A short film'
  tracks={[{ src: '/media/film.en.vtt', srcLang: 'en', label: 'English', default: true }]} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-videoplayer--playground)
- [Minimal & elastic timeline](https://storybook.gaudi.site/index.html?path=/story/core-videoplayer--minimal)
- [Poster to dialog](https://storybook.gaudi.site/index.html?path=/story/core-videoplayer--poster-dialog)
- [Empty, error & source changes](https://storybook.gaudi.site/index.html?path=/story/core-videoplayer--recovery)
- [Browser controls](https://storybook.gaudi.site/index.html?path=/story/core-videoplayer--native)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `src` | `string` | — | no | A browser-playable video URL. Changing it resets playback and pending requests. An empty source shows the empty state. |
| `poster` | `string` | — | no | Preview image while the video is idle, and the dialog trigger image. |
| `title` | `string` | `Video` | no | Names the video, player region, and dialog. |
| `variant` | `standard \| minimal \| dialog` | `standard` | no | Full toolbar, compact elastic scrubber, or pointer-enhanced poster opening a dialog. |
| `aspectRatio` | `string \| number` | `16 / 9` | no | CSS aspect ratio of the video stage and poster. |
| `fit` | `contain \| cover` | `contain` | no | Contain preserves the entire frame. Cover crops to fill the stage. |
| `tracks` | `Array<{ src, srcLang, label, kind?, default? }>` | `[]` | no | Native WebVTT tracks; kind defaults to captions. Only captions and subtitles appear in the language selector. Selecting or disabling captions leaves metadata and chapter track modes untouched. Serve track files from the same origin. |
| `autoPlay` | `boolean` | `false` | no | Attempts playback when this source mounts or its dialog opens. Browser rejection leaves a usable Play control and a status message. |
| `defaultMuted` | `boolean` | `false` | no | Initial muted preference for each source. Native volume events own later changes. |
| `defaultVolume` | `number (0–1)` | `1` | no | Initial volume, clamped to the supported range. Applied when the source mounts. |
| `loop` | `boolean` | `false` | no | Restarts the native video at the end. |
| `preload` | `none \| metadata \| auto` | `metadata` | no | Native browser preload hint. Metadata enables the duration and seek controls. |
| `nativeControls` | `boolean` | `false` | no | Uses the browser’s controls in place of the custom toolbar. The source must still be browser-playable; this adds no streaming adapters or codec support. |
| `open` | `boolean` | `uncontrolled` | no | Controlled or uncontrolled dialog visibility. Only used by the dialog variant. |
| `defaultOpen` | `boolean` | `false` | no | Controlled or uncontrolled dialog visibility. Only used by the dialog variant. |
| `onOpenChange` | `(open) => void` | — | no | Controlled or uncontrolled dialog visibility. Only used by the dialog variant. |
| `onPlay / onPause / onEnded / onTimeUpdate / onError` | `(event) => void` | — | no | Native media event callbacks. Time updates are not live announcements. |
| `ref` | `Ref<HTMLVideoElement>` | — | no | Access to the active native video for programmatic playback changes. Null while a dialog is closed. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `variant`: `standard`, `minimal`, `dialog`
- `fit`: `contain`, `cover`
- `preload`: `none`, `metadata`, `auto`

## Accessibility

All controls have accessible names. Space or Enter activates focused buttons; the seek and volume sliders support arrow keys, Home and End. Captions use native text tracks; provide captions for speech and meaningful audio. Dialog traps focus, closes with Escape, and restores focus to its poster. Touch controls stay visible, and reduced motion removes elastic movement.

## Notes

- autoPlay, defaultMuted, and defaultVolume are initial preferences applied when a source mounts or its dialog opens. Updating them does not restart playback or directly update the active video’s muted state or volume. Use the native ref for subsequent programmatic changes.
- Only documented video props are supported; arbitrary native attributes such as crossOrigin are not forwarded. Cross-origin media setup belongs to the host integration. className and style apply to the outer player wrapper.
- The custom toolbar supports finite-duration files. Unknown or infinite durations disable seeking. Use nativeControls for live streams or device-specific playback features.
- Picture-in-picture and fullscreen appear only when supported. Their state follows browser events, and rejected requests show a recoverable message. Support depends on the browser, operating system, and embedding permissions.
- Custom controls remain visible. Below a 640px player width they flow below the video; larger standard players place them over the frame. Enabling captions keeps the controls below so they cannot cover the text. Minimal controls stay below the frame at every width.
- The Skiper 67, 91, and 97 references informed the interactions. This implementation uses Gaudi primitives and native media APIs; it does not load remote examples or copy registry source.

## Related

- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Preview](https://design.gaudi.site/docs/mdx/preview): Preview renders inline link previews for markdown links transformed by the blog MDX pipeline.
- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio): Keep media at a stable aspect ratio as its container resizes.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group): Group related actions with joined borders and consistent sizing.

Source: https://design.gaudi.site/docs/components/video-player (Markdown with example code: https://design.gaudi.site/docs/components/video-player.md)

---

# Accordion

> Rich disclosure for FAQs, settings, member directories, nested help, and guided setup.

Eleven patterns use Gaudi tokens, icons, avatars, cards, and pills.

- Category: Core · Layout & Containers
- Import: `@gaudi/design-system/core/Accordion` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Accordion/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-accordion--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Accordion } from '@gaudi/design-system/core/Accordion';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/accordion-disabled-highlighted.json`.

## Usage

```jsx
import { AccordionGroup } from '@gaudi/design-system';

<AccordionGroup
  items={[
    { value: 'usage', title: 'When should I use it?', content: 'Use accordions for compact progressive disclosure.' },
  ]}
/>
```

## Examples

### Disabled and highlighted

Registry: `npx shadcn@latest add https://design.gaudi.site/r/accordion-disabled-highlighted.json`

### Guided setup

Registry: `npx shadcn@latest add https://design.gaudi.site/r/accordion-guided-setup.json`

### Icons and badges

Registry: `npx shadcn@latest add https://design.gaudi.site/r/accordion-icons-badges.json`

### Inside a card

Registry: `npx shadcn@latest add https://design.gaudi.site/r/accordion-in-card.json`

### Member directory

Registry: `npx shadcn@latest add https://design.gaudi.site/r/accordion-member-directory.json`

### Nested sections

Registry: `npx shadcn@latest add https://design.gaudi.site/r/accordion-nested.json`

### Variants and indicators

Registry: `npx shadcn@latest add https://design.gaudi.site/r/accordion-variants.json`

### Collapsible: Advanced form fields

Registry: `npx shadcn@latest add https://design.gaudi.site/r/collapsible-advanced-fields.json`

### Collapsible: Card that opens from its footer

Registry: `npx shadcn@latest add https://design.gaudi.site/r/collapsible-bottom-trigger.json`

### Collapsible: Tree view with file actions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/collapsible-file-tree.json`

### Collapsible: Framed sections

Registry: `npx shadcn@latest add https://design.gaudi.site/r/collapsible-framed-sections.json`

### Collapsible: Show more details

Registry: `npx shadcn@latest add https://design.gaudi.site/r/collapsible-show-more.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `items` | `Array<{ value, title, content, disabled?, leading?, description?, badge?, indicator?, indicatorPosition?, headingLevel?, forceMount?, className?, triggerClassName?, contentClassName? }>` | `[]` | no | Convenience group items. Rich slots accept React nodes. |
| `type` | `single \| multiple` | `single` | no | Allow one or several expanded panels. |
| `variant` | `outline \| flush \| separated \| solid \| framed` | `outline` | no | Shared border, quiet dividers, individual borders, muted items, or an inset frame. |
| `defaultValue` | `string \| string[] \| null` | `first enabled item (group)` | no | Initial uncontrolled state. Use null or [] to start collapsed. |
| `value` | `string \| string[] \| undefined` | — | no | Controlled state. Single close emits undefined; multiple close emits an array. |
| `onValueChange` | `function` | — | no | Controlled state. Single close emits undefined; multiple close emits an array. |
| `collapsible` | `boolean` | `true` | no | Allow the current single item to close. Set false to keep the active item expanded. |
| `disabled` | `boolean` | `false` | no | Disable all root items or one AccordionItem. |
| `indicator` | `chevron \| plus-minus \| arrow \| ReactNode \| ({isOpen}) => ReactNode \| null` | `chevron` | no | Root default with per-trigger or per-item overrides. |
| `indicatorPosition` | `start \| end` | `end` | no | Logical indicator position, including RTL. |
| `highlight` | `boolean` | `false` | no | Use the accent surface on expanded headers. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | no | Heading level; override per item or trigger. |
| `leading / description / badge` | `ReactNode` | — | no | Noninteractive slots on AccordionTrigger or group items. |
| `forceMount` | `boolean` | `false` | no | Retain closed panel children, hidden and inert, to preserve form drafts. |
| `children` | `ReactNode \| render function` | — | no | AccordionRoot compound children or the legacy state render function. |
| `className / ref / DOM attributes` (pass-through) | `native props` | — | no | Root, item, and trigger forward native props; content className styles its padded inner body. |

### Variants

- `type`: `single`, `multiple`
- `variant`: `outline`, `flush`, `separated`, `solid`, `framed`
- `indicatorPosition`: `start`, `end`
- `headingLevel`: `2`, `3`, `4`, `5`, `6`

## Accessibility

Radix-backed native buttons expose expanded state and labelled panels. Arrow Up/Down and Home/End navigate enabled headers within the current accordion; Enter/Space toggle. Disabled items are skipped. Headings default to h3 and can follow the document hierarchy. Closed panels are inert during animation and unmounted afterward; forceMount retains hidden, inert content. Reduced motion is respected.

## Notes

- `Accordion` and `AccordionGroup` from the package root are the items-based convenience API. Use `AccordionRoot` for compound composition. The named `Accordion` from the `core/Accordion` subpath remains the compound root for compatibility.
- Give every item a stable, unique, non-empty string value. Single mode uses a string; multiple mode uses an array. An explicit undefined controlled value collapses every panel.
- The group opens the first enabled item by default. Use `defaultValue={null}` for a collapsed single group or `defaultValue={[]}` in multiple mode. AccordionRoot starts closed unless a default is supplied.
- Existing render-function children and explicit `isOpen` / `onClick` composition remain supported. New compound usage manages state and ARIA associations automatically.
- Leading content and badges must be noninteractive. Put links, inputs, and action buttons inside AccordionContent. Provide an appropriate headingLevel for nested sections.
- forceMount preserves form state but does not omit closed inputs from native form submission. Consumers own persistence, validation, and submission scope.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Item](https://design.gaudi.site/docs/components/item): Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.
- [Tabs](https://design.gaudi.site/docs/components/tabs): Switch between related panels with keyboard-accessible tab controls.
- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.

Source: https://design.gaudi.site/docs/components/accordion (Markdown with example code: https://design.gaudi.site/docs/components/accordion.md)

---

# Carousel

> Carousel renders standard feature slides and editorial card rails.

- Category: Core · Layout & Containers
- Import: `@gaudi/design-system/core/Carousel` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Carousel/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-carousel--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Carousel from '@gaudi/design-system/core/Carousel';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/carousel-autoplay.json`.

## Usage

```jsx
import { Carousel } from '@gaudi/design-system';

<Carousel
  ariaLabel='Featured articles'
  items={[
    { title: 'Design systems keep editorial rhythm predictable', eyebrow: 'Design Systems', description: 'A focused carousel item.', href: '/blog' },
  ]}
/>
```

## Examples

### Autoplay

Registry: `npx shadcn@latest add https://design.gaudi.site/r/carousel-autoplay.json`

### Content overlays with dots

Registry: `npx shadcn@latest add https://design.gaudi.site/r/carousel-content-overlays.json`

### Layout options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/carousel-layouts.json`

### Thumbnail navigation

Registry: `npx shadcn@latest add https://design.gaudi.site/r/carousel-thumbnails.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `items` | `Array<{ id, title, description, eyebrow, image, alt, href, action, content }>` | `[]` | no | Slide data. Standard uses the active item; apple renders the horizontal rail. |
| `ariaLabel` | `string` | `Carousel` | no | Accessible name for the carousel region. |
| `variant` | `standard \| rail \| apple` | `standard` | no | Slide format. Use rail for editorial card rails; apple remains a legacy alias. |
| `size` | `sm \| md \| lg` | `md` | no | Controls max width and slide/card height. |
| `radius` | `none \| sm \| md \| lg` | `lg` | no | Legacy aliases use the global --ds-radius setting; none keeps square corners. |
| `controls` | `boolean` | `true` | no | Shows previous and next buttons. |
| `loop` | `boolean` | `false` | no | Wraps previous/next navigation. |
| `className` | `string` | — | no | Root class override. |
| `classNames` | `{ root, header, viewport, track, slide, card, image, content, eyebrow, title, description, action, controls, control, indicators, indicator, dialog, overlay }` | — | no | Slot-level overrides for visual composition. |

### Variants

- `variant`: `standard`, `rail`, `apple`
- `size`: `sm`, `md`, `lg`
- `radius`: `none`, `sm`, `md`, `lg`

## Accessibility

Carousel exposes a labelled carousel region, native previous/next buttons, aria-live status updates, keyboard arrow support, and named indicators.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.
- [usePrefersReducedMotion](https://design.gaudi.site/docs/hooks/use-prefers-reduced-motion): Whether the reader asked to reduce motion.

Source: https://design.gaudi.site/docs/components/carousel (Markdown with example code: https://design.gaudi.site/docs/components/carousel.md)

---

# Direction

> Scopes text direction for Gaudi controls that need directional keyboard and placement behavior.

- Category: Core · Layout & Containers
- Import: `@gaudi/design-system/core/Direction` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Direction/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-direction--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { DirectionProvider } from '@gaudi/design-system/core/Direction';
```

## Usage

```jsx
import { DirectionProvider } from '@gaudi/design-system/core/Direction';

<DirectionProvider dir='rtl'><div dir='rtl'>{controls}</div></DirectionProvider>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-direction--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `dir / direction` | `ltr \| rtl` | `inherited` | no | Direction for descendant controls; direction takes precedence when both are provided. |
| `children` | `ReactNode` | — | no | Controls that consume the direction context. |
| `useDirection(localDirection?)` (helper) | `(ltr \| rtl) => ltr \| rtl` | `inherited` | no | Read the local override or nearest provider direction. |

## Accessibility

Set the same direction on the surrounding DOM so text flow and control behavior agree. Nested providers may override the inherited direction.

## Related

- [Accordion](https://design.gaudi.site/docs/components/accordion): Rich disclosure for FAQs, settings, member directories, nested help, and guided setup.
- [Carousel](https://design.gaudi.site/docs/components/carousel): Carousel renders standard feature slides and editorial card rails.
- [Resizable](https://design.gaudi.site/docs/components/resizable): Resizable panes with accessible separators and bounded panel sizes.
- [ScrollArea](https://design.gaudi.site/docs/components/scroll-area): Contained scrolling with themed scrollbars and optional smooth wheel motion for article reading.
- [Sortable](https://design.gaudi.site/docs/components/sortable): Reorder lists and grids with drag handles, keyboard controls and cancellation.

Source: https://design.gaudi.site/docs/components/direction (Markdown with example code: https://design.gaudi.site/docs/components/direction.md)

---

# Resizable

> Resizable panes with accessible separators and bounded panel sizes.

- Category: Core · Layout & Containers
- Import: `@gaudi/design-system/core/Resizable` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Resizable/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-resizable--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ResizableHandle } from '@gaudi/design-system/core/Resizable';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/resizable-editor-workspace.json`.

## Usage

```jsx
import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '@gaudi/design-system/core/Resizable';

<ResizablePanelGroup orientation='horizontal'>
  <ResizablePanel defaultSize='30%'>{navigation}</ResizablePanel>
  <ResizableHandle aria-label='Resize navigation' />
  <ResizablePanel>{content}</ResizablePanel>
</ResizablePanelGroup>
```

## Examples

### Editor workspace

Registry: `npx shadcn@latest add https://design.gaudi.site/r/resizable-editor-workspace.json`

### Handle styles

Registry: `npx shadcn@latest add https://design.gaudi.site/r/resizable-handles.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ResizablePanelGroup.orientation` | `horizontal \| vertical` | `Required` | no | Direction in which panels are arranged. |
| `ResizablePanelGroup.onLayoutChanged` | `function` | — | no | Observe committed panel sizes. |
| `ResizablePanel.defaultSize / minSize / maxSize` | `number \| string` | — | no | Initial size and bounds accepted by react-resizable-panels. |
| `ResizablePanel.collapsible` | `boolean` | `false` | no | Allow a panel to collapse. |
| `ResizableHandle.withHandle` | `boolean` | `false` | no | Show a visible grip. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Separators support keyboard resizing. Keep minimum sizes large enough for panel content and retain a way to restore collapsed panes.

## Related

- [Direction](https://design.gaudi.site/docs/components/direction): Scopes text direction for Gaudi controls that need directional keyboard and placement behavior.
- [Accordion](https://design.gaudi.site/docs/components/accordion): Rich disclosure for FAQs, settings, member directories, nested help, and guided setup.
- [Carousel](https://design.gaudi.site/docs/components/carousel): Carousel renders standard feature slides and editorial card rails.
- [ScrollArea](https://design.gaudi.site/docs/components/scroll-area): Contained scrolling with themed scrollbars and optional smooth wheel motion for article reading.
- [Sortable](https://design.gaudi.site/docs/components/sortable): Reorder lists and grids with drag handles, keyboard controls and cancellation.

Source: https://design.gaudi.site/docs/components/resizable (Markdown with example code: https://design.gaudi.site/docs/components/resizable.md)

---

# ScrollArea

> Contained scrolling with themed scrollbars and optional smooth wheel motion for article reading.

- Category: Core · Layout & Containers
- Import: `@gaudi/design-system/core/ScrollArea` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/ScrollArea/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-scrollarea--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ScrollArea } from '@gaudi/design-system/core/ScrollArea';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/scroll-area-horizontal-gallery.json`.

## Usage

```jsx
import { ScrollArea } from '@gaudi/design-system/core/ScrollArea';

<ScrollArea smooth className='h-[32rem]' aria-label='Blog post content'>{article}</ScrollArea>
```

## Examples

### Horizontal gallery

Registry: `npx shadcn@latest add https://design.gaudi.site/r/scroll-area-horizontal-gallery.json`

### Wide table

Registry: `npx shadcn@latest add https://design.gaudi.site/r/scroll-area-wide-table.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `type` | `auto \| always \| scroll \| hover` | `hover` | no | Scrollbar visibility behavior. |
| `smooth` | `boolean` | `false` | no | Enhances vertical mouse-wheel scrolling with Lenis. Touch, keyboard, focus, links and reduced motion retain native behavior. The engine loads only when requested and pauses when the area or page is hidden. |
| `viewportRef` | `Ref<HTMLElement>` | — | no | Ref to the actual scrolling viewport. Share with ReadingIndicator.targetRef, a heading observer or native scrollTo calls. The ordinary ref still points to the outer root. |
| `scrollbarClassName` | `{ track?: string, thumb?: string }` | — | no | Classes for the built-in vertical scrollbar track and thumb, using Gaudi tokens. |
| `ScrollBar.orientation` | `horizontal \| vertical` | `vertical` | no | Axis of an additional scrollbar. Smooth wheel motion applies to the vertical viewport; horizontal regions remain native. |
| `ScrollBar.thumbClassName` | `string` | — | no | Classes for a separately composed scrollbar thumb. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `type`: `auto`, `always`, `scroll`, `hover`

## Accessibility

Give the viewport a useful accessible name using aria-label or aria-labelledby. Constrain the area dimensions and retain keyboard access. Reduced motion skips the smooth engine entirely; native scrolling remains available before hydration or if the enhancement cannot load. Nested scrollable content keeps its own wheel behavior.

## Notes

- Blog migration decision: use ScrollArea with smooth enabled as the main area hosting blog post content. Keep one article viewport, and pass its viewportRef to reading progress and heading navigation. Adapt the consuming layout, table of contents and route scroll restoration during that migration; this component does not migrate the blog shell itself.
- Smooth scrolling is an enhancement to the existing ScrollArea owner, not a second global page scroller. Bound the height, including min-h-0 when using a flex layout. Avoid stacking a second document-wide smoothing engine around it.
- Native fragment links, keyboard scrolling, focus, text selection and touch retain browser behavior. Pointer and keyboard intent interrupt any pending wheel inertia. Code, tables and other nested scroll regions scroll natively.
- Theme the track and thumb through scrollbarClassName. Keep enough contrast and an adequate hit area. Use ScrollBar with orientation="horizontal" for content that deliberately overflows horizontally.
- Inspired by Shadix UI Smooth Scroll Area. Gaudi composes its existing Radix viewport with the packaged Lenis engine; it does not load remote scripts or copy registry source.

## Related

- [Pointer](https://design.gaudi.site/docs/components/pointer): A pointer effect scoped to its container, with direct, spring and lazy tracking, hover feedback, and native input fallbacks.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.
- [ReadingIndicator](https://design.gaudi.site/docs/components/reading-indicator): Reading progress as a classic top bar, a vertical ruler with a moving percentage, or a movable circular meter.
- [Table](https://design.gaudi.site/docs/mdx/table): Semantic article tables with contained horizontal scrolling.

Source: https://design.gaudi.site/docs/components/scroll-area (Markdown with example code: https://design.gaudi.site/docs/components/scroll-area.md)

---

# Sortable

> Reorder lists and grids with drag handles, keyboard controls and cancellation.

- Category: Core · Layout & Containers
- Import: `@gaudi/design-system/core/Sortable` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Sortable/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-sortable--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Sortable } from '@gaudi/design-system/core/Sortable';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/sortable-media-grid.json`.

## Usage

```jsx
import { Sortable, SortableItem, SortableItemHandle } from '@gaudi/design-system/core/Sortable';

<Sortable value={ids} onValueChange={setIds}>
  {ids.map(id => <SortableItem key={id} value={id}>
    <SortableItemHandle aria-label={`Reorder ${labels[id]}`} />
    {labels[id]}
  </SortableItem>)}
</Sortable>
```

## Examples

### Media grid

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sortable-media-grid.json`

### Nested lists

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sortable-nested.json`

### Persisted order

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sortable-persisted.json`

### List with row controls

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sortable-row-controls.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value` | `Array` | — | no | Controlled item order. |
| `onValueChange` | `function` | — | no | Controlled item order. |
| `getItemValue` | `(item) => string` | — | no | Stable unique identity for each item. |
| `strategy` | `vertical \| horizontal \| grid` | `vertical` | no | Layout-specific sorting strategy. |
| `onMove / onValueCommit` | `function` | — | no | Move notification and committed order. |
| `onDragStart / onDragEnd / onDragCancel` | `function` | — | no | Drag lifecycle callbacks. |
| `accessibility / modifiers` | `DndContext props` | — | no | Announcements, instructions and movement constraints. |
| `SortableItem.disabled` | `boolean` | `false` | no | Locks the item in place; its handle dims and shows a not-allowed cursor. |
| `SortableOverlay.children` | `ReactNode \| ({ value }) => ReactNode` | `Copy of the active item` | no | Custom content for the single drag overlay. Place it directly inside Sortable. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `strategy`: `vertical`, `horizontal`, `grid`

## Accessibility

Keep a keyboard-operable handle and announce moves. The application owns saving and restoring the last committed order.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Toast](https://design.gaudi.site/docs/components/toast): Transient feedback for completed actions, errors and recoverable background work.
- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [useTimeout](https://design.gaudi.site/docs/hooks/use-timeout): A one-off timer with reset and clear.

Source: https://design.gaudi.site/docs/components/sortable (Markdown with example code: https://design.gaudi.site/docs/components/sortable.md)

---

# Attachment

> File attachments with metadata, previews, actions and upload states.

- Category: Core · Messaging
- Import: `@gaudi/design-system/core/Attachment` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Attachment/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-attachment--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Attachment } from '@gaudi/design-system/core/Attachment';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/attachment-assistant-reply.json`.

## Usage

```jsx
import { Attachment, AttachmentMedia, AttachmentContent, AttachmentTitle, AttachmentDescription } from '@gaudi/design-system/core/Attachment';

const file = { name: 'report.pdf', type: 'application/pdf', description: 'PDF · ready to send' };

<Attachment>
  <AttachmentMedia file={file} />
  <AttachmentContent>
    <AttachmentTitle>{file.name}</AttachmentTitle>
    <AttachmentDescription>{file.description}</AttachmentDescription>
  </AttachmentContent>
</Attachment>
```

## Examples

### Files in an assistant reply

Registry: `npx shadcn@latest add https://design.gaudi.site/r/attachment-assistant-reply.json`

### Composer tray with removable files

Registry: `npx shadcn@latest add https://design.gaudi.site/r/attachment-composer-tray.json`

### File picker that fills a tray

Registry: `npx shadcn@latest add https://design.gaudi.site/r/attachment-file-picker.json`

### Image thumbnail strip

Registry: `npx shadcn@latest add https://design.gaudi.site/r/attachment-thumbnail-strip.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `state` | `idle \| uploading \| processing \| done \| error` | `done` | no | State exposed to the attachment styling. |
| `size` | `default \| sm \| xs` | `default` | no | Density of the attachment row. |
| `orientation` | `horizontal \| vertical` | `horizontal` | no | Arrangement of media, details and actions. |
| `AttachmentMedia.variant` | `icon \| image` | `automatic with file, otherwise icon` | no | Presentation of the media slot; icon suppresses a supplied thumbnail. |
| `AttachmentMedia.file` | `{ name, type?, mediaType?, fileType?, kind?, previewUrl? }` | — | no | Shared file-type icons for image, audio, video, document, code, spreadsheet, archive and link. A host-provided thumbnail falls back to its type icon if loading fails; explicit children take precedence. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `idle`, `uploading`, `processing`, `done`, `error`
- `size`: `default`, `sm`, `xs`
- `orientation`: `horizontal`, `vertical`

## Accessibility

Use descriptive filenames and name every icon action. Keep retry and remove actions available when an upload fails.

## Related

- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [FileUpload](https://design.gaudi.site/docs/components/file-upload): Choose or drop attachments with validation, upload progress and recovery actions.

Source: https://design.gaudi.site/docs/components/attachment (Markdown with example code: https://design.gaudi.site/docs/components/attachment.md)

---

# Banner

> Banner renders a compact announcement strip.

- Category: Core · Feedback & States
- Import: `@gaudi/design-system/core/Banner` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Banner/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-banner--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Banner from '@gaudi/design-system/core/Banner';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/alert-dismissible.json`.

## Usage

```jsx
import { Banner } from '@gaudi/design-system';

<Banner title='Now published' href='/blog'>
  New essays and project notes are available.
</Banner>
```

## Examples

### Alert: Dismissible notices

Registry: `npx shadcn@latest add https://design.gaudi.site/r/alert-dismissible.json`

### Alert: Message notification

Registry: `npx shadcn@latest add https://design.gaudi.site/r/alert-message-notice.json`

### Alert: Actions and rich content

Registry: `npx shadcn@latest add https://design.gaudi.site/r/alert-rich-actions.json`

### Alert: Service status summary

Registry: `npx shadcn@latest add https://design.gaudi.site/r/alert-service-status.json`

### Alert: Variants

Registry: `npx shadcn@latest add https://design.gaudi.site/r/alert-variants.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `title` | `ReactNode` | — | no | Optional bold leading text. |
| `children` | `ReactNode` | — | no | Announcement body copy. |
| `href` | `string` | — | no | Turns the banner copy into a navigation link. |
| `ariaLabel` | `string` | `Rendered content` | no | Optional accessible-name override for linked banners. |
| `size` | `xs \| sm \| md \| lg` | `md` | no | Controls vertical and horizontal padding. |
| `tone` | `neutral \| accent \| info \| success \| warning \| danger \| attention \| discovery` | `neutral` | no | Semantic tone. Hue names (blue, green, amber…) still resolve to these. |
| `variant` | `solid \| soft \| outline` | `soft` | no | Visual treatment. |
| `className` | `string` | — | no | Root class override. |
| `classNames` | `{ root, body, action }` | — | no | Slot-level class overrides. |

### Variants

- `size`: `xs`, `sm`, `md`, `lg`
- `tone`: `neutral`, `accent`, `info`, `success`, `warning`, `danger`, `attention`, `discovery`
- `variant`: `solid`, `soft`, `outline`

## Accessibility

Static banners use status semantics. Linked banners derive their accessible name from the rendered title and body, including rich content; ariaLabel provides an explicit override.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [EmptyState](https://design.gaudi.site/docs/components/empty-state): Explain empty collections, unavailable results and the next useful action.
- [Skeleton](https://design.gaudi.site/docs/components/skeleton): Skeleton renders non-semantic loading placeholders on the theme border token, so blocks read clearly in light and dark themes.

Source: https://design.gaudi.site/docs/components/banner (Markdown with example code: https://design.gaudi.site/docs/components/banner.md)

---

# EmptyState

> Explain empty collections, unavailable results and the next useful action.

- Category: Core · Feedback & States
- Import: `@gaudi/design-system/core/EmptyState` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/EmptyState/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-emptystate--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import EmptyState from '@gaudi/design-system/core/EmptyState';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/empty-illustrated.json`.

## Usage

```jsx
import EmptyState from '@gaudi/design-system/core/EmptyState';
import Button from '@gaudi/design-system/core/Button';

<EmptyState title='No projects yet' description='Create a project to start organizing your work.'
  actions={<Button onClick={createProject}>Create project</Button>} />
```

## Examples

### Illustrated empty states

Registry: `npx shadcn@latest add https://design.gaudi.site/r/empty-illustrated.json`

### Inside a card

Registry: `npx shadcn@latest add https://design.gaudi.site/r/empty-in-card.json`

### Not found with search

Registry: `npx shadcn@latest add https://design.gaudi.site/r/empty-not-found.json`

### Surfaces and actions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/empty-surfaces-actions.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `title` | `ReactNode` | — | no | Short statement of the empty state. |
| `description` | `ReactNode` | — | no | Cause or next step. |
| `titleAs` | `div \| h2 \| h3 \| h4 \| h5 \| h6` | `div` | no | Renders the title as a heading at the level that fits the page outline; the look stays the same. EmptyTitle takes the same value as `as`. |
| `icon` | `ReactNode` | — | no | Decorative illustration or icon. |
| `actions` | `ReactNode` | — | no | Create, reset or retry actions. |
| `compact` | `boolean` | `false` | no | Reduced spacing inside small panels. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `titleAs`: `div`, `h2`, `h3`, `h4`, `h5`, `h6`

## Accessibility

The title and description carry the meaning. Give actions specific names and avoid announcing a stable empty state repeatedly.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Kbd](https://design.gaudi.site/docs/components/kbd): Kbd renders keyboard keys and multi-key shortcuts.
- [useHotkey](https://design.gaudi.site/docs/hooks/use-hotkey): Keyboard shortcuts with platform-aware mod keys.
- [FileUpload](https://design.gaudi.site/docs/components/file-upload): Choose or drop attachments with validation, upload progress and recovery actions.

Source: https://design.gaudi.site/docs/components/empty-state (Markdown with example code: https://design.gaudi.site/docs/components/empty-state.md)

---

# Skeleton

> Skeleton renders non-semantic loading placeholders on the theme border token, so blocks read clearly in light and dark themes.

Shimmer is the text counterpart: a highlight that sweeps across a label such as Thinking… while work is in progress.

- Category: Core · Feedback & States
- Import: `@gaudi/design-system/core/Skeleton` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Skeleton/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-skeleton--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Skeleton from '@gaudi/design-system/core/Skeleton';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/skeleton-avatar-list.json`.

## Usage

```jsx
import { Shimmer, Skeleton } from '@gaudi/design-system';

<>
<Skeleton className='h-4 w-40' />
<p role='status'><Shimmer>Searching the web…</Shimmer></p>
</>
```

## Examples

### List with avatars and actions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/skeleton-avatar-list.json`

### Chat messages

Registry: `npx shadcn@latest add https://design.gaudi.site/r/skeleton-chat.json`

### Dashboard stats and table

Registry: `npx shadcn@latest add https://design.gaudi.site/r/skeleton-dashboard.json`

### Form

Registry: `npx shadcn@latest add https://design.gaudi.site/r/skeleton-form.json`

### Media card

Registry: `npx shadcn@latest add https://design.gaudi.site/r/skeleton-media-card.json`

### Profile page

Registry: `npx shadcn@latest add https://design.gaudi.site/r/skeleton-profile.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `className` | `string` | — | no | Defines shape, width, height, radius, and layout placement. |
| `Shimmer.children` | `ReactNode` | — | no | Text that shimmers while work is in progress, such as Thinking… or Searching the web…; it stays real, readable text. |
| `Shimmer.active` | `boolean` | `true` | no | Run or rest the sweep, seconds per sweep, and band width in pixels per character. |
| `duration` | `number` | `2` | no | Run or rest the sweep, seconds per sweep, and band width in pixels per character. |
| `spread` | `number` | `2` | no | Run or rest the sweep, seconds per sweep, and band width in pixels per character. |
| `Shimmer.as` | `ElementType` | `span` | no | Element to render, such as p or h3. |

## Accessibility

Skeleton is aria-hidden and should be paired with loading text or a labelled busy region when content loading needs announcement. Shimmer keeps its words as real text; put it in a status region when the change should be announced. Both hold still for reduced motion.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Separator](https://design.gaudi.site/docs/components/separator): Separate related content with a horizontal or vertical rule.
- [Banner](https://design.gaudi.site/docs/components/banner): Banner renders a compact announcement strip.
- [EmptyState](https://design.gaudi.site/docs/components/empty-state): Explain empty collections, unavailable results and the next useful action.

Source: https://design.gaudi.site/docs/components/skeleton (Markdown with example code: https://design.gaudi.site/docs/components/skeleton.md)

---

# Breadcrumb

> Breadcrumb renders hierarchical page trails for navigation context.

- Category: Core · Navigation
- Import: `@gaudi/design-system/core/Breadcrumb` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Breadcrumb/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-breadcrumb--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Breadcrumb } from '@gaudi/design-system/core/Breadcrumb';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/breadcrumb-collapsed-path.json`.

## Usage

```jsx
import { BreadcrumbTrail } from '@gaudi/design-system';

<BreadcrumbTrail
  items={[
    { href: '/', label: 'Home' },
    { href: '/blog', label: 'Blog' },
    { current: true, label: 'Design Systems' },
  ]}
/>
```

## Examples

### Collapsed path with menu

Registry: `npx shadcn@latest add https://design.gaudi.site/r/breadcrumb-collapsed-path.json`

### Contained and button styles

Registry: `npx shadcn@latest add https://design.gaudi.site/r/breadcrumb-contained-buttons.json`

### Icons, badges and avatars

Registry: `npx shadcn@latest add https://design.gaudi.site/r/breadcrumb-icons-avatars.json`

### Separators

Registry: `npx shadcn@latest add https://design.gaudi.site/r/breadcrumb-separators.json`

### Workspace, user and document

Registry: `npx shadcn@latest add https://design.gaudi.site/r/breadcrumb-workspace-path.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `items` | `Array<{ href, label, current }>` | `[]` | no | Convenience API for a complete breadcrumb trail. |
| `label` | `string` | `Breadcrumb` | no | Accessible name for the nav landmark. |
| `className` | `string` | — | no | Root or slot class override depending on the exported primitive. |
| `children` | `ReactNode` | — | no | Composition API for custom Breadcrumb/List/Item/Link/Page layouts. |
| `href` | `string` | — | no | Link target for ancestor pages. |
| `current` | `boolean` | `false` | no | Marks the active page with aria-current. |

## Accessibility

Breadcrumb renders a nav landmark, ordered list, real links for ancestors, and aria-current on the current page.

## Related

- [Item](https://design.gaudi.site/docs/components/item): Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.
- [Link](https://design.gaudi.site/docs/components/link): Link centralizes navigation semantics for internal, anchor, and external links.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.

Source: https://design.gaudi.site/docs/components/breadcrumb (Markdown with example code: https://design.gaudi.site/docs/components/breadcrumb.md)

---

# FloatingMenu

> A compact, inverted pill of destinations that floats over the page once the reader scrolls away from the header, with an optional Back to top button.

LayoutContainer renders it for the site; pass targetRef and position sticky to use it inside a scroll container.

- Category: Core · Navigation
- Import: `@gaudi/design-system/core/FloatingMenu` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/FloatingMenu/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-floatingmenu--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import FloatingMenu from '@gaudi/design-system/core/FloatingMenu';
```

## Usage

```jsx
import { FloatingMenu } from '@gaudi/design-system';

// Fixed over the window; links default to SiteConfig navigation.links.
<FloatingMenu links={[{ href: '/blog', title: 'Blog' }, { href: '/about', title: 'About' }]} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-floatingmenu--playground)
- [Reveal Past Threshold](https://storybook.gaudi.site/index.html?path=/story/core-floatingmenu--reveal-past-threshold)
- [With Call To Action](https://storybook.gaudi.site/index.html?path=/story/core-floatingmenu--with-call-to-action)
- [Keyboard Reveal](https://storybook.gaudi.site/index.html?path=/story/core-floatingmenu--keyboard-reveal)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `links` | `Array<{ href, title, active? }>` | `SiteConfig navigation.links` | no | Destinations; the most specific match for the current path gets aria-current. |
| `revealOn` | `scroll-up \| scroll` | `scroll-up` | no | Show while scrolling back up past the threshold, or whenever past it. |
| `threshold` | `number` | `50` | no | Scroll offset in pixels before the pill can show. |
| `targetRef` | `RefObject<HTMLElement>` | `window` | no | Scroll container to observe and scroll back to the top. |
| `position` | `fixed \| sticky` | `fixed` | no | fixed floats over the viewport; sticky pins it to the top of a scroll container (render it as the first child). |
| `actions` | `ReactNode` | — | no | Extra controls after the links, such as a call to action. |
| `backToTop` | `boolean` | `true` | no | Show the Back to top button. |
| `currentPath` | `string` | `Next.js pathname` | no | Path used to mark the current link. |
| `label` | `string` | `Quick navigation` | no | Accessible name of the navigation landmark. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `revealOn`: `scroll-up`, `scroll`
- `position`: `fixed`, `sticky`

## Accessibility

A labelled navigation landmark that stays in the tab order while hidden; focusing it reveals it. The current link has aria-current="page". Reduced motion removes the slide and makes Back to top jump. On phones the links scroll inside the pill and Back to top collapses to its icon, so the page never overflows.

## Related

- [LayoutContainer](https://design.gaudi.site/docs/layout/layout-container): Async server layout that composes theme context, navigation, a skip link, article content, footer, and host-provided structured data.
- [Breadcrumb](https://design.gaudi.site/docs/components/breadcrumb): Breadcrumb renders hierarchical page trails for navigation context.
- [NavigationMenu](https://design.gaudi.site/docs/components/navigation-menu): NavigationMenu renders grouped site navigation with dropdown panels for categories, sections, and related destinations.
- [Pagination](https://design.gaudi.site/docs/components/pagination): Pagination renders blog-style previous/status/next navigation.
- [Scrollspy](https://design.gaudi.site/docs/components/scrollspy): Track the visible section and navigate a long document using anchor links.
- [Stepper](https://design.gaudi.site/docs/components/stepper): Show progress through a sequence of labelled steps.

Source: https://design.gaudi.site/docs/components/floating-menu (Markdown with example code: https://design.gaudi.site/docs/components/floating-menu.md)

---

# NavigationMenu

> NavigationMenu renders grouped site navigation with dropdown panels for categories, sections, and related destinations.

- Category: Core · Navigation
- Import: `@gaudi/design-system/core/NavigationMenu` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/NavigationMenu/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-navigationmenu--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { NavigationMenu } from '@gaudi/design-system/core/NavigationMenu';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/navigation-menu-blog-recent-posts.json`.

## Usage

```jsx
import { NavigationMenu, NavigationMenuDropdown, NavigationMenuLink, NavigationMenuList, NavigationMenuPanel } from '@gaudi/design-system';

<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuLink href='' active>Blog</NavigationMenuLink>
    <NavigationMenuDropdown label='Categories' width='xl'>
      <NavigationMenuPanel columns={2}>
        <NavigationMenuLink href='' variant='panel' description='Knowledge graphs, semantic web, and linked data.'>
          Data
        </NavigationMenuLink>
        <NavigationMenuLink href='' variant='panel' description='Implementation notes and developer tooling.'>
          Engineering
        </NavigationMenuLink>
      </NavigationMenuPanel>
    </NavigationMenuDropdown>
  </NavigationMenuList>
</NavigationMenu>
```

## Examples

### Blog menu with recent posts

Registry: `npx shadcn@latest add https://design.gaudi.site/r/navigation-menu-blog-recent-posts.json`

### Site header menu

Registry: `npx shadcn@latest add https://design.gaudi.site/r/navigation-menu-site-header.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | `Main navigation` | no | Accessible name for the nav landmark. |
| `children` | `ReactNode` | — | no | Composition API for list, items, links, and dropdowns. |
| `href` | `string` | — | no | NavigationMenuLink destination. |
| `active` | `boolean` | `false` | no | Marks a NavigationMenuLink as the current page with aria-current. |
| `variant` | `link \| panel` | `link` | no | Use link for top-level items and panel for dropdown card links. |
| `description` | `ReactNode` | — | no | Supporting copy shown in panel links. |
| `meta` | `ReactNode` | — | no | Small metadata line for panel links. |
| `trigger` | `ReactNode` | `label` | no | Custom dropdown trigger content. |
| `defaultOpen` | `boolean` | `false` | no | Initial uncontrolled dropdown state. Useful for demos and persistent nav panels. |
| `align` | `start \| center \| end` | `start` | no | Controls dropdown panel alignment. |
| `width` | `sm \| md \| lg \| xl \| 2xl` | `lg` | no | Controls dropdown panel width. |
| `aside` | `ReactNode` | — | no | NavigationMenuDropdown second block: turns the panel into two columns (children, then aside), stacked below sm. |
| `NavigationMenuAside.title` | `ReactNode` | — | no | Muted second column with a title that labels its group and an optional See all link. |
| `action` | `{ href, label } \| ReactNode` | — | no | Muted second column with a title that labels its group and an optional See all link. |
| `columns` | `1 \| 2 \| 3` | `2` | no | Responsive panel grid columns. |
| `panelClassName` | `string` | — | no | Dropdown panel class override. |
| `className` | `string` | — | no | Class override on each slot. |

### Variants

- `variant`: `link`, `panel`
- `align`: `start`, `center`, `end`
- `width`: `sm`, `md`, `lg`, `xl`, `2xl`
- `columns`: `1`, `2`, `3`

## Accessibility

NavigationMenu renders a nav landmark, real links, native dropdown buttons, aria-expanded triggers, Escape-to-close behavior, outside-click dismissal, and aria-current for active links.

## Related

- [Breadcrumb](https://design.gaudi.site/docs/components/breadcrumb): Breadcrumb renders hierarchical page trails for navigation context.
- [FloatingMenu](https://design.gaudi.site/docs/components/floating-menu): A compact, inverted pill of destinations that floats over the page once the reader scrolls away from the header, with an optional Back to top button.
- [Pagination](https://design.gaudi.site/docs/components/pagination): Pagination renders blog-style previous/status/next navigation.
- [Scrollspy](https://design.gaudi.site/docs/components/scrollspy): Track the visible section and navigate a long document using anchor links.
- [Stepper](https://design.gaudi.site/docs/components/stepper): Show progress through a sequence of labelled steps.
- [Tree](https://design.gaudi.site/docs/components/tree): Browse hierarchical content with expansion, selection, checkboxes and drag feedback.

Source: https://design.gaudi.site/docs/components/navigation-menu (Markdown with example code: https://design.gaudi.site/docs/components/navigation-menu.md)

---

# Pagination

> Pagination renders blog-style previous/status/next navigation.

Hovering or focusing the center status reveals direct page shortcuts.

- Category: Core · Navigation
- Import: `@gaudi/design-system/core/Pagination` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Pagination/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-pagination--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Pagination } from '@gaudi/design-system/core/Pagination';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/pagination-jump-to-page.json`.

## Usage

```jsx
import { PaginationBar } from '@gaudi/design-system';

<PaginationBar currentPage={1} totalPages={4} getHref={(page) => `?page=${page}`} />
```

## Examples

### Jump to a page

Registry: `npx shadcn@latest add https://design.gaudi.site/r/pagination-jump-to-page.json`

### Numbered page styles

Registry: `npx shadcn@latest add https://design.gaudi.site/r/pagination-numbered.json`

### Previous and next with page info

Registry: `npx shadcn@latest add https://design.gaudi.site/r/pagination-previous-next.json`

### Rows per page and range

Registry: `npx shadcn@latest add https://design.gaudi.site/r/pagination-rows-per-page.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `currentPage` | `number` | `1` | no | Active page number. |
| `totalPages` | `number` | `1` | no | Total page count. |
| `getHref` | `(page) => string` | `?page={page}` | no | Builds each page link URL. |
| `onPageChange` | `(page) => void` | — | no | Optional client-side page change handler for filtered lists. |
| `label` | `string` | `Pagination` | no | Accessible name for the pagination nav. |
| `previousLabel / nextLabel / ofLabel / shortcutsLabel` | `string` | `Previous / Next / of / Page shortcuts` | no | Translatable copy for the actions, the status and the shortcut list name. |
| `children` | `ReactNode` | — | no | Composition API for custom PaginationContent/Item/Link layouts. |
| `href` | `string` | `#` | no | Link destination for previous/next/link slots. |
| `disabled` | `boolean` | `false` | no | Disables previous/next or numbered controls. |
| `isActive` | `boolean` | `false` | no | Marks a page link as current. |
| `className` | `string` | — | no | Class override on each slot. |

## Accessibility

Pagination renders a nav landmark, disabled button states for unavailable directions, keyboard-focusable status shortcuts, and aria-current on active numbered links.

## Related

- [Item](https://design.gaudi.site/docs/components/item): Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.
- [Link](https://design.gaudi.site/docs/components/link): Link centralizes navigation semantics for internal, anchor, and external links.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [NumberField](https://design.gaudi.site/docs/components/number-field): Numeric entry with increment buttons, bounds, locale formatting and scrubbing.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.

Source: https://design.gaudi.site/docs/components/pagination (Markdown with example code: https://design.gaudi.site/docs/components/pagination.md)

---

# Scrollspy

> Track the visible section and navigate a long document using anchor links.

- Category: Core · Navigation
- Import: `@gaudi/design-system/core/Scrollspy` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Scrollspy/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-scrollspy--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Scrollspy } from '@gaudi/design-system/core/Scrollspy';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/scrollspy-top-navigation.json`.

## Usage

```jsx
import { Scrollspy } from '@gaudi/design-system/core/Scrollspy';
import Button from '@gaudi/design-system/core/Button';

<>
<Scrollspy targetRef={articleRef}>
  <Button data-scrollspy-anchor='overview'>Overview</Button>
  <Button data-scrollspy-anchor='details'>Details</Button>
</Scrollspy>
<div ref={articleRef}>
  <section id='overview'><h2>Overview</h2>{overview}</section>
  <section id='details'><h2>Details</h2>{details}</section>
</div>
</>
```

## Examples

### Top navigation

Registry: `npx shadcn@latest add https://design.gaudi.site/r/scrollspy-top-navigation.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `targetRef` | `RefObject<HTMLElement>` | — | no | Scrollable region or ScrollArea viewport to observe. Omit to track the document. |
| `onUpdate` | `(activeId: string \| null) => void` | — | no | Respond to the active section changing. |
| `offset` | `number` | `0` | no | Compensate for sticky headers. |
| `smooth` | `boolean` | `true` | no | Smooth scrolling when an anchor is clicked. |
| `history` | `boolean` | `false` | no | Opt in to rewriting the page URL hash to the active section. |
| `dataAttribute` | `string` | `scrollspy` | no | Attribute identifying tracked content. |
| `fallbackToFirst` | `boolean` | `true` | no | Mark the first section before it reaches the offset. Disable for an index whose first target appears later in the article; onUpdate then receives null before that target. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Use real links with valid targets. Preserve focus and allow navigation without motion.

## Related

- [ScrollArea](https://design.gaudi.site/docs/components/scroll-area): Contained scrolling with themed scrollbars and optional smooth wheel motion for article reading.
- [Breadcrumb](https://design.gaudi.site/docs/components/breadcrumb): Breadcrumb renders hierarchical page trails for navigation context.
- [FloatingMenu](https://design.gaudi.site/docs/components/floating-menu): A compact, inverted pill of destinations that floats over the page once the reader scrolls away from the header, with an optional Back to top button.
- [NavigationMenu](https://design.gaudi.site/docs/components/navigation-menu): NavigationMenu renders grouped site navigation with dropdown panels for categories, sections, and related destinations.
- [Pagination](https://design.gaudi.site/docs/components/pagination): Pagination renders blog-style previous/status/next navigation.
- [Stepper](https://design.gaudi.site/docs/components/stepper): Show progress through a sequence of labelled steps.

Source: https://design.gaudi.site/docs/components/scrollspy (Markdown with example code: https://design.gaudi.site/docs/components/scrollspy.md)

---

# Stepper

> Show progress through a sequence of labelled steps.

- Category: Core · Navigation
- Import: `@gaudi/design-system/core/Stepper` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Stepper/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-stepper--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Stepper from '@gaudi/design-system/core/Stepper';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/stepper-basic.json`.

## Usage

```jsx
import Stepper from '@gaudi/design-system/core/Stepper';

<Stepper steps={steps} activeStep={currentStep} />
```

## Examples

### Simple linear steps

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stepper-basic.json`

### Titles and descriptions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stepper-descriptions.json`

### Controlled with icons and badges

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stepper-icons-badges.json`

### Loading state

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stepper-loading.json`

### Progress bar

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stepper-progress-bar.json`

### Vertical orientation

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stepper-vertical.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `steps` | `Array<{ id, label, description? }>` | `[]` | no | Ordered steps with stable identities. |
| `activeStep` | `number` | `0` | no | Zero-based index of the current step. |
| `label` | `string` | `Progress` | no | Accessible name of the sequence. |
| `orientation` | `horizontal \| vertical` | `horizontal` | no | Row of steps, or a stacked list for a sidebar. |
| `onStepSelect` | `(index: number) => void` | — | no | Turns completed steps into buttons that go back to them. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `orientation`: `horizontal`, `vertical`

## Accessibility

The active item exposes aria-current="step" and completed items have readable status. Selectable completed steps are buttons named by their label.

## Notes

- The convenience Stepper displays progress. Use Wizard for validation and navigation; the compound Stepper exports support custom interactive flows.

## Related

- [Wizard](https://design.gaudi.site/docs/blocks/wizard): A guided multi-step form with validation, progress and recoverable completion.
- [Loader](https://design.gaudi.site/docs/components/loader): An accessible loading indicator with arcs, dots, expanding rings, and an indeterminate bar.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.

Source: https://design.gaudi.site/docs/components/stepper (Markdown with example code: https://design.gaudi.site/docs/components/stepper.md)

---

# Tree

> Browse hierarchical content with expansion, selection, checkboxes and drag feedback.

- Category: Core · Navigation
- Import: `@gaudi/design-system/core/Tree` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Tree/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-tree--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Tree } from '@gaudi/design-system/core/Tree';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/tree-display-options.json`.

## Usage

```jsx
import { Tree, TreeItem, TreeItemLabel } from '@gaudi/design-system/core/Tree';

// tree is the host's @headless-tree/react useTree instance.
<Tree tree={tree} aria-label='Project files'>
  {tree.getItems().map(item => <TreeItem key={item.getId()} item={item}>
    <TreeItemLabel>{item.getItemName()}</TreeItemLabel>
  </TreeItem>)}
</Tree>
```

## Examples

### Display options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/tree-display-options.json`

### Organization chart

Registry: `npx shadcn@latest add https://design.gaudi.site/r/tree-org-chart.json`

### Permission checkboxes

Registry: `npx shadcn@latest add https://design.gaudi.site/r/tree-permissions.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `tree` | `Headless Tree instance` | `Required` | no | State and feature configuration returned by useTree. |
| `indent` | `number` | `20` | no | Indentation per hierarchy level. |
| `toggleIconType` | `chevron \| plus-minus` | `chevron` | no | Expansion indicator style. |
| `TreeItem.item` | `Headless Tree item instance` | `Required` | no | Node state and event bindings. |
| `asChild` | `boolean` | `false` | no | Merge the root into a child element. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `toggleIconType`: `chevron`, `plus-minus`

## Accessibility

Headless Tree supplies hierarchical keyboard navigation. Keep node names stable and announce loading or failed child fetches.

## Related

- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.
- [Checkbox](https://design.gaudi.site/docs/components/checkbox): Checkbox renders a token-styled binary control.

Source: https://design.gaudi.site/docs/components/tree (Markdown with example code: https://design.gaudi.site/docs/components/tree.md)

---

# Calendar

> Date selection for single dates, ranges, bookings and localized calendars.

- Category: Core · Advanced Inputs
- Import: `@gaudi/design-system/core/Calendar` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Calendar/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-calendar--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Calendar } from '@gaudi/design-system/core/Calendar';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/calendar-appointment-booking.json`.

## Usage

```jsx
import { Calendar } from '@gaudi/design-system/core/Calendar';

<Calendar mode='single' selected={date} onSelect={setDate} />
```

## Examples

### Appointment booking

Registry: `npx shadcn@latest add https://design.gaudi.site/r/calendar-appointment-booking.json`

### Caption and navigation

Registry: `npx shadcn@latest add https://design.gaudi.site/r/calendar-caption-navigation.json`

### Daily pricing

Registry: `npx shadcn@latest add https://design.gaudi.site/r/calendar-daily-pricing.json`

### Event list

Registry: `npx shadcn@latest add https://design.gaudi.site/r/calendar-event-list.json`

### Date pickers in popovers

Registry: `npx shadcn@latest add https://design.gaudi.site/r/calendar-popover-pickers.json`

### Presets

Registry: `npx shadcn@latest add https://design.gaudi.site/r/calendar-presets.json`

### Selection and display options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/calendar-selection-options.json`

### Year and month grid

Registry: `npx shadcn@latest add https://design.gaudi.site/r/calendar-year-month-grid.json`

### Date selector: Opened from a field

Registry: `npx shadcn@latest add https://design.gaudi.site/r/date-selector-in-popover.json`

### Date selector: Options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/date-selector-options.json`

### Date selector: Translated, in a dialog

Registry: `npx shadcn@latest add https://design.gaudi.site/r/date-selector-translated-dialog.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `mode` | `single \| multiple \| range` | — | no | DayPicker selection mode. |
| `selected` | `Date \| Date[] \| DateRange` | — | no | Controlled selection and selection callback; the shape follows mode. |
| `onSelect` | `function` | — | no | Controlled selection and selection callback; the shape follows mode. |
| `disabled` | `Matcher \| Matcher[]` | — | no | Dates that cannot be selected. |
| `numberOfMonths` | `number` | `1` | no | Number of visible months. |
| `showOutsideDays` | `boolean` | `true` | no | Show dates outside the current month. |
| `captionLayout` | `label \| dropdown \| dropdown-months \| dropdown-years` | `label` | no | Month and year navigation controls. |
| `buttonVariant` | `Button variant` | `ghost` | no | Variant for calendar navigation buttons. |
| `locale` | `Locale` | — | no | Localized text and explicit DayPicker overrides. |
| `formatters` | `Formatters` | — | no | Localized text and explicit DayPicker overrides. |
| `components` | `CustomComponents` | — | no | Localized text and explicit DayPicker overrides. |
| `classNames` | `Partial<ClassNames>` | — | no | Classes for individual DayPicker slots. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `mode`: `single`, `multiple`, `range`
- `captionLayout`: `label`, `dropdown`, `dropdown-months`, `dropdown-years`

## Accessibility

DayPicker supplies grid navigation and selected-date announcements. Label the calendar and explain disabled dates.

## Notes

- Calendar forwards DayPicker props. Range selection uses `{ from, to }`; an incomplete range may have no end date.
- DateSelector is a separate compound export for period selection. Its examples include the complete value and localization shape.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Popover](https://design.gaudi.site/docs/components/popover): Popover renders compact positioned supporting content next to its trigger.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.

Source: https://design.gaudi.site/docs/components/calendar (Markdown with example code: https://design.gaudi.site/docs/components/calendar.md)

---

# Cascader

> Select items from hierarchical data using drill-down, columns, search and multiple selection.

- Category: Core · Advanced Inputs
- Import: `@gaudi/design-system/core/Cascader` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Cascader/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-cascader--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Cascader } from '@gaudi/design-system/core/Cascader';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/cascader-async-drill-down.json`.

## Usage

```jsx
import { Cascader, CascaderTrigger, CascaderValue, CascaderContent, CascaderList, CascaderItems } from '@gaudi/design-system/core/Cascader';

<Cascader items={categories} value={category} onValueChange={setCategory}>
  <CascaderTrigger aria-label='Category'><CascaderValue placeholder='Choose category' /></CascaderTrigger>
  <CascaderContent><CascaderList><CascaderItems /></CascaderList></CascaderContent>
</Cascader>
```

## Examples

### Async drill-down

Registry: `npx shadcn@latest add https://design.gaudi.site/r/cascader-async-drill-down.json`

### Avatars and role badges

Registry: `npx shadcn@latest add https://design.gaudi.site/r/cascader-avatars-roles.json`

### Columns mode

Registry: `npx shadcn@latest add https://design.gaudi.site/r/cascader-columns.json`

### Controlled state

Registry: `npx shadcn@latest add https://design.gaudi.site/r/cascader-controlled.json`

### Drill-down picker

Registry: `npx shadcn@latest add https://design.gaudi.site/r/cascader-drill-down.json`

### Form field

Registry: `npx shadcn@latest add https://design.gaudi.site/r/cascader-form-field.json`

### Multi-select with chips and presets

Registry: `npx shadcn@latest add https://design.gaudi.site/r/cascader-multi-select-chips.json`

### Cascading tree in a popover

Registry: `npx shadcn@latest add https://design.gaudi.site/r/cascader-popover-tree.json`

### Recently used groups

Registry: `npx shadcn@latest add https://design.gaudi.site/r/cascader-recent-groups.json`

### Translated labels

Registry: `npx shadcn@latest add https://design.gaudi.site/r/cascader-translated.json`

### Two-line rows with branch colours

Registry: `npx shadcn@latest add https://design.gaudi.site/r/cascader-two-line-rows.json`

### Virtualized rows

Registry: `npx shadcn@latest add https://design.gaudi.site/r/cascader-virtualized.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `items` | `Array<node>` | — | no | Root nodes; keep node values stable across loads. |
| `value / defaultValue / onValueChange` | `node value \| node value[] / function` | — | no | Controlled or initial selection and changes. |
| `multiple / cascade` | `boolean` | `false` | no | Enable multiple values or branch selection propagation. |
| `selectable` | `leaf \| all \| function` | `leaf` | no | Choose which nodes can be selected. |
| `mode` | `drill \| columns \| tree` | `drill` | no | Hierarchy navigation layout. |
| `getChildren / getParent / resolveValue` | `function` | — | no | Resolve remote children, ancestry and selected values. |
| `onSearch / onLoadError` | `function` | — | no | Remote search and load failure handling. |
| `disabled / readOnly / required / invalid` | `boolean` | — | no | Form and interaction state. |
| `name / form / id` | `string` | — | no | Form association and control identity. |
| `open / defaultOpen` | `boolean` | — | no | Controlled or initial open state. Use one state model for the lifetime of the component. |
| `onOpenChange` | `(open: boolean) => void` | — | no | Responds to open and close requests. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |

### Variants

- `mode`: `drill`, `columns`, `tree`

## Accessibility

Keep loading and failure messages in the panel. Keyboard users need a clear path back to a parent and a named trigger.

## Notes

- The asynchronous examples demonstrate cancellation, remote lookup and recovery without replacing the current selection.

## Related

- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Icon](https://design.gaudi.site/docs/components/icon): Static and interactive artwork from Gaudi’s centralized icon registry.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.

Source: https://design.gaudi.site/docs/components/cascader (Markdown with example code: https://design.gaudi.site/docs/components/cascader.md)

---

# ColorPicker

> An inline color canvas with hue, opacity, an eyedropper, and HEX/RGB/HSL/CSS editors.

- Category: Core · Advanced Inputs
- Import: `@gaudi/design-system/core/ColorPicker` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/ColorPicker/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-colorpicker--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ColorPicker } from '@gaudi/design-system/core/ColorPicker';
```

## Usage

```jsx
import { ColorPicker } from '@gaudi/design-system/core/ColorPicker';

<ColorPicker label='Accent color' value={color} onValueChange={setColor} swatches={['#2563eb', '#16a34a', '#e11d48']} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-colorpicker--playground)
- [Controlled](https://storybook.gaudi.site/index.html?path=/story/core-colorpicker--controlled)
- [Form and states](https://storybook.gaudi.site/index.html?path=/story/core-colorpicker--form-and-states)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value / defaultValue` | `string` | `#2563eb (defaultValue)` | no | Controlled or initial color: hex, rgb(), rgba(), hsl(), or hsla(). |
| `onValueChange` | `(value: string) => void` | — | no | Receives lowercase #rrggbb, or #rrggbbaa for a translucent color. |
| `defaultFormat` | `hex \| rgb \| hsl \| css` | `hex` | no | Initial editor format. The selector changes presentation without changing the color. |
| `showAlpha` | `boolean` | `true` | no | Show the opacity slider and percentage editor. Hiding them preserves existing alpha. |
| `showEyeDropper` | `boolean` | `true` | no | Show screen sampling, enabled when the browser supports the EyeDropper API in a secure context. |
| `label` | `string` | `Color` | no | Visible label and accessible name for every control. |
| `description` | `ReactNode` | — | no | Help text associated with the canvas keyboard controls and text editor. |
| `swatches` | `string[]` | `[]` | no | Optional color presets. Duplicate and invalid entries are omitted. |
| `disabled / readOnly` | `boolean` | `false` | no | Prevent editing. Read-only values allow format inspection; disabled values are omitted from forms. |
| `name / id` | `string` | — | no | Form field name and hex/CSS input ID. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `defaultFormat`: `hex`, `rgb`, `hsl`, `css`

## Accessibility

The canvas supports mouse, pen, and touch. Its two keyboard stops adjust saturation and brightness with visible thumb focus; hue and opacity also support arrows and Home/End. Presets expose selection with a checkmark and pressed state. Invalid drafts have associated errors.

## Notes

- Hex/CSS text commits on Enter or blur; Escape restores the current color. Invalid drafts never change the selection. RGB and HSL use Gaudi NumberField.
- With opacity controls shown, three- or six-digit hex preserves opacity; four- or eight-digit hex sets alpha explicitly. Screen sampling always preserves opacity. CSS names and other color spaces are unsupported.
- Sampling requires browser support and a secure context. Cancellation is silent. Changing the color, disabling the picker, making it read-only, or hiding/unmounting the eyedropper aborts pending sampling.
- Form reset clears drafts and restores the initial uncontrolled color, notifying only when it changes. Controlled values remain authoritative.
- Layout and interactions are inspired by the shadcn.io Color Picker; all controls use Gaudi styling and primitives.

## Related

- [NumberField](https://design.gaudi.site/docs/components/number-field): Numeric entry with increment buttons, bounds, locale formatting and scrubbing.
- [Calendar](https://design.gaudi.site/docs/components/calendar): Date selection for single dates, ranges, bookings and localized calendars.
- [Cascader](https://design.gaudi.site/docs/components/cascader): Select items from hierarchical data using drill-down, columns, search and multiple selection.
- [FileUpload](https://design.gaudi.site/docs/components/file-upload): Choose or drop attachments with validation, upload progress and recovery actions.
- [InputOtp](https://design.gaudi.site/docs/components/input-otp): One-time code entry with grouped slots, paste support and completion feedback.
- [PhoneInput](https://design.gaudi.site/docs/components/phone-input): International phone entry with country selection and formatted numbers.

Source: https://design.gaudi.site/docs/components/color-picker (Markdown with example code: https://design.gaudi.site/docs/components/color-picker.md)

---

# FileUpload

> Choose or drop attachments with validation, upload progress and recovery actions.

- Category: Core · Advanced Inputs
- Import: `@gaudi/design-system/core/FileUpload` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/FileUpload/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-fileupload--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import FileUpload from '@gaudi/design-system/core/FileUpload';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/file-upload-avatar.json`.

## Usage

```jsx
import FileUpload from '@gaudi/design-system/core/FileUpload';

<FileUpload label='Attachments' files={files} onFilesChange={setFiles} multiple
  accept='image/*,application/pdf' getFileState={getUploadState} onRetry={retryUpload} onCancel={cancelUpload} />
```

## Examples

### Profile photo picker

Registry: `npx shadcn@latest add https://design.gaudi.site/r/file-upload-avatar.json`

### Banner image for a page

Registry: `npx shadcn@latest add https://design.gaudi.site/r/file-upload-cover-image.json`

### Drag and drop

Registry: `npx shadcn@latest add https://design.gaudi.site/r/file-upload-drag-drop.json`

### Upload table with progress

Registry: `npx shadcn@latest add https://design.gaudi.site/r/file-upload-progress-table.json`

### Image gallery with sorting

Registry: `npx shadcn@latest add https://design.gaudi.site/r/file-upload-sortable-gallery.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `files` | `File[]` | — | no | Host-owned file selection. |
| `onFilesChange` | `(files: File[]) => void` | — | no | Host-owned file selection. |
| `label / description` | `string` | `Attachments / Choose files or drop them here.` | no | Visible label and instructions. |
| `accept` | `string` | — | no | Accepted MIME types or extensions. |
| `multiple` | `boolean` | `false` | no | Allow more than one file. |
| `maxFiles / maxSize` | `number` | — | no | Count and byte limits. |
| `onReject` | `function` | — | no | Receives rejected-file feedback. |
| `getFileState / onRetry / onCancel` | `function` | — | no | Read upload state and perform host-owned retry or cancellation. |
| `disabled` | `boolean` | — | no | Disable new selections. |
| `labels` | `Record<string, string>` | `{}` | no | Localized action and validation labels. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

The native file input remains keyboard accessible. Announce rejection reasons and retain valid files.

## Notes

- Selecting files does not upload them. The application owns storage, network requests and cancellation.

## Related

- [Banner](https://design.gaudi.site/docs/components/banner): Banner renders a compact announcement strip.
- [Table](https://design.gaudi.site/docs/mdx/table): Semantic article tables with contained horizontal scrolling.
- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Progress](https://design.gaudi.site/docs/components/progress): Determinate and indeterminate progress with a readable task label.
- [Sortable](https://design.gaudi.site/docs/components/sortable): Reorder lists and grids with drag handles, keyboard controls and cancellation.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.

Source: https://design.gaudi.site/docs/components/file-upload (Markdown with example code: https://design.gaudi.site/docs/components/file-upload.md)

---

# InputOtp

> One-time code entry with grouped slots, paste support and completion feedback.

- Category: Core · Advanced Inputs
- Import: `@gaudi/design-system/core/InputOtp` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/InputOtp/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-inputotp--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { InputOTP } from '@gaudi/design-system/core/InputOtp';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/input-otp-code-formats.json`.

## Usage

```jsx
import { InputOTP, InputOTPGroup, InputOTPSlot } from '@gaudi/design-system/core/InputOtp';

<InputOTP maxLength={6} aria-label='Verification code' value={code} onChange={setCode}>
  <InputOTPGroup>{Array.from({ length: 6 }, (_, index) => <InputOTPSlot key={index} index={index} />)}</InputOTPGroup>
</InputOTP>
```

## Examples

### Code formats

Registry: `npx shadcn@latest add https://design.gaudi.site/r/input-otp-code-formats.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `maxLength` | `number` | `Required` | no | Number of characters accepted. |
| `value` | `string` | — | no | Controlled code entry. |
| `onChange` | `(value: string) => void` | — | no | Controlled code entry. |
| `onComplete` | `(value: string) => void` | — | no | Called when every slot is filled. |
| `pattern` | `string` | — | no | Allowed character pattern. |
| `disabled` | `boolean` | `false` | no | Dims every slot and blocks code entry. |
| `containerClassName` | `string` | — | no | Classes on the slot container. |
| `InputOTPSlot.index` | `number` | `Required` | no | Zero-based character index. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `Native input props / ref` (pass-through) | `InputHTMLAttributes<HTMLInputElement>` | — | no | Forwards value, defaultValue, onChange, disabled, required, name, autocomplete and ARIA attributes to the input. |

## Accessibility

The underlying input supports keyboard entry and paste. Label the complete code field and announce validation beside it.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Calendar](https://design.gaudi.site/docs/components/calendar): Date selection for single dates, ranges, bookings and localized calendars.
- [Cascader](https://design.gaudi.site/docs/components/cascader): Select items from hierarchical data using drill-down, columns, search and multiple selection.
- [ColorPicker](https://design.gaudi.site/docs/components/color-picker): An inline color canvas with hue, opacity, an eyedropper, and HEX/RGB/HSL/CSS editors.
- [FileUpload](https://design.gaudi.site/docs/components/file-upload): Choose or drop attachments with validation, upload progress and recovery actions.
- [NumberField](https://design.gaudi.site/docs/components/number-field): Numeric entry with increment buttons, bounds, locale formatting and scrubbing.

Source: https://design.gaudi.site/docs/components/input-otp (Markdown with example code: https://design.gaudi.site/docs/components/input-otp.md)

---

# NumberField

> Numeric entry with increment buttons, bounds, locale formatting and scrubbing.

- Category: Core · Advanced Inputs
- Import: `@gaudi/design-system/core/NumberField` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/NumberField/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-numberfield--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { NumberField } from '@gaudi/design-system/core/NumberField';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/number-field-button-layouts.json`.

## Usage

```jsx
import { NumberField, NumberFieldGroup, NumberFieldInput, NumberFieldDecrement, NumberFieldIncrement } from '@gaudi/design-system/core/NumberField';

<NumberField value={quantity} onValueChange={setQuantity} min={1}>
  <NumberFieldGroup><NumberFieldDecrement /><NumberFieldInput aria-label='Quantity' /><NumberFieldIncrement /></NumberFieldGroup>
</NumberField>
```

## Examples

### Button layouts

Registry: `npx shadcn@latest add https://design.gaudi.site/r/number-field-button-layouts.json`

### Form validation

Registry: `npx shadcn@latest add https://design.gaudi.site/r/number-field-validation.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value / defaultValue / onValueChange` | `number \| null / function` | — | no | Controlled or initial numeric value and change callback. |
| `min / max / step` | `number` | — | no | Numeric bounds and increment. |
| `size` | `sm \| default \| lg` | `default` | no | Shared size for input, group and buttons. |
| `format` | `Intl.NumberFormatOptions` | — | no | Number formatting and locale. |
| `locale` | `string` | — | no | Number formatting and locale. |
| `disabled / readOnly / required` | `boolean` | — | no | Interaction and form state. |
| `NumberFieldScrubArea.label` | `ReactNode` | — | no | Visible label associated with the generated input ID. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `size`: `sm`, `default`, `lg`

## Accessibility

Compose the input and increment/decrement parts inside NumberField. Base UI preserves spinbutton semantics and keyboard adjustment.

## Notes

- The text editor inherits InputConfigProvider. Set caretMode="native" or caretMode="smooth" on NumberFieldInput to override the provider. Numeric parsing, formatting, bounds and stepping stay with NumberField.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Banner](https://design.gaudi.site/docs/components/banner): Banner renders a compact announcement strip.
- [Toast](https://design.gaudi.site/docs/components/toast): Transient feedback for completed actions, errors and recoverable background work.

Source: https://design.gaudi.site/docs/components/number-field (Markdown with example code: https://design.gaudi.site/docs/components/number-field.md)

---

# PhoneInput

> International phone entry with country selection and formatted numbers.

- Category: Core · Advanced Inputs
- Import: `@gaudi/design-system/core/PhoneInput` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/PhoneInput/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-phoneinput--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { PhoneInput } from '@gaudi/design-system/core/PhoneInput';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/phone-input-field-states.json`.

## Usage

```jsx
import { PhoneInput } from '@gaudi/design-system/core/PhoneInput';

<PhoneInput aria-label='Phone number' value={phone} onChange={setPhone} defaultCountry='GB' />
```

## Examples

### Field states

Registry: `npx shadcn@latest add https://design.gaudi.site/r/phone-input-field-states.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value` | `string` | — | no | Phone number in international format. |
| `onChange` | `(value: string) => void` | — | no | Receives the entered number; cleared values are normalized to an empty string. |
| `defaultCountry` | `CountryCode` | — | no | Initial country when no international prefix is entered. |
| `variant` | `sm \| default \| lg` | `default` | no | Height of the country button and input. |
| `disabled / international` | `boolean` | — | no | Input availability and international number formatting. |
| `popupClassName / scrollAreaClassName` | `string` | — | no | Country menu and scrolling-region classes. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `variant`: `sm`, `default`, `lg`

## Accessibility

Associate a visible label with the input and name the country selector. The application owns phone verification and validity feedback.

## Related

- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Calendar](https://design.gaudi.site/docs/components/calendar): Date selection for single dates, ranges, bookings and localized calendars.
- [Cascader](https://design.gaudi.site/docs/components/cascader): Select items from hierarchical data using drill-down, columns, search and multiple selection.
- [ColorPicker](https://design.gaudi.site/docs/components/color-picker): An inline color canvas with hue, opacity, an eyedropper, and HEX/RGB/HSL/CSS editors.
- [FileUpload](https://design.gaudi.site/docs/components/file-upload): Choose or drop attachments with validation, upload progress and recovery actions.

Source: https://design.gaudi.site/docs/components/phone-input (Markdown with example code: https://design.gaudi.site/docs/components/phone-input.md)

---

# Questionnaire

> A sequence of form questions with selection, validation and progress.

- Category: Core · Advanced Inputs
- Import: `@gaudi/design-system/core/Questionnaire` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Questionnaire/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-questionnaire--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Questionnaire } from '@gaudi/design-system/core/Questionnaire';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/questionnaire-answer-types.json`.

## Usage

```jsx
import { Questionnaire, QuestionnaireItem, QuestionnaireTitle, QuestionnaireInput, QuestionnaireActions, QuestionnaireSubmit } from '@gaudi/design-system/core/Questionnaire';

<Questionnaire onSubmit={submitAnswers}>
  <QuestionnaireItem name='goal'>
    <QuestionnaireTitle>What would you like to achieve?</QuestionnaireTitle>
    <QuestionnaireInput placeholder='Your goal' />
  </QuestionnaireItem>
  <QuestionnaireActions><QuestionnaireSubmit>Submit</QuestionnaireSubmit></QuestionnaireActions>
</Questionnaire>
```

## Examples

### Answer types

Registry: `npx shadcn@latest add https://design.gaudi.site/r/questionnaire-answer-types.json`

### Conditional branch

Registry: `npx shadcn@latest add https://design.gaudi.site/r/questionnaire-conditional-branch.json`

### Cross-question validation

Registry: `npx shadcn@latest add https://design.gaudi.site/r/questionnaire-cross-validation.json`

### Guided setup

Registry: `npx shadcn@latest add https://design.gaudi.site/r/questionnaire-guided-setup.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `items` | `QuestionnaireItemDefinition[]` | — | no | Question identities and constraints. |
| `item / defaultItem / onItemChange` | `string / function` | — | no | Controlled or initial active question. |
| `onSubmit / onReset` | `FormEventHandler` | — | no | Native form submission and reset. |
| `shortcuts` | `QuestionnaireShortcutMode` | — | no | Keyboard shortcut mode. |
| `QuestionnaireItem.name` | `string` | `Required` | no | Question field name. |
| `QuestionnaireItem.multiple / required / invalid` | `boolean` | — | no | Selection and validation constraints. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Question titles render as legends. Keep validation beside the question and ensure Previous, Next and Submit have clear names.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.

Source: https://design.gaudi.site/docs/components/questionnaire (Markdown with example code: https://design.gaudi.site/docs/components/questionnaire.md)

---

# Rating

> Display a rating or let people select a score using labelled stars.

- Category: Core · Advanced Inputs
- Import: `@gaudi/design-system/core/Rating` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Rating/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-rating--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Rating } from '@gaudi/design-system/core/Rating';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/rating-display-options.json`.

## Usage

```jsx
import { Rating } from '@gaudi/design-system/core/Rating';

<Rating aria-label='Rate this article' value={rating} onValueChange={setRating} />
```

## Examples

### Display options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/rating-display-options.json`

### Emoji reactions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/rating-emoji-reactions.json`

### Review form

Registry: `npx shadcn@latest add https://design.gaudi.site/r/rating-review-form.json`

### Review summary

Registry: `npx shadcn@latest add https://design.gaudi.site/r/rating-review-summary.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `rating` | `number` | — | no | Current score. |
| `maxRating` | `number` | `5` | no | Maximum score. |
| `editable` | `boolean` | `false` | no | Enable score selection. |
| `onRatingChange` | `(rating: number) => void` | — | no | Receives a new score. |
| `showValue` | `boolean` | `false` | no | Display the numeric score. |
| `size` | `sm \| default \| lg` | `default` | no | Star size: sm 16px, default 20px, lg 24px. |
| `starClassName` | `string` | — | no | Class override applied to every star. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `size`: `sm`, `default`, `lg`

## Accessibility

Editable ratings expose keyboard-operable controls. Include enough text to explain the score and its range.

## Related

- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Toast](https://design.gaudi.site/docs/components/toast): Transient feedback for completed actions, errors and recoverable background work.
- [Progress](https://design.gaudi.site/docs/components/progress): Determinate and indeterminate progress with a readable task label.
- [Separator](https://design.gaudi.site/docs/components/separator): Separate related content with a horizontal or vertical rule.

Source: https://design.gaudi.site/docs/components/rating (Markdown with example code: https://design.gaudi.site/docs/components/rating.md)

---

# SignaturePad

> A composable signature input with pressure-aware SVG ink, undo and redo, native forms, saved previews, and image or JSON export.

- Category: Core · Advanced Inputs
- Import: `@gaudi/design-system/core/SignaturePad` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/SignaturePad/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-signaturepad--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { SignaturePad } from '@gaudi/design-system/core/SignaturePad';
```

## Usage

```jsx
import { SignaturePad, SignaturePadArea, SignaturePadGuide, SignaturePadPlaceholder, SignaturePadUndo, SignaturePadRedo, SignaturePadClear, SignaturePadSave } from '@gaudi/design-system/core/SignaturePad';

<SignaturePad name='signature' required onValueChange={setStrokes}>
  <SignaturePadArea aria-label='Recipient signature'>
    <SignaturePadGuide />
    <SignaturePadPlaceholder />
  </SignaturePadArea>
  <div className='flex flex-wrap gap-2'>
    <SignaturePadUndo />
    <SignaturePadRedo />
    <SignaturePadClear />
    <SignaturePadSave format='svg' onSave={handleSave} />
  </div>
</SignaturePad>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-signaturepad--playground)
- [Native Form](https://storybook.gaudi.site/index.html?path=/story/core-signaturepad--native-form)
- [Draw Or Type](https://storybook.gaudi.site/index.html?path=/story/core-signaturepad--draw-or-type)
- [Export Formats](https://storybook.gaudi.site/index.html?path=/story/core-signaturepad--export-formats)
- [Controlled And Stylus](https://storybook.gaudi.site/index.html?path=/story/core-signaturepad--controlled-and-stylus)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value / defaultValue / onValueChange` | `SignaturePadStroke[] / function` | `[]` | no | Controlled or initial strokes. A stroke is { points: [x, y, diameter][], color? }. Changes fire once per completed stroke or history action. |
| `disabled / readOnly / invalid` | `boolean` | `false` | no | Disabled prevents interaction and form submission; readOnly allows saving existing ink. Invalid marks the drawing area. |
| `name` | `string` | — | no | Native form field name, external form association, validation, and submission format. Reset restores defaultValue and clears history. |
| `form` | `string` | — | no | Native form field name, external form association, validation, and submission format. Reset restores defaultValue and clears history. |
| `required` | `boolean` | `false` | no | Native form field name, external form association, validation, and submission format. Reset restores defaultValue and clears history. |
| `format` | `svg \| png \| jpeg \| json` | `svg` | no | Native form field name, external form association, validation, and submission format. Reset restores defaultValue and clears history. |
| `color` | `CSS color` | `currentColor` | no | Optional ink color recorded per stroke; unset ink follows the theme. Export defaults to black. |
| `minWidth / maxWidth` | `number` | `0.8 / 3.2` | no | Minimum and maximum ink diameter in CSS pixels. Equal values produce a constant line. |
| `smoothing` | `number` | `0.5` | no | 0–1 smoothing; higher values soften the curve. |
| `sizing` | `auto \| pressure \| velocity` | `auto` | no | Auto reads pen pressure and uses speed for mouse or touch. |
| `pointerTypes` | `(mouse \| touch \| pen)[]` | `all` | no | Filter input devices, such as ["pen"] to ignore touch. |
| `onStrokeStart / onStrokeEnd` | `function` | — | no | Receive { pointerType } when drawing starts and the completed stroke when it ends. Cancelled strokes are discarded. |
| `apiRef` | `ref` | — | no | Access strokes, isEmpty, isDrawing, canUndo, canRedo, clear, undo, redo, focus, toSVG, toDataURL, toBlob, and serialize. |
| `useSignaturePad()` (helper) | `hook` | — | no | Access strokes, isEmpty, isDrawing, canUndo, canRedo, clear, undo, redo, focus, toSVG, toDataURL, toBlob, and serialize. |
| `labels` | `object` | `English labels` | no | Override drawing instructions, placeholder, state announcements, and default button labels. Area and Preview accept their own ARIA names. |
| `SignaturePadArea.variant` | `default \| muted \| ghost` | `default` | no | Drawing surface appearance. Root sizing and state props are shared with every part. |
| `SignaturePadControls.position` | `top-start \| top-end \| bottom-start \| bottom-end` | `top-end` | no | Pins controls inside the drawing surface; a regular flex row can place them outside. |
| `SignaturePadSave.format` | `format` | `png` | no | Serialize to a data URL or JSON and pass it to the host. Saving performs no download or upload itself. |
| `options` | `export options` | — | no | Serialize to a data URL or JSON and pass it to the host. Saving performs no download or upload itself. |
| `onSave` | `(value, strokes) => void` | — | no | Serialize to a data URL or JSON and pass it to the host. Saving performs no download or upload itself. |
| `SignaturePadPreview.strokes` | `strokes` | — | no | A standalone SVG preview cropped to its ink; aria-label names its purpose. |
| `padding` | `number` | `4` | no | A standalone SVG preview cropped to its ink; aria-label names its purpose. |
| `color` | `CSS color` | `currentColor` | no | A standalone SVG preview cropped to its ink; aria-label names its purpose. |
| `export options` (pass-through) | `object` | `padding 8; raster scale 2` | no | width and height set a fixed frame. Otherwise crop includes ink thickness and padding. background, color, scale, type, and quality configure output. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `format`: `svg`, `png`, `jpeg`, `json`
- `sizing`: `auto`, `pressure`, `velocity`

## Accessibility

Give the area a visible label and useful instructions. Drawing requires a pointer, so compose a typed-name alternative with Core Tabs and Input when the workflow needs keyboard-only entry. Undo/redo shortcuts apply only within the area, respect editable overlays and IME, and do not capture page shortcuts. Cancel a live stroke with Escape. Clear and exhausted history controls return focus to the area.

## Notes

- Compose SignaturePadArea inside SignaturePad; guide, placeholder, controls, and save actions are optional.
- Store the stroke array to reopen and edit a signature. A changed controlled value clears history; an equivalent deep copy preserves it.
- Applications own consent, document identity, validation policy, upload, persistence, and any signing audit trail.

## Related

- [Tabs](https://design.gaudi.site/docs/components/tabs): Switch between related panels with keyboard-accessible tab controls.
- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [Preview](https://design.gaudi.site/docs/mdx/preview): Preview renders inline link previews for markdown links transformed by the blog MDX pipeline.

Source: https://design.gaudi.site/docs/components/signature-pad (Markdown with example code: https://design.gaudi.site/docs/components/signature-pad.md)

---

# CodeBlock

> CodeBlock renders syntax-highlighted source with an optional header, copy button, line numbers, highlighted and focused lines, diffs, folding and line selection.

- Category: Core · Data Display
- Import: `@gaudi/design-system/core/CodeBlock` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/CodeBlock/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-codeblock--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { CodeBlock } from '@gaudi/design-system/core/CodeBlock';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/code-block-chat-references.json`.

## Usage

```jsx
import { CodeBlock, CodeBlockCopyButton, CodeBlockHeader, CodeBlockLanguage, CodeBlockTitle } from '@gaudi/design-system';

<CodeBlock code={code} language='typescript' showLineNumbers highlightedLines='3-5'>
  <CodeBlockHeader>
    <CodeBlockTitle>hooks/use-cart.ts</CodeBlockTitle>
    <CodeBlockLanguage />
    <CodeBlockCopyButton className='ml-auto' />
  </CodeBlockHeader>
</CodeBlock>
```

## Examples

### Quoted lines in a chat answer

Registry: `npx shadcn@latest add https://design.gaudi.site/r/code-block-chat-references.json`

### Diagnostics with fixes

Registry: `npx shadcn@latest add https://design.gaudi.site/r/code-block-diagnostics.json`

### Find within a long file

Registry: `npx shadcn@latest add https://design.gaudi.site/r/code-block-file-search.json`

### Long file with folding

Registry: `npx shadcn@latest add https://design.gaudi.site/r/code-block-folding.json`

### Line states

Registry: `npx shadcn@latest add https://design.gaudi.site/r/code-block-line-states.json`

### Code block options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/code-block-options.json`

### Patch review

Registry: `npx shadcn@latest add https://design.gaudi.site/r/code-block-patch-review.json`

### Streaming assistant reply

Registry: `npx shadcn@latest add https://design.gaudi.site/r/code-block-streaming-reply.json`

### Tabbed code

Registry: `npx shadcn@latest add https://design.gaudi.site/r/code-block-tabbed.json`

### Shell session with output

Registry: `npx shadcn@latest add https://design.gaudi.site/r/code-block-terminal-output.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `code` | `string` | — | no | Source text to render. |
| `language` | `string` | — | no | Grammar name or alias such as tsx, python, bash or sql. Unknown languages render as plain text. |
| `variant` | `default \| ghost` | `default` | no | default draws the bordered surface; ghost is transparent for use inside another frame. |
| `showLineNumbers` | `boolean` | `false` | no | Shows the line-number gutter. |
| `startLine` | `number` | `1` | no | First line number in the gutter. |
| `wrap / defaultWrap / onWrapChange` | `boolean / (wrap) => void` | `false` | no | Controlled or initial soft wrapping of long lines. |
| `highlightedLines` | `string \| number[]` | — | no | Lines to emphasise, as a spec like 3-5,9 or an array. |
| `focusedLines` | `string \| number[]` | — | no | Lines kept sharp while the rest are dimmed. |
| `maxLines` | `number` | — | no | Collapses longer code to this many lines; add CodeBlockExpandButton to reveal the rest. |
| `diff` | `boolean \| diff options` | — | no | Marks added and removed lines. |
| `themes` | `{ light, dark }` | `github-light / github-dark` | no | Shiki themes per colour scheme; css-variables reads --code-token-* design tokens. |
| `foldable / selectable` | `boolean` | `false` | no | Enables fold regions and gutter line selection. |
| `children` | `ReactNode` | — | no | Header and action parts: CodeBlockHeader, CodeBlockTitle, CodeBlockLanguage, CodeBlockCopyButton, CodeBlockWrapToggle, CodeBlockExpandButton, CodeBlockDownloadButton. |
| `className` | `string` | — | no | Root class override. |

### Variants

- `variant`: `default`, `ghost`

## Accessibility

The code region is a labelled, keyboard-scrollable region; the copy, wrap, expand and download buttons have accessible names and announce their result. Line numbers, fold markers and decorations are hidden from assistive technology and never copied.

## Related

- [Tabs](https://design.gaudi.site/docs/components/tabs): Switch between related panels with keyboard-accessible tab controls.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [ScrollArea](https://design.gaudi.site/docs/components/scroll-area): Contained scrolling with themed scrollbars and optional smooth wheel motion for article reading.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.

Source: https://design.gaudi.site/docs/components/code-block (Markdown with example code: https://design.gaudi.site/docs/components/code-block.md)

---

# DataTable

> DataTable is a TanStack table with a compact data anatomy: shared headers that preserve label casing, hairline rows, synced column and row hover, a tinted wash for selected rows, and declarative column alignment, width and pinning.

It adds search with a live count, single or multi-column sorting, selection with bulk actions, expandable rows, row action menus, pinned rows, grouped bands, a totals footer, sticky headers, automatic virtualization, pagination or load-more, CSV export, and loading, refreshing, empty and error states. Sorting, selection, expansion and pinning work controlled or uncontrolled.

- Category: Core · Data Display
- Import: `@gaudi/design-system/core/DataTable` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/DataTable/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-datatable--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { DataTable } from '@gaudi/design-system/core/DataTable';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-column-controls.json`.

## Usage

```jsx
import { DataTable } from '@gaudi/design-system';

<DataTable
  columns={[{ key: 'component', header: 'Component' }]}
  rows={[{ component: 'Button' }]}
/>
```

## Examples

### Column controls

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-column-controls.json`

### Column virtualization

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-column-virtualization.json`

### CRM workspace

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-crm.json`

### CRUD in a frame

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-crud-frame.json`

### Export to CSV

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-csv-export.json`

### Draggable rows and columns

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-draggable.json`

### Editorial desk

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-editorial-desk.json`

### Grouping and aggregation

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-grouping.json`

### Infinite scroll

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-infinite-scroll.json`

### Inventory workspace

Spreadsheet editing with built-in editors, validation, Save and Discard, undo and redo, and row add, duplicate and delete

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-inventory.json`

### Layout options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-layouts.json`

### Pricing plans

Per-row edit mode with Save and Cancel in the row actions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-pricing-plans.json`

### Selection, expansion and pinned rows

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-selection-pinning.json`

### Server-side pagination

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-server-pagination.json`

### Shared drive tree

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-shared-drive.json`

### Shipment exceptions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-shipment-exceptions.json`

### Spreadsheet editing

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-spreadsheet.json`

### Sub table

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-sub-table.json`

### Tree rows

Registry: `npx shadcn@latest add https://design.gaudi.site/r/data-grid-tree-rows.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `columns` | `Array<{ key, header, render?, align?, width?, sticky?, footer?, sortable?, searchable?, hideable? }>` | `[]` | no | Column definitions. align: right sets tabular numerals; sticky: start \| end pins to the inline start or end (left \| right are read as start \| end, so pins mirror in RTL); className styles the column header and cells; footer(rows) renders a total. |
| `rows` | `Array<Record<string, unknown>>` | `[]` | no | Rows keyed by column key. row.id is used as the stable key when present. |
| `searchable / sortable / selectable` | `boolean` | `false` | no | Search with a live count, header sorting, and page-scoped row selection. |
| `columnVisibility / pagination` | `boolean` | `false` | no | Column controls and paged rows with first, previous, next and last. |
| `pageSize` | `number` | `10` | no | Rows per page when pagination is enabled. |
| `density` | `compact \| normal \| comfortable` | `normal` | no | Cell padding and header height. |
| `headerVariant` | `muted \| plain` | `muted` | no | Shared header fill; casing and typography stay consistent across table APIs. |
| `striped / footer` | `boolean` | `false` | no | Alternate row wash; a footer row with the record count and column totals. |
| `renderExpanded` | `function(row)` | — | no | Detail rows under an expand toggle. |
| `canExpand` | `function(row)` | — | no | Detail rows under an expand toggle. |
| `expandMode` | `single \| multiple` | `single` | no | Detail rows under an expand toggle. |
| `getRowActions` | `function(row) => Array<{ label, onSelect, icon?, tone?, disabled? }>` | — | no | An overflow menu at the end of each row; it also opens with a right-click, Shift+F10 or the Menu key. |
| `onRowClick` | `function(row)` | — | no | Makes rows focusable and activatable, ignoring clicks on inner controls; canActivateRow leaves rows that return false inert. |
| `canActivateRow` | `function(row) => boolean` | — | no | Makes rows focusable and activatable, ignoring clicks on inner controls; canActivateRow leaves rows that return false inert. |
| `sorting` | `Array<{ id, desc }>` | — | no | Controlled or initial sort state. The host can refuse or replace a change by not applying it. |
| `defaultSorting` | `Array` | `[]` | no | Controlled or initial sort state. The host can refuse or replace a change by not applying it. |
| `onSortingChange` | `function` | — | no | Controlled or initial sort state. The host can refuse or replace a change by not applying it. |
| `multiSort` | `boolean` | `false` | no | Shift-click a header to sort by more than one column; headers show their sort order. |
| `expanded` | `string[]` | — | no | Controlled or initial open detail rows by row ID. |
| `defaultExpanded` | `string[]` | `[]` | no | Controlled or initial open detail rows by row ID. |
| `onExpandedChange` | `function` | — | no | Controlled or initial open detail rows by row ID. |
| `pinnableRows` | `boolean` | `false` | no | Adds Pin to top, Pin to bottom and Unpin to each row menu. |
| `rowPinning` | `{ top: string[], bottom: string[] }` | — | no | Pinned rows stay above or below the others across sorting, search and pages, and stick under the header while the rest scroll. |
| `defaultRowPinning` | `object` | `{ top: [], bottom: [] }` | no | Pinned rows stay above or below the others across sorting, search and pages, and stick under the header while the rest scroll. |
| `onRowPinningChange` | `function` | — | no | Pinned rows stay above or below the others across sorting, search and pages, and stick under the header while the rest scroll. |
| `stickyHeader` | `false \| container \| page` | `container with maxHeight, otherwise false` | no | Keep the header in view inside the table region, or under page chrome while the page scrolls. Page mode lets the table fit its container rather than scroll sideways. |
| `stickyOffset` | `CSS length` | `0px` | no | Keep the header in view inside the table region, or under page chrome while the page scrolls. Page mode lets the table fit its container rather than scroll sideways. |
| `maxHeight` | `CSS length` | — | no | Scroll rows inside the table region so the header and pinned rows stay in view. |
| `virtualize` | `auto \| true \| false` | `auto` | no | Render only the rows in view for long flat lists; auto switches on above the threshold and gives the region a 32rem height unless maxHeight is set. |
| `virtualThreshold` | `number` | `100` | no | Render only the rows in view for long flat lists; auto switches on above the threshold and gives the region a 32rem height unless maxHeight is set. |
| `onLoadMore` | `function` | — | no | A Load more action for incremental collections; loadMoreOnScroll requests the next batch as the last row comes into view. |
| `hasMore` | `boolean` | `false` | no | A Load more action for incremental collections; loadMoreOnScroll requests the next batch as the last row comes into view. |
| `loadingMore` | `boolean` | `false` | no | A Load more action for incremental collections; loadMoreOnScroll requests the next batch as the last row comes into view. |
| `loadMoreOnScroll` | `boolean` | `false` | no | A Load more action for incremental collections; loadMoreOnScroll requests the next batch as the last row comes into view. |
| `exportable` | `boolean \| { filename, scope, label, delimiter, onExport }` | `false` | no | An Export CSV action: visible columns, current search and sort, and only the selected rows when there is a selection. Columns format values with exportValue(value, row) and opt out with export: false. |
| `groupBy` | `function(row) => { key, label }` | — | no | Collapsible group bands with counts. |
| `toolbar` | `ReactNode` | — | no | Extra controls beside the search, such as a FilterBar facet trigger. |
| `selection` | `Record<string, boolean>` | — | no | Controlled or initial selection keyed by stable row IDs. |
| `defaultSelection` | `object` | `{}` | no | Controlled or initial selection keyed by stable row IDs. |
| `onSelectionChange` | `function` | — | no | Controlled or initial selection keyed by stable row IDs. |
| `getRowId` | `function` | `row.id or index` | no | Supply stable identity for interactive collections. |
| `getRowLabel` | `function(row) => string` | `row ID` | no | Names a row in its select, details and actions controls (for example the title instead of an ID). |
| `renderSelectionActions` | `function(rows)` | — | no | Bulk actions for the selected rows. |
| `loading` | `boolean` | — | no | Skeleton rows, a floating updating pill over current rows, and host-owned recovery. |
| `refreshing` | `boolean` | — | no | Skeleton rows, a floating updating pill over current rows, and host-owned recovery. |
| `error` | `string` | — | no | Skeleton rows, a floating updating pill over current rows, and host-owned recovery. |
| `onRetry` | `function` | — | no | Skeleton rows, a floating updating pill over current rows, and host-owned recovery. |
| `caption` | `ReactNode` | — | no | Visually hidden caption that names the table and its scroll region. |
| `overflowLabel` | `string` | `Scrollable data table` | no | Accessible name for the scroll region when no caption is present. |
| `labels` | `object` | — | no | Visible and accessible copy overrides; labels.scrollRegion(caption) names the scroll region when a caption is set (default: caption + " scrollable table"). |
| `className` | `string` | — | no | Outer table frame class override. |

### Variants

- `density`: `compact`, `normal`, `comfortable`
- `headerVariant`: `muted`, `plain`
- `expandMode`: `single`, `multiple`

## Accessibility

DataTable renders a real table: a visually hidden caption, scoped column headers with aria-sort, named selection checkboxes, and a labelled, keyboard-focusable scroll region that pans with the arrow keys. Expand, row-action and group toggles are named buttons with aria-expanded; clickable rows take focus and activate with Enter or Space. The row menu also opens with a right-click, Shift+F10 or the Menu key and returns focus to where it was. Virtualized tables keep aria-rowcount and aria-rowindex so assistive technology knows the full size, and export, load-more and pinning changes are announced through a status region.

## Related

- [FilterBar](https://design.gaudi.site/docs/components/filter-bar): A collection toolbar: search with a live result count, a Filters popover of facets with counts, and removable Field: Value chips.
- [Skeleton](https://design.gaudi.site/docs/components/skeleton): Skeleton renders non-semantic loading placeholders on the theme border token, so blocks read clearly in light and dark themes.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.

Source: https://design.gaudi.site/docs/components/data-table (Markdown with example code: https://design.gaudi.site/docs/components/data-table.md)

---

# FilterBar

> A collection toolbar: search with a live result count, a Filters popover of facets with counts, and removable Field: Value chips.

The host owns matching and persistence.

- Category: Core · Data Display
- Import: `@gaudi/design-system/core/FilterBar` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/FilterBar/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-filterbar--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import FilterBar from '@gaudi/design-system/core/FilterBar';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/filters-all-in-one.json`.

## Usage

```jsx
import FilterBar from '@gaudi/design-system/core/FilterBar';

<FilterBar query={query} onQueryChange={setQuery} facets={facets} />
```

## Examples

### One bar, every filter kind

Registry: `npx shadcn@latest add https://design.gaudi.site/r/filters-all-in-one.json`

### Controlled state, sizes and locales

Registry: `npx shadcn@latest add https://design.gaudi.site/r/filters-controlled-translated.json`

### Custom value editors

Registry: `npx shadcn@latest add https://design.gaudi.site/r/filters-custom-editors.json`

### Nested groups edited in place

Registry: `npx shadcn@latest add https://design.gaudi.site/r/filters-inline-groups.json`

### Deep attribute menus for large libraries

Registry: `npx shadcn@latest add https://design.gaudi.site/r/filters-nested-attributes.json`

### Filtering a table with nested groups

Registry: `npx shadcn@latest add https://design.gaudi.site/r/filters-table-groups.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `query` | `string` | — | no | Controlled search query. |
| `onQueryChange` | `(query: string) => void` | — | no | Controlled search query. |
| `labels.removeFilter / labels.findIn / labels.findPlaceholder` | `(value, field) => string / (facet) => string` | `Remove {value} filter / Find {facet}` | no | Translatable phrases with names in them. |
| `dir` | `'ltr' \| 'rtl'` | — | no | Reading direction of the bar and its search; extra search input attributes. |
| `inputProps` | `object` | — | no | Reading direction of the bar and its search; extra search input attributes. |
| `count` | `{ shown, total }` | — | no | Live result count shown inside the search field. |
| `facets` | `Array<{ id, label, options: Array<{ value, label, count? }>, value, onChange, multiple? }>` | `[]` | no | Controlled facets listed in the Filters popover; every selected value becomes a chip. |
| `filterLabel` | `string` | `Filters` | no | Filters trigger label. |
| `searchLabel / placeholder` | `string` | `Search records / Search…` | no | Search control label and hint. |
| `filters` | `Array<{ id, label, field? }>` | `[]` | no | Other applied filters shown as chips. |
| `onRemoveFilter / onClearFilters` | `function` | — | no | Remove one filter or reset the collection. |
| `actions` | `ReactNode` | — | no | Collection actions, aligned to the end. |
| `labels` | `object` | — | no | Visible and accessible copy overrides; labels.facet names the phone facet select. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `dir`: `ltr`, `rtl`

## Accessibility

Search has a visible or programmatic label. Each chip names its remove action; the facet popover uses tabs for categories (a labelled facet select on phones) and checkbox or radio rows for values. Truncated option labels keep their full text as a tooltip.

## Notes

- Filters is the compound query-builder export. Its examples cover nested groups, operators, asynchronous values and saved queries.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [DataTable](https://design.gaudi.site/docs/components/data-table): DataTable is a TanStack table with a compact data anatomy: shared headers that preserve label casing, hairline rows, synced column and row hover, a tinted wash for selected rows, and declarative column alignment, width and pinning.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.

Source: https://design.gaudi.site/docs/components/filter-bar (Markdown with example code: https://design.gaudi.site/docs/components/filter-bar.md)

---

# Item

> Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.

- Category: Core · Data Display
- Import: `@gaudi/design-system/core/Item` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Item/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-item--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Item } from '@gaudi/design-system/core/Item';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/item-activity-feed.json`.

## Usage

```jsx
import { Button, Item, ItemActions, ItemContent, ItemDescription, ItemGroup, ItemMedia, ItemTitle } from '@gaudi/design-system';
import { RegistryIcon } from '@gaudi/design-system/icons';

<ItemGroup>
  <Item variant='outline'>
    <ItemMedia variant='icon'><RegistryIcon lucide='GithubIcon' aria-hidden='true' /></ItemMedia>
    <ItemContent>
      <ItemTitle>GitHub</ItemTitle>
      <ItemDescription>Sync pull requests and issues.</ItemDescription>
    </ItemContent>
    <ItemActions><Button href='/settings/integrations/github' size='sm' variant='outline'>Connect</Button></ItemActions>
  </Item>
</ItemGroup>
```

## Examples

### Activity feed

Registry: `npx shadcn@latest add https://design.gaudi.site/r/item-activity-feed.json`

### Changed files summary

Registry: `npx shadcn@latest add https://design.gaudi.site/r/item-changed-files.json`

### Header and footer

Registry: `npx shadcn@latest add https://design.gaudi.site/r/item-header-footer.json`

### Log links and a reversible action

Registry: `npx shadcn@latest add https://design.gaudi.site/r/item-links-action.json`

### Run status with a live step

Registry: `npx shadcn@latest add https://design.gaudi.site/r/item-live-run.json`

### Menu with counts and shortcuts

Registry: `npx shadcn@latest add https://design.gaudi.site/r/item-menu-counts.json`

### Navigation rows

Registry: `npx shadcn@latest add https://design.gaudi.site/r/item-navigation.json`

### Run log grouped by phase

Registry: `npx shadcn@latest add https://design.gaudi.site/r/item-run-log.json`

### Settings and integrations

Registry: `npx shadcn@latest add https://design.gaudi.site/r/item-settings-integrations.json`

### Team members and roles

Registry: `npx shadcn@latest add https://design.gaudi.site/r/item-team-roles.json`

### Variants and sizes

Registry: `npx shadcn@latest add https://design.gaudi.site/r/item-variants.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `variant` | `default \| outline \| muted` | `default` | no | Row surface: plain, bordered or tinted. |
| `size` | `default \| sm \| xs` | `default` | no | Row density. |
| `as` | `ElementType` | `div` | no | Render the row as another element, or merge it into a link or button child. |
| `asChild` | `boolean` | `false` | no | Render the row as another element, or merge it into a link or button child. |
| `ItemMedia.variant` | `default \| icon \| image` | `default` | no | Presentation of the leading media slot. |
| `ItemGroup` (sub-component) | `HTMLAttributes<HTMLDivElement>` | — | no | A role="group" wrapper that stacks rows; pair with ItemSeparator. |
| `ItemTitle / ItemDescription` (sub-component) | `ReactNode` | — | no | Row title (one line) and supporting text (two lines). |
| `ItemActions / ItemHeader / ItemFooter` (sub-component) | `ReactNode` | — | no | Trailing controls and full-width rows above or below the content. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `variant`: `default`, `outline`, `muted`
- `size`: `default`, `sm`, `xs`

## Accessibility

Use asChild with a link when the whole row navigates and keep independent actions outside that link. Name icon-only actions after their row, and label a group when the surrounding heading does not describe it.

## Related

- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [Progress](https://design.gaudi.site/docs/components/progress): Determinate and indeterminate progress with a readable task label.
- [Loader](https://design.gaudi.site/docs/components/loader): An accessible loading indicator with arcs, dots, expanding rings, and an indeterminate bar.

Source: https://design.gaudi.site/docs/components/item (Markdown with example code: https://design.gaudi.site/docs/components/item.md)

---

# SchemaDisplay

> Read an API endpoint or a JSON Schema: method badge, path with highlighted parameters, and request and response schemas as an expandable property tree.

- Category: Core · Data Display
- Import: `@gaudi/design-system/core/SchemaDisplay` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/SchemaDisplay/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-schemadisplay--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { SchemaDisplay } from '@gaudi/design-system/core/SchemaDisplay';
```

## Usage

```jsx
import { SchemaDisplay } from '@gaudi/design-system';

<SchemaDisplay
  method='GET'
  path='/posts/{slug}/comments'
  parameters={[{ name: 'slug', in: 'path', type: 'string' }, { name: 'limit', in: 'query', type: 'integer' }]}
  responseBody={commentsSchema}
/>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-schemadisplay--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `method` | `string` | — | no | Endpoint verb and path; {id} and :id parameters are highlighted. |
| `path` | `string` | — | no | Endpoint verb and path; {id} and :id parameters are highlighted. |
| `title / description` | `ReactNode` | — | no | A name for a bare schema and a summary line. |
| `parameters` | `Array<{ name, in, type?, schema?, required?, description? }>` | `[]` | no | Path, query and header parameters; path parameters are always required. |
| `requestBody / responseBody / schema` | `JSONSchema` | — | no | Schemas read as trees: type, format, required, description, enum, items and oneOf. |
| `defaultExpandDepth` | `number` | `1` | no | Levels of nested objects that start open. |
| `showJson` | `boolean` | `false` | no | Adds a Schema / JSON toggle with the raw definition in CodeBlock. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | no | Heading level of the section titles. |
| `labels` | `object` | `English copy` | no | Section titles and the required marker. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `headingLevel`: `2`, `3`, `4`, `5`, `6`

## Accessibility

Sections are real headings at headingLevel. Nested objects are disclosure buttons with aria-expanded; required is written out, never colour alone, and parameter highlights keep their braces.

## Related

- [CodeBlock](https://design.gaudi.site/docs/components/code-block): CodeBlock renders syntax-highlighted source with an optional header, copy button, line numbers, highlighted and focused lines, diffs, folding and line selection.
- [DataTable](https://design.gaudi.site/docs/components/data-table): DataTable is a TanStack table with a compact data anatomy: shared headers that preserve label casing, hairline rows, synced column and row hover, a tinted wash for selected rows, and declarative column alignment, width and pinning.
- [FilterBar](https://design.gaudi.site/docs/components/filter-bar): A collection toolbar: search with a live result count, a Filters popover of facets with counts, and removable Field: Value chips.
- [Item](https://design.gaudi.site/docs/components/item): Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.
- [Terminal](https://design.gaudi.site/docs/components/terminal): Terminal renders mac-style shell examples with typed commands and structured output lines.
- [Timeline](https://design.gaudi.site/docs/components/timeline): Display dated activity and milestones with readable descriptions and optional actions.

Source: https://design.gaudi.site/docs/components/schema-display (Markdown with example code: https://design.gaudi.site/docs/components/schema-display.md)

---

# Terminal

> Terminal renders mac-style shell examples with typed commands and structured output lines.

- Category: Core · Data Display
- Import: `@gaudi/design-system/core/Terminal` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Terminal/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-terminal--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Terminal from '@gaudi/design-system/core/Terminal';
```

## Usage

```jsx
import { Terminal } from '@gaudi/design-system';

<Terminal
  title='blog — zsh'
  username='ahmad'
  commands={[
    { command: 'pnpm test:ds-contracts', output: [{ text: '85 component contracts passed.', tone: 'success' }] },
  ]}
/>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-terminal--playground)
- [Legacy Outputs](https://storybook.gaudi.site/index.html?path=/story/core-terminal--legacy-outputs)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `commands` | `Array<string \| { command, output, tone }>` | `example commands` | no | Command history. output can be strings or { text, tone } lines. |
| `outputs` | `Record<number, output[]>` | `{}` | no | Legacy output mapping for string command arrays. |
| `ariaLabel` | `string` | `Terminal` | no | Accessible name for the terminal region. |
| `title` | `string` | `terminal` | no | Header title. |
| `username` | `string` | `ahmad` | no | Prompt username segment. |
| `promptSymbol` | `string` | `$` | no | Prompt separator. |
| `variant` | `dark \| light \| translucent` | `dark` | no | Terminal surface treatment. |
| `size` | `sm \| md \| lg` | `md` | no | Controls max width, body height, and text size. |
| `radius` | `none \| sm \| md \| lg` | `lg` | no | Legacy aliases use the global --ds-radius setting; none keeps square corners. |
| `showHeader` | `boolean` | `true` | no | Shows mac window controls and title. |
| `animate` | `boolean` | `true` | no | Types commands over time unless reduced motion is preferred. |
| `typingSpeed` | `number` | `35` | no | Milliseconds between typed characters. |
| `initialDelay` | `number` | `400` | no | Delay before the first command starts. |
| `delayBetweenCommands` | `number` | `700` | no | Delay after a command before the next command starts. |
| `className` | `string` | — | no | Root class override. |
| `classNames` | `{ root, header, controls, title, body, line, prompt, command, output }` | — | no | Slot-level class overrides. |

### Variants

- `variant`: `dark`, `light`, `translucent`
- `size`: `sm`, `md`, `lg`
- `radius`: `none`, `sm`, `md`, `lg`

## Accessibility

Terminal renders readable command history inside a labelled region. Motion is disabled when users prefer reduced motion.

## Related

- [CodeBlock](https://design.gaudi.site/docs/components/code-block): CodeBlock renders syntax-highlighted source with an optional header, copy button, line numbers, highlighted and focused lines, diffs, folding and line selection.
- [DataTable](https://design.gaudi.site/docs/components/data-table): DataTable is a TanStack table with a compact data anatomy: shared headers that preserve label casing, hairline rows, synced column and row hover, a tinted wash for selected rows, and declarative column alignment, width and pinning.
- [FilterBar](https://design.gaudi.site/docs/components/filter-bar): A collection toolbar: search with a live result count, a Filters popover of facets with counts, and removable Field: Value chips.
- [Item](https://design.gaudi.site/docs/components/item): Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.
- [SchemaDisplay](https://design.gaudi.site/docs/components/schema-display): Read an API endpoint or a JSON Schema: method badge, path with highlighted parameters, and request and response schemas as an expandable property tree.
- [Timeline](https://design.gaudi.site/docs/components/timeline): Display dated activity and milestones with readable descriptions and optional actions.

Source: https://design.gaudi.site/docs/components/terminal (Markdown with example code: https://design.gaudi.site/docs/components/terminal.md)

---

# Timeline

> Display dated activity and milestones with readable descriptions and optional actions.

- Category: Core · Data Display
- Import: `@gaudi/design-system/core/Timeline` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Timeline/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-timeline--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Timeline from '@gaudi/design-system/core/Timeline';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/timeline-activity-stream.json`.

## Usage

```jsx
import Timeline from '@gaudi/design-system/core/Timeline';

<Timeline items={milestones} />
```

## Examples

### Activity stream

Registry: `npx shadcn@latest add https://design.gaudi.site/r/timeline-activity-stream.json`

### Alternating milestones

Registry: `npx shadcn@latest add https://design.gaudi.site/r/timeline-alternating.json`

### Release changelog

Registry: `npx shadcn@latest add https://design.gaudi.site/r/timeline-changelog.json`

### Horizontal releases

Registry: `npx shadcn@latest add https://design.gaudi.site/r/timeline-horizontal-releases.json`

### Pipeline steps

Registry: `npx shadcn@latest add https://design.gaudi.site/r/timeline-pipeline-steps.json`

### Vertical progress

Registry: `npx shadcn@latest add https://design.gaudi.site/r/timeline-vertical-progress.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `items` | `Array<{ id, title, description?, time?, dateTime?, icon?, children? }>` | `[]` | no | Chronological entries with stable IDs. |
| `label` | `string` | `Activity` | no | Accessible name of the list. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Use machine-readable dateTime values with visible dates. Icons supplement the text and are decorative.

## Related

- [Attachment](https://design.gaudi.site/docs/components/attachment): File attachments with metadata, previews, actions and upload states.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Accordion](https://design.gaudi.site/docs/components/accordion): Rich disclosure for FAQs, settings, member directories, nested help, and guided setup.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.

Source: https://design.gaudi.site/docs/components/timeline (Markdown with example code: https://design.gaudi.site/docs/components/timeline.md)

---

# Commander

> Commander provides the site command palette with host-supplied destinations for navigation, content search, and theme actions.

- Category: Core · Overlays & Menus
- Import: `@gaudi/design-system/core/Commander` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Commander/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-commander--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Commander from '@gaudi/design-system/core/Commander';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/command-dialog-shortcuts.json`.

## Usage

```jsx
import { useState } from 'react';
import { Button, Commander } from '@gaudi/design-system';

export function ContentSearch({ posts = [], projects = [], publications = [], tags = [], thoughts = [] }) {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button onClick={() => setOpen(true)}>Search content</Button>
      <Commander
        open={open}
        setOpen={setOpen}
        posts={posts}
        projects={projects}
        publications={publications}
        tags={tags}
        thoughts={thoughts}
      />
    </>
  );
}
```

## Examples

### Command dialog with groups and shortcuts

Registry: `npx shadcn@latest add https://design.gaudi.site/r/command-dialog-shortcuts.json`

### Inline palette

Registry: `npx shadcn@latest add https://design.gaudi.site/r/command-inline-palette.json`

### Search everything

Registry: `npx shadcn@latest add https://design.gaudi.site/r/command-search-everything.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `open` | `boolean` | — | no | Controlled palette state. |
| `setOpen` | `(open: boolean) => void` | — | no | State setter used by the trigger, shortcut, keyboard handler, and close behavior. |
| `navigation` | `Array` | `[]` | no | Prepared destinations with id, title, href or onClick, and optional disabled. No built-in routes. |
| `posts` | `Array` | `[]` | no | Searchable post records with prepared id/slug, title and href or onClick. |
| `projects` | `Array` | `[]` | no | Searchable project records. |
| `publications` | `Array` | `[]` | no | Searchable publication records. |
| `tags` | `Array` | `[]` | no | Searchable tag records. |
| `thoughts` | `Array` | `[]` | no | Searchable thought records. |

## Accessibility

Commander is a keyboard-first overlay. Keep focus visible, support Escape close/back behavior, expose readable result labels, and make Cmd/Ctrl + K available without hiding the visible trigger.

## Related

- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Kbd](https://design.gaudi.site/docs/components/kbd): Kbd renders keyboard keys and multi-key shortcuts.

Source: https://design.gaudi.site/docs/components/commander (Markdown with example code: https://design.gaudi.site/docs/components/commander.md)

---

# Dialog

> Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.

- Category: Core · Overlays & Menus
- Import: `@gaudi/design-system/core/Dialog` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Dialog/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-dialog--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Dialog from '@gaudi/design-system/core/Dialog';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/confirmation-checklist.json`.

## Usage

```jsx
import Dialog from '@gaudi/design-system/core/Dialog';
import Button from '@gaudi/design-system/core/Button';

<Dialog title='Edit profile' description='Update your public details.'
  trigger={<Button>Edit profile</Button>}>
  {profileForm}
</Dialog>
```

## Examples

### Checklist before an action

Registry: `npx shadcn@latest add https://design.gaudi.site/r/confirmation-checklist.json`

### Confirmation with a don't-ask-again option

Registry: `npx shadcn@latest add https://design.gaudi.site/r/confirmation-dont-ask-again.json`

### Confirmation layouts

Registry: `npx shadcn@latest add https://design.gaudi.site/r/confirmation-layouts.json`

### Confirmation nested in a dialog

Registry: `npx shadcn@latest add https://design.gaudi.site/r/confirmation-nested-dialog.json`

### Notice with a status badge

Registry: `npx shadcn@latest add https://design.gaudi.site/r/confirmation-status-notice.json`

### Success summary with details

Registry: `npx shadcn@latest add https://design.gaudi.site/r/confirmation-success-summary.json`

### Close button and footer options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dialog-close-footer.json`

### Form dialog

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dialog-form.json`

### Scrollable content

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dialog-scrollable.json`

### Settings with switches

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dialog-settings-switches.json`

### Keyboard shortcuts list

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dialog-shortcuts-list.json`

### Drawer from each edge

Registry: `npx shadcn@latest add https://design.gaudi.site/r/drawer-edges.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `variant` | `modal \| confirmation \| bare` | `modal` | no | Presentation and interaction contract; side panels use Sheet. |
| `label` | `string` | — | no | Bare only: the accessible name without a visible title, the portal container, the element focused on open, and the fallback focus target when the opener is gone. |
| `container` | `Element` | — | no | Bare only: the accessible name without a visible title, the portal container, the element focused on open, and the fallback focus target when the opener is gone. |
| `initialFocusRef` | `Ref` | — | no | Bare only: the accessible name without a visible title, the portal container, the element focused on open, and the fallback focus target when the opener is gone. |
| `restoreFocusRef` | `Ref` | — | no | Bare only: the accessible name without a visible title, the portal container, the element focused on open, and the fallback focus target when the opener is gone. |
| `trigger` | `ReactElement` | — | no | A ref-forwarding button that opens the dialog. |
| `title / description` | `ReactNode` | — | no | Accessible title and optional supporting description. |
| `open / defaultOpen` | `boolean` | — | no | Controlled or initial open state. Use one state model for the lifetime of the component. |
| `onOpenChange` | `(open: boolean) => void` | — | no | Responds to open and close requests. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `footer` | `ReactNode` | — | no | Actions in the modal or sheet footer. |
| `closeLabel` | `string` | `Close dialog` | no | Accessible name of the close button. |
| `contentProps` | `DialogContentProps` | — | no | Modal or sheet content and focus overrides. |
| `onConfirm` | `() => void \| Promise<void>` | — | no | Confirmation only: resolving closes; rejecting keeps the dialog open for retry. |
| `confirmLabel / cancelLabel / pendingLabel` | `string` | `Confirm / Cancel / Working…` | no | Labels for confirmation mode. |
| `errorMessage` | `string` | `The action could not be completed. Please try again.` | no | Feedback when the confirmation promise rejects. |
| `tone` | `accent \| danger` | `danger` | no | Confirmation action tone. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `variant`: `modal`, `confirmation`, `bare`
- `tone`: `accent`, `danger`

## Accessibility

Focus stays in the dialog and returns to its trigger. Confirmation mode focuses Cancel and blocks dismissal while a decision is pending.

## Notes

- Use DialogClose for modal and sheet actions. Confirmation mode owns its actions and pending state; children and footer apply to modal and sheet variants.

## Related

- [Sheet](https://design.gaudi.site/docs/components/sheet): A panel that slides in from an edge over a dimmed page, for side tasks such as settings, details, comments, notifications or an assistant, without leaving the current screen.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Checkbox](https://design.gaudi.site/docs/components/checkbox): Checkbox renders a token-styled binary control.
- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.
- [Kbd](https://design.gaudi.site/docs/components/kbd): Kbd renders keyboard keys and multi-key shortcuts.

Source: https://design.gaudi.site/docs/components/dialog (Markdown with example code: https://design.gaudi.site/docs/components/dialog.md)

---

# DropdownMenu

> Action menus with keyboard navigation, checkbox choices and destructive actions.

- Category: Core · Overlays & Menus
- Import: `@gaudi/design-system/core/DropdownMenu` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/DropdownMenu/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-dropdownmenu--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import DropdownMenu from '@gaudi/design-system/core/DropdownMenu';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/context-menu-in-dialog.json`.

## Usage

```jsx
import DropdownMenu, { DropdownMenuItem } from '@gaudi/design-system/core/DropdownMenu';
import Button from '@gaudi/design-system/core/Button';

<DropdownMenu trigger={<Button variant='outline'>Document actions</Button>}>
  <DropdownMenuItem onSelect={duplicate}>Duplicate</DropdownMenuItem>
  <DropdownMenuItem onSelect={archive}>Archive</DropdownMenuItem>
</DropdownMenu>
```

## Examples

### Context menu inside a dialog

Registry: `npx shadcn@latest add https://design.gaudi.site/r/context-menu-in-dialog.json`

### Context menu

Registry: `npx shadcn@latest add https://design.gaudi.site/r/context-menu-item-kinds.json`

### Account and create menus

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dropdown-menu-account-create.json`

### Item kinds

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dropdown-menu-item-kinds.json`

### Notifications

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dropdown-menu-notifications.json`

### Side and alignment

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dropdown-menu-placement.json`

### Workspace and model switchers

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dropdown-menu-switchers.json`

### Application menubar

Registry: `npx shadcn@latest add https://design.gaudi.site/r/menubar-application.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `trigger` | `ReactElement` | — | no | Ref-forwarding button that opens the menu. |
| `align` | `start \| center \| end` | `end` | no | Horizontal alignment of the popup. |
| `open / defaultOpen` | `boolean` | — | no | Controlled or initial open state. Use one state model for the lifetime of the component. |
| `onOpenChange` | `(open: boolean) => void` | — | no | Responds to open and close requests. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `DropdownMenuItem.onSelect` | `(event: Event) => void` | — | no | Action invoked by keyboard or pointer selection. |
| `DropdownMenuItem.destructive / disabled` | `boolean` | — | no | Destructive styling or unavailable action. |
| `DropdownMenuCheckboxItem.checked` | `boolean \| indeterminate` | — | no | Controlled checkbox menu item. |
| `onCheckedChange` | `function` | — | no | Controlled checkbox menu item. |

### Variants

- `align`: `start`, `center`, `end`

## Accessibility

Arrow keys navigate items; Escape closes and returns focus. Use menu items for actions and links for navigation.

## Related

- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Tabs](https://design.gaudi.site/docs/components/tabs): Switch between related panels with keyboard-accessible tab controls.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Separator](https://design.gaudi.site/docs/components/separator): Separate related content with a horizontal or vertical rule.

Source: https://design.gaudi.site/docs/components/dropdown-menu (Markdown with example code: https://design.gaudi.site/docs/components/dropdown-menu.md)

---

# Popover

> Popover renders compact positioned supporting content next to its trigger.

- Category: Core · Overlays & Menus
- Import: `@gaudi/design-system/core/Popover` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Popover/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-popover--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Popover } from '@gaudi/design-system/core/Popover';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/hover-card-relative-time.json`.

## Usage

```jsx
import { Popover } from '@gaudi/design-system';

<Popover trigger='Open popover'>Compact supporting content.</Popover>
```

## Examples

### Relative timestamp

Registry: `npx shadcn@latest add https://design.gaudi.site/r/hover-card-relative-time.json`

### Rich hover cards

Registry: `npx shadcn@latest add https://design.gaudi.site/r/hover-card-rich.json`

### Sides

Registry: `npx shadcn@latest add https://design.gaudi.site/r/hover-card-sides.json`

### Inside a dialog

Registry: `npx shadcn@latest add https://design.gaudi.site/r/popover-in-dialog.json`

### Paged content

Registry: `npx shadcn@latest add https://design.gaudi.site/r/popover-paged.json`

### Sides and alignment

Registry: `npx shadcn@latest add https://design.gaudi.site/r/popover-placement.json`

### Rich content

Registry: `npx shadcn@latest add https://design.gaudi.site/r/popover-rich.json`

### Settings form

Registry: `npx shadcn@latest add https://design.gaudi.site/r/popover-settings-form.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `trigger` | `ReactNode` | — | no | Label or content of the outline trigger button. |
| `children` | `ReactNode` | — | no | Panel content. |
| `side` | `top \| right \| bottom \| left` | `bottom` | no | Placement of the panel relative to the trigger. |
| `align` | `start \| center \| end` | `center` | no | Placement of the panel relative to the trigger. |
| `open` | `boolean` | — | no | Controlled or initial open state, and whether outside content is inert while open. |
| `defaultOpen` | `boolean` | — | no | Controlled or initial open state, and whether outside content is inert while open. |
| `onOpenChange` | `function` | — | no | Controlled or initial open state, and whether outside content is inert while open. |
| `modal` | `boolean` | — | no | Controlled or initial open state, and whether outside content is inert while open. |
| `contentClassName` | `string` | — | no | Panel class override. |
| `className` | `string` | — | no | Trigger button class override. |

### Variants

- `side`: `top`, `right`, `bottom`, `left`
- `align`: `start`, `center`, `end`

## Accessibility

The trigger is a DS button with aria-expanded; the panel is portalled, dismisses on Escape or an outside click, and returns focus to the trigger. Keep popover content short and non-modal.

## Related

- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Separator](https://design.gaudi.site/docs/components/separator): Separate related content with a horizontal or vertical rule.
- [Slider](https://design.gaudi.site/docs/components/slider): Adjust one value or a range with pointer and keyboard input.

Source: https://design.gaudi.site/docs/components/popover (Markdown with example code: https://design.gaudi.site/docs/components/popover.md)

---

# Sheet

> A panel that slides in from an edge over a dimmed page, for side tasks such as settings, details, comments, notifications or an assistant, without leaving the current screen.

- Category: Core · Overlays & Menus
- Import: `@gaudi/design-system/core/Sheet` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Sheet/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-sheet--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Sheet } from '@gaudi/design-system/core/Sheet';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/sheet-assistant.json`.

## Usage

```jsx
import { Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription } from '@gaudi/design-system/core/Sheet';

<Sheet>
  <SheetTrigger>Inspect details</SheetTrigger>
  <SheetContent side='right'><SheetHeader><SheetTitle>Details</SheetTitle><SheetDescription>Review the selected record.</SheetDescription></SheetHeader>{details}</SheetContent>
</Sheet>
```

## Examples

### Assistant

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sheet-assistant.json`

### Comments

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sheet-comments.json`

### Sheet from each edge

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sheet-edges.json`

### Help and shortcuts

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sheet-help-shortcuts.json`

### New project

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sheet-new-project.json`

### Notifications

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sheet-notifications.json`

### Record details

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sheet-record-details.json`

### Settings

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sheet-settings.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `Sheet.open / defaultOpen / onOpenChange` | `boolean / (open) => void` | — | no | Controlled or initial open state. |
| `SheetContent.side` | `right \| left \| top \| bottom` | `right` | no | Edge the panel slides from. |
| `SheetContent.size` | `sm \| md \| lg \| xl` | `sm` | no | Width of side panels. |
| `SheetContent.inset` | `boolean` | `false` | no | Float the panel off the edge with a rounded border. |
| `SheetContent.overlay` | `dim \| blur` | `dim` | no | How the page behind is dimmed. |
| `SheetContent.showCloseButton` | `boolean` | `true` | no | Corner close button. |
| `SheetHeader / SheetTitle / SheetDescription / SheetFooter` (sub-component) | `parts` | — | no | Fixed header and footer around a scrolling body. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

The sheet is a modal dialog: focus moves in and is trapped, Escape and the backdrop close it, the page behind is inert, and focus returns to the trigger. Give every sheet a SheetTitle.

## Notes

- Use Dialog for short centred decisions and Sheet for longer side tasks.

## Related

- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Timeline](https://design.gaudi.site/docs/components/timeline): Display dated activity and milestones with readable descriptions and optional actions.
- [Item](https://design.gaudi.site/docs/components/item): Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.

Source: https://design.gaudi.site/docs/components/sheet (Markdown with example code: https://design.gaudi.site/docs/components/sheet.md)

---

# Toast

> Transient feedback for completed actions, errors and recoverable background work.

- Category: Core · Overlays & Menus
- Import: `@gaudi/design-system/core/Toast` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Toast/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-toast--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Toast from '@gaudi/design-system/core/Toast';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/toast-actions.json`.

## Usage

```jsx
import ToastProvider, { toast } from '@gaudi/design-system/core/Toast';
import Button from '@gaudi/design-system/core/Button';

<><ToastProvider /><Button onClick={() => toast.success('Changes saved')}>Save</Button></>
```

## Examples

### Actions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/toast-actions.json`

### Progress and async work

Registry: `npx shadcn@latest add https://design.gaudi.site/r/toast-async-progress.json`

### Custom content

Registry: `npx shadcn@latest add https://design.gaudi.site/r/toast-custom-content.json`

### Types and options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/toast-types-options.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `position` | `top-left \| top-center \| top-right \| bottom-left \| bottom-center \| bottom-right` | `bottom-right` | no | Toast stack position. |
| `closeButton` | `boolean` | `true` | no | Show an explicit dismiss action. |
| `expand` | `boolean` | `false` | no | Show every toast in the stack instead of collapsing them behind the front one. |
| `duration` | `number` | `Sonner default` | no | Default display duration in milliseconds. |
| `toastOptions` | `ExternalToast` | `Gaudi class names` | no | Default appearance and behavior for each toast. |
| `toast(message, options)` (helper) | `function` | — | no | Show a message; options include description, action and cancellation. |
| `toast.promise(promise, options)` (helper) | `function` | — | no | Show loading, success and error feedback for one operation. |

### Variants

- `position`: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`

## Accessibility

Use inline errors for fields and persistent failures. Keep toast actions keyboard accessible and allow enough time to act.

## Notes

- Mount one ToastProvider for a region. The toast API and additional provider props are forwarded from Sonner.

## Related

- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Progress](https://design.gaudi.site/docs/components/progress): Determinate and indeterminate progress with a readable task label.

Source: https://design.gaudi.site/docs/components/toast (Markdown with example code: https://design.gaudi.site/docs/components/toast.md)

---

# Embed

> The shared preview vocabulary for messages and content: one switch that hands each piece of content to its owner.

Links go to LinkPreview, code to CodeBlock, generated pages to WebPreview; images and videos default to a LinkPreview card until you pass a renderer.

- Category: Core · Media & Previews
- Import: `@gaudi/design-system/core/Embed` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Embed/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-embed--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Embed from '@gaudi/design-system/core/Embed';
```

## Usage

```jsx
import { Embed } from '@gaudi/design-system';

<>
<Embed url='https://github.com/ahmadassaf/design-system' />
<Embed code={source} language='html' filename='index.html' />
<Embed url='https://preview.example.dev/' html={generatedHtml} title='Generated page' />
<Embed src='/images/diagram.png' alt='Architecture diagram' components={{ image: ImageWithLightbox }} />
</>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-embed--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `type` | `auto \| link \| web \| code \| image \| video` | `auto` | no | What to render; auto decides from code, html and the address. |
| `url / src` | `string` | — | no | Link, page or media address. |
| `code / language / filename` | `string` | — | no | Code for CodeBlock. |
| `html` | `string` | — | no | Generated HTML for WebPreview. |
| `title / alt` | `string` | — | no | Link text or page title; image alternative text. |
| `previewData` | `object` | — | no | Static link metadata. |
| `variant` | `card \| compact \| inline` | `card` | no | LinkPreview presentation for links and media. |
| `components` | `{ link?, web?, code?, image?, video? }` | `{}` | no | Renderer overrides, for example a lightbox image or a video player. |
| `codeProps / webPreviewProps / linkPreviewProps` | `object` | — | no | Passed to the owner. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `type`: `auto`, `link`, `web`, `code`, `image`, `video`
- `variant`: `card`, `compact`, `inline`

## Accessibility

Embed adds no markup of its own beyond a wrapper; accessibility comes from the owner it renders. Give images alt text and generated pages a title.

## Notes

- resolveEmbedType(content) is pure, so a message parser can classify parts before rendering.

## Related

- [LinkPreview](https://design.gaudi.site/docs/components/link-preview): A link enriched with what the destination is.
- [CodeBlock](https://design.gaudi.site/docs/components/code-block): CodeBlock renders syntax-highlighted source with an optional header, copy button, line numbers, highlighted and focused lines, diffs, folding and line selection.
- [WebPreview](https://design.gaudi.site/docs/components/web-preview): A framed browser for a live or generated page: back, forward and reload, an editable address bar, open in a new tab, device widths, a sandboxed iframe with a loading state, an optional console, and a link preview card when a site refuses framing.
- [Link](https://design.gaudi.site/docs/components/link): Link centralizes navigation semantics for internal, anchor, and external links.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.

Source: https://design.gaudi.site/docs/components/embed (Markdown with example code: https://design.gaudi.site/docs/components/embed.md)

---

# LinkPreview

> A link enriched with what the destination is.

One normaliser, normalizeLinkPreview, turns the app's preview payload into a kind (repository, video, article, social post, docs, Wikipedia, package, image, file, internal post or website) and the rich fields that kind earns; three variants present it.

- Category: Core · Media & Previews
- Import: `@gaudi/design-system/core/LinkPreview` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/LinkPreview/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-linkpreview--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import LinkPreview from '@gaudi/design-system/core/LinkPreview';
```

## Usage

```jsx
import { LinkPreview, SiteConfigProvider } from '@gaudi/design-system';

// Inline: the link text reveals a rich card on hover or focus.
<>
<p>The source is in <LinkPreview url='https://github.com/ahmadassaf/design-system' title='Gaudi on GitHub' />.</p>

{/* Card and compact row; previewData skips fetching (server-rendered or cached metadata). */}
<LinkPreview url='https://www.youtube.com/watch?v=qh3NGpYRG3I' variant='card' previewData={{ title: 'Designing with tokens', image: '/og/tokens.jpg', author: 'Gaudi', duration: 'PT12M41S' }} />
<LinkPreview url='https://medium.com/@ahmadassaf/knowledge-graphs' variant='compact' />

{/* The app owns the endpoint that fetches metadata and any derived images; Gaudi loads nothing by default. */}
<SiteConfigProvider preview={{ endpoint: '/api/preview', resolveImage: { video: '/thumbs/{videoId}.jpg' } }}>{children}</SiteConfigProvider>
</>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-linkpreview--playground)
- [Link previews](https://storybook.gaudi.site/index.html?path=/story/core-linkpreview--link-previews)
- [States](https://storybook.gaudi.site/index.html?path=/story/core-linkpreview--states)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `url` | `string` | — | no | Destination, absolute or an app path such as /blog/post. |
| `title` | `string` | `page title` | no | Visible link text; the card keeps the page's own title. |
| `variant` | `inline \| card \| compact` | `inline` | no | Link with a hover card, a standalone card, or a one-line row. |
| `orientation` | `vertical \| horizontal` | `vertical` | no | Card layout: image above or beside the text. |
| `previewData` | `object` | — | no | Static payload; skips fetching. Understands title, description, image, favicon, siteName, author, publishedTime, readingTime, duration, stars, forks, language, likes, replies, views, tags, category, excerpt. |
| `endpoint` | `string \| (url) => string \| null` | `SiteConfig preview.endpoint (none)` | no | App-owned preview endpoint. With none configured nothing is fetched and the link renders from previewData or as a plain link. |
| `showImage` | `boolean` | `true` | no | Inline: open the hover card. Card: show the image. |
| `resolveImage` | `(link) => string \| null \| template map` | `SiteConfig preview.resolveImage (none)` | no | Image for links whose payload has none, e.g. a video thumbnail or a screenshot. Gaudi ships no image services. |
| `internal` | `boolean` | `paths starting with /` | no | Treat the link as an app page. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | no | Heading level of the card title. |
| `defaultOpen` | `boolean` | `false` | no | Start the inline hover card open. |
| `timeout` | `number` | `10000` | no | Request timeout in milliseconds. |
| `onLoad / onError` | `function` | — | no | Load callbacks. |
| `fallback` | `ReactNode` | — | no | Replaces the plain-link fallback when metadata fails. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `variant`: `inline`, `card`, `compact`
- `orientation`: `vertical`, `horizontal`
- `headingLevel`: `2`, `3`, `4`, `5`, `6`

## Accessibility

Every variant is a real link with a readable name; the hover card opens on focus too and only adds detail. Unavailable links (400, 404, 410) say so in their accessible name, and stats are read as "1.3K stars", not bare numbers.

## Notes

- The app owns fetching: Gaudi only calls an endpoint the app configures, never third-party pages, and derives no image URLs itself.
- usePreviewData caches responses (LRU, one hour; failures for a minute) and deduplicates concurrent requests.

## Related

- [Link](https://design.gaudi.site/docs/components/link): Link centralizes navigation semantics for internal, anchor, and external links.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Image](https://design.gaudi.site/docs/mdx/image): Image renders editorial MDX images with caption, dark-mode source, fallback source, and click-to-open modal behavior.

Source: https://design.gaudi.site/docs/components/link-preview (Markdown with example code: https://design.gaudi.site/docs/components/link-preview.md)

---

# WebPreview

> A framed browser for a live or generated page: back, forward and reload, an editable address bar, open in a new tab, device widths, a sandboxed iframe with a loading state, an optional console, and a link preview card when a site refuses framing.

- Category: Core · Media & Previews
- Import: `@gaudi/design-system/core/WebPreview` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/WebPreview/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-webpreview--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import WebPreview from '@gaudi/design-system/core/WebPreview';
```

## Usage

```jsx
import { WebPreview } from '@gaudi/design-system';

<>
<WebPreview
  defaultUrl='https://preview.example.dev/'
  srcDoc={(url) => generatedPages[url]}
  logs={logs}
  title='Generated landing page'
/>

{/* A site that refuses framing: the app knows from the headers. */}
<WebPreview defaultUrl='https://github.com/vercel/next.js' embeddable={false} />
</>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/core-webpreview--playground)
- [AI message with web preview](https://storybook.gaudi.site/index.html?path=/story/core-webpreview--ai-message-with-web-preview)
- [Blocked embed](https://storybook.gaudi.site/index.html?path=/story/core-webpreview--blocked-embed)
- [Controlled navigation](https://storybook.gaudi.site/index.html?path=/story/core-webpreview--controlled-navigation)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `url / defaultUrl` | `string` | `''` | no | Controlled or initial address. |
| `onUrlChange` | `(url) => void` | — | no | Called with each visited address. |
| `srcDoc` | `string \| (url) => string \| null` | — | no | Generated HTML instead of loading the address; a function serves several pages. |
| `title` | `string` | `Preview of <url>` | no | Accessible name of the framed page. |
| `device / defaultDevice` | `desktop \| tablet \| phone` | `desktop` | no | Frame width: full, 768px or 390px. Narrow screens scroll inside the frame. |
| `onDeviceChange` | `(device) => void` | — | no | Called with the chosen width. |
| `devices` | `boolean \| string[]` | `true` | no | Show the width toggle, or limit it. |
| `logs` | `Array<{ level, message, timestamp? }>` | — | no | Console entries; passing an array shows the console. |
| `defaultConsoleOpen` | `boolean` | `false` | no | Open the console initially. |
| `embeddable` | `boolean` | `true` | no | false replaces the frame with a LinkPreview card. |
| `previewData` | `object` | — | no | Metadata or endpoint for that fallback card. |
| `endpoint` | `string` | — | no | Metadata or endpoint for that fallback card. |
| `sandbox` | `string` | `allow-scripts allow-forms allow-popups allow-presentation allow-modals` | no | iframe sandbox; allow-same-origin is left out on purpose. |
| `actions` | `ReactNode` | — | no | Extra toolbar controls. |
| `labels` | `object` | `English` | no | Copy overrides. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

The toolbar is a labelled toolbar of named buttons, the address bar is a labelled text field that flags unusable input in an alert, the width toggle is a radio group, the iframe has a title, the body is aria-busy while loading, and the console is a disclosure over a role="log" list.

## Notes

- Compose WebPreviewRoot, WebPreviewNavigation, WebPreviewHistoryButtons, WebPreviewUrl, WebPreviewOpenButton, WebPreviewDevices, WebPreviewBody and WebPreviewConsole for a different toolbar.
- Browsers do not report blocked frames, so the app decides embeddable (for example from X-Frame-Options read by its preview endpoint).

## Related

- [LinkPreview](https://design.gaudi.site/docs/components/link-preview): A link enriched with what the destination is.
- [Embed](https://design.gaudi.site/docs/components/embed): The shared preview vocabulary for messages and content: one switch that hands each piece of content to its owner.

Source: https://design.gaudi.site/docs/components/web-preview (Markdown with example code: https://design.gaudi.site/docs/components/web-preview.md)

---

# EventCalendar

> Schedule events across day, week, month, agenda and resource views.

- Category: Core · Planning
- Import: `@gaudi/design-system/core/EventCalendar` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/EventCalendar/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-eventcalendar--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { EventCalendar } from '@gaudi/design-system/core/EventCalendar';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/event-calendar-all-views.json`.

## Usage

```jsx
import { useState } from 'react';
import { EventCalendar, EventCalendarNav, EventCalendarContent } from '@gaudi/design-system/core/EventCalendar';

const resources = [{ id: 'design', title: 'Design team' }];
const initialEvents = [{ id: 'review', title: 'Design review', resourceId: 'design', start: new Date(2026, 9, 5, 9, 15), end: new Date(2026, 9, 5, 10) }];

export function CalendarExample() {
  const [events, setEvents] = useState(initialEvents);
  return <EventCalendar events={events} onEventsChange={setEvents} resources={resources} defaultDate={new Date(2026, 9, 5)} defaultView='week' className='h-150'><EventCalendarNav /><EventCalendarContent /></EventCalendar>;
}
```

## Examples

### All views with live settings

Registry: `npx shadcn@latest add https://design.gaudi.site/r/event-calendar-all-views.json`

### Custom event chips

Registry: `npx shadcn@latest add https://design.gaudi.site/r/event-calendar-custom-chips.json`

### Drag-to-book appointments

Registry: `npx shadcn@latest add https://design.gaudi.site/r/event-calendar-drag-to-book.json`

### Create and edit dialog

Registry: `npx shadcn@latest add https://design.gaudi.site/r/event-calendar-edit-dialog.json`

### Resource view for room bookings

Registry: `npx shadcn@latest add https://design.gaudi.site/r/event-calendar-room-resources.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `calendar` | `EventCalendar instance` | — | no | Adopt a state instance created by useEventCalendarState. |
| `events / defaultEvents / onEventsChange` | `Event[] / function` | — | no | Controlled or initial events and updates. |
| `view / defaultView / onViewChange` | `string / function` | — | no | Active calendar view. |
| `date / defaultDate / onDateChange` | `Date / function` | — | no | Calendar navigation date. |
| `timeZone` | `string` | — | no | Date interpretation and localized labels. |
| `locale` | `Locale` | — | no | Date interpretation and localized labels. |
| `resources` | `Resource[]` | `[]` | no | Resource rows or columns. |
| `slotDuration / snapDuration` | `number` | `30 / 15` | no | Visible and drag increments in minutes. |
| `apiRef` | `MutableRefObject` | — | no | Imperative calendar API. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Keep event titles and times readable, provide keyboard alternatives to dragging, and announce changes through host feedback.

## Notes

- When calendar is supplied, configure options on that instance; option props on EventCalendar are ignored.

## Related

- [Calendar](https://design.gaudi.site/docs/components/calendar): Date selection for single dates, ranges, bookings and localized calendars.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.

Source: https://design.gaudi.site/docs/components/event-calendar (Markdown with example code: https://design.gaudi.site/docs/components/event-calendar.md)

---

# Flow

> A node-and-edge canvas for workflows, pipelines, agent trees and driver maps, themed with Gaudi tokens and built on React Flow.

- Category: Core · Planning
- Import: `@gaudi/design-system/core/Flow` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Flow/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-flow--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system @xyflow/react
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Flow } from '@gaudi/design-system/core/Flow';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/flow-agent-tree.json`.

## Usage

```jsx
import '@gaudi/design-system/flow.css';
import { Flow, layoutFlow } from '@gaudi/design-system/core/Flow';

const edges = [{ id: 'start-review', source: 'start', target: 'review' }];
const nodes = layoutFlow([
  { id: 'start', type: 'pill', data: { title: 'Draft ready', icon: 'FileText', target: false } },
  { id: 'review', type: 'step', data: { title: 'Editor review', status: 'running', meta: ['Due today'] } }
], edges);

<Flow label='Publishing pipeline' nodes={nodes} edges={edges} className='h-[32rem]' />
```

## Examples

### Agent tree with test run

Registry: `npx shadcn@latest add https://design.gaudi.site/r/flow-agent-tree.json`

### Automation workflow editor

Registry: `npx shadcn@latest add https://design.gaudi.site/r/flow-automation-editor.json`

### Growth impact map

Registry: `npx shadcn@latest add https://design.gaudi.site/r/flow-impact-map.json`

### Payments pipeline with an inspector

Registry: `npx shadcn@latest add https://design.gaudi.site/r/flow-payments-inspector.json`

### Pipeline run monitor

Registry: `npx shadcn@latest add https://design.gaudi.site/r/flow-pipeline-monitor.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | `Required` | no | Accessible name of the canvas region. |
| `nodes` | `Node[]` | — | no | Controlled graph. Pair with onNodesChange and onEdgesChange, or use useFlowHistory for undo and redo. |
| `edges` | `Edge[]` | — | no | Controlled graph. Pair with onNodesChange and onEdgesChange, or use useFlowHistory for undo and redo. |
| `defaultNodes` | `Node[]` | — | no | Uncontrolled graph for read-only or self-managed canvases. |
| `defaultEdges` | `Edge[]` | — | no | Uncontrolled graph for read-only or self-managed canvases. |
| `node.type` | `step \| pill \| tile \| task` | `step` | no | Card, compact pill, service tile with a run badge (round with data.shape circle, for satellites), or a one-line task card with an inline data.action. |
| `node.data.status` | `idle \| queued \| running \| success \| failed \| waiting \| blocked \| skipped` | — | no | Run state shown as a Badge, a tinted ring and the minimap colour; statusLabel overrides the text. |
| `node.data.outputs` | `{ id, label? }[]` | — | no | Named source handles for branches, and dashed attachment ports on any side. |
| `ports` | `{ id, label, position, type }[]` | — | no | Named source handles for branches, and dashed attachment ports on any side. |
| `edge.data` | `{ label, tone, status, variant, animated, path, emphasis, onInsert }` | — | no | Connector label, colour or run status, solid \| dashed \| dotted line, a flow toward the target, path shape and an insert button. |
| `background` | `dots \| lines \| cross \| none` | `dots` | no | Canvas pattern. |
| `controls / minimap` | `boolean` | `true / false` | no | Built-in zoom controls and the overview map. Render FlowControls yourself for the toolbar variant, Auto layout (onAutoLayout), Fit selection, select / pan tools and the issues count. |
| `summary` | `boolean` | `true` | no | Visually hidden count and step list that describe the graph without the canvas. |
| `labels` | `object` | `DEFAULT_FLOW_LABELS` | no | Every visible and announced string, including the toolbar, tool and issue labels. |
| `tool` | `select \| hand` | — | no | Select drags a selection box and pans with scroll; hand pans by dragging. |
| `onNodeActivate` | `(node, event) => void` | — | no | Called when a node is clicked or Enter is pressed on a focused node; use it to open a FlowInspector. |
| `FlowInspector` (sub-component) | `open, onOpenChange, nodeId, title, icon, status, tabs, callout, dirty, onSave, onCancel` | — | no | Side panel for the selected node: floats over the canvas and becomes a Sheet under 768px, with focus moving in and back to the node. |
| `layoutFlow(nodes, edges, options)` (helper) | `function` | `direction TB` | no | Layered layout (TB or LR) for tidy trees and driver maps, without another dependency. |
| `useFlowHistory({ nodes, edges, limit })` (helper) | `hook` | `limit 50` | no | Undo and redo that treat one drag as one step; commit() records edits made outside React Flow. |
| `topologicalOrder / createsCycle / hasEdge / unreachableNodes / descendants` | `function` | — | no | Dependency order with a cycle fallback, relink validation and reachability checks. |
| `Other props` (pass-through) | `ReactFlowProps` | — | no | Passed to React Flow, such as onConnect, onBeforeDelete, snapToGrid and onNodeContextMenu. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `node.type`: `step`, `pill`, `tile`, `task`
- `node.data.status`: `idle`, `queued`, `running`, `success`, `failed`, `waiting`, `blocked`, `skipped`
- `background`: `dots`, `lines`, `cross`, `none`
- `tool`: `select`, `hand`

## Accessibility

The canvas is a labelled region described by a step count, followed by a visually hidden list of every step and where it leads. Nodes and edges are focusable: Enter or Space selects, arrow keys move a selected node and Delete removes it, with React Flow announcing moves. Controls, menus and insert buttons are labelled; handles are pointer targets described by their node. Dragging is never the only way to edit: offer menus, toolbars or an inspector for the same actions.

## Notes

- Requires the @xyflow/react peer dependency; its structural CSS is imported inside the Gaudi stylesheet.
- React Flow does not provide a keyboard way to draw a new connection between handles; offer an inspector field or menu action for linking.
- Give the canvas an explicit height with className; it scrolls and zooms inside its own region.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [Sheet](https://design.gaudi.site/docs/components/sheet): A panel that slides in from an edge over a dimmed page, for side tasks such as settings, details, comments, notifications or an assistant, without leaving the current screen.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Breadcrumb](https://design.gaudi.site/docs/components/breadcrumb): Breadcrumb renders hierarchical page trails for navigation context.

Source: https://design.gaudi.site/docs/components/flow (Markdown with example code: https://design.gaudi.site/docs/components/flow.md)

---

# Gantt

> A timeline board for scheduled work, dependencies and resource planning.

- Category: Core · Planning
- Import: `@gaudi/design-system/core/Gantt` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/Gantt/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-gantt--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Gantt } from '@gaudi/design-system/core/Gantt';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/gantt-agent-playbook.json`.

## Usage

```jsx
import { useState } from 'react';
import { Gantt } from '@gaudi/design-system/core/Gantt';

const resources = [{ id: 'design', title: 'Design' }];
const initialTasks = [{ id: 'review', title: 'Design review', resourceId: 'design', start: new Date(2026, 9, 4), end: new Date(2026, 9, 6), allDay: true }];

export default function ProjectSchedule() {
  const [tasks, setTasks] = useState(initialTasks);
  return <Gantt events={tasks} onEventsChange={setTasks} resources={resources} defaultDate={new Date(2026, 9, 4)} defaultScale='week' />;
}
```

## Examples

### Agent playbook

Registry: `npx shadcn@latest add https://design.gaudi.site/r/gantt-agent-playbook.json`

### Baseline, dependencies and milestones

Registry: `npx shadcn@latest add https://design.gaudi.site/r/gantt-baselines-dependencies.json`

### Day dispatch

Registry: `npx shadcn@latest add https://design.gaudi.site/r/gantt-day-dispatch.json`

### Project planner with live validation

Registry: `npx shadcn@latest add https://design.gaudi.site/r/gantt-live-validation.json`

### Quarter roadmap with rollups

Registry: `npx shadcn@latest add https://design.gaudi.site/r/gantt-quarter-roadmap.json`

### Capacity-aware resource planner

Registry: `npx shadcn@latest add https://design.gaudi.site/r/gantt-resource-planner.json`

### Settings menu, row reordering and scheduling

Registry: `npx shadcn@latest add https://design.gaudi.site/r/gantt-settings-reordering.json`

### Task table with progress

Registry: `npx shadcn@latest add https://design.gaudi.site/r/gantt-task-table.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `calendar` | `Gantt state instance` | `Internal state` | no | Optionally adopt an instance created with useGanttState. |
| `events / defaultEvents / onEventsChange` | `Event[] / function` | `[] (uncontrolled)` | no | Scheduled work and host-owned updates. |
| `resources` | `Resource[]` | `[]` | no | Resource hierarchy used for board rows. |
| `scale / defaultScale / onScaleChange` | `GanttScale / function` | `day (uncontrolled)` | no | Controlled or initial timeline scale. |
| `date / defaultDate / onDateChange` | `Date / function` | `Current date (uncontrolled)` | no | Navigation date and changes. |
| `slotDuration / snapDuration` | `number` | `30 / 15` | no | Scheduling and drag increments in minutes. |
| `apiRef` | `MutableRefObject` | — | no | Imperative navigation and update API. |
| `GanttView.interval` | `number` | `60` | no | Time-grid interval in minutes, clamped from 15 to 240. |
| `GanttBar.segment` | `Gantt segment` | `Required` | no | Scheduled segment rendered by the bar. |
| `GanttScaleSwitcher.scales` | `Scale[]` | `GANTT_SCALES` | no | Available timeline scales. |
| `columns` | `{id, title, width, render}[]` | `[]` | no | Extra tree columns beside the row names, and the resizable split between tree and timeline. |
| `treePanel` | `{width, nameColumnWidth, minWidth, maxWidth, resizable}` | `200px, resizable` | no | Extra tree columns beside the row names, and the resizable split between tree and timeline. |
| `canDropEvent` | `fn(update) => boolean` | — | no | Validates a move or resize live; with enforceCanDrop a refused drop snaps back. |
| `enforceCanDrop` | `boolean` | `false` | no | Validates a move or resize live; with enforceCanDrop a refused drop snaps back. |
| `renderEvent / renderEventMenu / renderResourceLabel` | `fn(props) => ReactNode` | `Built-in bar` | no | Custom bar content such as booking cards, a right-click menu of ContextMenu items, and row labels. |
| `checkDependencies(update, events)` (helper) | `{ok, blockedBy, blocking}` | — | no | Finish-to-start check for a proposed move; pair it with canDropEvent. |
| `getCriticalPath(events)` (helper) | `string[]` | — | no | Task ids on the chain that drives the finish date. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Keep the timeline in its own scroll region. Provide labelled date navigation and preserve non-drag ways to inspect scheduled work.

## Notes

- When calendar is supplied, set state options on that instance. The Gantt root still accepts presentation settings, including dependency lines, baseline bars and row selection.

## Related

- [Navigation](https://design.gaudi.site/docs/blocks/navigation): The site header block: brand, primary NavigationMenu with a two-block Blog panel (categories beside recent posts) or a Categories panel on the supplied blog route, search, theme switch, and a phone sheet below lg.
- [Scheduling](https://design.gaudi.site/docs/blocks/scheduling): Scheduling building blocks on the Core Calendar and ToggleGroup: a calendar with per-day markers and a single-choice grid of time slots, plus time helpers.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.

Source: https://design.gaudi.site/docs/components/gantt (Markdown with example code: https://design.gaudi.site/docs/components/gantt.md)

---

# Kanban

> Move work items between columns while retaining an accessible move action.

- Category: Core · Planning
- Import: `@gaudi/design-system/core/KanbanBoard` (also `@gaudi/design-system/core`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/core/KanbanBoard/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/core-kanban--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Kanban } from '@gaudi/design-system/core/KanbanBoard';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/kanban-access-review.json`.

## Usage

```jsx
import KanbanBoard from '@gaudi/design-system/core/KanbanBoard';

<KanbanBoard columns={columns} items={tasks} onMove={moveTask} />
```

## Examples

### Pipeline and access review

Registry: `npx shadcn@latest add https://design.gaudi.site/r/kanban-access-review.json`

### Workflow with collapsible columns

Registry: `npx shadcn@latest add https://design.gaudi.site/r/kanban-collapsible-columns.json`

### Issue tracking

Registry: `npx shadcn@latest add https://design.gaudi.site/r/kanban-issue-tracking.json`

### Board options

Registry: `npx shadcn@latest add https://design.gaudi.site/r/kanban-options.json`

### Persisted to a backend

Registry: `npx shadcn@latest add https://design.gaudi.site/r/kanban-persisted.json`

### Recruiting pipeline

Registry: `npx shadcn@latest add https://design.gaudi.site/r/kanban-recruiting.json`

### Release readiness

Registry: `npx shadcn@latest add https://design.gaudi.site/r/kanban-release-readiness.json`

### Renewals risk

Registry: `npx shadcn@latest add https://design.gaudi.site/r/kanban-renewals-risk.json`

### Feature roadmap

Registry: `npx shadcn@latest add https://design.gaudi.site/r/kanban-roadmap.json`

### Support escalations

Registry: `npx shadcn@latest add https://design.gaudi.site/r/kanban-support-escalations.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `columns` | `Array<{ id, label, limit? }>` | `[]` | no | Board columns with stable IDs; limit adds a work-in-progress count that warns when exceeded. |
| `items` | `Array<{ id, columnId }>` | `[]` | no | Host-owned work items. |
| `renderItem` | `(item) => ReactNode` | — | no | Item card content. |
| `onMove` | `(itemId, columnId) => void` | — | no | Request a move; the application updates items. |
| `label / moveLabel / emptyLabel` | `string` | `Board / Move / No items` | no | Accessible board and action labels. |
| `disabled` | `boolean` | `false` | no | Disable moving items. |

## Accessibility

Every item has a move control so dragging is optional. Keep columns inside the contained horizontal scrolling region (layout="scroll" on the composition board). Collapsed rails are buttons that name the column and its count; cards with their own controls use withHandle so the drag grip, not the card, is the sortable control.

## Related

- [Item](https://design.gaudi.site/docs/components/item): Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Progress](https://design.gaudi.site/docs/components/progress): Determinate and indeterminate progress with a readable task label.

Source: https://design.gaudi.site/docs/components/kanban (Markdown with example code: https://design.gaudi.site/docs/components/kanban.md)

---

# Blocks

> Composed application blocks: app shells, auth and onboarding screens, dashboards, forms, scheduling, stat cards and wizards.

14 pages · 89 live examples, generated from the design system metadata.

## All

- [App Shell](https://design.gaudi.site/docs/blocks/app-shell): Application frames: a simple AppShell (rail or top bar, header, content, detail rail and status bar) and the Sidebar parts for collapsible icon rails, floating and inset sidebars, nested groups, secondary panels and right-hand inspectors.
- [Auth](https://design.gaudi.site/docs/blocks/auth): Sign-in, sign-up, magic-link, passkey and single sign-on screens: AuthForm handles the fields, feedback and providers, and Screen frames it beside imagery, quotes or logos.
- [Chat](https://design.gaudi.site/docs/blocks/chat): The chat frame: a shell for a full page or a sidebar assistant that composes the Chat parts: the thread, the composer, sessions, files, the plan and activity.
- [Dashboard](https://design.gaudi.site/docs/blocks/dashboard): Full dashboards composed from Stat Cards, Charts, DataTable and Core parts, on a grid that reflows by its own width, with a period toolbar for presets, a custom range and comparison.
- [Forms](https://design.gaudi.site/docs/blocks/forms): Form behaviour on the Core Field parts: validation with accessible errors, a summary that takes focus after a failed submit, values you edit in place and live character counts.
- [Navigation](https://design.gaudi.site/docs/blocks/navigation): The site header block: brand, primary NavigationMenu with a two-block Blog panel (categories beside recent posts) or a Categories panel on the supplied blog route, search, theme switch, and a phone sheet below lg. LayoutContainer renders it from menuProps.
- [Onboarding](https://design.gaudi.site/docs/blocks/onboarding): First-run flows: workspace setup, a publication with a progress rail, a product tour in a dialog and connecting a coding agent.
- [Profile](https://design.gaudi.site/docs/blocks/profile): Account and organisation pages for an application: profile details, organisation members and permissions, billing and usage, referrals, and connected mailboxes.
- [Scheduling](https://design.gaudi.site/docs/blocks/scheduling): Scheduling building blocks on the Core Calendar and ToggleGroup: a calendar with per-day markers and a single-choice grid of time slots, plus time helpers.
- [Screens](https://design.gaudi.site/docs/blocks/screens): Full-screen frames for sign-in, sign-up and onboarding: the main column beside an optional aside for imagery, quotes or logos, plus header and footer bands. Profile, settings, wizard, onboarding and auth examples compose it with AuthForm, Wizard and Core parts.
- [Settings](https://design.gaudi.site/docs/blocks/settings): Settings pages: preferences in collapsible sections, notification channels, integrations with connect toggles, and developer keys and webhooks.
- [Stat Cards](https://design.gaudi.site/docs/blocks/stat-cards): Metric cards on the Core Card: a label, value and change badge with optional icon tile, actions, description, footer and a segmented meter.
- [Wizard](https://design.gaudi.site/docs/blocks/wizard): A guided multi-step form with validation, progress and recoverable completion.

## Marketing

- [Heroes](https://design.gaudi.site/docs/blocks/heroes): Responsive hero sections for product, editorial, and marketing pages. One shared layout owns the heading, introduction, action group, and media; compose the slots with existing Gaudi components.

Source: https://design.gaudi.site/docs/blocks (Markdown with example code: https://design.gaudi.site/docs/blocks.md)

---

# App Shell

> Application frames: a simple AppShell (rail or top bar, header, content, detail rail and status bar) and the Sidebar parts for collapsible icon rails, floating and inset sidebars, nested groups, secondary panels and right-hand inspectors.

- Category: Blocks
- Import: `@gaudi/design-system/blocks/AppShell` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/AppShell/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/blocks-application-appshell--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import AppShell from '@gaudi/design-system/blocks/AppShell';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-crawler-control.json`.

## Usage

```jsx
import AppShell from '@gaudi/design-system/blocks/AppShell';

<AppShell brand={brand} navigation={navigation} header={header} aside={inspector}>
  <h1>Workspace overview</h1>
  {content}
</AppShell>
```

## Examples

### Capture console · icon rail, capture queue tabs and expandable run feeds

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-crawler-control.json`

### Dual sidebar · digest inbox, reading-plan panel and an author directory

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-digest-inbox.json`

### Finance dashboard · grouped sidebar, search and reports

A finance workspace with grouped navigation, search, revenue, visitor and product panels, customer filters and reports.

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-finance-dashboard.json`

### Icon rail · library switcher, nested collections and a reader menu

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-library-rail.json`

### Newsletter reader · library and topics sidebar, issue list, reading pane and a reading-tools rail

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-newsletter-reader.json`

### Mini icon rail · research notebooks with per-section pages and view tabs

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-notebook-tabs.json`

### Inset icon rail · per-section navigation, site, publication and environment switchers

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-publishing-console.json`

### Floating sidebar · header ⌘K search, reading queue and shelf switcher

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-reading-desk.json`

### Floating sidebar · library research assistant with answer modes, sources and cited replies

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-research-assistant.json`

### Inset sidebar · study progress rings, reading goal and a header notifications feed

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-research-projects.json`

### Source tile rail · workspace tabs, section tiles and a status-badged source tree

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-source-network.json`

### Resizable sidebar · reading-group study threads, notes tab and a header tutor picker

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-study-chat.json`

### Library top bar · circle and collection switchers, grouped routes and an apps grid

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-topbar-collections.json`

### Journal top bar · section pills, sidebar page search and an inset notifications sheet

Registry: `npx shadcn@latest add https://design.gaudi.site/r/app-shell-topbar-journal.json`

### Documentation sub-menus

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sidebar-docs-submenus.json`

### Search, loading and no-result states

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sidebar-filter-states.json`

### Collapsible icon rail

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sidebar-icon-rail.json`

### Details panel on the right

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sidebar-inspector.json`

### Workspace switcher

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sidebar-workspace-switcher.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `brand / navigation / header / footer` | `ReactNode` | — | no | Shell slots built from Gaudi components; footer sits at the foot of the rail. |
| `layout` | `sidebar \| topbar` | `sidebar` | no | A navigation rail, or brand and navigation in the header for sidebar-free apps. |
| `aside` | `ReactNode` | — | no | A complementary detail rail beside the content; it stacks below the content under xl. |
| `asideLabel` | `string` | `Details` | no | A complementary detail rail beside the content; it stacks below the content under xl. |
| `statusBar` | `ReactNode` | — | no | A status strip under the content, for sync state, counts or environment. |
| `navigationLabel` | `string` | `Workspace navigation` | no | Navigation landmark name. |
| `menuLabel / skipLabel` | `string` | `Open navigation / Skip to content` | no | Mobile trigger and skip-link labels. |
| `SidebarProvider.storageKey` | `string` | — | no | Restores and saves the expanded state in localStorage, after mount. |
| `SidebarProvider.shortcut` | `string \| false` | `b` | no | The ⌘/Ctrl key that toggles the sidebar; false turns it off. |
| `SidebarProvider.labels` | `{ expanded, collapsed, toggle }` | `English copy` | no | Announcements when the sidebar toggles, and the trigger name. |
| `Sidebar.variant` | `sidebar \| floating \| inset` | `sidebar` | no | Sidebar style, how it collapses and which edge it docks to; collapsed-row tooltips open toward the other edge. |
| `collapsible` | `offcanvas \| icon \| none` | `offcanvas` | no | Sidebar style, how it collapses and which edge it docks to; collapsed-row tooltips open toward the other edge. |
| `side` | `left \| right` | `inline start (left in LTR, right in RTL)` | no | Sidebar style, how it collapses and which edge it docks to; collapsed-row tooltips open toward the other edge. |
| `SidebarTrigger.label` | `string` | `Toggle Sidebar` | no | Trigger name and a tooltip showing the shortcut. |
| `tooltip` | `boolean` | `true` | no | Trigger name and a tooltip showing the shortcut. |
| `SidebarMenuButton.tooltip` | `string \| TooltipContent props` | — | no | Names the item on the collapsed icon rail. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `layout`: `sidebar`, `topbar`
- `collapsible`: `offcanvas`, `icon`, `none`
- `side`: `left`, `right`

## Accessibility

Preserve the skip link and main landmark (it leaves the tab order while a modal is open), and name each navigation and complementary region. Mark the current page with aria-current. The mobile drawer keeps focus inside while open and restores it on close; the trigger reports aria-expanded and its shortcut, and toggles are announced politely.

## Related

- [Navigation](https://design.gaudi.site/docs/blocks/navigation): The site header block: brand, primary NavigationMenu with a two-block Blog panel (categories beside recent posts) or a Categories panel on the supplied blog route, search, theme switch, and a phone sheet below lg.
- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Commander](https://design.gaudi.site/docs/components/commander): Commander provides the site command palette with host-supplied destinations for navigation, content search, and theme actions.
- [Breadcrumb](https://design.gaudi.site/docs/components/breadcrumb): Breadcrumb renders hierarchical page trails for navigation context.
- [Tooltip](https://design.gaudi.site/docs/components/tooltip): Brief contextual help attached to an independently labelled control.

Source: https://design.gaudi.site/docs/blocks/app-shell (Markdown with example code: https://design.gaudi.site/docs/blocks/app-shell.md)

---

# Auth

> Sign-in, sign-up, magic-link, passkey and single sign-on screens: AuthForm handles the fields, feedback and providers, and Screen frames it beside imagery, quotes or logos.

- Category: Blocks
- Import: `@gaudi/design-system/blocks/AuthForm` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/AuthForm/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/blocks-application-authform--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Auth from '@gaudi/design-system/blocks/AuthForm';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/screens-centred-card.json`.

## Usage

```jsx
import AuthForm from '@gaudi/design-system/blocks/AuthForm';

<AuthForm mode='password' onSubmit={signIn} />
```

## Examples

### Centred card

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-centred-card.json`

### Free trial sign-up

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-free-trial.json`

### Magic link with logos

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-magic-link.json`

### Choose a sign-in method

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-sign-in-methods.json`

### Split with imagery

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-split-imagery.json`

### Split with testimonials

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-split-testimonials.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `mode` | `password \| email \| signup` | `password` | no | Authentication form fields; email sends a sign-in link without a password, signup adds a name and a new password. Password fields have a reveal button. |
| `onSubmit` | `(values) => void \| Promise<void>` | — | no | Host-owned authentication request. |
| `title / submitLabel` | `string` | `Sign in` | no | Form heading and submission action. |
| `description / footer` | `ReactNode` | — | no | Instructions and related actions. |
| `nameLabel / emailLabel / passwordLabel` | `string` | `Full name / Email / Password` | no | Input labels. |
| `emailPlaceholder / passwordPlaceholder` | `string` | — | no | Optional example text inside the fields. |
| `passwordMinLength` | `number` | — | no | Optional host-defined native minimum; signup has no built-in password length policy. |
| `passwordHint` | `ReactNode \| false` | `Per mode` | no | Help text under the password field; false hides it. |
| `passwordAction` | `ReactNode` | — | no | A link beside the password label, such as Forgot password. |
| `identifier` | `email \| username` | `email` | no | Ask for an email, or a username that also accepts an email. |
| `providers` | `Array<{ id, label, icon }>` | — | no | Single sign-on buttons above the form, sharing its pending and error state. |
| `onProvider` | `(id) => void \| Promise<void>` | — | no | Single sign-on buttons above the form, sharing its pending and error state. |
| `providerLayout` | `grid \| stack` | `grid` | no | Provider buttons side by side or stacked, and the divider before the email fields. |
| `dividerLabel` | `string` | `or` | no | Provider buttons side by side or stacked, and the divider before the email fields. |
| `showPasswordLabel / hidePasswordLabel` | `string` | `Show password / Hide password` | no | Accessible names of the password reveal button, for translation. |
| `children` | `ReactNode` | — | no | Extra fields before the submit button, such as keep me signed in or terms. |
| `pendingLabel` | `string` | `Per mode` | no | Submit text while the request is pending. |
| `successMessage / errorMessage` | `string` | `Built-in feedback` | no | Submission result messages. |
| `Screen` (sub-component) | `component` | — | no | Full-screen frame: the form beside an optional aside, with header and footer bands. See the Screen frame example for its props. |

### Variants

- `mode`: `password`, `email`, `signup`
- `identifier`: `email`, `username`
- `providerLayout`: `grid`, `stack`

## Accessibility

Native labels and autocomplete support password managers; the password keeps its label and hint when revealed. Pending submissions and provider redirects share one guard so requests never overlap; errors retain the user’s values.

## Related

- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [Onboarding](https://design.gaudi.site/docs/blocks/onboarding): First-run flows: workspace setup, a publication with a progress rail, a product tour in a dialog and connecting a coding agent.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [InputOtp](https://design.gaudi.site/docs/components/input-otp): One-time code entry with grouped slots, paste support and completion feedback.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.

Source: https://design.gaudi.site/docs/blocks/auth (Markdown with example code: https://design.gaudi.site/docs/blocks/auth.md)

---

# Chat

> The chat frame: a shell for a full page or a sidebar assistant that composes the Chat parts: the thread, the composer, sessions, files, the plan and activity.

- Category: Blocks
- Import: `@gaudi/design-system/blocks/Chat` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/Chat/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/blocks-chat--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Chat from '@gaudi/design-system/blocks/Chat';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/chat-agent-activity.json`.

## Usage

```jsx
import { ChatShell } from '@gaudi/design-system/blocks/Chat';
import { ChatPlan, ChatSessionList, ChatMessageParts, ChatMessageScroller, ChatMessageScrollerContent, ChatMessageScrollerItem, ChatMessageScrollerProvider, ChatMessageScrollerViewport, ChatPromptComposer } from '@gaudi/design-system/chat';

<ChatMessageScrollerProvider autoScroll>
  <ChatShell
    title='Local-first drafts post'
    navigation={<ChatSessionList sessions={sessions} activeId={activeId} onSelect={openChat} onRename={rename} onDelete={remove} />}
    details={<ChatPlan steps={plan} />}
    composer={<ChatPromptComposer status={streaming ? 'streaming' : 'ready'} onSubmit={send} onStop={stop} />}
  >
    <ChatMessageScroller>
      <ChatMessageScrollerViewport aria-label='Conversation'>
        <ChatMessageScrollerContent>
          {turns.map((turn) => (
            <ChatMessageScrollerItem key={turn.id} messageId={turn.id} scrollAnchor={turn.role === 'user'}>
              <ChatMessageParts parts={turn.parts} streaming={turn.streaming} />
            </ChatMessageScrollerItem>
          ))}
        </ChatMessageScrollerContent>
      </ChatMessageScrollerViewport>
    </ChatMessageScroller>
  </ChatShell>
</ChatMessageScrollerProvider>
```

## Examples

### Agent at work: Plan and activity

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chat-agent-activity.json`

### Full page: Reviewing a pull request

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chat-pull-request-review.json`

### New chat: Welcome and suggestions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chat-welcome-suggestions.json`

### Sidebar: Writing assistant beside the editor

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chat-writing-assistant.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ChatShell.variant` | `page \| sidebar` | `page` | no | Page lays navigation, thread and details side by side from md and xl; sidebar is one narrow column. Side content moves into Sheets on narrow screens. |
| `ChatShell.title` | `string` | — | no | Conversation heading and actions. |
| `subtitle` | `string` | — | no | Conversation heading and actions. |
| `headerActions` | `ReactNode` | — | no | Conversation heading and actions. |
| `ChatShell.navigation / details / composer` | `ReactNode` | — | no | Side columns and the composer, filled with Chat parts such as ChatSessionList, ChatPlan and ChatPromptComposer. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

The thread owns its scrolling (ChatMessageScroller) so the page never scrolls, the header names the conversation, Sheets restore focus to the button that opened them, and every icon action has a label.

## Related

- [ChatSessionList](https://design.gaudi.site/docs/chat/chat-session-list): Session navigation inside a complete chat: grouped conversations with title search, new chat, rename and delete.
- [ChatMessageList](https://design.gaudi.site/docs/chat/chat-message-list): The conversation: a scroller that keeps the thread anchored and ChatMessageParts rendering each assistant turn from its parts.
- [ChatMessage](https://design.gaudi.site/docs/chat/chat-message): One turn in a conversation: avatar, sender and time, the content stack and a status footer.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [ChatInput](https://design.gaudi.site/docs/chat/chat-input): The composer: ChatPromptComposer with mentions, commands, attachments and send or stop; ChatPromptQueue; ChatModelSelect.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.

Source: https://design.gaudi.site/docs/blocks/chat (Markdown with example code: https://design.gaudi.site/docs/blocks/chat.md)

---

# Dashboard

> Full dashboards composed from Stat Cards, Charts, DataTable and Core parts, on a grid that reflows by its own width, with a period toolbar for presets, a custom range and comparison.

- Category: Blocks
- Import: `@gaudi/design-system/blocks/Dashboard` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/Dashboard/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/blocks-dashboard--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Dashboard from '@gaudi/design-system/blocks/Dashboard';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/dashboard-agent-analytics.json`.

## Usage

```jsx
import { DashboardGrid, DashboardPanel } from '@gaudi/design-system/blocks/Dashboard';

<DashboardGrid label='Overview'>
  <DashboardPanel title='Traffic' span={8}>{trafficChart}</DashboardPanel>
  <DashboardPanel title='Sources' span={4}>{sourceList}</DashboardPanel>
</DashboardGrid>
```

## Examples

### AI agents · Conversation analytics

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dashboard-agent-analytics.json`

### Commerce · Revenue

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dashboard-commerce-revenue.json`

### Creators · Payouts

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dashboard-creator-payouts.json`

### Project · Delivery timesheet

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dashboard-delivery-timesheet.json`

### Security · Edge telemetry

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dashboard-edge-security.json`

### Field teams · Coverage

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dashboard-field-coverage.json`

### Content · Newsletter analytics

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dashboard-newsletter-analytics.json`

### Operations · Capacity and exceptions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/dashboard-operations-capacity.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `DashboardGrid.label` | `string` | — | no | Names the dashboard region. |
| `DashboardPanel.span / spanMd / rowSpan` | `number` | `12 / derived / —` | no | Columns of twelve on wide containers, of six on medium ones, and rows to span. |
| `DashboardPanel.title / description / action / toolbar / footer` | `ReactNode` | — | no | Panel heading, help, header action, controls row and footer. |
| `DashboardPanel.scroll` | `x \| y \| both` | — | no | A labelled, focusable scroll region for wide tables and long lists. |
| `scrollLabel` | `string` | — | no | A labelled, focusable scroll region for wide tables and long lists. |
| `maxHeight` | `CSS length` | — | no | A labelled, focusable scroll region for wide tables and long lists. |
| `dashboardSpan(span, spanMd, rowSpan)` (helper) | `function` | — | no | Grid placement classes for any child, such as a StatCard. |
| `DashboardToolbar.period / defaultPeriod / onPeriodChange` | `string / function` | `30d` | no | Active preset, or custom. |
| `DashboardToolbar.range / defaultRange / onRangeChange` | `{ from, to } / function` | — | no | Custom date range from the calendar. |
| `DashboardToolbar.compare / defaultCompare / onCompareChange` | `boolean / function` | `false` | no | Compare with the previous period. |
| `DashboardToolbar.onChange` | `(period) => void` | — | no | Resolved { period, from, to, days, previous, compare } on every change. |
| `DashboardToolbar.periods` | `Period[]` | `DEFAULT_DASHBOARD_PERIODS` | no | Presets, optional controls, the end date and copy. |
| `allowCustom` | `boolean` | `true` | no | Presets, optional controls, the end date and copy. |
| `showCompare` | `boolean` | `true` | no | Presets, optional controls, the end date and copy. |
| `today` | `Date` | `now` | no | Presets, optional controls, the end date and copy. |
| `labels` | `object` | `English` | no | Presets, optional controls, the end date and copy. |
| `resolveDashboardPeriod(period, options)` (helper) | `function` | — | no | The dates a period covers and the equally long period before it. |

## Accessibility

The grid and each panel are named regions; panel titles are headings. Scrolling panel bodies take focus so the keyboard can scroll them. The toolbar presets are a single-choice group, the calendar opens in a popover, and the active range is announced politely.

## Related

- [DataTable](https://design.gaudi.site/docs/components/data-table): DataTable is a TanStack table with a compact data anatomy: shared headers that preserve label casing, hairline rows, synced column and row hover, a tinted wash for selected rows, and declarative column alignment, width and pinning.
- [Tabs](https://design.gaudi.site/docs/components/tabs): Switch between related panels with keyboard-accessible tab controls.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Stat Cards](https://design.gaudi.site/docs/blocks/stat-cards): Metric cards on the Core Card: a label, value and change badge with optional icon tile, actions, description, footer and a segmented meter.
- [Table](https://design.gaudi.site/docs/mdx/table): Semantic article tables with contained horizontal scrolling.
- [Progress](https://design.gaudi.site/docs/components/progress): Determinate and indeterminate progress with a readable task label.

Source: https://design.gaudi.site/docs/blocks/dashboard (Markdown with example code: https://design.gaudi.site/docs/blocks/dashboard.md)

---

# Forms

> Form behaviour on the Core Field parts: validation with accessible errors, a summary that takes focus after a failed submit, values you edit in place and live character counts.

- Category: Blocks
- Import: `@gaudi/design-system/blocks/Forms` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/Forms/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/blocks-forms--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Forms from '@gaudi/design-system/blocks/Forms';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/forms-api-key.json`.

## Usage

```jsx
import { FormErrorSummary, useFormValidation, validators } from '@gaudi/design-system/blocks/Forms';
import Button from '@gaudi/design-system/core/Button';
import { EmailInput } from '@gaudi/design-system/core/Input';

function ContactForm() {
  const form = useFormValidation({
    initialValues: { email: '' },
    rules: { email: [validators.required('Enter an email.'), validators.email()] }
  });
  return <form onSubmit={form.handleSubmit(saveContact)}>
    <FormErrorSummary form={form} labels={{ email: 'Email' }} />
    <EmailInput aria-label='Email' {...form.field('email')} />
    <Button type='submit'>Save contact</Button>
  </form>;
}
```

## Examples

### Developer · Create an API key

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-api-key.json`

### Launch · New app with live summary

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-app-launch.json`

### Feedback · Article survey

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-article-feedback.json`

### Compliance · Business verification

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-business-verification.json`

### Checkout · Address and payment

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-checkout.json`

### Contact · Message with error summary

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-contact.json`

### Onboarding · Customer intake

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-customer-intake.json`

### Events · Registration with email code

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-event-registration.json`

### Billing · Hosted checkout setup

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-hosted-checkout.json`

### Billing · Invoice with line items

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-invoice.json`

### Commerce · New product

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-new-product.json`

### Newsletter · Signup and preferences

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-newsletter.json`

### Profile · Card with completion and office hours

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-profile-card.json`

### Profile · Tabs with audit rail

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-profile-tabs.json`

### Security · Sign-in policy

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-sign-in-policy.json`

### Support · Ticket details

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-support-ticket.json`

### Team · Invite with permissions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/forms-team-invite.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `useFormValidation({ initialValues, rules, validateOn })` (helper) | `hook` | `validateOn 'blur'` | no | Values, errors and handlers. Rules map a field name to one validator or a list, run in order; errors show on blur or submit and re-check as the person types. |
| `form.field(name, { describedBy })` (helper) | `props` | — | no | id, name, value, onChange, onBlur, aria-invalid and aria-describedby for a text-like control. |
| `form.setValue / setValues / handleSubmit / reset` | `functions` | — | no | Update values, block invalid submits (onValid receives the values) and restore a state. |
| `validators` | `required \| email \| minLength \| maxLength \| pattern \| min \| max` | — | no | Message-returning validators; custom rules receive (value, values). |
| `FormErrorSummary.form` | `form` | — | no | Lists errors after a submit, takes focus and links each entry to its control. |
| `labels` | `Record<name, string>` | — | no | Lists errors after a submit, takes focus and links each entry to its control. |
| `title` | `string` | — | no | Lists errors after a submit, takes focus and links each entry to its control. |
| `EditableField.label` | `string` | — | no | A label and value with Edit; Save calls onSave and closes, a thrown error keeps it open. |
| `value` | `any` | — | no | A label and value with Edit; Save calls onSave and closes, a thrown error keeps it open. |
| `onSave` | `(value) => void \| Promise` | — | no | A label and value with Edit; Save calls onSave and closes, a thrown error keeps it open. |
| `EditableField.validate / format / renderControl` | `function` | — | no | Message for an invalid draft, how the value reads, and a custom control instead of Input. |
| `CharacterCount.value` | `string` | — | no | Remaining characters, announced politely near the limit; reference the id from aria-describedby. |
| `max` | `number` | — | no | Remaining characters, announced politely near the limit; reference the id from aria-describedby. |
| `id` | `string` | — | no | Remaining characters, announced politely near the limit; reference the id from aria-describedby. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `validators`: `required`, `email`, `minLength`, `maxLength`, `pattern`, `min`, `max`

## Accessibility

Errors sit next to their control, are linked with aria-describedby and mark it aria-invalid. The summary is an alert that receives focus and moves focus to a field from each link. EditableField returns focus to Edit after Save, Cancel or Escape.

## Notes

- Lay out rows with FieldGroup and Field orientation=responsive; Forms adds behaviour, not layout.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [NumberField](https://design.gaudi.site/docs/components/number-field): Numeric entry with increment buttons, bounds, locale formatting and scrubbing.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Banner](https://design.gaudi.site/docs/components/banner): Banner renders a compact announcement strip.

Source: https://design.gaudi.site/docs/blocks/forms (Markdown with example code: https://design.gaudi.site/docs/blocks/forms.md)

---

# Navigation

> The site header block: brand, primary NavigationMenu with a two-block Blog panel (categories beside recent posts) or a Categories panel on the supplied blog route, search, theme switch, and a phone sheet below lg.

LayoutContainer renders it from menuProps.

- Category: Blocks
- Import: `@gaudi/design-system/blocks/Navigation` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/Navigation/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/blocks-navigation--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Navigation from '@gaudi/design-system/blocks/Navigation';
```

## Usage

```jsx
import { Menu } from '@gaudi/design-system';

<Menu blogLink={blogLink} categories={categories} posts={posts} logo={<img src='/logo.svg' alt='' className='size-10' />} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/blocks-navigation--playground)
- [Blog Route](https://storybook.gaudi.site/index.html?path=/story/blocks-navigation--blog-route)
- [Custom logo](https://storybook.gaudi.site/index.html?path=/story/blocks-navigation--custom-logo-slot)
- [Phone Sheet](https://storybook.gaudi.site/index.html?path=/story/blocks-navigation--phone-sheet)
- [Search Handoff](https://storybook.gaudi.site/index.html?path=/story/blocks-navigation--search-handoff)
- [Search trigger](https://storybook.gaudi.site/index.html?path=/story/blocks-navigation--search-trigger)
- [Apple-style mega menu](https://storybook.gaudi.site/index.html?path=/story/blocks-navigation--apple-style)
- [Scroll-merging header](https://storybook.gaudi.site/index.html?path=/story/blocks-navigation--merging-header)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `blogLink` | `{ href, title }` | — | no | Prepared destination that enables the blog panel and identifies its current route. |
| `categories` | `Array<{ id, href, title, description }>` | `[]` | no | Blog or Categories panel and phone sheet destinations. |
| `posts` | `Array<{ id?, slug?, href, title, date }>` | `[]` | no | The newest three appear in Recent posts; all are searchable. |
| `projects / publications / tags / thoughts` | `Array` | `[]` | no | Command launcher search records. |
| `logo` | `ReactNode` | `Gaudi brand mark` | no | Brand inside the home link; the link is named by the SiteConfig author or title. |
| `MenuSearch.setOpen` | `(open: boolean) => void` | — | no | Exported search entry for custom headers; opens Commander. |

## Accessibility

One Main navigation landmark with real links and aria-current on the current destination. Panels close on Escape (focus returns to the trigger) or an outside click. The phone sheet is a named modal dialog that takes focus, closes on Escape or Close and returns focus to the menu button; search closes it before the launcher opens.

## Notes

- Site links come from SiteConfig navigation.links; showInPath and hideInPath filter them per route.
- The phone sheet and brand mark are private parts; replace the mark through logo.
- The Apple-style mega menu example composes public navigation, dialog, and accordion parts with a full-width hover panel, a mobile disclosure menu, and reduced-motion support.
- The Scroll-merging header example moves the section tabs alongside the brand as its contained workspace scrolls; reduced motion keeps a compact header.

## Related

- [NavigationMenu](https://design.gaudi.site/docs/components/navigation-menu): NavigationMenu renders grouped site navigation with dropdown panels for categories, sections, and related destinations.
- [LayoutContainer](https://design.gaudi.site/docs/layout/layout-container): Async server layout that composes theme context, navigation, a skip link, article content, footer, and host-provided structured data.
- [Commander](https://design.gaudi.site/docs/components/commander): Commander provides the site command palette with host-supplied destinations for navigation, content search, and theme actions.

Source: https://design.gaudi.site/docs/blocks/navigation (Markdown with example code: https://design.gaudi.site/docs/blocks/navigation.md)

---

# Onboarding

> First-run flows: workspace setup, a publication with a progress rail, a product tour in a dialog and connecting a coding agent.

- Category: Blocks
- Import: `@gaudi/design-system/blocks/Screens` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/Screens/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/blocks-onboarding--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Onboarding from '@gaudi/design-system/blocks/Screens';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/screens-coding-agent.json`.

## Usage

```jsx
import Wizard from '@gaudi/design-system/blocks/Wizard';

<Wizard title='Set up your workspace' steps={steps} onComplete={createWorkspace}>
  {stepIndex => panels[steps[stepIndex].id]}
</Wizard>
```

## Examples

### Connect a coding agent

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-coding-agent.json`

### Tour in a dialog

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-dialog-tour.json`

### Create a publication

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-new-publication.json`

### Workspace setup

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-workspace-setup.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `Wizard` (sub-component) | `Blocks/Wizard` | — | no | Steps, validation and progress for multi-step setup. |
| `Field / RadioGroup / ToggleGroup / Switch` (sub-component) | `Core form parts` | — | no | Choices for each step with visible labels. |
| `Dialog / Carousel` (sub-component) | `Core overlays` | — | no | Tours that walk through features one slide at a time. |
| `EmptyState / CodeBlock / Kbd` (sub-component) | `Core display` | — | no | First-run guidance, install commands and shortcuts. |

## Accessibility

Let people skip or come back to optional steps, keep focus on the step heading when it changes, and never trap focus outside a dialog tour.

## Related

- [Profile](https://design.gaudi.site/docs/blocks/profile): Account and organisation pages for an application: profile details, organisation members and permissions, billing and usage, referrals, and connected mailboxes.
- [Settings](https://design.gaudi.site/docs/blocks/settings): Settings pages: preferences in collapsible sections, notification channels, integrations with connect toggles, and developer keys and webhooks.
- [Screens](https://design.gaudi.site/docs/blocks/screens): Full-screen frames for sign-in, sign-up and onboarding: the main column beside an optional aside for imagery, quotes or logos, plus header and footer bands.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.

Source: https://design.gaudi.site/docs/blocks/onboarding (Markdown with example code: https://design.gaudi.site/docs/blocks/onboarding.md)

---

# Profile

> Account and organisation pages for an application: profile details, organisation members and permissions, billing and usage, referrals, and connected mailboxes.

- Category: Blocks
- Import: `@gaudi/design-system/blocks/Screens` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/Screens/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/blocks-profile--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Profile from '@gaudi/design-system/blocks/Screens';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/screens-account-settings.json`.

## Usage

```jsx
import { Screen } from '@gaudi/design-system/blocks/Screens';
import Avatar from '@gaudi/design-system/core/Avatar';

<Screen>
  <Avatar src={person.avatar} name={person.name} />
  <h1>{person.name}</h1>
  {profileContent}
</Screen>
```

## Examples

### Account settings

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-account-settings.json`

### Billing

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-billing.json`

### Inbox and meeting capture

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-inbox-capture.json`

### Organisation tabs

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-organisation-tabs.json`

### Referral rewards

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-referral-rewards.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `Tabs / Accordion` (sub-component) | `Core navigation` | — | no | Switch between profile panels; collapsible groups on narrow layouts. |
| `Field / Input / Select / Switch` (sub-component) | `Core form parts` | — | no | Editable profile and organisation settings with visible labels. |
| `Avatar / Pill / FileUpload` (sub-component) | `Core display parts` | — | no | People, roles, statuses and the profile photo upload. |
| `Progress / StatCard` (sub-component) | `Usage meters` | — | no | Plan usage, quotas and referral tiers. |

## Accessibility

Each panel keeps one heading level, labels every control, and announces saved or failed changes next to the form.

## Related

- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.
- [Onboarding](https://design.gaudi.site/docs/blocks/onboarding): First-run flows: workspace setup, a publication with a progress rail, a product tour in a dialog and connecting a coding agent.
- [Settings](https://design.gaudi.site/docs/blocks/settings): Settings pages: preferences in collapsible sections, notification channels, integrations with connect toggles, and developer keys and webhooks.
- [Screens](https://design.gaudi.site/docs/blocks/screens): Full-screen frames for sign-in, sign-up and onboarding: the main column beside an optional aside for imagery, quotes or logos, plus header and footer bands.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Table](https://design.gaudi.site/docs/mdx/table): Semantic article tables with contained horizontal scrolling.

Source: https://design.gaudi.site/docs/blocks/profile (Markdown with example code: https://design.gaudi.site/docs/blocks/profile.md)

---

# Scheduling

> Scheduling building blocks on the Core Calendar and ToggleGroup: a calendar with per-day markers and a single-choice grid of time slots, plus time helpers.

- Category: Blocks
- Import: `@gaudi/design-system/blocks/Scheduling` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/Scheduling/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/blocks-scheduling--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Scheduling from '@gaudi/design-system/blocks/Scheduling';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/scheduling-book-meeting.json`.

## Usage

```jsx
import { TimeSlots, timeSlots } from '@gaudi/design-system/blocks/Scheduling';

<TimeSlots
  slots={timeSlots({ start: '09:00', end: '17:00', step: 30, duration: 30 })}
  unavailable={bookedTimes}
  value={selectedTime}
  onValueChange={setSelectedTime}
/>
```

## Examples

### Book a meeting

Registry: `npx shadcn@latest add https://design.gaudi.site/r/scheduling-book-meeting.json`

### Create a schedule

Registry: `npx shadcn@latest add https://design.gaudi.site/r/scheduling-create-schedule.json`

### Date and time popover

Registry: `npx shadcn@latest add https://design.gaudi.site/r/scheduling-date-time-popover.json`

### Day agenda

Registry: `npx shadcn@latest add https://design.gaudi.site/r/scheduling-day-agenda.json`

### Month at a glance

Registry: `npx shadcn@latest add https://design.gaudi.site/r/scheduling-month-overview.json`

### Plan a meeting

Registry: `npx shadcn@latest add https://design.gaudi.site/r/scheduling-plan-meeting.json`

### Webinar details and RSVP

Registry: `npx shadcn@latest add https://design.gaudi.site/r/scheduling-webinar-rsvp.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ScheduleCalendar.markers` | `Record<YYYY-MM-DD, tone[]>` | `{}` | no | Up to three dots per day; build keys with dayKey(date). |
| `ScheduleCalendar.markerLabel` | `(tones) => string` | `n events` | no | Screen-reader text for a marked day. |
| `TimeSlots.slots` | `string[]` | `[]` | no | HH:MM start times, usually from timeSlots(). |
| `TimeSlots.value / defaultValue / onValueChange` | `string / (slot) => void` | — | no | Controlled or initial selected slot. |
| `TimeSlots.unavailable` | `string[]` | `[]` | no | Booked slots: listed but disabled. |
| `TimeSlots.hour12` | `boolean` | `false` | no | Clock format and grid columns. |
| `columns` | `1 \| 2 \| 3 \| 4` | `3` | no | Clock format and grid columns. |
| `timeSlots({ start, end, step, duration })` (helper) | `helper` | `09:00–17:00 every 30` | no | Start times where the whole meeting fits before end. |
| `formatTime / formatDuration / addMinutes / minutesBetween` | `helpers` | — | no | Format and calculate HH:MM times and durations. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `columns`: `1`, `2`, `3`, `4`

## Accessibility

Marked days add their marker label to the day button name; time slots are a radio group with arrow-key navigation and disabled booked times.

## Notes

- Pass every other Calendar prop (mode, selected, disabled) straight to ScheduleCalendar.

## Related

- [Calendar](https://design.gaudi.site/docs/components/calendar): Date selection for single dates, ranges, bookings and localized calendars.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [Attachment](https://design.gaudi.site/docs/components/attachment): File attachments with metadata, previews, actions and upload states.
- [Popover](https://design.gaudi.site/docs/components/popover): Popover renders compact positioned supporting content next to its trigger.

Source: https://design.gaudi.site/docs/blocks/scheduling (Markdown with example code: https://design.gaudi.site/docs/blocks/scheduling.md)

---

# Screens

> Full-screen frames for sign-in, sign-up and onboarding: the main column beside an optional aside for imagery, quotes or logos, plus header and footer bands.

Profile, settings, wizard, onboarding and auth examples compose it with AuthForm, Wizard and Core parts.

- Category: Blocks
- Import: `@gaudi/design-system/blocks/Screens` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/Screens/

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Screens from '@gaudi/design-system/blocks/Screens';
```

## Usage

```jsx
import { Screen } from '@gaudi/design-system/blocks/Screens';

<Screen>{pageContent}</Screen>
```

## Examples

Examples (rendered from Storybook):



## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `aside` | `ReactNode` | — | no | Panel beside the main column; hidden below md so the form comes first on phones. |
| `asideSide` | `start \| end` | `end` | no | Which side the aside sits on from md up. |
| `asideClassName` | `string` | — | no | Classes for the aside panel, such as a surface or backdrop. |
| `header / footer` | `ReactNode` | — | no | Bands above and below the main column for a logo, account links, legal links or customer logos. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |
| `ScreenTestimonial.quotes` | `Array<{ quote, name, role, avatar? }>` | `[]` | no | Customer quotes; more than one rotates. |
| `ScreenTestimonial.rating / interval` | `number` | `— / 6000` | no | Optional star rating and rotation delay in milliseconds. |

### Variants

- `asideSide`: `start`, `end`

## Accessibility

The main column always renders first in reading order. Rotating quotes pause on hover, focus and reduced motion, and their dots are 24px targets that name each quote.

## Notes

- Screens frame flows the host owns; authentication, validation and saving stay in AuthForm, Wizard and the consuming app.

## Related

- [Profile](https://design.gaudi.site/docs/blocks/profile): Account and organisation pages for an application: profile details, organisation members and permissions, billing and usage, referrals, and connected mailboxes.
- [Wizard](https://design.gaudi.site/docs/blocks/wizard): A guided multi-step form with validation, progress and recoverable completion.
- [Onboarding](https://design.gaudi.site/docs/blocks/onboarding): First-run flows: workspace setup, a publication with a progress rail, a product tour in a dialog and connecting a coding agent.
- [Settings](https://design.gaudi.site/docs/blocks/settings): Settings pages: preferences in collapsible sections, notification channels, integrations with connect toggles, and developer keys and webhooks.

Source: https://design.gaudi.site/docs/blocks/screens (Markdown with example code: https://design.gaudi.site/docs/blocks/screens.md)

---

# Settings

> Settings pages: preferences in collapsible sections, notification channels, integrations with connect toggles, and developer keys and webhooks.

- Category: Blocks
- Import: `@gaudi/design-system/blocks/Screens` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/Screens/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/blocks-settings--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Settings from '@gaudi/design-system/blocks/Screens';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/screens-developer.json`.

## Usage

```jsx
import { Screen } from '@gaudi/design-system/blocks/Screens';
import Button from '@gaudi/design-system/core/Button';

<Screen>
  <h1>Account settings</h1>
  <form onSubmit={saveSettings}>
    {settingsFields}
    <Button type='submit'>Save settings</Button>
  </form>
</Screen>
```

## Examples

### Developer

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-developer.json`

### Integrations

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-integrations.json`

### Notifications

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-notifications.json`

### Preferences

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-preferences.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `Accordion / Tabs` (sub-component) | `Core navigation` | — | no | Group related settings; sections stay reachable by keyboard. |
| `Switch / Checkbox / Select / ToggleGroup` (sub-component) | `Core form parts` | — | no | One control per row with its label and help text. |
| `Banner / Pill` (sub-component) | `Status` | — | no | Plan badges, integration status and webhook health. |
| `CodeBlock` (sub-component) | `Core display` | — | no | Copyable keys, endpoints and payload samples. |

## Accessibility

Pair every switch with a visible label and description, and confirm destructive actions such as revoking a key.

## Related

- [Onboarding](https://design.gaudi.site/docs/blocks/onboarding): First-run flows: workspace setup, a publication with a progress rail, a product tour in a dialog and connecting a coding agent.
- [Profile](https://design.gaudi.site/docs/blocks/profile): Account and organisation pages for an application: profile details, organisation members and permissions, billing and usage, referrals, and connected mailboxes.
- [Screens](https://design.gaudi.site/docs/blocks/screens): Full-screen frames for sign-in, sign-up and onboarding: the main column beside an optional aside for imagery, quotes or logos, plus header and footer bands.
- [Table](https://design.gaudi.site/docs/mdx/table): Semantic article tables with contained horizontal scrolling.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Accordion](https://design.gaudi.site/docs/components/accordion): Rich disclosure for FAQs, settings, member directories, nested help, and guided setup.

Source: https://design.gaudi.site/docs/blocks/settings (Markdown with example code: https://design.gaudi.site/docs/blocks/settings.md)

---

# Stat Cards

> Metric cards on the Core Card: a label, value and change badge with optional icon tile, actions, description, footer and a segmented meter.

- Category: Blocks
- Import: `@gaudi/design-system/blocks/StatCard` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/StatCard/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/blocks-stat-cards--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import StatCards from '@gaudi/design-system/blocks/StatCard';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/stat-card-balance.json`.

## Usage

```jsx
import { StatCard } from '@gaudi/design-system/blocks/StatCard';

<StatCard label='Subscribers' value='4,180' delta='+8.4%' deltaDirection='up' deltaTone='success' />
```

## Examples

### Balance

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stat-card-balance.json`

### Breakdowns

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stat-card-breakdowns.json`

### Hero metrics

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stat-card-hero.json`

### KPI overview

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stat-card-kpi-overview.json`

### Leads with a range

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stat-card-lead-range.json`

### Quota and progress

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stat-card-quota.json`

### Revenue breakdown

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stat-card-revenue.json`

### Support metrics

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stat-card-support.json`

### Team performance

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stat-card-team-performance.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label / value` | `ReactNode` | — | no | Metric name and its prepared value. |
| `delta` | `string \| number` | — | no | Change in your formatting, including its sign and zero. |
| `deltaDirection` | `up \| down \| flat` | — | no | Explicit arrow and semantic colour; the host decides what the change means. |
| `deltaTone` | `semantic tone` | `neutral` | no | Explicit arrow and semantic colour; the host decides what the change means. |
| `icon` | `string` | — | no | Icon tile and its colour. |
| `tone` | `neutral \| accent \| info \| success \| warning \| danger \| discovery \| attention` | `neutral` | no | Icon tile and its colour. |
| `variant` | `default \| tinted \| inverse` | `default` | no | Card, colour block in tone, or dark surface. |
| `action` | `ReactNode` | — | no | Header slot, usually a menu, range switch or status badge. |
| `description / footer` | `ReactNode` | — | no | Comparison line and footer text. |
| `StatMeter.segments` | `Array<{ label, value, tone }>` | `[]` | no | Segmented bar with a legend of values and shares. |
| `StatDelta.value` | `string \| number` | — | no | Standalone change badge with explicit presentation and unchanged value. |
| `direction` | `up \| down \| flat` | — | no | Standalone change badge with explicit presentation and unchanged value. |
| `tone` | `semantic tone` | `neutral` | no | Standalone change badge with explicit presentation and unchanged value. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `deltaDirection`: `up`, `down`, `flat`
- `tone`: `neutral`, `accent`, `info`, `success`, `warning`, `danger`, `discovery`, `attention`
- `variant`: `default`, `tinted`, `inverse`
- `direction`: `up`, `down`, `flat`

## Accessibility

Change badges announce their direction (Up, Down, Unchanged) and never rely on colour alone; meters are decorative bars backed by a text legend.

## Notes

- Values are prepared by the host; StatCard never formats or infers data.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Icon](https://design.gaudi.site/docs/components/icon): Static and interactive artwork from Gaudi’s centralized icon registry.
- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Progress](https://design.gaudi.site/docs/components/progress): Determinate and indeterminate progress with a readable task label.

Source: https://design.gaudi.site/docs/blocks/stat-cards (Markdown with example code: https://design.gaudi.site/docs/blocks/stat-cards.md)

---

# Wizard

> A guided multi-step form with validation, progress and recoverable completion.

- Category: Blocks
- Import: `@gaudi/design-system/blocks/Wizard` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/Wizard/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/blocks-application-wizard--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Wizard from '@gaudi/design-system/blocks/Wizard';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/screens-add-product.json`.

## Usage

```jsx
import Wizard from '@gaudi/design-system/blocks/Wizard';

<Wizard steps={steps} validateStep={validateStep} onComplete={save}>
  {stepIndex => steps[stepIndex].id === 'details' ? detailsForm : review}
</Wizard>
```

## Examples

### Add a product

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-add-product.json`

### Plan upgrade

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-plan-upgrade.json`

### Send an invoice

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-send-invoice.json`

### Send money

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-send-money.json`

### Invite your team

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-team-invite.json`

### Vendor onboarding

Registry: `npx shadcn@latest add https://design.gaudi.site/r/screens-vendor-onboarding.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `steps` | `Array<{ id, label, description? }>` | `[]` | no | Ordered steps. |
| `children` | `ReactNode \| (activeIndex: number) => ReactNode` | — | no | Render content or fields for the zero-based active step. |
| `validateStep` | `function` | — | no | Validate before allowing the next step. |
| `onComplete` | `function \| async function` | — | no | Commit the completed flow. |
| `title / description` | `ReactNode` | — | no | Flow heading and instructions. |
| `completeLabel / completionTitle` | `string` | `Finish / All set` | no | Final action and completion heading. |
| `completionDescription / errorMessage / validationMessage` | `string` | `Built-in feedback` | no | Completion and recoverable failure text. |
| `labels` | `Record<string, string>` | `{}` | no | Navigation labels. |
| `indicator` | `steps \| progress \| dots \| vertical` | `steps` | no | Numbered steps, a progress bar, compact dots, or a vertical step list beside the form. |
| `aside` | `ReactNode \| (activeIndex, complete) => ReactNode` | — | no | A live summary or preview beside the form. |
| `navigable` | `boolean` | `false` | no | Let people jump back to any completed step; steps ahead stay behind validation. |
| `completion` | `ReactNode` | — | no | Replaces the default finished state, e.g. a celebration with next actions. |

### Variants

- `indicator`: `steps`, `progress`, `dots`, `vertical`

## Accessibility

Announce the active step, errors and completion. Keep entered values when validation or saving fails.

## Related

- [Flow](https://design.gaudi.site/docs/components/flow): A node-and-edge canvas for workflows, pipelines, agent trees and driver maps, themed with Gaudi tokens and built on React Flow.
- [Navigation](https://design.gaudi.site/docs/blocks/navigation): The site header block: brand, primary NavigationMenu with a two-block Blog panel (categories beside recent posts) or a Categories panel on the supplied blog route, search, theme switch, and a phone sheet below lg.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [Table](https://design.gaudi.site/docs/mdx/table): Semantic article tables with contained horizontal scrolling.
- [NumberField](https://design.gaudi.site/docs/components/number-field): Numeric entry with increment buttons, bounds, locale formatting and scrubbing.

Source: https://design.gaudi.site/docs/blocks/wizard (Markdown with example code: https://design.gaudi.site/docs/blocks/wizard.md)

---

# Heroes

> Responsive hero sections for product, editorial, and marketing pages.

One shared layout owns the heading, introduction, action group, and media; compose the slots with existing Gaudi components.

- Category: Blocks · Marketing
- Import: `@gaudi/design-system/blocks/Hero` (also `@gaudi/design-system/blocks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/blocks/Hero/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/blocks-marketing-heroes--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Heroes from '@gaudi/design-system/blocks/Hero';
```

## Usage

```jsx
import { Hero } from '@gaudi/design-system/blocks/Hero';
import Button from '@gaudi/design-system/core/Button';

<Hero title='A good place to start.' description='Your content. Shared foundations.' actions={<Button href='/start'>Get started</Button>} />
```

## Examples

Examples (rendered from Storybook):

- [Aurora](https://storybook.gaudi.site/index.html?path=/story/blocks-marketing-heroes--playground)
- [Mesh gradient](https://storybook.gaudi.site/index.html?path=/story/blocks-marketing-heroes--mesh-gradient)
- [Live surface](https://storybook.gaudi.site/index.html?path=/story/blocks-marketing-heroes--live-surface)
- [Journal topics](https://storybook.gaudi.site/index.html?path=/story/blocks-marketing-heroes--journal-topics)
- [Split image](https://storybook.gaudi.site/index.html?path=/story/blocks-marketing-heroes--split-image)
- [Product preview](https://storybook.gaudi.site/index.html?path=/story/blocks-marketing-heroes--product-preview)
- [Editorial](https://storybook.gaudi.site/index.html?path=/story/blocks-marketing-heroes--editorial)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `eyebrow` | `ReactNode` | — | no | Optional label, badge, or mark above the heading. It stays outside the heading so the section name is only the title. |
| `title` | `ReactNode` | — | no | The primary heading. Keep it concise and specific. |
| `description` | `ReactNode` | — | no | Supporting paragraph, rendered with Gaudi typography. |
| `layout` | `centered \| split \| editorial \| background` | `centered` | no | Centered stack, side-by-side image, editorial heading and introduction, or background image with an opaque readable content panel. |
| `actions` | `ReactNode` | — | no | Primary and secondary actions; use Button and Link. Long labels wrap. |
| `media` | `ReactNode` | — | no | Prepared image, video, or product preview. Background layout is intended for decorative imagery. |
| `children` | `ReactNode` | — | no | Optional supporting content below the actions. |
| `headingAs` | `h1 \| h2 \| h3` | `h1` | no | Choose the heading level for its place in the page. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `layout`: `centered`, `split`, `editorial`, `background`
- `headingAs`: `h1`, `h2`, `h3`

## Accessibility

The section is labelled by its heading. Reading order is eyebrow, heading, description, actions, supporting content, then media. Images need meaningful alternative text, or empty alt text when decorative. Background imagery must be decorative and non-interactive.

## Notes

- The hero responds to its container, stacking split and editorial layouts below 48rem.
- Supply prepared content and real destinations. Navigation, forms, claims, and product behavior belong to the host.
- Animated examples reuse Gaudi backgrounds (Aurora, Grainient, Dark Veil, Floating Lines, Liquid Ether) and include a pause control; reduced motion stops them.
- The examples are original Gaudi compositions using local artwork; no Tailwind Plus source is included.

## Related

- [Navigation](https://design.gaudi.site/docs/blocks/navigation): The site header block: brand, primary NavigationMenu with a two-block Blog panel (categories beside recent posts) or a Categories panel on the supplied blog route, search, theme switch, and a phone sheet below lg.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [Grainient](https://design.gaudi.site/docs/animations/grainient): A slowly warped three-color gradient with fine animated grain.
- [Button](https://design.gaudi.site/docs/components/button): Button renders the Gaudi action and link-button variants.
- [Link](https://design.gaudi.site/docs/components/link): Link centralizes navigation semantics for internal, anchor, and external links.

Source: https://design.gaudi.site/docs/blocks/heroes (Markdown with example code: https://design.gaudi.site/docs/blocks/heroes.md)

---

# Chat & Agents

> Chat and agent interface owners (every export is Chat-prefixed).

20 pages · 20 live examples, generated from the design system metadata.

- [ChatActivityHistory](https://design.gaudi.site/docs/chat/chat-activity-history): What happened in a conversation, newest last.
- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator): What the assistant is doing: idle, thinking, streaming, tool, done or error.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [ChatDelegation](https://design.gaudi.site/docs/chat/chat-delegation): Work handed to another agent: who took it, the brief, its status and its activity.
- [ChatEffortSlider](https://design.gaudi.site/docs/chat/chat-effort-slider): How hard the assistant should think, as a stepped slider over named levels.
- [ChatFeedback](https://design.gaudi.site/docs/chat/chat-feedback): Copy, rate and regenerate a finished reply.
- [ChatFileExplorer](https://design.gaudi.site/docs/chat/chat-file-explorer): A searchable file hierarchy for shared files, uploads and agent outputs, built on Core Tree.
- [ChatInput](https://design.gaudi.site/docs/chat/chat-input): The composer: ChatPromptComposer with mentions, commands, attachments and send or stop; ChatPromptQueue; ChatModelSelect.
- [ChatMessage](https://design.gaudi.site/docs/chat/chat-message): One turn in a conversation: avatar, sender and time, the content stack and a status footer.
- [ChatMessageList](https://design.gaudi.site/docs/chat/chat-message-list): The conversation: a scroller that keeps the thread anchored and ChatMessageParts rendering each assistant turn from its parts.
- [ChatPersona](https://design.gaudi.site/docs/chat/chat-persona): The assistant’s presence in a voice conversation: an orb that rests, connects, listens, thinks, speaks, sleeps or shows an error, drawn by one of eight renderers.
- [ChatPlanPanel](https://design.gaudi.site/docs/chat/chat-plan-panel): The assistant’s plan for the current request, with progress.
- [ChatReasoning](https://design.gaudi.site/docs/chat/chat-reasoning): The thinking trail before an answer: a shimmering Thinking… label while it streams, a chain of thought of detailed steps with search results and images, folding into Thought for Ns once the answer starts.
- [ChatSessionList](https://design.gaudi.site/docs/chat/chat-session-list): Session navigation inside a complete chat: grouped conversations with title search, new chat, rename and delete. The compact panel opens History in place of the transcript; the full-page composition uses ChatShell navigation and its narrow-screen Sheet. The host keeps a separate transcript and draft for each session.
- [ChatSources](https://design.gaudi.site/docs/chat/chat-sources): Numbered citations that open a hover card (with a carousel when one marker cites several sources) and the list of sources under a reply.
- [ChatThreadNav](https://design.gaudi.site/docs/chat/chat-thread-nav): Previous, next and a menu of every prompt in a long thread.
- [ChatTool](https://design.gaudi.site/docs/chat/chat-tool): One tool call with status, input and output as data, nested calls and a retry, plus ChatMessageToolApproval for calls that wait on the person.
- [ChatVoice](https://design.gaudi.site/docs/chat/chat-voice): Voice building blocks: ChatSpeechInput dictates into the composer, ChatMicSelector picks the input device, ChatVoiceSelector picks the voice that answers and ChatAudioPlayer plays voice messages and spoken replies.
- [ChatWorkspace](https://design.gaudi.site/docs/chat/chat-workspace): A context panel that connects the agent roster to each agent’s files, with a return to the complete workspace.

Source: https://design.gaudi.site/docs/chat (Markdown with example code: https://design.gaudi.site/docs/chat.md)

---

# ChatActivityHistory

> What happened in a conversation, newest last.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatActivityHistory` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatActivityHistory/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-chatactivityhistory--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import ChatActivityHistory from '@gaudi/design-system/chat/ChatActivityHistory';
```

## Usage

```jsx
import { ChatActivity } from '@gaudi/design-system/chat';

<ChatActivity items={[{ id: '1', time: '09:12', title: 'Searched the archive', icon: 'Search' }]} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/chat-chatactivityhistory--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `title` | `string` | `Activity` | no | Region name. |
| `details` | `boolean` | `true` | no | Example only: shows item details. |
| `items` | `Array<{ id, title, time, detail?, status?, icon? }>` | `[]` | no | History rows. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

A labelled region with a heading.

## Related

- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator): What the assistant is doing: idle, thinking, streaming, tool, done or error.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [ChatDelegation](https://design.gaudi.site/docs/chat/chat-delegation): Work handed to another agent: who took it, the brief, its status and its activity.
- [ChatEffortSlider](https://design.gaudi.site/docs/chat/chat-effort-slider): How hard the assistant should think, as a stepped slider over named levels.
- [ChatFeedback](https://design.gaudi.site/docs/chat/chat-feedback): Copy, rate and regenerate a finished reply.

Source: https://design.gaudi.site/docs/chat/chat-activity-history (Markdown with example code: https://design.gaudi.site/docs/chat/chat-activity-history.md)

---

# ChatActivityIndicator

> What the assistant is doing: idle, thinking, streaming, tool, done or error.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatActivityIndicator` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatActivityIndicator/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-activityindicator--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ChatActivityIndicator } from '@gaudi/design-system/chat/ChatActivityIndicator';
```

## Usage

```jsx
import { ChatActivityIndicator } from '@gaudi/design-system/chat';

<>
<ChatActivityIndicator state='thinking' showLabel />
<ChatActivityIndicator state='done' variant='badge' />
</>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/chat-activityindicator--playground)
- [A reply from thinking to done](https://storybook.gaudi.site/index.html?path=/story/chat-activityindicator--reply-lifecycle)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `state` | `idle \| thinking \| streaming \| tool \| done \| error` | `idle` | no | Current activity. |
| `variant` | `inline \| badge` | `inline` | no | Inline mark or corner badge. |
| `showLabel` | `boolean` | `false` | no | Visible label beside the mark. |
| `labels` | `object` | — | no | Copy per state, and hiding. |
| `decorative` | `boolean` | — | no | Copy per state, and hiding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `idle`, `thinking`, `streaming`, `tool`, `done`, `error`
- `variant`: `inline`, `badge`

## Accessibility

A polite status; motion slows to a fade for reduced motion.

## Related

- [ChatActivityHistory](https://design.gaudi.site/docs/chat/chat-activity-history): What happened in a conversation, newest last.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [ChatDelegation](https://design.gaudi.site/docs/chat/chat-delegation): Work handed to another agent: who took it, the brief, its status and its activity.
- [ChatEffortSlider](https://design.gaudi.site/docs/chat/chat-effort-slider): How hard the assistant should think, as a stepped slider over named levels.
- [ChatFeedback](https://design.gaudi.site/docs/chat/chat-feedback): Copy, rate and regenerate a finished reply.

Source: https://design.gaudi.site/docs/chat/chat-activity-indicator (Markdown with example code: https://design.gaudi.site/docs/chat/chat-activity-indicator.md)

---

# ChatAgentMark

> The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatAgentMark` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatAgentMark/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-agentmark--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ChatAgentMark } from '@gaudi/design-system/chat/ChatAgentMark';
```

## Usage

```jsx
import { ChatAgentMark } from '@gaudi/design-system/chat';

<>
<ChatAgentMark name='Gaudi' state='thinking' />
<ChatAgentMark name='Research agent' icon='Search' tone='discovery' size='sm' decorative />
</>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/chat-agentmark--playground)
- [Motifs and glazes](https://storybook.gaudi.site/index.html?path=/story/chat-agentmark--motifs)
- [Status at every size](https://storybook.gaudi.site/index.html?path=/story/chat-agentmark--statuses)
- [Icon, image or monogram instead](https://storybook.gaudi.site/index.html?path=/story/chat-agentmark--icons-and-monograms)
- [In a thread, with several agents](https://storybook.gaudi.site/index.html?path=/story/chat-agentmark--in-a-thread)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | `string` | `Gaudi` | no | Accessible name, monogram source and default seed. |
| `seed` | `string` | `name` | no | Stable id that picks the motif and hue. |
| `motif` | `auto \| trencadis \| spire \| ironwork \| rose \| palmetto \| panot \| helicoid \| sun \| star` | `auto` | no | Pin a motif. |
| `hue` | `auto \| teal \| blue \| amber \| rose \| green \| indigo \| red \| yellow` | `auto` | no | Pin a glaze. |
| `size` | `xs \| sm \| md \| lg \| xl` | `md` | no | Tile size. |
| `tone` | `accent \| discovery \| neutral \| solid` | `accent` | no | Tile colour. |
| `state` | `idle \| thinking \| streaming \| tool \| done \| error` | — | no | Adds an ChatActivityIndicator badge. |
| `monogram` | `boolean` | `false` | no | Initials instead of the icon. |
| `icon` | `string` | `Sparkles` | no | Glyph, image and hiding. |
| `image` | `string` | — | no | Glyph, image and hiding. |
| `decorative` | `boolean` | `false` | no | Glyph, image and hiding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `motif`: `auto`, `trencadis`, `spire`, `ironwork`, `rose`, `palmetto`, `panot`, `helicoid`, `sun`, `star`
- `hue`: `auto`, `teal`, `blue`, `amber`, `rose`, `green`, `indigo`, `red`, `yellow`
- `size`: `xs`, `sm`, `md`, `lg`, `xl`
- `tone`: `accent`, `discovery`, `neutral`, `solid`
- `state`: `idle`, `thinking`, `streaming`, `tool`, `done`, `error`

## Accessibility

role=img named after the agent unless decorative.

## Related

- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator): What the assistant is doing: idle, thinking, streaming, tool, done or error.
- [ChatActivityHistory](https://design.gaudi.site/docs/chat/chat-activity-history): What happened in a conversation, newest last.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [ChatDelegation](https://design.gaudi.site/docs/chat/chat-delegation): Work handed to another agent: who took it, the brief, its status and its activity.
- [ChatEffortSlider](https://design.gaudi.site/docs/chat/chat-effort-slider): How hard the assistant should think, as a stepped slider over named levels.
- [ChatFeedback](https://design.gaudi.site/docs/chat/chat-feedback): Copy, rate and regenerate a finished reply.

Source: https://design.gaudi.site/docs/chat/chat-agent-mark (Markdown with example code: https://design.gaudi.site/docs/chat/chat-agent-mark.md)

---

# ChatBubble

> The surface around a message, with seven variants and reactions.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatBubble` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatBubble/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-bubble--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ChatBubble } from '@gaudi/design-system/chat/ChatBubble';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/chat-bubble-quick-replies.json`.

## Usage

```jsx
import { ChatBubble, ChatBubbleContent, ChatBubbleReactions } from '@gaudi/design-system/chat';

<ChatBubble variant='tinted' align='end'>
  <ChatBubbleContent>Shipped to 4,180 readers.</ChatBubbleContent>
  <ChatBubbleReactions align='start'>🎉 3</ChatBubbleReactions>
</ChatBubble>
```

## Examples

### Suggested replies under a question

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chat-bubble-quick-replies.json`

### Bubble styles across a deploy thread

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chat-bubble-release-thread.json`

### Formatted answer with show more

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chat-bubble-show-more.json`

### Support thread

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chat-bubble-support-thread.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `variant` | `default \| secondary \| muted \| tinted \| outline \| ghost \| destructive` | `default` | no | ChatBubble surface. |
| `align` | `start \| end` | `start` | no | Matches the message side. |
| `children` | `string` | — | no | The text, inside ChatBubbleContent. |
| `ChatBubbleReactions.align` | `start \| end` | `end` | no | Edge the reactions pin to. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `variant`: `default`, `secondary`, `muted`, `tinted`, `outline`, `ghost`, `destructive`
- `align`: `start`, `end`

## Accessibility

Label reactions; quick-reply bubbles must be real buttons through asChild.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Accordion](https://design.gaudi.site/docs/components/accordion): Rich disclosure for FAQs, settings, member directories, nested help, and guided setup.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.

Source: https://design.gaudi.site/docs/chat/chat-bubble (Markdown with example code: https://design.gaudi.site/docs/chat/chat-bubble.md)

---

# ChatDelegation

> Work handed to another agent: who took it, the brief, its status and its activity.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatDelegation` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatDelegation/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-chatdelegation--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import ChatDelegation from '@gaudi/design-system/chat/ChatDelegation';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/chat-delegation-agent-handoff.json`.

## Usage

```jsx
import { ChatMessageDelegation, ChatMessageTool } from '@gaudi/design-system/chat';

<ChatMessageDelegation agent={{ name: 'Research agent' }} status='running' instructions={brief}>
  <ChatMessageTool name='web_search' status='done' />
</ChatMessageDelegation>
```

## Examples

### Handing work to another agent

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chat-delegation-agent-handoff.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | `pending \| running \| done \| failed` | `running` | no | Delegation status. |
| `instructions` | `string` | — | no | The brief. |
| `agent` | `{ name }` | — | no | The agent that took the work. |
| `error` | `string` | — | no | Shown as an alert. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `status`: `pending`, `running`, `done`, `failed`

## Accessibility

The status is named in text, not colour alone.

## Related

- [ChatMessage](https://design.gaudi.site/docs/chat/chat-message): One turn in a conversation: avatar, sender and time, the content stack and a status footer.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatMessageList](https://design.gaudi.site/docs/chat/chat-message-list): The conversation: a scroller that keeps the thread anchored and ChatMessageParts rendering each assistant turn from its parts.

Source: https://design.gaudi.site/docs/chat/chat-delegation (Markdown with example code: https://design.gaudi.site/docs/chat/chat-delegation.md)

---

# ChatEffortSlider

> How hard the assistant should think, as a stepped slider over named levels.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatEffortSlider` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatEffortSlider/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-chateffortslider--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ChatEffortSlider } from '@gaudi/design-system/chat/ChatEffortSlider';
```

## Usage

```jsx
import { ChatEffortSlider } from '@gaudi/design-system/chat';

<ChatEffortSlider value={effort} onValueChange={setEffort} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/chat-chateffortslider--playground)
- [Custom levels: review depth](https://storybook.gaudi.site/index.html?path=/story/chat-chateffortslider--review-depth)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | `Effort` | no | Slider name. |
| `defaultValue` | `low \| medium \| high \| max` | `medium` | no | Initial level. |
| `compact` | `boolean` | `false` | no | Drops step labels and the description. |
| `disabled` | `boolean` | `false` | no | Locks the control. |
| `levels` | `Array<{ value, label, description? }>` | `chatEffortLevels` | no | The levels. |
| `value` | `string` | — | no | Controlled level. |
| `onValueChange` | `(value, level) => void` | — | no | Controlled level. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `defaultValue`: `low`, `medium`, `high`, `max`

## Accessibility

The thumb announces the level name through aria-valuetext.

## Related

- [Slider](https://design.gaudi.site/docs/components/slider): Adjust one value or a range with pointer and keyboard input.
- [ChatActivityHistory](https://design.gaudi.site/docs/chat/chat-activity-history): What happened in a conversation, newest last.
- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator): What the assistant is doing: idle, thinking, streaming, tool, done or error.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [ChatDelegation](https://design.gaudi.site/docs/chat/chat-delegation): Work handed to another agent: who took it, the brief, its status and its activity.

Source: https://design.gaudi.site/docs/chat/chat-effort-slider (Markdown with example code: https://design.gaudi.site/docs/chat/chat-effort-slider.md)

---

# ChatFeedback

> Copy, rate and regenerate a finished reply.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatFeedback` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatFeedback/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-chatfeedback--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import ChatFeedback from '@gaudi/design-system/chat/ChatFeedback';
```

## Usage

```jsx
import { ChatMessageFeedback } from '@gaudi/design-system/chat';

<ChatMessageFeedback copyText={reply.text} rating={rating} onRatingChange={setRating} onRegenerate={regenerate} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/chat-chatfeedback--playground)
- [Rating with a reason](https://storybook.gaudi.site/index.html?path=/story/chat-chatfeedback--rating-with-a-reason)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `defaultRating` | `none \| up \| down` | `none` | no | Initial rating. |
| `regenerate` | `boolean` | `true` | no | Example only: shows Regenerate through onRegenerate. |
| `copyText` | `string` | — | no | What copy writes. |
| `rating` | `'up' \| 'down' \| null` | — | no | Controlled rating. |
| `onRatingChange` | `function` | — | no | Controlled rating. |
| `onCopy / onRegenerate` | `function` | — | no | Host callbacks. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `defaultRating`: `none`, `up`, `down`

## Accessibility

A labelled group; ratings are pressed buttons, each action confirmed in a status.

## Related

- [ChatActivityHistory](https://design.gaudi.site/docs/chat/chat-activity-history): What happened in a conversation, newest last.
- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator): What the assistant is doing: idle, thinking, streaming, tool, done or error.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [ChatDelegation](https://design.gaudi.site/docs/chat/chat-delegation): Work handed to another agent: who took it, the brief, its status and its activity.
- [ChatEffortSlider](https://design.gaudi.site/docs/chat/chat-effort-slider): How hard the assistant should think, as a stepped slider over named levels.

Source: https://design.gaudi.site/docs/chat/chat-feedback (Markdown with example code: https://design.gaudi.site/docs/chat/chat-feedback.md)

---

# ChatFileExplorer

> A searchable file hierarchy for shared files, uploads and agent outputs, built on Core Tree.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatFileExplorer` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatFileExplorer/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-chatfileexplorer--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ChatFileExplorer } from '@gaudi/design-system/chat/ChatFileExplorer';
```

## Usage

```jsx
import { ChatFileExplorer } from '@gaudi/design-system/chat';

<ChatFileExplorer items={files} defaultExpanded={['shared']} selectedId={selectedId} onSelect={selectFile} onPreview={previewFile} onRefresh={refreshFiles} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/chat-chatfileexplorer--playground)
- [Controlled Selection](https://storybook.gaudi.site/index.html?path=/story/chat-chatfileexplorer--controlled-selection)
- [Live file updates](https://storybook.gaudi.site/index.html?path=/story/chat-chatfileexplorer--data-replacement)
- [Loading](https://storybook.gaudi.site/index.html?path=/story/chat-chatfileexplorer--loading)
- [Error And Retry](https://storybook.gaudi.site/index.html?path=/story/chat-chatfileexplorer--error-and-retry)
- [Empty](https://storybook.gaudi.site/index.html?path=/story/chat-chatfileexplorer--empty)
- [Empty folders](https://storybook.gaudi.site/index.html?path=/story/chat-chatfileexplorer--empty-folders)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | `Files` | no | Region and tree name. |
| `expanded` | `boolean` | `true` | no | Example only: opens the folders. |
| `items` | `{ [id]: { name, children?, meta?, typeLabel?, sizeLabel?, modifiedLabel?, modifiedAt?, downloadUrl?, downloadName?, canPreview?, agent? } }` | `{}` | no | Flat file map. Agent folders accept ChatAgentMark identity props; labels are prepared by the host. |
| `rootId` | `string` | `root` | no | Flat file map. Agent folders accept ChatAgentMark identity props; labels are prepared by the host. |
| `defaultExpanded` | `string[]` | `[]` | no | Initially open folders. |
| `selectedId` | `string \| null` | — | no | Controlled or local single-file selection. |
| `defaultSelectedId` | `string \| null` | `null` | no | Controlled or local single-file selection. |
| `onSelect` | `(id, item) => void` | — | no | Controlled or local single-file selection. |
| `onPreview` | `(id, item) => void` | — | no | Adds a named preview action for eligible files; the host supplies content. |
| `searchable` | `boolean` | `true` | no | Search names and metadata while preserving ancestors. |
| `loading` | `boolean` | `false` | no | Initial loading, background refresh and recoverable failure. |
| `refreshing` | `boolean` | `false` | no | Initial loading, background refresh and recoverable failure. |
| `error` | `ReactNode` | — | no | Initial loading, background refresh and recoverable failure. |
| `onRefresh` | `function` | — | no | Header refresh, recovery callback and extra actions. |
| `onRetry` | `function` | — | no | Header refresh, recovery callback and extra actions. |
| `actions` | `ReactNode` | — | no | Header refresh, recovery callback and extra actions. |
| `labels` | `object` | `English copy` | no | Search, actions and recovery copy. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Core Tree provides arrow navigation; Enter or Space selects files. Row actions are named and keyboard reachable. Search preserves folder context and announces matches.

## Related

- [Tree](https://design.gaudi.site/docs/components/tree): Browse hierarchical content with expansion, selection, checkboxes and drag feedback.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatActivityHistory](https://design.gaudi.site/docs/chat/chat-activity-history): What happened in a conversation, newest last.
- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator): What the assistant is doing: idle, thinking, streaming, tool, done or error.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [ChatDelegation](https://design.gaudi.site/docs/chat/chat-delegation): Work handed to another agent: who took it, the brief, its status and its activity.

Source: https://design.gaudi.site/docs/chat/chat-file-explorer (Markdown with example code: https://design.gaudi.site/docs/chat/chat-file-explorer.md)

---

# ChatInput

> The composer: ChatPromptComposer with mentions, commands, attachments and send or stop; ChatPromptQueue; ChatModelSelect.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatInput` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatInput/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-chatinput--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import ChatInput from '@gaudi/design-system/chat/ChatInput';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/prompt-composer-mentions-attachments.json`.

## Usage

```jsx
import { ChatEffortSlider, ChatModelSelect, ChatPromptComposer, ChatPromptQueue } from '@gaudi/design-system/chat';

<>
<ChatPromptQueue items={queue} onEdit={edit} onRemove={remove} onSendNow={sendNow} onMove={move} />
<ChatPromptComposer
  status={streaming ? 'streaming' : 'ready'}
  mentions={people}
  commands={commands}
  onSubmit={(text, { queued }) => (queued ? enqueue(text) : send(text))}
  onStop={stop}
  toolbar={<ChatModelSelect searchable providers={providers} models={models} value={model} onValueChange={setModel}><ChatEffortSlider value={effort} onValueChange={setEffort} compact /></ChatModelSelect>}
/>
</>
```

## Examples

### Chat composer: Mentions, commands and attachments

Registry: `npx shadcn@latest add https://design.gaudi.site/r/prompt-composer-mentions-attachments.json`

### Chat composer: Model and effort

Registry: `npx shadcn@latest add https://design.gaudi.site/r/prompt-composer-model-effort.json`

### Chat composer: Queue follow-ups while a reply streams

Registry: `npx shadcn@latest add https://design.gaudi.site/r/prompt-composer-queued-follow-ups.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | `ready \| streaming` | `ready` | no | Streaming shows Stop and queues new messages. |
| `placeholder` | `string` | `Message` | no | Prompt placeholder, through labels. |
| `models` | `boolean` | `true` | no | Example only: a ChatModelSelect with an effort slider in the toolbar. |
| `ChatPromptComposer.onSubmit` | `(text, { queued, mentions, command, attachments }) => void` | — | no | Send or queue. |
| `ChatPromptComposer.attachments` | `Array<{ id, name, type?, size?, kind?, previewUrl? }>` | `[]` | no | Compact shared Attachment pills; supplied image/poster thumbnails or file-type icons. The host owns removal and preview URL lifecycle. |
| `onRemoveAttachment` | `(id) => void` | — | no | Compact shared Attachment pills; supplied image/poster thumbnails or file-type icons. The host owns removal and preview URL lifecycle. |
| `ChatPromptComposer.mentions / commands` | `Array<{ id, name, description?, icon? }>` | `[]` | no | @ anywhere and / at the start open them. |
| `ChatPromptComposer.leftControls` | `ReactNode` | `toolbar` | no | Independent left/right control slots; children set order and both groups wrap. Explicit values, including null, override legacy toolbar/actions. Send/stop/voice stay after the right controls. |
| `rightControls` | `ReactNode` | `actions` | no | Independent left/right control slots; children set order and both groups wrap. Explicit values, including null, override legacy toolbar/actions. Send/stop/voice stay after the right controls. |
| `ChatPromptComposer.toolbar` | `ReactNode` | — | no | Compatible left/right aliases, footer text and copy. |
| `actions` | `ReactNode` | — | no | Compatible left/right aliases, footer text and copy. |
| `footer` | `ReactNode` | — | no | Compatible left/right aliases, footer text and copy. |
| `labels` | `object` | — | no | Compatible left/right aliases, footer text and copy. |
| `ChatPromptQueue.items / onEdit / onRemove / onSendNow / onMove` | `Array<{ id, text }> / functions` | — | no | Waiting messages. |
| `ChatModelSelect.models` | `Array<{ value, label, description?, badge? }>` | — | no | The model a prompt runs on. |
| `value` | `string` | — | no | The model a prompt runs on. |
| `onValueChange` | `function` | — | no | The model a prompt runs on. |
| `ChatModelSelect.children` | `ReactNode` | — | no | Footer content switches to a popover with a model list and separate controls; Tab reaches the footer, and Escape returns focus to the trigger. |
| `ChatModelSelect.searchable` | `boolean` | `false` | no | A searchable command list grouped by provider, with context, speed, cost and capability badges. |
| `providers` | `Record<provider, { label, icon }>` | `{}` | no | A searchable command list grouped by provider, with context, speed, cost and capability badges. |
| `ChatPromptComposer.variant` | `'default' \| 'card'` | `'default'` | no | The card composer has a muted writing area and inset toolbar; voice takes the send slot while the prompt is empty. |
| `voice` | `ReactNode \| ({ value, setValue, insert, disabled }) => ReactNode` | — | no | The card composer has a muted writing area and inset toolbar; voice takes the send slot while the prompt is empty. |
| `ChatPromptToggle.icon` | `string` | — | no | A compact tool toggle with an animated registry icon. Hover animates the icon and shows a tooltip; keyboard focus and selection expand its label. Selected tools retain their label and accent. Supports controlled state, reduced motion and touch. Hosts disable supplied controls explicitly. |
| `label` | `string` | — | no | A compact tool toggle with an animated registry icon. Hover animates the icon and shows a tooltip; keyboard focus and selection expand its label. Selected tools retain their label and accent. Supports controlled state, reduced motion and touch. Hosts disable supplied controls explicitly. |
| `pressed` | `boolean` | — | no | A compact tool toggle with an animated registry icon. Hover animates the icon and shows a tooltip; keyboard focus and selection expand its label. Selected tools retain their label and accent. Supports controlled state, reduced motion and touch. Hosts disable supplied controls explicitly. |
| `defaultPressed` | `boolean` | `false` | no | A compact tool toggle with an animated registry icon. Hover animates the icon and shows a tooltip; keyboard focus and selection expand its label. Selected tools retain their label and accent. Supports controlled state, reduced motion and touch. Hosts disable supplied controls explicitly. |
| `onPressedChange` | `(pressed) => void` | — | no | A compact tool toggle with an animated registry icon. Hover animates the icon and shows a tooltip; keyboard focus and selection expand its label. Selected tools retain their label and accent. Supports controlled state, reduced motion and touch. Hosts disable supplied controls explicitly. |
| `disabled` | `boolean` | `false` | no | A compact tool toggle with an animated registry icon. Hover animates the icon and shows a tooltip; keyboard focus and selection expand its label. Selected tools retain their label and accent. Supports controlled state, reduced motion and touch. Hosts disable supplied controls explicitly. |
| `ChatPromptAttachMenu.items` | `Array<{ value, label, icon?, accept?, capture? }>` | — | no | The + menu: items with accept open the file picker. |
| `onAttach` | `(files, item) => void` | — | no | The + menu: items with accept open the file picker. |
| `onSelect` | `(item) => void` | — | no | The + menu: items with accept open the file picker. |
| `ChatPromptSettings.options` | `Array<{ value, label, description?, icon? }>` | — | no | Options popover with an effort slider and switches. |
| `values` | `Record<string, boolean>` | — | no | Options popover with an effort slider and switches. |
| `onValuesChange` | `function` | — | no | Options popover with an effort slider and switches. |
| `effort` | `string` | — | no | Options popover with an effort slider and switches. |
| `onEffortChange` | `function` | — | no | Options popover with an effort slider and switches. |
| `ChatContextMeter.usedTokens` | `number` | `0` | no | Prepared totals and breakdown values; only the percentage is derived. |
| `maxTokens` | `number` | `0` | no | Prepared totals and breakdown values; only the percentage is derived. |
| `breakdown` | `Array<{ id, label, value, detail? }>` | `[]` | no | Prepared totals and breakdown values; only the percentage is derived. |
| `ChatContextMeter.cost` | `ReactNode` | — | no | Host-supplied cost text, meaning and status copy; no billing or workflow policy. |
| `costLabel` | `ReactNode` | `Cost` | no | Host-supplied cost text, meaning and status copy; no billing or workflow policy. |
| `tone` | `accent \| warning \| danger` | `accent` | no | Host-supplied cost text, meaning and status copy; no billing or workflow policy. |
| `message` | `ReactNode` | — | no | Host-supplied cost text, meaning and status copy; no billing or workflow policy. |
| `ChatContextMeter.formatTokens` | `(number) => string` | `compact token count` | no | Format the supplied counts and derived percentage. |
| `formatPercentage` | `(number) => string` | `percentage` | no | Format the supplied counts and derived percentage. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `status`: `ready`, `streaming`
- `tone`: `accent`, `warning`, `danger`

## Accessibility

The prompt is a labelled combobox; icon buttons and queue actions are named. The model trigger names the current model; the searchable list is a labelled combobox with grouped options and the current one checked. The context meter names the share used and opens its breakdown on press. The options switches are named and the trigger lists the options that are on.

## Related

- [Attachment](https://design.gaudi.site/docs/components/attachment): File attachments with metadata, previews, actions and upload states.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [Loader](https://design.gaudi.site/docs/components/loader): An accessible loading indicator with arcs, dots, expanding rings, and an indeterminate bar.

Source: https://design.gaudi.site/docs/chat/chat-input (Markdown with example code: https://design.gaudi.site/docs/chat/chat-input.md)

---

# ChatMessage

> One turn in a conversation: avatar, sender and time, the content stack and a status footer.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatMessage` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatMessage/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-message--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ChatMessage } from '@gaudi/design-system/chat/ChatMessage';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/chat-error-retry-suggestions.json`.

## Usage

```jsx
import { ChatBubble, ChatBubbleContent, ChatMessage, ChatMessageAvatar, ChatMessageContent, ChatMessageFooter } from '@gaudi/design-system/chat';

<ChatMessage align='end'>
  <ChatMessageAvatar><Avatar src={me.src} name={me.name} size='sm' alt='' /></ChatMessageAvatar>
  <ChatMessageContent>
    <ChatBubble align='end'><ChatBubbleContent>Moving the legend under the axis.</ChatBubbleContent></ChatBubble>
    <ChatMessageFooter>Read 10:42</ChatMessageFooter>
  </ChatMessageContent>
</ChatMessage>
```

## Examples

### Error, retry and suggestions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chat-error-retry-suggestions.json`

### Delivered files and data

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chat-file-delivered-files.json`

### Assistant reply

Registry: `npx shadcn@latest add https://design.gaudi.site/r/message-assistant-reply.json`

### Team conversation

Registry: `npx shadcn@latest add https://design.gaudi.site/r/message-team-conversation.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ChatMessage.align` | `start \| end` | `start` | no | Side of the conversation; the avatar flips with it. |
| `ChatMessageGroup` (sub-component) | `component` | — | no | Consecutive turns from one sender under one avatar. |
| `ChatMessageAvatar / ChatMessageHeader / ChatMessageContent / ChatMessageFooter` (sub-component) | `components` | — | no | Avatar column, sender and time, content stack and status. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Name the sender in a header or visually hidden text; side alone is lost when a thread is read aloud.

## Related

- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [Attachment](https://design.gaudi.site/docs/components/attachment): File attachments with metadata, previews, actions and upload states.
- [Item](https://design.gaudi.site/docs/components/item): Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatMessageList](https://design.gaudi.site/docs/chat/chat-message-list): The conversation: a scroller that keeps the thread anchored and ChatMessageParts rendering each assistant turn from its parts.

Source: https://design.gaudi.site/docs/chat/chat-message (Markdown with example code: https://design.gaudi.site/docs/chat/chat-message.md)

---

# ChatMessageList

> The conversation: a scroller that keeps the thread anchored and ChatMessageParts rendering each assistant turn from its parts.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatMessageList` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatMessageList/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-messagelist--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import ChatMessageList from '@gaudi/design-system/chat/ChatMessageList';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/message-scroller-anchored-turn.json`.

## Usage

```jsx
import { ChatMessageParts, ChatMessageScroller, ChatMessageScrollerContent, ChatMessageScrollerItem, ChatMessageScrollerProvider, ChatMessageScrollerViewport } from '@gaudi/design-system/chat';

<ChatMessageScrollerProvider autoScroll>
  <ChatMessageScroller>
    <ChatMessageScrollerViewport aria-label='Conversation'>
      <ChatMessageScrollerContent>
        {turns.map((turn) => (
          <ChatMessageScrollerItem key={turn.id} scrollAnchor={turn.role === 'user'}>
            <ChatMessageParts parts={turn.parts} streaming={turn.streaming} />
          </ChatMessageScrollerItem>
        ))}
      </ChatMessageScrollerContent>
    </ChatMessageScrollerViewport>
  </ChatMessageScroller>
</ChatMessageScrollerProvider>
```

## Examples

### New turn anchored under the last answer

Registry: `npx shadcn@latest add https://design.gaudi.site/r/message-scroller-anchored-turn.json`

### Streamed reply: drafting a post

Registry: `npx shadcn@latest add https://design.gaudi.site/r/message-scroller-drafting-post.json`

### Opening position and jump to latest

Registry: `npx shadcn@latest add https://design.gaudi.site/r/message-scroller-jump-to-latest.json`

### Older history that keeps your position

Registry: `npx shadcn@latest add https://design.gaudi.site/r/message-scroller-load-earlier.json`

### Pinned to the newest streamed line

Registry: `npx shadcn@latest add https://design.gaudi.site/r/message-scroller-streaming-follow.json`

### Step between turns from a navigator

Registry: `npx shadcn@latest add https://design.gaudi.site/r/message-scroller-thread-navigator.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `streaming` | `boolean` | `false` | no | Marks the last reply as arriving: aria-busy, a live fence and an open thinking trail. |
| `feedback` | `boolean` | `true` | no | Example only: copy and rating under finished replies. |
| `ChatMessageParts.parts` | `Array<text \| reasoning \| tool \| approval \| delegation \| source \| file \| data \| error \| suggestions>` | `[]` | no | One assistant turn; sources gather into one list cited as [1], [2]… |
| `ChatMessageParts.onRetry / onToolRetry / onToolApproval / onFileAction / onSuggestion` | `function` | — | no | Retry a turn or tool, answer an approval, act on a file, pick a follow-up. |
| `ChatMessageScrollerItem.scrollAnchor` | `boolean` | `false` | no | Lift a sent message near the top. |
| `ChatMessageMarkdown.children` | `string` | `''` | no | Runtime markdown; code through CodeBlock; [1] or [1, 3] cite sources. |
| `ChatMessageCheckpoint.label` | `string` | `Checkpoint` | no | A restore point between turns. |
| `time` | `string \| Date` | — | no | A restore point between turns. |
| `ChatMessageCheckpoint.onRestore` | `function` | — | no | Restore action, asked first in an alert dialog unless confirm is false. |
| `confirm` | `boolean` | `true` | no | Restore action, asked first in an alert dialog unless confirm is false. |
| `restored` | `boolean` | `false` | no | Restore action, asked first in an alert dialog unless confirm is false. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

The thread scrolls inside a labelled region; announce the start and end of a reply once, never every token. A checkpoint is a labelled group whose restore button is described by its label and time.

## Notes

- See Agent run on Chat/ChatReasoning for a checkpoint between turns with a confirmed restore.

## Related

- [Chat](https://design.gaudi.site/docs/blocks/chat): The chat frame: a shell for a full page or a sidebar assistant that composes the Chat parts: the thread, the composer, sessions, files, the plan and activity.
- [ChatReasoning](https://design.gaudi.site/docs/chat/chat-reasoning): The thinking trail before an answer: a shimmering Thinking… label while it streams, a chain of thought of detailed steps with search results and images, folding into Thought for Ns once the answer starts.
- [CodeBlock](https://design.gaudi.site/docs/components/code-block): CodeBlock renders syntax-highlighted source with an optional header, copy button, line numbers, highlighted and focused lines, diffs, folding and line selection.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [ChatMessage](https://design.gaudi.site/docs/chat/chat-message): One turn in a conversation: avatar, sender and time, the content stack and a status footer.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.

Source: https://design.gaudi.site/docs/chat/chat-message-list (Markdown with example code: https://design.gaudi.site/docs/chat/chat-message-list.md)

---

# ChatPersona

> The assistant’s presence in a voice conversation: an orb that rests, connects, listens, thinks, speaks, sleeps or shows an error, drawn by one of eight renderers.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatPersona` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatPersona/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-persona--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ChatPersona } from '@gaudi/design-system/chat/ChatPersona';
```

## Usage

```jsx
import { ChatPersona, useAudioLevel } from '@gaudi/design-system/chat';

const { levelRef, waveformRef } = useAudioLevel(micStream);

<>
<ChatPersona name='Gaudi' state='listening' variant='waveform' size='lg' levelRef={levelRef} waveformRef={waveformRef} />
<ChatPersona name='Gaudi' state='speaking' variant='iridescent' level={replyLevel} showLabel />
</>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/chat-persona--playground)
- [Orbs and states](https://storybook.gaudi.site/index.html?path=/story/chat-persona--orbs)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `state` | `idle \| connecting \| listening \| thinking \| speaking \| asleep \| error` | `idle` | no | What the assistant is doing. |
| `variant` | `iridescent \| mercury \| waveform \| activity \| circle \| bars \| cloud \| radial` | `iridescent` | no | Renderer: WebGL film, CSS metal, canvas ring, SVG dot sphere, CSS disc, CSS bars, WebGL cloud or WebGL pinwheel. |
| `size` | `xs \| sm \| md \| lg \| xl \| number` | `md` | no | 32, 48, 96, 168 or 240 pixels, or a number. |
| `level` | `number` | — | no | Live audio level 0..1. |
| `levelRef` | `RefObject<number>` | — | no | Live audio level 0..1. |
| `waveformRef` | `RefObject<Uint8Array>` | — | no | Time-domain samples for the waveform ring. |
| `speed` | `number` | `1` | no | Animation multiplier and whether it moves. |
| `active` | `boolean` | `true unless asleep` | no | Animation multiplier and whether it moves. |
| `name` | `string` | `Assistant` | no | Accessible name, copy per state and a visible label. |
| `labels` | `object` | — | no | Accessible name, copy per state and a visible label. |
| `showLabel` | `boolean` | `false` | no | Accessible name, copy per state and a visible label. |
| `announce` | `boolean` | `true` | no | Polite state announcements, or hide it entirely. |
| `decorative` | `boolean` | `false` | no | Polite state announcements, or hide it entirely. |
| `colorFrom / colorTo` | `string` | `palette tokens` | no | Hex overrides for the artwork. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `idle`, `connecting`, `listening`, `thinking`, `speaking`, `asleep`, `error`
- `variant`: `iridescent`, `mercury`, `waveform`, `activity`, `circle`, `bars`, `cloud`, `radial`

## Accessibility

role=img named after the assistant and state, with a polite status for changes; the still frame differs per state, and animation stops off screen, when asleep and for reduced motion.

## Related

- [ChatActivityHistory](https://design.gaudi.site/docs/chat/chat-activity-history): What happened in a conversation, newest last.
- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator): What the assistant is doing: idle, thinking, streaming, tool, done or error.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [ChatDelegation](https://design.gaudi.site/docs/chat/chat-delegation): Work handed to another agent: who took it, the brief, its status and its activity.
- [ChatEffortSlider](https://design.gaudi.site/docs/chat/chat-effort-slider): How hard the assistant should think, as a stepped slider over named levels.

Source: https://design.gaudi.site/docs/chat/chat-persona (Markdown with example code: https://design.gaudi.site/docs/chat/chat-persona.md)

---

# ChatPlanPanel

> The assistant’s plan for the current request, with progress.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatPlanPanel` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatPlanPanel/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-chatplanpanel--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import ChatPlanPanel from '@gaudi/design-system/chat/ChatPlanPanel';
```

## Usage

```jsx
import { ChatPlan } from '@gaudi/design-system/chat';

<ChatPlan title='Plan' steps={[
  { id: 'read', title: 'Read the draft', status: 'done' },
  { id: 'draft', title: 'Draft the opening', status: 'running' }
]} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/chat-chatplanpanel--playground)
- [Plan in progress](https://storybook.gaudi.site/index.html?path=/story/chat-chatplanpanel--plan-in-progress)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `title` | `string` | `Plan` | no | Header. |
| `defaultOpen` | `boolean` | `true` | no | Initial disclosure. |
| `steps` | `Array<{ id, title, status, description?, owner?, todos? }>` | `[]` | no | Plan steps with the shared statuses. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

The header reads the count of finished steps.

## Related

- [ChatActivityHistory](https://design.gaudi.site/docs/chat/chat-activity-history): What happened in a conversation, newest last.
- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator): What the assistant is doing: idle, thinking, streaming, tool, done or error.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [ChatDelegation](https://design.gaudi.site/docs/chat/chat-delegation): Work handed to another agent: who took it, the brief, its status and its activity.
- [ChatEffortSlider](https://design.gaudi.site/docs/chat/chat-effort-slider): How hard the assistant should think, as a stepped slider over named levels.

Source: https://design.gaudi.site/docs/chat/chat-plan-panel (Markdown with example code: https://design.gaudi.site/docs/chat/chat-plan-panel.md)

---

# ChatReasoning

> The thinking trail before an answer: a shimmering Thinking… label while it streams, a chain of thought of detailed steps with search results and images, folding into Thought for Ns once the answer starts.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatReasoning` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatReasoning/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-chatreasoning--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import ChatReasoning from '@gaudi/design-system/chat/ChatReasoning';
```

## Usage

```jsx
import { ChatMessageReasoning, ChatMessageReasoningResults, ChatMessageReasoningStep } from '@gaudi/design-system/chat';

<ChatMessageReasoning streaming={thinking} variant='steps'>
  <ChatMessageReasoningStep status='done' icon='Search' label='Searched the web' meta='4 results'>
    <ChatMessageReasoningResults results={results} />
  </ChatMessageReasoningStep>
  <ChatMessageReasoningStep status='running' icon='BookOpen' label='Reading the sources' />
</ChatMessageReasoning>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/chat-chatreasoning--playground)
- [Thinking, then the answer](https://storybook.gaudi.site/index.html?path=/story/chat-chatreasoning--thinking-then-answer)
- [Agent run](https://storybook.gaudi.site/index.html?path=/story/chat-chatreasoning--agent-run)
- [AI message with steps](https://storybook.gaudi.site/index.html?path=/story/chat-chatreasoning--ai-message-with-steps)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `streaming` | `boolean` | `false` | no | Opens the trail with a shimmering Thinking… label; it opens again whenever thinking restarts. |
| `duration` | `number` | `measured` | no | Seconds spent; measured from streaming start to end when omitted. |
| `defaultOpen` | `boolean` | `true` | no | Initial disclosure state. |
| `open` | `boolean` | — | no | Controlled disclosure; the reader’s choice otherwise wins over the automatic fold. |
| `onOpenChange` | `(open) => void` | — | no | Controlled disclosure; the reader’s choice otherwise wins over the automatic fold. |
| `variant` | `trail \| steps` | `trail` | no | steps drops the quote rule so detailed steps draw their own rail. |
| `thinkingLabel` | `string` | `Thinking…` | no | Streaming label, a fixed label, and the fold delay in ms. |
| `label` | `string` | — | no | Streaming label, a fixed label, and the fold delay in ms. |
| `autoCloseDelay` | `number` | `1000` | no | Streaming label, a fixed label, and the fold delay in ms. |
| `ChatMessageReasoningStep.status` | `pending \| running \| done \| failed \| cancelled` | `done` | no | A step with the shared statuses. |
| `ChatMessageReasoningStep.label` | `ReactNode` | — | no | A detailed chain-of-thought step: kind icon, title, summary and right-hand meta; children open as details. |
| `icon` | `string` | — | no | A detailed chain-of-thought step: kind icon, title, summary and right-hand meta; children open as details. |
| `description` | `ReactNode` | — | no | A detailed chain-of-thought step: kind icon, title, summary and right-hand meta; children open as details. |
| `meta` | `ReactNode` | — | no | A detailed chain-of-thought step: kind icon, title, summary and right-hand meta; children open as details. |
| `ChatMessageReasoningResults.results` | `Array<{ title, url?, site?, icon? }>` | `[]` | no | Search results as link chips with favicons; max limits them with a +n more. |
| `ChatMessageReasoningImage.src` | `string` | — | no | A thumbnail the step looked at. |
| `alt` | `string` | — | no | A thumbnail the step looked at. |
| `caption` | `ReactNode` | — | no | A thumbnail the step looked at. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `variant`: `trail`, `steps`

## Accessibility

The trail and each detailed step are disclosure buttons with aria-expanded; step status is spoken after the label, not left to colour. The shimmer is real text and holds still for reduced motion.

## Notes

- The Agent run and AI message with steps examples on this page combine reasoning, a chain of thought, a tool approval (Chat/ChatTool) and a checkpoint (Chat/ChatMessageList).

## Related

- [Chat](https://design.gaudi.site/docs/blocks/chat): The chat frame: a shell for a full page or a sidebar assistant that composes the Chat parts: the thread, the composer, sessions, files, the plan and activity.
- [ChatTool](https://design.gaudi.site/docs/chat/chat-tool): One tool call with status, input and output as data, nested calls and a retry, plus ChatMessageToolApproval for calls that wait on the person.
- [ChatMessageList](https://design.gaudi.site/docs/chat/chat-message-list): The conversation: a scroller that keeps the thread anchored and ChatMessageParts rendering each assistant turn from its parts.

Source: https://design.gaudi.site/docs/chat/chat-reasoning (Markdown with example code: https://design.gaudi.site/docs/chat/chat-reasoning.md)

---

# ChatSessionList

> Session navigation inside a complete chat: grouped conversations with title search, new chat, rename and delete.

The compact panel opens History in place of the transcript; the full-page composition uses ChatShell navigation and its narrow-screen Sheet. The host keeps a separate transcript and draft for each session.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatSessionList` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatSessionList/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-chatsessionlist--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ChatSessionList } from '@gaudi/design-system/chat/ChatSessionList';
```

## Usage

```jsx
import { ChatShell } from '@gaudi/design-system/blocks/Chat';
import { ChatSessionList, ChatMessageParts, ChatPromptComposer } from '@gaudi/design-system/chat';

<ChatShell
  title={activeSession.title}
  navigation={
    <ChatSessionList
      sessions={sessions}
      activeId={activeSession.id}
      onSelect={openChat}
      onNew={startChat}
      onRename={renameChat}
      onDelete={deleteChat}
    />
  }
  composer={<ChatPromptComposer value={activeSession.draft} onValueChange={saveDraft} onSubmit={send} />}
>
  <div role='region' aria-label='Conversation' tabIndex={0} className='min-h-0 flex-1 overflow-y-auto p-4'>
    {activeSession.turns.map((turn) => <ChatMessageParts key={turn.id} parts={turn.parts} />)}
  </div>
</ChatShell>
```

## Examples

Examples (rendered from Storybook):

- [Session history in a full chat panel](https://storybook.gaudi.site/index.html?path=/story/chat-chatsessionlist--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `searchable` | `boolean` | `true` | no | Search box. |
| `sessions` | `Array<{ id, title, preview?, updated?, group?, live? }>` | `[]` | no | Conversations, grouped by group. |
| `activeId` | `string` | — | no | Current chat and selection. |
| `onSelect` | `function` | — | no | Current chat and selection. |
| `onNew / onRename / onDelete` | `function` | — | no | New chat, rename dialog, delete confirmation. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

The current chat has aria-current; row menus are named after each chat, and rename and delete use labelled dialogs. In the compact composition, History and New chat remain in the header while history hides the composer; Back to conversation or session selection resumes the transcript. The page navigation Sheet closes after selection and returns focus to its opener.

## Related

- [Sheet](https://design.gaudi.site/docs/components/sheet): A panel that slides in from an edge over a dimmed page, for side tasks such as settings, details, comments, notifications or an assistant, without leaving the current screen.
- [ChatActivityHistory](https://design.gaudi.site/docs/chat/chat-activity-history): What happened in a conversation, newest last.
- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator): What the assistant is doing: idle, thinking, streaming, tool, done or error.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [ChatDelegation](https://design.gaudi.site/docs/chat/chat-delegation): Work handed to another agent: who took it, the brief, its status and its activity.

Source: https://design.gaudi.site/docs/chat/chat-session-list (Markdown with example code: https://design.gaudi.site/docs/chat/chat-session-list.md)

---

# ChatSources

> Numbered citations that open a hover card (with a carousel when one marker cites several sources) and the list of sources under a reply.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatSources` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatSources/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-chatsources--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import ChatSources from '@gaudi/design-system/chat/ChatSources';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/chat-sources-research-citations.json`.

## Usage

```jsx
import { ChatMessageCitation, ChatMessageSources } from '@gaudi/design-system/chat';

<>
<p>
  Readers leave early <ChatMessageCitation index={1} source={sources[0]} /> on long posts
  <ChatMessageCitation index={2} sources={[sources[1], sources[2]]} />.
</p>
<ChatMessageSources sources={sources} />
</>
```

## Examples

### Research with citations

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chat-sources-research-citations.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | `n sources` | no | Toggle label for the list. |
| `defaultOpen` | `boolean` | `false` | no | Initial disclosure. |
| `sources` | `Array<{ title, url?, kind?, site?, excerpt?, quote?, icon? }>` | `[]` | no | Sources in citation order. |
| `ChatMessageCitation.index` | `number` | — | no | Inline numbered pill; several sources page through a carousel in the card. |
| `source` | `source` | — | no | Inline numbered pill; several sources page through a carousel in the card. |
| `sources` | `source[]` | — | no | Inline numbered pill; several sources page through a carousel in the card. |
| `ChatMessageCitation.labels` | `{ trigger, carousel, position, previous, next }` | `English copy` | no | Names for the pill, the carousel and its controls. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Citations are buttons named “Source n: title”. The card opens on hover without taking focus, and on click, tap, Enter or Space with focus inside; arrow keys and buttons page the carousel and the position is announced.

## Notes

- See Cited answer on this page for grouped citations [1, 3] beside a SchemaDisplay tool result.

## Related

- [SchemaDisplay](https://design.gaudi.site/docs/components/schema-display): Read an API endpoint or a JSON Schema: method badge, path with highlighted parameters, and request and response schemas as an expandable property tree.
- [ChatMessage](https://design.gaudi.site/docs/chat/chat-message): One turn in a conversation: avatar, sender and time, the content stack and a status footer.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatFeedback](https://design.gaudi.site/docs/chat/chat-feedback): Copy, rate and regenerate a finished reply.

Source: https://design.gaudi.site/docs/chat/chat-sources (Markdown with example code: https://design.gaudi.site/docs/chat/chat-sources.md)

---

# ChatThreadNav

> Previous, next and a menu of every prompt in a long thread.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatThreadNav` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatThreadNav/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-chatthreadnav--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ChatThreadNav } from '@gaudi/design-system/chat/ChatThreadNav';
```

## Usage

```jsx
import { ChatThreadNav } from '@gaudi/design-system/chat';

<ChatThreadNav turns={prompts} current={currentId} onNavigate={scrollToTurn} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/chat-chatthreadnav--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `start` | `string` | `t2` | no | Example only: the turn in view at first. |
| `turns` | `Array<{ id, label }>` | `[]` | no | Prompts in thread order. |
| `current` | `string` | — | no | The turn in view and navigation. |
| `onNavigate` | `(id) => void` | — | no | The turn in view and navigation. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

A labelled group; the menu button reads its position.

## Related

- [ChatActivityHistory](https://design.gaudi.site/docs/chat/chat-activity-history): What happened in a conversation, newest last.
- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator): What the assistant is doing: idle, thinking, streaming, tool, done or error.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [ChatDelegation](https://design.gaudi.site/docs/chat/chat-delegation): Work handed to another agent: who took it, the brief, its status and its activity.
- [ChatEffortSlider](https://design.gaudi.site/docs/chat/chat-effort-slider): How hard the assistant should think, as a stepped slider over named levels.

Source: https://design.gaudi.site/docs/chat/chat-thread-nav (Markdown with example code: https://design.gaudi.site/docs/chat/chat-thread-nav.md)

---

# ChatTool

> One tool call with status, input and output as data, nested calls and a retry, plus ChatMessageToolApproval for calls that wait on the person.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatTool` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatTool/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-chattool--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import ChatTool from '@gaudi/design-system/chat/ChatTool';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/chat-tool-running-tools.json`.

## Usage

```jsx
import { ChatMessageTool, ChatMessageToolApproval } from '@gaudi/design-system/chat';

<>
<ChatMessageTool name='schedule_newsletter' status={status} input={input} output={output} error={error} onRetry={retry} />

<ChatMessageToolApproval
  name='publish_post'
  description='Publish the draft to the blog'
  input={{ slug: 'local-first-drafts' }}
  allowAlways
  onApprove={({ always }) => approve(always)}
  onDeny={deny}
/>
</>
```

## Examples

### Running tools

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chat-tool-running-tools.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | `string` | — | no | Tool name. |
| `status` | `pending \| running \| done \| failed \| cancelled \| awaiting \| denied` | `pending` | no | Status badge; failed opens with the error. |
| `defaultOpen` | `boolean` | `false` | no | Initial disclosure; a failed call opens on its own. |
| `input` | `unknown` | — | no | Shown with ChatMessageData. |
| `output` | `unknown` | — | no | Shown with ChatMessageData. |
| `error` | `string` | — | no | Shown with ChatMessageData. |
| `onRetry` | `function` | — | no | Retry a failed call. |
| `ChatMessageData.value` | `unknown` | — | no | A list or table with a JSON view. |
| `label` | `string` | — | no | A list or table with a JSON view. |
| `ChatMessageToolApproval.state / defaultState / onStateChange` | `requested \| approved \| denied \| executed` | `requested` | no | Approval lifecycle; control it to move to executed with the result as children. |
| `ChatMessageToolApproval.onApprove` | `({ always }) => void` | — | no | The person’s decision; always is the “always allow” choice. |
| `onDeny` | `() => void` | — | no | The person’s decision; always is the “always allow” choice. |
| `ChatMessageToolApproval.allowAlways` | `boolean` | `false` | no | Offer “always allow”, explain a denial, and replace the copy. |
| `reason` | `ReactNode` | — | no | Offer “always allow”, explain a denial, and replace the copy. |
| `labels` | `object` | `English copy` | no | Offer “always allow”, explain a denial, and replace the copy. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `status`: `pending`, `running`, `done`, `failed`, `cancelled`, `awaiting`, `denied`

## Accessibility

The header is a disclosure naming the tool and status; errors are alerts. An approval is a labelled group; after a decision focus moves to its outcome, which is a status message.

## Notes

- See Agent run on Chat/ChatReasoning for an approval inside a full agent run, with approve and deny.

## Related

- [Chat](https://design.gaudi.site/docs/blocks/chat): The chat frame: a shell for a full page or a sidebar assistant that composes the Chat parts: the thread, the composer, sessions, files, the plan and activity.
- [ChatReasoning](https://design.gaudi.site/docs/chat/chat-reasoning): The thinking trail before an answer: a shimmering Thinking… label while it streams, a chain of thought of detailed steps with search results and images, folding into Thought for Ns once the answer starts.
- [ChatMessage](https://design.gaudi.site/docs/chat/chat-message): One turn in a conversation: avatar, sender and time, the content stack and a status footer.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatMessageList](https://design.gaudi.site/docs/chat/chat-message-list): The conversation: a scroller that keeps the thread anchored and ChatMessageParts rendering each assistant turn from its parts.

Source: https://design.gaudi.site/docs/chat/chat-tool (Markdown with example code: https://design.gaudi.site/docs/chat/chat-tool.md)

---

# ChatVoice

> Voice building blocks: ChatSpeechInput dictates into the composer, ChatMicSelector picks the input device, ChatVoiceSelector picks the voice that answers and ChatAudioPlayer plays voice messages and spoken replies.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatVoice` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatVoice/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-voice--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ChatAudioPlayer } from '@gaudi/design-system/chat/ChatVoice';
```

## Usage

```jsx
import { ChatAudioPlayer, ChatMicSelector, ChatSpeechInput, ChatVoiceSelector } from '@gaudi/design-system/chat';

<>
<ChatMicSelector value={deviceId} onValueChange={setDeviceId} />
<ChatSpeechInput deviceId={deviceId} onInterim={setPreview} onTranscript={append} onAudio={transcribe} />
<ChatVoiceSelector voices={voices} groupBy='provider' value={voice} onValueChange={setVoice} onPreview={speakSample} />
<ChatAudioPlayer src={reply.audioUrl} title='Reply' peaks={reply.peaks} download='reply.mp3' />
</>
```

## Examples

Examples (rendered from Storybook):

- [Voice mode](https://storybook.gaudi.site/index.html?path=/story/chat-voice--voice-mode)
- [Cancel capture and pending transcription](https://storybook.gaudi.site/index.html?path=/story/chat-voice--capture-cancellation)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ChatSpeechInput.onTranscript` | `(text, { final }) => void` | — | no | Final phrases and the live interim text from the Web Speech API. |
| `onInterim` | `(text) => void` | — | no | Final phrases and the live interim text from the Web Speech API. |
| `ChatSpeechInput.onAudio` | `(blob: Blob) => string \| Promise<string> \| void` | — | no | MediaRecorder fallback; return the transcript. |
| `ChatSpeechInput.mode` | `auto \| speech \| recorder` | `auto` | no | Engine, recognition language and input device. |
| `lang` | `string` | `en-US` | no | Engine, recognition language and input device. |
| `deviceId` | `string` | — | no | Engine, recognition language and input device. |
| `ChatSpeechInput.onStateChange` | `(state) => void` | — | no | idle, listening, processing; denied, no-device, unsupported, failed; live level 0..1. |
| `onError` | `(kind, cause) => void` | — | no | idle, listening, processing; denied, no-device, unsupported, failed; live level 0..1. |
| `onLevel` | `(level) => void` | — | no | idle, listening, processing; denied, no-device, unsupported, failed; live level 0..1. |
| `ChatMicSelector.value` | `string` | — | no | Chosen device and a Test level meter. |
| `onValueChange` | `(deviceId, device) => void` | — | no | Chosen device and a Test level meter. |
| `meter` | `boolean` | `true` | no | Chosen device and a Test level meter. |
| `ChatVoiceSelector.voices` | `Array<{ id, name, provider?, gender?, accent?, age?, style?, description?, previewUrl? }>` | `[]` | no | The voices, supplied by the app. |
| `ChatVoiceSelector.value` | `string` | — | no | Choice, sample playback, headings and filter. |
| `onValueChange` | `(id, voice) => void` | — | no | Choice, sample playback, headings and filter. |
| `onPreview` | `(voice, { signal }) => Promise` | — | no | Choice, sample playback, headings and filter. |
| `groupBy` | `string` | — | no | Choice, sample playback, headings and filter. |
| `searchable` | `boolean` | — | no | Choice, sample playback, headings and filter. |
| `ChatAudioPlayer.src` | `string` | — | no | Audio, label, waveform peaks 0..1 and a length before metadata. |
| `title` | `string` | — | no | Audio, label, waveform peaks 0..1 and a length before metadata. |
| `peaks` | `number[]` | — | no | Audio, label, waveform peaks 0..1 and a length before metadata. |
| `duration` | `number` | — | no | Audio, label, waveform peaks 0..1 and a length before metadata. |
| `ChatAudioPlayer.speeds` | `number[]` | `[1, 1.5, 2]` | no | Speed toggle and an optional download. |
| `download` | `boolean \| string` | `false` | no | Speed toggle and an optional download. |
| `useAudioLevel(stream, { onLevel })` (helper) | `{ levelRef, waveformRef }` | — | no | Live level and samples for ChatPersona. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

ChatSpeechInput is a pressed-state button stopped by Escape that announces listening and transcribing politely and explains when it is disabled; ChatMicSelector names its select and explains a blocked permission; ChatVoiceSelector is a fieldset of native radios with named sample buttons; the ChatAudioPlayer scrubber is a slider that reads time.

## Related

- [ChatPersona](https://design.gaudi.site/docs/chat/chat-persona): The assistant’s presence in a voice conversation: an orb that rests, connects, listens, thinks, speaks, sleeps or shows an error, drawn by one of eight renderers.
- [ChatActivityHistory](https://design.gaudi.site/docs/chat/chat-activity-history): What happened in a conversation, newest last.
- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator): What the assistant is doing: idle, thinking, streaming, tool, done or error.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark): The assistant’s mark: a Gaudí-inspired motif glazed in a tile hue picked from a seed, or an icon, image or monogram on a token tile, with an optional activity badge.
- [ChatBubble](https://design.gaudi.site/docs/chat/chat-bubble): The surface around a message, with seven variants and reactions.
- [ChatDelegation](https://design.gaudi.site/docs/chat/chat-delegation): Work handed to another agent: who took it, the brief, its status and its activity.

Source: https://design.gaudi.site/docs/chat/chat-voice (Markdown with example code: https://design.gaudi.site/docs/chat/chat-voice.md)

---

# ChatWorkspace

> A context panel that connects the agent roster to each agent’s files, with a return to the complete workspace.

- Category: Chat
- Import: `@gaudi/design-system/chat/ChatWorkspace` (also `@gaudi/design-system/chat`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/chat/ChatWorkspace/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/chat-chatworkspace--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ChatWorkspace } from '@gaudi/design-system/chat/ChatWorkspace';
```

## Usage

```jsx
import { ChatWorkspace } from '@gaudi/design-system/chat';

<ChatWorkspace agents={agents} fileExplorerProps={{ items, selectedId, onSelect, onPreview, onRefresh }} view={view} onViewChange={setView} agentId={agentId} onAgentChange={setAgentId} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/chat-chatworkspace--playground)
- [Agent roster and activity](https://storybook.gaudi.site/index.html?path=/story/chat-chatworkspace--agent-roster)
- [Empty](https://storybook.gaudi.site/index.html?path=/story/chat-chatworkspace--empty)
- [Controlled workspace navigation](https://storybook.gaudi.site/index.html?path=/story/chat-chatworkspace--controlled-navigation)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `title` | `string` | `Workspace` | no | Panel heading and optional supporting content. |
| `description` | `string` | — | no | Panel heading and optional supporting content. |
| `actions` | `ReactNode` | — | no | Panel heading and optional supporting content. |
| `agents` | `Array<{ id, name, description?, state?, labels?, fileRootId? }>` | `[]` | no | Stable agent identity, ChatActivityIndicator state and an existing file-tree folder. |
| `fileExplorerProps` | `ChatFileExplorer props` | `{}` | no | Reuse the complete explorer contract for data, selection, preview, download and recovery. |
| `view` | `files \| agents` | — | no | Controlled or local tab state. |
| `defaultView` | `files \| agents` | `files` | no | Controlled or local tab state. |
| `onViewChange` | `function` | — | no | Controlled or local tab state. |
| `agentId` | `string \| null` | — | no | Controlled or local agent scope. Null restores all files. |
| `defaultAgentId` | `string \| null` | `null` | no | Controlled or local agent scope. Null restores all files. |
| `onAgentChange` | `function` | — | no | Controlled or local agent scope. Null restores all files. |
| `labels` | `object` | `English copy` | no | Tabs, navigation and empty-agent copy. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `view`: `files`, `agents`
- `defaultView`: `files`, `agents`

## Accessibility

Core Tabs and Tree own keyboard navigation. Agent actions move focus to the Files tab. Control view, agentId and explorer selection when composing desktop and Sheet copies in ChatShell.

## Notes

- The host owns preview rendering, permissions and file IO. ChatShell owns responsive layout and overlays.

## Related

- [Tabs](https://design.gaudi.site/docs/components/tabs): Switch between related panels with keyboard-accessible tab controls.
- [Tree](https://design.gaudi.site/docs/components/tree): Browse hierarchical content with expansion, selection, checkboxes and drag feedback.
- [Sheet](https://design.gaudi.site/docs/components/sheet): A panel that slides in from an edge over a dimmed page, for side tasks such as settings, details, comments, notifications or an assistant, without leaving the current screen.
- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator): What the assistant is doing: idle, thinking, streaming, tool, done or error.

Source: https://design.gaudi.site/docs/chat/chat-workspace (Markdown with example code: https://design.gaudi.site/docs/chat/chat-workspace.md)

---

# Charts

> Recharts-based charts framed by ChartFrame. Not in the root entry; install the optional `recharts` peer.

22 pages · 22 live examples, generated from the design system metadata.

- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points. Use it around a custom visual, with the Recharts composition parts and Gaudi primitives.
- [ComposedChart](https://design.gaudi.site/docs/charts/composed-chart): Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.
- [DonutChart](https://design.gaudi.site/docs/charts/donut-chart): Parts of a whole as a donut with a centre summary, or a pie (PieChart); slices are selectable and small ones fold into Other.
- [FunnelChart](https://design.gaudi.site/docs/charts/funnel-chart): Steps in order with the conversion from each step to the next, as left-aligned bars or a centred funnel.
- [GaugeChart](https://design.gaudi.site/docs/charts/gauge-chart): One reading against threshold bands with a target tick, on any scale.
- [HeatmapChart](https://design.gaudi.site/docs/charts/heatmap-chart): Values on a grid of rows and columns, on a sequential or diverging ramp; Up and Down move between rows.
- [HistogramChart](https://design.gaudi.site/docs/charts/histogram-chart): Observations in round bins with labelled markers such as the median, a percentile or a budget.
- [LineChart](https://design.gaudi.site/docs/charts/line-chart): Lines per series over categories, with projections, references, annotations and a choice of curve.
- [OrgChart](https://design.gaudi.site/docs/charts/org-chart): A connected organization hierarchy with person cards, expandable reporting lines, and contained scrolling.
- [RadarChart](https://design.gaudi.site/docs/charts/radar-chart): Scores on several axes at once, one record per axis and a value per series; a dashed series reads as a target.
- [RadialChart](https://design.gaudi.site/docs/charts/radial-chart): Progress against a full 0–100 track, one ring per record (RadialBarChart).
- [RangeChart](https://design.gaudi.site/docs/charts/range-chart): A band between a low and a high value per category with a line through it: forecasts, percentile spreads, highs and lows.
- [SankeyChart](https://design.gaudi.site/docs/charts/sankey-chart): Flows between stages with widths proportional to volume; each flow is a keyboard point and a table row.
- [ScatterChart](https://design.gaudi.site/docs/charts/scatter-chart): Correlation between two numbers, with labelled points, reference lines and bubbles sized by a third value (BubbleChart).
- [Sparkline](https://design.gaudi.site/docs/charts/sparkline): A word-sized trend without axes, for stat cards, tables and prose; still a named chart with its data table.
- [StackedBarList](https://design.gaudi.site/docs/charts/stacked-bar-list): Ranked rows of stacked segments that grow with the list: issues by status per team, readers by source per post.
- [TournamentBracket](https://design.gaudi.site/docs/charts/tournament-bracket): A knockout bracket with connected match cards, round paging, scores, penalties, and explicit winners.
- [TreemapChart](https://design.gaudi.site/docs/charts/treemap-chart): Nested rectangles sized by value, tinted by group or shaded on the heat ramp.
- [WaterfallChart](https://design.gaudi.site/docs/charts/waterfall-chart): How a starting value becomes an ending one through increases and decreases, with running totals and subtotals.

Source: https://design.gaudi.site/docs/charts (Markdown with example code: https://design.gaudi.site/docs/charts.md)

---

# AreaChart

> Filled areas per series over categories, stacked into a total or overlapping from zero.

- Category: Charts
- Import: `@gaudi/design-system/charts/AreaChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/AreaChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-areachart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { AreaChart } from '@gaudi/design-system/charts/AreaChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/area-chart-annotated-traffic.json`.

## Usage

```jsx
import { AreaChart } from '@gaudi/design-system/charts';

<AreaChart title='Readers by device' ariaLabel='Daily readers by device' data={days} series={devices} stacked showLegend />
```

## Examples

### Annotated traffic with keyboard reading

Registry: `npx shadcn@latest add https://design.gaudi.site/r/area-chart-annotated-traffic.json`

### Fills, curves and stacking

Registry: `npx shadcn@latest add https://design.gaudi.site/r/area-chart-fills-stacking.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `xKey / yKey` | `string` | `label / value` | no | Category field and the single value field when series is omitted. |
| `series` | `Array<{ key, label?, dashed? }>` | `from yKey` | no | Value fields drawn as series, in order; a dashed series reads as a projection or target. |
| `stacked` | `boolean` | `false` | no | Stack the areas into a total. |
| `curve` | `monotone \| linear \| step` | `monotone` | no | Area interpolation. |
| `references / annotations` | `Array<{ x?, y?, label, tone? }>` | — | no | Labelled guide lines and point notes. |
| `showGrid / showLegend / showTooltip` | `boolean` | `true / false / true` | no | Presentation. |
| `colors` | `string[]` | `categorical palette` | no | Override the series colours with chart tokens. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `curve`: `monotone`, `linear`, `step`
- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.

Source: https://design.gaudi.site/docs/charts/area-chart (Markdown with example code: https://design.gaudi.site/docs/charts/area-chart.md)

---

# BarChart

> Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.

- Category: Charts
- Import: `@gaudi/design-system/charts/BarChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/BarChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-barchart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { BarChart } from '@gaudi/design-system/charts/BarChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/bar-chart-fills-layout.json`.

## Usage

```jsx
import { BarChart } from '@gaudi/design-system/charts';

<BarChart title='Readers by channel' ariaLabel='Monthly readers by channel' data={readers} series={[{ key: 'search', label: 'Search' }, { key: 'newsletter', label: 'Newsletter' }]} showLegend />
```

## Examples

### Fills, comparison and layout

Registry: `npx shadcn@latest add https://design.gaudi.site/r/bar-chart-fills-layout.json`

### Hover to reveal values

Registry: `npx shadcn@latest add https://design.gaudi.site/r/bar-chart-hover-values.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `xKey / yKey` | `string` | `label / value` | no | Category field and the single value field when series is omitted. |
| `series` | `Array<{ key, label?, dashed? }>` | `from yKey` | no | Value fields drawn as series, in order; a dashed series reads as a projection or target. |
| `stacked` | `boolean` | `false` | no | Stack the series into one bar. |
| `layout` | `vertical \| horizontal` | `vertical` | no | Horizontal lays bars along the value axis for long labels. |
| `highlight` | `string` | — | no | Category to emphasise; the others dim. |
| `barRadius` | `number` | `4` | no | Corner radius at the bar end. |
| `references / annotations` | `Array<{ x?, y?, label, tone? }>` | — | no | Labelled guide lines and point notes. |
| `showGrid / showLegend / showTooltip` | `boolean` | `true / false / true` | no | Presentation. |
| `colors` | `string[]` | `categorical palette` | no | Override the series colours with chart tokens. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `layout`: `vertical`, `horizontal`
- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.

Source: https://design.gaudi.site/docs/charts/bar-chart (Markdown with example code: https://design.gaudi.site/docs/charts/bar-chart.md)

---

# BoxPlotChart

> Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.

- Category: Charts
- Import: `@gaudi/design-system/charts/BoxPlotChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/BoxPlotChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-boxplotchart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { BoxPlotChart } from '@gaudi/design-system/charts/BoxPlotChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/box-plot-chart-response-times.json`.

## Usage

```jsx
import { BoxPlotChart } from '@gaudi/design-system/charts';

<BoxPlotChart ariaLabel='Load time by template' data={[{ label: 'Home', values: [410, 460, 480, 520, 1420] }]} unit='ms' />
```

## Examples

### Response time by route

Registry: `npx shadcn@latest add https://design.gaudi.site/r/box-plot-chart-response-times.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `data` | `Array<{ label, values } \| { label, min, q1, median, q3, max, outliers? }>` | `[]` | no | Groups. |
| `labelKey / valuesKey` | `string` | `label / values` | no | Field names. |
| `unit` | `string` | — | no | Suffix on axis ticks. |
| `color` | `string` | `chart-1` | no | Box colour. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [ComposedChart](https://design.gaudi.site/docs/charts/composed-chart): Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.

Source: https://design.gaudi.site/docs/charts/box-plot-chart (Markdown with example code: https://design.gaudi.site/docs/charts/box-plot-chart.md)

---

# ChartFrame

> The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.

Use it around a custom visual, with the Recharts composition parts and Gaudi primitives.

- Category: Charts
- Import: `@gaudi/design-system/charts/ChartFrame` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/ChartFrame/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-chartframe--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ChartFrame } from '@gaudi/design-system/charts/ChartFrame';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/chart-frame-states-locale.json`.

## Usage

```jsx
import { ChartFrame, useChartFrame } from '@gaudi/design-system/charts';

<ChartFrame title='Writing goals' ariaLabel='Progress towards writing goals' points={points} showData='toggle'>
  <GoalBars />
</ChartFrame>
```

## Examples

### Loading, empty, invalid, error and locale

Registry: `npx shadcn@latest add https://design.gaudi.site/r/chart-frame-states-locale.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `points` | `Array<{ label, values: Array<{ name, value, display?, color? }> }>` | `[]` | no | What the keyboard walks and the table lists. |
| `status` | `ready \| loading \| empty \| invalid \| error` | `ready` | no | The frame state; charts derive it from their data. |
| `columns` | `number` | — | no | Row length for Up and Down on grid-shaped visuals. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `useChartFrame()` (helper) | `hook` | — | no | activeIndex, setActive and format for drawn elements; mark them with data-chart-index. |
| `ChartContainer / ChartGrid / ChartXAxis / ChartYAxis / ChartReferenceLine / ChartAnnotations / createRowsTooltip` | `parts` | — | no | Style bespoke Recharts charts with chart tokens. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `status`: `ready`, `loading`, `empty`, `invalid`, `error`
- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ComposedChart](https://design.gaudi.site/docs/charts/composed-chart): Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.
- [DonutChart](https://design.gaudi.site/docs/charts/donut-chart): Parts of a whole as a donut with a centre summary, or a pie (PieChart); slices are selectable and small ones fold into Other.

Source: https://design.gaudi.site/docs/charts/chart-frame (Markdown with example code: https://design.gaudi.site/docs/charts/chart-frame.md)

---

# ComposedChart

> Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.

- Category: Charts
- Import: `@gaudi/design-system/charts/ComposedChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/ComposedChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-composedchart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ComposedChart } from '@gaudi/design-system/charts/ComposedChart';
```

## Usage

```jsx
import { ComposedChart } from '@gaudi/design-system/charts';

<ComposedChart ariaLabel='Weekly views and minutes read' data={weeks} series={[{ key: 'views', type: 'bar' }, { key: 'readTime', type: 'line', axis: 'right' }]} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/charts-composedchart--playground)
- [Daily values with a rolling average](https://storybook.gaudi.site/index.html?path=/story/charts-composedchart--rolling-average)
- [Stacked bars with a rate line](https://storybook.gaudi.site/index.html?path=/story/charts-composedchart--stacked-with-rate)
- [Area behind a line](https://storybook.gaudi.site/index.html?path=/story/charts-composedchart--area-band)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `series` | `Array<{ key, label?, type: bar \| line \| area, axis?: right, stack?, dashed? }>` | `views bar + readTime line` | no | Each series names how it draws and which axis it reads against. |
| `xKey` | `string` | `label` | no | Category field. |
| `references / annotations` | `Array<{ x?, y?, label, tone? }>` | — | no | Labelled guide lines and point notes. |
| `showGrid / showLegend / showTooltip` | `boolean` | `true` | no | Presentation. |
| `colors` | `string[]` | `categorical palette` | no | Override the series colours with chart tokens. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [DonutChart](https://design.gaudi.site/docs/charts/donut-chart): Parts of a whole as a donut with a centre summary, or a pie (PieChart); slices are selectable and small ones fold into Other.
- [FunnelChart](https://design.gaudi.site/docs/charts/funnel-chart): Steps in order with the conversion from each step to the next, as left-aligned bars or a centred funnel.

Source: https://design.gaudi.site/docs/charts/composed-chart (Markdown with example code: https://design.gaudi.site/docs/charts/composed-chart.md)

---

# DonutChart

> Parts of a whole as a donut with a centre summary, or a pie (PieChart); slices are selectable and small ones fold into Other.

- Category: Charts
- Import: `@gaudi/design-system/charts/DonutChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/DonutChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-donutchart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { DonutChart } from '@gaudi/design-system/charts/DonutChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/donut-chart-patterned-slices.json`.

## Usage

```jsx
import { DonutChart } from '@gaudi/design-system/charts';

<DonutChart title='Where readers came from' ariaLabel='Sessions by source' data={sources} otherThreshold={0.03} onSelect={(slice) => setSource(slice?.label)} />
```

## Examples

### Patterned slices

Registry: `npx shadcn@latest add https://design.gaudi.site/r/donut-chart-patterned-slices.json`

### Select a topic, small slices as Other

Registry: `npx shadcn@latest add https://design.gaudi.site/r/donut-chart-topic-select.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `data` | `object[]` | `[]` | no | Slices. |
| `nameKey` | `string` | `label` | no | Slices. |
| `valueKey` | `string` | `value` | no | Slices. |
| `selectable` | `boolean` | — | no | Selection pins a slice; the centre shows its share. |
| `selectedIndex` | `number \| null` | — | no | Selection pins a slice; the centre shows its share. |
| `defaultSelectedIndex` | `number \| null` | — | no | Selection pins a slice; the centre shows its share. |
| `onSelect` | `(slice, index) => void` | — | no | Selection pins a slice; the centre shows its share. |
| `otherThreshold` | `number` | — | no | Fold small slices into Other. |
| `maxSlices` | `number` | — | no | Fold small slices into Other. |
| `otherLabel` | `string` | `Other` | no | Fold small slices into Other. |
| `centerLabel` | `string` | `Total` | no | Caption under the centre value. |
| `innerRadius` | `string \| number` | `'56%' (DonutChart), 0 (PieChart)` | no | Hole size. |
| `colors` | `string[]` | `categorical palette` | no | Override the series colours with chart tokens. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.

Source: https://design.gaudi.site/docs/charts/donut-chart (Markdown with example code: https://design.gaudi.site/docs/charts/donut-chart.md)

---

# FunnelChart

> Steps in order with the conversion from each step to the next, as left-aligned bars or a centred funnel.

- Category: Charts
- Import: `@gaudi/design-system/charts/FunnelChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/FunnelChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-funnelchart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { FunnelChart } from '@gaudi/design-system/charts/FunnelChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/funnel-chart-newsletter-signups.json`.

## Usage

```jsx
import { FunnelChart } from '@gaudi/design-system/charts';

<FunnelChart ariaLabel='Trial to paid funnel' data={steps} align='center' />
```

## Examples

### Newsletter signups

Registry: `npx shadcn@latest add https://design.gaudi.site/r/funnel-chart-newsletter-signups.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `data` | `object[]` | `[]` | no | Steps in order. |
| `labelKey` | `string` | `label` | no | Steps in order. |
| `valueKey` | `string` | `value` | no | Steps in order. |
| `align` | `start \| center` | `start` | no | Left-aligned bars or a centred funnel. |
| `monochrome` | `boolean` | `true` | no | One hue fading by step. |
| `conversionLabel` | `string` | `from previous` | no | Suffix on each conversion rate. |
| `colors` | `string[]` | `categorical palette` | no | Override the series colours with chart tokens. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `align`: `start`, `center`
- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [ComposedChart](https://design.gaudi.site/docs/charts/composed-chart): Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.

Source: https://design.gaudi.site/docs/charts/funnel-chart (Markdown with example code: https://design.gaudi.site/docs/charts/funnel-chart.md)

---

# GaugeChart

> One reading against threshold bands with a target tick, on any scale.

- Category: Charts
- Import: `@gaudi/design-system/charts/GaugeChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/GaugeChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-gaugechart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { GaugeChart } from '@gaudi/design-system/charts/GaugeChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/gauge-chart-web-vitals.json`.

## Usage

```jsx
import { GaugeChart } from '@gaudi/design-system/charts';

<GaugeChart ariaLabel='Mobile performance score' value={84} target={90} bands={[{ to: 50, tone: 'danger' }, { to: 90, tone: 'warning' }, { to: 100, tone: 'success' }]} />
```

## Examples

### Core Web Vitals

Registry: `npx shadcn@latest add https://design.gaudi.site/r/gauge-chart-web-vitals.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value` | `number` | `required` | no | The reading. |
| `min / max` | `number` | `0 / 100` | no | Scale. |
| `target` | `number` | — | no | Goal marked on the track. |
| `bands` | `Array<{ to, tone }>` | `[]` | no | Ascending threshold bands. |
| `label / unit` | `string` | — | no | Caption under the value and its suffix. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [ComposedChart](https://design.gaudi.site/docs/charts/composed-chart): Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.
- [DonutChart](https://design.gaudi.site/docs/charts/donut-chart): Parts of a whole as a donut with a centre summary, or a pie (PieChart); slices are selectable and small ones fold into Other.

Source: https://design.gaudi.site/docs/charts/gauge-chart (Markdown with example code: https://design.gaudi.site/docs/charts/gauge-chart.md)

---

# HeatmapChart

> Values on a grid of rows and columns, on a sequential or diverging ramp; Up and Down move between rows.

- Category: Charts
- Import: `@gaudi/design-system/charts/HeatmapChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/HeatmapChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-heatmapchart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { HeatmapChart } from '@gaudi/design-system/charts/HeatmapChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/heatmap-chart-errors-by-hour.json`.

## Usage

```jsx
import { HeatmapChart } from '@gaudi/design-system/charts';

<HeatmapChart ariaLabel='Readers by day and time' data={cells} valueLabel='Readers' />
```

## Examples

### Errors by service and hour

Registry: `npx shadcn@latest add https://design.gaudi.site/r/heatmap-chart-errors-by-hour.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `data` | `Array<{ x, y, value }>` | `[]` | no | Cells. |
| `xKey / yKey / valueKey` | `string` | `x / y / value` | no | Field names. |
| `xLabels / yLabels` | `string[]` | `first appearance` | no | Column and row order. |
| `scale` | `sequential \| diverging` | `sequential` | no | Ramp; diverging centres on midpoint. |
| `midpoint` | `number` | `0` | no | Ramp; diverging centres on midpoint. |
| `showValues` | `boolean` | `up to 12 columns` | no | Print values in cells; their name in the readout. |
| `valueLabel` | `string` | `Value` | no | Print values in cells; their name in the readout. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `scale`: `sequential`, `diverging`
- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.

Source: https://design.gaudi.site/docs/charts/heatmap-chart (Markdown with example code: https://design.gaudi.site/docs/charts/heatmap-chart.md)

---

# HistogramChart

> Observations in round bins with labelled markers such as the median, a percentile or a budget.

- Category: Charts
- Import: `@gaudi/design-system/charts/HistogramChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/HistogramChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-histogramchart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { HistogramChart } from '@gaudi/design-system/charts/HistogramChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/histogram-chart-reading-time.json`.

## Usage

```jsx
import { HistogramChart } from '@gaudi/design-system/charts';

<HistogramChart ariaLabel='Distribution of page weight' values={weights} markers={[{ value: 520, label: 'Median' }]} unit=' KB' />
```

## Examples

### Reading time with median and p90

Registry: `npx shadcn@latest add https://design.gaudi.site/r/histogram-chart-reading-time.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `values` | `number[]` | `[]` | no | Observations (or data). |
| `bins` | `number` | `auto` | no | Approximate bin count; edges snap to round numbers. |
| `domain` | `[number, number]` | `data extent` | no | Fix the axis so histograms compare. |
| `markers` | `Array<{ value, label, tone? }>` | `[]` | no | Vertical guides. |
| `unit / countLabel` | `string` | `— / Count` | no | Bin suffix and the count column name. |
| `color` | `string` | `chart-1` | no | Bar colour. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [ComposedChart](https://design.gaudi.site/docs/charts/composed-chart): Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.

Source: https://design.gaudi.site/docs/charts/histogram-chart (Markdown with example code: https://design.gaudi.site/docs/charts/histogram-chart.md)

---

# LineChart

> Lines per series over categories, with projections, references, annotations and a choice of curve.

- Category: Charts
- Import: `@gaudi/design-system/charts/LineChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/LineChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-linechart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { LineChart } from '@gaudi/design-system/charts/LineChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/line-chart-forecast-zone.json`.

## Usage

```jsx
import { LineChart } from '@gaudi/design-system/charts';

<LineChart title='Subscribers' ariaLabel='Newsletter subscribers per month' data={subscribers} series={[{ key: 'subscribers', label: 'Subscribers' }, { key: 'projected', label: 'Projected', dashed: true }]} />
```

## Examples

### Forecast with a stripe zone

Registry: `npx shadcn@latest add https://design.gaudi.site/r/line-chart-forecast-zone.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `xKey / yKey` | `string` | `label / value` | no | Category field and the single value field when series is omitted. |
| `series` | `Array<{ key, label?, dashed? }>` | `from yKey` | no | Value fields drawn as series, in order; a dashed series reads as a projection or target. |
| `curve` | `monotone \| linear \| step` | `monotone` | no | Line interpolation. |
| `showDots` | `boolean` | `true` | no | Point markers. |
| `references / annotations` | `Array<{ x?, y?, label, tone? }>` | — | no | Labelled guide lines and point notes. |
| `showGrid / showLegend / showTooltip` | `boolean` | `true / false / true` | no | Presentation. |
| `colors` | `string[]` | `categorical palette` | no | Override the series colours with chart tokens. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `curve`: `monotone`, `linear`, `step`
- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ComposedChart](https://design.gaudi.site/docs/charts/composed-chart): Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.

Source: https://design.gaudi.site/docs/charts/line-chart (Markdown with example code: https://design.gaudi.site/docs/charts/line-chart.md)

---

# OrgChart

> A connected organization hierarchy with person cards, expandable reporting lines, and contained scrolling.

- Category: Charts
- Import: `@gaudi/design-system/charts/OrgChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/OrgChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-orgchart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { OrgChart } from '@gaudi/design-system/charts/OrgChart';
```

## Usage

```jsx
import { OrgChart } from '@gaudi/design-system/charts/OrgChart';

const team = { id: 'lead', name: 'Bram Ellery', role: 'Engineering Lead', children: [{ id: 'dev', name: 'Sam Rivera', role: 'Engineer' }] };
<OrgChart label='Engineering organization' data={team} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/charts-orgchart--playground)
- [Collapsed departments](https://storybook.gaudi.site/index.html?path=/story/charts-orgchart--department-overview)
- [Empty](https://storybook.gaudi.site/index.html?path=/story/charts-orgchart--empty)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `data` | `OrgNode \| null` | — | no | Root { id, name, role?, department?, avatar?, children? }. IDs must be unique; children form an acyclic tree. |
| `label` | `string` | `Organization chart` | no | Accessible name of the scrolling region. |
| `collapsedIds / defaultCollapsedIds / onCollapsedIdsChange` | `string[] / function` | `[]` | no | Controlled or initial collapsed branches; callback receives the next IDs. |
| `onNodeClick` | `(node) => void` | — | no | Makes person cards keyboard-accessible buttons. The host owns details or selection. |
| `renderNode` | `(node) => ReactNode` | `Person avatar and text` | no | Custom card content. Keep it non-interactive when onNodeClick wraps it in a button. |
| `disabled` | `boolean` | `false` | no | Disables person and branch actions; scrolling remains available. |
| `labels` | `object` | `English labels` | no | Override empty and expand(node), collapse(node), reports(count) text. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Nested lists convey reporting relationships. Branch buttons expose expanded state, retain focus when toggled, and work with Enter or Space. The labelled scroll region is keyboard focusable. Avatars are decorative because names are visible.

## Related

- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [ComposedChart](https://design.gaudi.site/docs/charts/composed-chart): Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.
- [DonutChart](https://design.gaudi.site/docs/charts/donut-chart): Parts of a whole as a donut with a centre summary, or a pie (PieChart); slices are selectable and small ones fold into Other.

Source: https://design.gaudi.site/docs/charts/org-chart (Markdown with example code: https://design.gaudi.site/docs/charts/org-chart.md)

---

# RadarChart

> Scores on several axes at once, one record per axis and a value per series; a dashed series reads as a target.

- Category: Charts
- Import: `@gaudi/design-system/charts/RadarChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/RadarChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-radarchart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { RadarChart } from '@gaudi/design-system/charts/RadarChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/radar-chart-target-scores.json`.

## Usage

```jsx
import { RadarChart } from '@gaudi/design-system/charts';

<RadarChart ariaLabel='Draft scores against the target' data={review} series={[{ key: 'draft', label: 'Draft' }, { key: 'target', label: 'Target', dashed: true }]} domain={[0, 100]} />
```

## Examples

### Scores against a target

Registry: `npx shadcn@latest add https://design.gaudi.site/r/radar-chart-target-scores.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `xKey / yKey` | `string` | `label / value` | no | Category field and the single value field when series is omitted. |
| `series` | `Array<{ key, label?, dashed? }>` | `from yKey` | no | Value fields drawn as series, in order; a dashed series reads as a projection or target. |
| `domain` | `[number, number \| auto]` | `[0, auto]` | no | Fix the scale so charts compare. |
| `filled` | `boolean` | `true` | no | Fill each outline. |
| `showRings` | `boolean` | `true` | no | Value labels on the rings. |
| `showLegend / showTooltip` | `boolean` | `true` | no | Presentation. |
| `colors` | `string[]` | `categorical palette` | no | Override the series colours with chart tokens. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.

Source: https://design.gaudi.site/docs/charts/radar-chart (Markdown with example code: https://design.gaudi.site/docs/charts/radar-chart.md)

---

# RadialChart

> Progress against a full 0–100 track, one ring per record (RadialBarChart).

- Category: Charts
- Import: `@gaudi/design-system/charts/RadialChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/RadialChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-radialchart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import RadialChart from '@gaudi/design-system/charts/RadialChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/radial-chart-labelled-scores.json`.

## Usage

```jsx
import { RadialBarChart } from '@gaudi/design-system/charts';

<RadialBarChart title='Goals this year' ariaLabel='Progress towards each goal' data={[{ label: 'Essays', value: 75 }]} />
```

## Examples

### Labelled scores

Registry: `npx shadcn@latest add https://design.gaudi.site/r/radial-chart-labelled-scores.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `data` | `object[]` | `[]` | no | One ring per record; values are percentages. |
| `nameKey` | `string` | `label` | no | One ring per record; values are percentages. |
| `valueKey` | `string` | `value` | no | One ring per record; values are percentages. |
| `color` | `string` | `chart-1` | no | Colour of a single ring. |
| `colors` | `string[]` | `categorical palette` | no | Override the series colours with chart tokens. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [Progress](https://design.gaudi.site/docs/components/progress): Determinate and indeterminate progress with a readable task label.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.

Source: https://design.gaudi.site/docs/charts/radial-chart (Markdown with example code: https://design.gaudi.site/docs/charts/radial-chart.md)

---

# RangeChart

> A band between a low and a high value per category with a line through it: forecasts, percentile spreads, highs and lows.

- Category: Charts
- Import: `@gaudi/design-system/charts/RangeChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/RangeChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-rangechart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { RangeChart } from '@gaudi/design-system/charts/RangeChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/range-chart-burn-down.json`.

## Usage

```jsx
import { RangeChart } from '@gaudi/design-system/charts';

<RangeChart ariaLabel='Median response time with its p10 to p90 band' data={latency} bandLabel='p10–p90' valueLabel='Median' />
```

## Examples

### Release burn-down forecast

Registry: `npx shadcn@latest add https://design.gaudi.site/r/range-chart-burn-down.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `lowKey / highKey / valueKey` | `string` | `low / high / value` | no | Band edges and the optional line. |
| `bandLabel / valueLabel` | `string` | `Range / Value` | no | Names in tooltips and the table. |
| `xKey` | `string` | `label` | no | Category field. |
| `references / annotations` | `Array<{ x?, y?, label, tone? }>` | — | no | Labelled guide lines and point notes. |
| `color` | `string` | `chart-1` | no | Band and line colour. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [ComposedChart](https://design.gaudi.site/docs/charts/composed-chart): Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.
- [DonutChart](https://design.gaudi.site/docs/charts/donut-chart): Parts of a whole as a donut with a centre summary, or a pie (PieChart); slices are selectable and small ones fold into Other.

Source: https://design.gaudi.site/docs/charts/range-chart (Markdown with example code: https://design.gaudi.site/docs/charts/range-chart.md)

---

# SankeyChart

> Flows between stages with widths proportional to volume; each flow is a keyboard point and a table row.

- Category: Charts
- Import: `@gaudi/design-system/charts/SankeyChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/SankeyChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-sankeychart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { SankeyChart } from '@gaudi/design-system/charts/SankeyChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/sankey-chart-reader-paths.json`.

## Usage

```jsx
import { SankeyChart } from '@gaudi/design-system/charts';

<SankeyChart ariaLabel='Support tickets from channel to outcome' links={[{ source: 'Email', target: 'Billing', value: 420 }, { source: 'Billing', target: 'Solved', value: 390 }]} />
```

## Examples

### Where readers go

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sankey-chart-reader-paths.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `links` | `Array<{ source, target, value }>` | `[]` | no | Flows by stage name or index. |
| `nodes` | `Array<string \| { name, color? }>` | `from links` | no | Stage order and colours. |
| `nodeWidth` | `number` | `10` | no | Stage bar width. |
| `colors` | `string[]` | `categorical palette` | no | Override the series colours with chart tokens. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [ComposedChart](https://design.gaudi.site/docs/charts/composed-chart): Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.
- [DonutChart](https://design.gaudi.site/docs/charts/donut-chart): Parts of a whole as a donut with a centre summary, or a pie (PieChart); slices are selectable and small ones fold into Other.

Source: https://design.gaudi.site/docs/charts/sankey-chart (Markdown with example code: https://design.gaudi.site/docs/charts/sankey-chart.md)

---

# ScatterChart

> Correlation between two numbers, with labelled points, reference lines and bubbles sized by a third value (BubbleChart).

- Category: Charts
- Import: `@gaudi/design-system/charts/ScatterChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/ScatterChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-scatterchart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ScatterChart } from '@gaudi/design-system/charts/ScatterChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/scatter-chart-length-vs-shares.json`.

## Usage

```jsx
import { BubbleChart, ScatterChart } from '@gaudi/design-system/charts';

<ScatterChart ariaLabel='Essay length against minutes read' data={essays} xKey='words' yKey='minutes' xLabel='Words' yLabel='Minutes' />
```

## Examples

### Length, read time and shares

Registry: `npx shadcn@latest add https://design.gaudi.site/r/scatter-chart-length-vs-shares.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `xKey / yKey / zKey` | `string` | `x / y / —` | no | Numeric fields; zKey sizes bubbles. |
| `xLabel / yLabel / zLabel` | `string` | `field names` | no | Names in the readout, tooltip and table. |
| `zRange` | `[number, number]` | `[60, 900]` | no | Bubble area range. |
| `references` | `Array<{ x?, y?, label }>` | — | no | Guide lines on either axis. |
| `color` | `string` | `chart-1` | no | Point colour; a point may carry its own color. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [ComposedChart](https://design.gaudi.site/docs/charts/composed-chart): Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.
- [DonutChart](https://design.gaudi.site/docs/charts/donut-chart): Parts of a whole as a donut with a centre summary, or a pie (PieChart); slices are selectable and small ones fold into Other.

Source: https://design.gaudi.site/docs/charts/scatter-chart (Markdown with example code: https://design.gaudi.site/docs/charts/scatter-chart.md)

---

# Sparkline

> A word-sized trend without axes, for stat cards, tables and prose; still a named chart with its data table.

- Category: Charts
- Import: `@gaudi/design-system/charts/Sparkline` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/Sparkline/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-sparkline--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Sparkline } from '@gaudi/design-system/charts/Sparkline';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/sparkline-stat-trends.json`.

## Usage

```jsx
import { Sparkline } from '@gaudi/design-system/charts';

<Sparkline ariaLabel='Readers, last 14 days' data={readers} variant='area' height={48} />
```

## Examples

### Stat cards with trends

Registry: `npx shadcn@latest add https://design.gaudi.site/r/sparkline-stat-trends.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `data` | `number[] \| object[]` | `[]` | no | Numbers, or records read through xKey / yKey. |
| `variant` | `line \| area \| bar` | `line` | no | How the trend draws. |
| `reference` | `number` | — | no | A dashed guide such as a target. |
| `showEndpoint` | `boolean` | `true` | no | Dot on the latest value. |
| `color` | `string` | `chart-1` | no | Trend colour. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `variant`: `line`, `area`, `bar`
- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [Stat Cards](https://design.gaudi.site/docs/blocks/stat-cards): Metric cards on the Core Card: a label, value and change badge with optional icon tile, actions, description, footer and a segmented meter.
- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [ComposedChart](https://design.gaudi.site/docs/charts/composed-chart): Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.

Source: https://design.gaudi.site/docs/charts/sparkline (Markdown with example code: https://design.gaudi.site/docs/charts/sparkline.md)

---

# StackedBarList

> Ranked rows of stacked segments that grow with the list: issues by status per team, readers by source per post.

- Category: Charts
- Import: `@gaudi/design-system/charts/StackedBarList` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/StackedBarList/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-stackedbarlist--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { StackedBarList } from '@gaudi/design-system/charts/StackedBarList';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/stacked-bar-list-top-posts.json`.

## Usage

```jsx
import { StackedBarList } from '@gaudi/design-system/charts';

<StackedBarList ariaLabel='Issues per team by status' data={teams} series={[{ key: 'open', label: 'Open' }, { key: 'done', label: 'Done' }]} />
```

## Examples

### Top posts by source

Registry: `npx shadcn@latest add https://design.gaudi.site/r/stacked-bar-list-top-posts.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `data` | `object[]` | `[]` | no | Rows. |
| `labelKey` | `string` | `label` | no | Rows. |
| `series` | `Array<{ key, label? }>` | `valueKey` | no | Segments in order. |
| `normalize` | `boolean` | `false` | no | Each row as 100% to compare mixes. |
| `sort` | `boolean` | `true` | no | Largest row first. |
| `showLegend` | `boolean` | `true` | no | Segment legend. |
| `colors` | `string[]` | `categorical palette` | no | Override the series colours with chart tokens. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [Switch](https://design.gaudi.site/docs/components/switch): Switch renders a token-styled boolean preference control.
- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.

Source: https://design.gaudi.site/docs/charts/stacked-bar-list (Markdown with example code: https://design.gaudi.site/docs/charts/stacked-bar-list.md)

---

# TournamentBracket

> A knockout bracket with connected match cards, round paging, scores, penalties, and explicit winners.

- Category: Charts
- Import: `@gaudi/design-system/charts/TournamentBracket` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/TournamentBracket/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-tournamentbracket--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { TournamentBracket } from '@gaudi/design-system/charts/TournamentBracket';
```

## Usage

```jsx
import { TournamentBracket } from '@gaudi/design-system/charts/TournamentBracket';

const rounds = [{ id: 'final', name: 'Final', matches: [{ id: 'f1', status: 'completed', home: { name: 'North', score: 2 }, away: { name: 'South', score: 1 }, winner: 'home' }] }];
<TournamentBracket rounds={rounds} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/charts-tournamentbracket--playground)
- [Final with a winner](https://storybook.gaudi.site/index.html?path=/story/charts-tournamentbracket--final-result)
- [Empty](https://storybook.gaudi.site/index.html?path=/story/charts-tournamentbracket--empty)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `rounds` | `Round[]` | `[]` | no | Ordered { id, name, matches } rounds, each with half the matches of the previous one, ending in a single final. IDs are unique. |
| `label` | `string` | `Tournament bracket` | no | Accessible name of the bracket region. |
| `round / defaultRound / onRoundChange` | `number / function` | `0` | no | Controlled or initial leftmost round index. Clamped for the current container width. |
| `onMatchClick` | `(match) => void` | — | no | Makes match cards buttons for host-owned details. |
| `disabled` | `boolean` | `false` | no | Disables round navigation and match actions. |
| `labels` | `object` | `English labels` | no | Localize navigation, match statuses, TBD, winner, penalties, versus, empty and invalid-state text. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Labelled match groups expose round and participant names. Native buttons support keyboard navigation; current rounds are announced politely. Winners have a text alternative as well as an icon and weight. Motion respects reduced-motion preferences. One, two or three rounds fit the container without page overflow.

## Related

- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.
- [ComposedChart](https://design.gaudi.site/docs/charts/composed-chart): Bars, lines and areas on one category axis, with a right-hand axis for a series in other units.
- [DonutChart](https://design.gaudi.site/docs/charts/donut-chart): Parts of a whole as a donut with a centre summary, or a pie (PieChart); slices are selectable and small ones fold into Other.

Source: https://design.gaudi.site/docs/charts/tournament-bracket (Markdown with example code: https://design.gaudi.site/docs/charts/tournament-bracket.md)

---

# TreemapChart

> Nested rectangles sized by value, tinted by group or shaded on the heat ramp.

- Category: Charts
- Import: `@gaudi/design-system/charts/TreemapChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/TreemapChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-treemapchart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { TreemapChart } from '@gaudi/design-system/charts/TreemapChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/treemap-chart-storage-folders.json`.

## Usage

```jsx
import { TreemapChart } from '@gaudi/design-system/charts';

<TreemapChart ariaLabel='Hours read by section' data={[{ name: 'Essays', children: [{ name: 'Engineering', value: 1240 }] }]} />
```

## Examples

### Storage by folder

Registry: `npx shadcn@latest add https://design.gaudi.site/r/treemap-chart-storage-folders.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `data` | `Array<{ name, value } \| { name, children }>` | `[]` | no | One or two levels. |
| `nameKey / valueKey` | `string` | `name / value` | no | Field names. |
| `colorBy` | `group \| value` | `group` | no | Tint by top-level group or shade by value. |
| `colors` | `string[]` | `categorical palette` | no | Override the series colours with chart tokens. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `colorBy`: `group`, `value`
- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.

Source: https://design.gaudi.site/docs/charts/treemap-chart (Markdown with example code: https://design.gaudi.site/docs/charts/treemap-chart.md)

---

# WaterfallChart

> How a starting value becomes an ending one through increases and decreases, with running totals and subtotals.

- Category: Charts
- Import: `@gaudi/design-system/charts/WaterfallChart` (also `@gaudi/design-system/charts`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/charts/WaterfallChart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/charts-waterfallchart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system recharts
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { WaterfallChart } from '@gaudi/design-system/charts/WaterfallChart';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/waterfall-chart-revenue-bridge.json`.

## Usage

```jsx
import { WaterfallChart } from '@gaudi/design-system/charts';

<WaterfallChart ariaLabel='Change in subscribers' data={[{ label: 'September', value: 4180, total: true }, { label: 'New', value: 620 }, { label: 'Lost', value: -310 }, { label: 'October', total: true }]} />
```

## Examples

### Recurring revenue bridge

Registry: `npx shadcn@latest add https://design.gaudi.site/r/waterfall-chart-revenue-bridge.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `data` | `Array<{ label, value? , total? }>` | `[]` | no | Steps; total: true draws the running total or its own value. |
| `labelKey / valueKey / totalKey` | `string` | `label / value / total` | no | Field names. |
| `changeLabel / totalLabel` | `string` | `Change / Total` | no | Names in tooltips and the table. |
| `title / description` | `ReactNode` | — | no | Figure caption above the plot. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot, the single keyboard stop. |
| `height` | `number` | `type-specific` | no | Plot height in pixels. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; empty and invalid are otherwise detected from the data. |
| `labels` | `Partial<DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number format for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `number` | no | Number format for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true` | no | Controls beside the caption; the figure border and padding. |
| `className` | `string` | — | no | Additional classes on the outer element. |

### Variants

- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

The plot is one tab stop named by ariaLabel. The arrow keys walk the points, Home and End jump to the ends, Enter or Space activates and Escape clears; the active point is drawn and read out politely. Every value is mirrored in a data table, and the SVG is hidden from assistive technology.

## Related

- [Field](https://design.gaudi.site/docs/components/field): Field composes form label, description, error, and input building blocks.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [AreaChart](https://design.gaudi.site/docs/charts/area-chart): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart): Bars per category: single, grouped or stacked, upright or on their side, with references, annotations and a highlighted bar.
- [BoxPlotChart](https://design.gaudi.site/docs/charts/box-plot-chart): Distributions side by side: median, quartiles, whiskers at 1.5 × IQR and outliers, from raw samples or precomputed summaries.
- [ChartFrame](https://design.gaudi.site/docs/charts/chart-frame): The frame every chart renders in: a captioned figure with one keyboard stop and a readout, loading, empty, invalid and error states, locale-aware numbers and a data table built from points.

Source: https://design.gaudi.site/docs/charts/waterfall-chart (Markdown with example code: https://design.gaudi.site/docs/charts/waterfall-chart.md)

---

# Hooks

> Shared React hooks for accessibility, data, environment, interaction, layout and state.

48 pages · 0 live examples, generated from the design system metadata.

## A11y

- [useArrowKeyNav](https://design.gaudi.site/docs/hooks/use-arrow-key-nav): Arrow-key navigation with a roving tabindex for toolbars, lists and grids.
- [useFocusTrap](https://design.gaudi.site/docs/hooks/use-focus-trap): Keep Tab focus inside a custom overlay and restore it on close.
- [useLiveAnnouncer](https://design.gaudi.site/docs/hooks/use-live-announcer): Polite or assertive screen reader announcements for changes away from focus.
- [usePrefersReducedMotion](https://design.gaudi.site/docs/hooks/use-prefers-reduced-motion): Whether the reader asked to reduce motion.

## Data

- [useLocalStorage](https://design.gaudi.site/docs/hooks/use-local-storage): useState persisted to localStorage, synced across components and tabs.
- [useMap](https://design.gaudi.site/docs/hooks/use-map): Map state with immutable set, replace, remove, clear and reset actions.
- [useReadLocalStorage](https://design.gaudi.site/docs/hooks/use-read-local-storage): Read-only localStorage subscriptions shared with useLocalStorage.
- [useSelection](https://design.gaudi.site/docs/hooks/use-selection): Multi-select state in a Set, with select-all and indeterminate support.
- [useSessionStorage](https://design.gaudi.site/docs/hooks/use-session-storage): useState persisted to sessionStorage for one tab.

## Environment

- [useDocumentTitle](https://design.gaudi.site/docs/hooks/use-document-title): Set a document title and restore the previous owner on cleanup.
- [useIsClient](https://design.gaudi.site/docs/hooks/use-is-client): False on the server and during hydration, true on the client.
- [useIsMobile](https://design.gaudi.site/docs/hooks/use-is-mobile): True below the 768px phone breakpoint.
- [useIsMounted](https://design.gaudi.site/docs/hooks/use-is-mounted): A stable getter for whether this hook is currently mounted.
- [useMediaQuery](https://design.gaudi.site/docs/hooks/use-media-query): Track a CSS media query, SSR-safe.
- [useOnlineStatus](https://design.gaudi.site/docs/hooks/use-online-status): Whether the browser reports a network connection.
- [usePageVisibility](https://design.gaudi.site/docs/hooks/use-page-visibility): Whether the tab is visible, to pause work in the background.
- [usePrefersColorScheme](https://design.gaudi.site/docs/hooks/use-prefers-color-scheme): The operating system colour scheme: 'light' or 'dark'.
- [useScreen](https://design.gaudi.site/docs/hooks/use-screen): Read a reactive snapshot of the browser screen properties.
- [useScript](https://design.gaudi.site/docs/hooks/use-script): Load an explicitly configured script with shared status and ownership.
- [useWindowSize](https://design.gaudi.site/docs/hooks/use-window-size): Track layout viewport width and height in CSS pixels.

## Interaction

- [useCopyToClipboard](https://design.gaudi.site/docs/hooks/use-copy-to-clipboard): Copy text with a temporary copied state and a fallback.
- [useEventListener](https://design.gaudi.site/docs/hooks/use-event-listener): Declarative DOM event listener with cleanup.
- [useHotkey](https://design.gaudi.site/docs/hooks/use-hotkey): Keyboard shortcuts with platform-aware mod keys.
- [useHover](https://design.gaudi.site/docs/hooks/use-hover): Pointer hover state with props to spread, ignoring touch.
- [useMousePosition](https://design.gaudi.site/docs/hooks/use-mouse-position): Track viewport, page and optional element-relative pointer coordinates.
- [useOnClickOutside](https://design.gaudi.site/docs/hooks/use-on-click-outside): Run a callback when a press lands outside one or more elements.
- [useScrollLock](https://design.gaudi.site/docs/hooks/use-scroll-lock): Lock page scrolling while a custom overlay is open.

## Layout

- [useCollapsibleSections](https://design.gaudi.site/docs/hooks/use-collapsible-sections): Expanded state for several sections, with expand all and collapse all.
- [useElementSize](https://design.gaudi.site/docs/hooks/use-element-size): An element's size, kept current with a ResizeObserver.
- [useInView](https://design.gaudi.site/docs/hooks/use-in-view): Whether an element is in the viewport, from an IntersectionObserver.
- [useScrollPosition](https://design.gaudi.site/docs/hooks/use-scroll-position): The vertical scroll offset of the page or a scroll container.

## State

- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.
- [useDisclosure](https://design.gaudi.site/docs/hooks/use-disclosure): Open, close and toggle state for overlays and disclosures.
- [useEventCallback](https://design.gaudi.site/docs/hooks/use-event-callback): A stable function that always calls the latest callback.
- [useInterval](https://design.gaudi.site/docs/hooks/use-interval): setInterval that can pause and always runs the latest callback.
- [useIsomorphicLayoutEffect](https://design.gaudi.site/docs/hooks/use-isomorphic-layout-effect): useLayoutEffect in the browser, useEffect on the server.
- [useMergedRefs](https://design.gaudi.site/docs/hooks/use-merged-refs): Combine a forwarded ref with your own refs.
- [usePrevious](https://design.gaudi.site/docs/hooks/use-previous): The value a prop or state held before it last changed.
- [useSliderInput](https://design.gaudi.site/docs/hooks/use-slider-input): Keep a range slider and its number inputs in sync.
- [useStep](https://design.gaudi.site/docs/hooks/use-step): Zero-based step state for wizards and multi-page forms.
- [useThrottleCallback](https://design.gaudi.site/docs/hooks/use-throttle-callback): A function that runs at most once per interval.
- [useTimeout](https://design.gaudi.site/docs/hooks/use-timeout): A one-off timer with reset and clear.
- [useUnmount](https://design.gaudi.site/docs/hooks/use-unmount): Run the latest committed callback when an effect is cleaned up.

Source: https://design.gaudi.site/docs/hooks (Markdown with example code: https://design.gaudi.site/docs/hooks.md)

---

# useArrowKeyNav

> Arrow-key navigation with a roving tabindex for toolbars, lists and grids.

Moves focus between items with the arrow keys, Home and End while the group stays one Tab stop. The active item has tabIndex 0 and the rest -1. Keys typed in text fields and keys with Command, Control or Alt are left alone.

- Category: Hooks · A11y
- Import: `@gaudi/design-system/hooks/a11y/use-arrow-key-nav` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/a11y/use-arrow-key-nav.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-a11y-usearrowkeynav--docs

## Usage

```jsx
import { useArrowKeyNav } from '@gaudi/design-system/hooks';

const { getItemProps, containerProps } = useArrowKeyNav(tools.length, { orientation: 'horizontal', role: 'toolbar', wrap: true });

<div {...containerProps} aria-label='Formatting'>
  {tools.map((tool, index) => <Button key={tool} {...getItemProps(index)}>{tool}</Button>)}
</div>
```

## Examples

Examples (rendered from Storybook):

- [Toolbar](https://storybook.gaudi.site/index.html?path=/story/hooks-a11y-usearrowkeynav--toolbar)
- [Vertical section list](https://storybook.gaudi.site/index.html?path=/story/hooks-a11y-usearrowkeynav--vertical-list)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `itemCount` | `number` | — | no | Number of navigable items; the active index is clamped when items are removed. |
| `options.orientation` | `'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | no | Which arrow keys move: Up and Down, Left and Right, or all four. |
| `options.wrap` | `boolean` | `false` | no | Loop from the last item to the first and back. |
| `options.dir` | `'ltr' \| 'rtl'` | `'ltr'` | no | In right-to-left layouts ArrowLeft moves forward. |
| `options.role` | `string` | `'group'` | no | Container role; aria-orientation is added for roles that support it (toolbar, listbox, menu, tablist…). |
| `options.defaultIndex` | `number` | `0` | no | Initial active item, and a callback when it changes. |
| `onActiveChange` | `(index) => void` | — | no | Initial active item, and a callback when it changes. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `activeIndex` | `number` | The item that holds tabIndex 0. |
| `getItemProps(index)` | `{ tabIndex, onKeyDown, onFocus, ref }` | Spread on each item. |
| `containerProps` | `{ role, aria-orientation? }` | Spread on the container, then give it an accessible name. |
| `setActiveIndex(index, { focus })` | `function` | Move the active item from code; focuses it unless focus is false. |

## Accessibility

Implements the WAI-ARIA roving tabindex pattern: one Tab stop for the group, arrows inside it. Name the container (aria-label or aria-labelledby) and give it the role the widget really is, such as toolbar.

## Notes

- Gaudi Tabs, ToggleGroup, RadioGroup and menus already handle their own arrow keys.
- `getNextIndex(current, key, options)` is exported for custom key handling.

## Related

- [Tabs](https://design.gaudi.site/docs/components/tabs): Switch between related panels with keyboard-accessible tab controls.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group): Single or multiple pressed choices for view modes and compact formatting controls.
- [RadioGroup](https://design.gaudi.site/docs/components/radio-group): Choose one option using native radio controls or selectable cards.

Source: https://design.gaudi.site/docs/hooks/use-arrow-key-nav (Markdown with example code: https://design.gaudi.site/docs/hooks/use-arrow-key-nav.md)

---

# useFocusTrap

> Keep Tab focus inside a custom overlay and restore it on close.

While active, Tab and Shift+Tab wrap inside the container. On activation it focuses the first tabbable element (or the container), and on release it returns focus to where it was. Traps nest, and portaled menus inside the trap keep their own focus.

- Category: Hooks · A11y
- Import: `@gaudi/design-system/hooks/a11y/use-focus-trap` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/a11y/use-focus-trap.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-a11y-usefocustrap--docs

## Usage

```jsx
import { useFocusTrap } from '@gaudi/design-system/hooks';

const trapRef = useFocusTrap({ active: open });

<div ref={trapRef} role='dialog' aria-modal='true' aria-labelledby='menu-title'>…</div>
```

## Examples

Examples (rendered from Storybook):

- [Custom reply panel](https://storybook.gaudi.site/index.html?path=/story/hooks-a11y-usefocustrap--inline-panel)
- [Focus the container first](https://storybook.gaudi.site/index.html?path=/story/hooks-a11y-usefocustrap--container-focus)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.active` | `boolean` | `true` | no | Whether the trap is on. |
| `options.autoFocus` | `boolean` | `true` | no | Move focus into the container when it activates. |
| `options.initialFocus` | `'first' \| 'container'` | `'first'` | no | Focus the first tabbable element or the container itself (give it tabIndex={-1}). |
| `options.returnFocus` | `boolean` | `true` | no | Return focus to the previously focused element on release. |
| `options.containerRef` | `RefObject<HTMLElement>` | — | no | Use an existing ref instead of the returned one. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `ref` | `RefObject<HTMLElement>` | Attach to the container. |

## Accessibility

A trap must always have a visible, keyboard-reachable way out (a Close button and Escape). Pair it with role="dialog", aria-modal and a label, and with useScrollLock so the page behind does not scroll.

## Notes

- Gaudi Dialog, Dialog confirmation, Sheet and Drawer already trap focus; use this hook only for custom overlays.

## Related

- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Sheet](https://design.gaudi.site/docs/components/sheet): A panel that slides in from an edge over a dimmed page, for side tasks such as settings, details, comments, notifications or an assistant, without leaving the current screen.
- [useScrollLock](https://design.gaudi.site/docs/hooks/use-scroll-lock): Lock page scrolling while a custom overlay is open.

Source: https://design.gaudi.site/docs/hooks/use-focus-trap (Markdown with example code: https://design.gaudi.site/docs/hooks/use-focus-trap.md)

---

# useLiveAnnouncer

> Polite or assertive screen reader announcements for changes away from focus.

Announces short messages ("Saved", "3 results", "Copied") through shared visually hidden live regions. The regions exist before the first message so it is not lost, and repeating a message announces it again.

- Category: Hooks · A11y
- Import: `@gaudi/design-system/hooks/a11y/use-live-announcer` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/a11y/use-live-announcer.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-a11y-useliveannouncer--docs

## Usage

```jsx
import { useLiveAnnouncer } from '@gaudi/design-system/hooks';

const { announce } = useLiveAnnouncer();

const save = async () => {
  await saveDraft();
  announce('Draft saved');
};
```

## Examples

Examples (rendered from Storybook):

- [Polite and assertive messages](https://storybook.gaudi.site/index.html?path=/story/hooks-a11y-useliveannouncer--save-feedback)
- [Result count after typing settles](https://storybook.gaudi.site/index.html?path=/story/hooks-a11y-useliveannouncer--result-count)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.clearAfter` | `number` | `5000` | no | Milliseconds before an announced message is cleared from the region. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `announce(message, politeness)` | `(string, 'polite' \| 'assertive') => void` | Read a message; 'polite' waits, 'assertive' interrupts. |
| `clear()` | `function` | Empty both regions. |

## Accessibility

Use 'polite' for almost everything. Reserve 'assertive' for errors and time-critical changes, keep messages short, and never announce every keystroke or streamed token.

## Notes

- `announce(message, politeness)` is also exported for non-React code.

## Related

- [useArrowKeyNav](https://design.gaudi.site/docs/hooks/use-arrow-key-nav): Arrow-key navigation with a roving tabindex for toolbars, lists and grids.
- [useFocusTrap](https://design.gaudi.site/docs/hooks/use-focus-trap): Keep Tab focus inside a custom overlay and restore it on close.
- [usePrefersReducedMotion](https://design.gaudi.site/docs/hooks/use-prefers-reduced-motion): Whether the reader asked to reduce motion.

Source: https://design.gaudi.site/docs/hooks/use-live-announcer (Markdown with example code: https://design.gaudi.site/docs/hooks/use-live-announcer.md)

---

# usePrefersReducedMotion

> Whether the reader asked to reduce motion.

True when the operating system reduce-motion setting is on, updated live. Built on useMediaQuery.

- Category: Hooks · A11y
- Import: `@gaudi/design-system/hooks/a11y/use-prefers-reduced-motion` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/a11y/use-prefers-reduced-motion.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-a11y-useprefersreducedmotion--docs

## Usage

```jsx
import { usePrefersReducedMotion } from '@gaudi/design-system/hooks';

const reduced = usePrefersReducedMotion();

window.scrollTo({ top: 0, behavior: reduced ? 'auto' : 'smooth' });
```

## Examples

Examples (rendered from Storybook):

- [Read the preference](https://storybook.gaudi.site/index.html?path=/story/hooks-a11y-useprefersreducedmotion--reading)
- [Turn autoplay off](https://storybook.gaudi.site/index.html?path=/story/hooks-a11y-useprefersreducedmotion--autoplay-off)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `fallback` | `boolean` | `false` | no | Value during server rendering and hydration. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `reduced` | `boolean` | True when motion should be reduced. |

## Accessibility

When set, skip autoplay, parallax, typing effects and smooth scrolling, or replace them with an instant change. global.css already shortens CSS transitions; use this hook for motion driven from JavaScript.

## Notes

- `REDUCED_MOTION_QUERY` is exported for CSS-in-JS or imperative checks.

## Related

- [useMediaQuery](https://design.gaudi.site/docs/hooks/use-media-query): Track a CSS media query, SSR-safe.
- [useArrowKeyNav](https://design.gaudi.site/docs/hooks/use-arrow-key-nav): Arrow-key navigation with a roving tabindex for toolbars, lists and grids.
- [useFocusTrap](https://design.gaudi.site/docs/hooks/use-focus-trap): Keep Tab focus inside a custom overlay and restore it on close.
- [useLiveAnnouncer](https://design.gaudi.site/docs/hooks/use-live-announcer): Polite or assertive screen reader announcements for changes away from focus.

Source: https://design.gaudi.site/docs/hooks/use-prefers-reduced-motion (Markdown with example code: https://design.gaudi.site/docs/hooks/use-prefers-reduced-motion.md)

---

# useLocalStorage

> useState persisted to localStorage, synced across components and tabs.

Stores a JSON value under a key. The server render and hydration use the initial value, and the stored value is read right after. Every caller with the same key stays in sync in this tab and in other tabs; blocked storage falls back to memory.

- Category: Hooks · Data
- Import: `@gaudi/design-system/hooks/data/use-local-storage` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/data/use-local-storage.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-data-uselocalstorage--docs

## Usage

```jsx
import { useLocalStorage } from '@gaudi/design-system/hooks';

const [fontSize, setFontSize, resetFontSize] = useLocalStorage('reader:font-size', 'md');
```

## Examples

Examples (rendered from Storybook):

- [Reading preference](https://storybook.gaudi.site/index.html?path=/story/hooks-data-uselocalstorage--preference)
- [Callers stay in sync](https://storybook.gaudi.site/index.html?path=/story/hooks-data-uselocalstorage--synced)
- [Preferences follow the active key](https://storybook.gaudi.site/index.html?path=/story/hooks-data-uselocalstorage--per-project)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `key` | `string` | — | no | Storage key; namespace it, for example reader:font-size. |
| `initialValue` | `any` | — | no | Value on the server, during hydration and when nothing is stored. |
| `options.serialize` | `(value) => string` | — | no | Custom encoding. |
| `deserialize` | `(raw) => any` | — | no | Custom encoding. |
| `options.syncTabs` | `boolean` | `true` | no | Follow writes from other tabs. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `[0] value` | `any` | Current value. |
| `[1] setValue` | `(value \| (current) => value) => void` | Store a new value. |
| `[2] removeValue` | `() => void` | Delete the key and fall back to initialValue. |

## Accessibility

Persisted preferences (text size, reduced motion, dismissed notices) must still have a visible control to change them back.

## Notes

- Never store secrets, tokens or personal data in localStorage.

## Related

- [useMap](https://design.gaudi.site/docs/hooks/use-map): Map state with immutable set, replace, remove, clear and reset actions.
- [useReadLocalStorage](https://design.gaudi.site/docs/hooks/use-read-local-storage): Read-only localStorage subscriptions shared with useLocalStorage.
- [useSelection](https://design.gaudi.site/docs/hooks/use-selection): Multi-select state in a Set, with select-all and indeterminate support.
- [useSessionStorage](https://design.gaudi.site/docs/hooks/use-session-storage): useState persisted to sessionStorage for one tab.

Source: https://design.gaudi.site/docs/hooks/use-local-storage (Markdown with example code: https://design.gaudi.site/docs/hooks/use-local-storage.md)

---

# useMap

> Map state with immutable set, replace, remove, clear and reset actions.

Accepts a Map or iterable of key-value pairs. Each mutation creates a new Map, preserving caller-owned input. The initial entries are snapshotted once, including single-use iterators; reset copies that snapshot.

- Category: Hooks · Data
- Import: `@gaudi/design-system/hooks/data/use-map` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/data/use-map.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-data-usemap--docs

## Usage

```jsx
import { useMap } from '@gaudi/design-system/hooks';

const [drafts, { set, remove, reset }] = useMap([['intro', 'Draft']]);
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/hooks-data-usemap--playground)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `initialEntries` | `Map \| Iterable<[key, value]>` | `[]` | no | Initial contents, snapshotted at mount for reset. Later changes to this argument are ignored; use setAll to replace state. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `[map, actions]` | `[Map, object]` | Read-only-by-convention Map and stable actions. |
| `actions.set / remove / setAll / clear / reset` | `function` | Set one key, remove a key, replace all entries, empty the Map or restore the initial entries. |

## Accessibility

Render stable keys and keep focus meaningful when entries are removed.

## Notes

- Do not call map.set/delete/clear directly; those mutations cannot notify React.

## Related

- [Map](https://design.gaudi.site/docs/components/map): An interactive geographic map with selectable markers, route lines, and camera controls.
- [useLocalStorage](https://design.gaudi.site/docs/hooks/use-local-storage): useState persisted to localStorage, synced across components and tabs.
- [useReadLocalStorage](https://design.gaudi.site/docs/hooks/use-read-local-storage): Read-only localStorage subscriptions shared with useLocalStorage.
- [useSelection](https://design.gaudi.site/docs/hooks/use-selection): Multi-select state in a Set, with select-all and indeterminate support.
- [useSessionStorage](https://design.gaudi.site/docs/hooks/use-session-storage): useState persisted to sessionStorage for one tab.

Source: https://design.gaudi.site/docs/hooks/use-map (Markdown with example code: https://design.gaudi.site/docs/hooks/use-map.md)

---

# useReadLocalStorage

> Read-only localStorage subscriptions shared with useLocalStorage.

Reads through the same store as useLocalStorage, including same-tab notifications, native cross-tab storage events and blocked-storage fallback. It never exposes write actions.

- Category: Hooks · Data
- Import: `@gaudi/design-system/hooks/data/use-read-local-storage` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/data/use-read-local-storage.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-data-usereadlocalstorage--docs

## Usage

```jsx
import { useReadLocalStorage } from '@gaudi/design-system/hooks';

const density = useReadLocalStorage('reading-density', 'comfortable');
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/hooks-data-usereadlocalstorage--playground)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `key` | `string` | — | no | Storage key to subscribe to. |
| `initialValue` | `any` | `null` | no | Server, hydration, absent-key and invalid-JSON fallback. |
| `options.deserialize` | `function` | `JSON.parse` | no | Custom reader and whether to subscribe to cross-tab changes. |
| `syncTabs` | `boolean` | `true` | no | Custom reader and whether to subscribe to cross-tab changes. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `value` | `any` | Current parsed value or initialValue. |

## Accessibility

Announce meaningful changes in context. Do not put sensitive data in browser storage.

## Notes

- Same-tab changes made with useLocalStorage notify readers. Direct localStorage.setItem calls in the same tab do not dispatch a storage event.

## Related

- [useLocalStorage](https://design.gaudi.site/docs/hooks/use-local-storage): useState persisted to localStorage, synced across components and tabs.
- [useMap](https://design.gaudi.site/docs/hooks/use-map): Map state with immutable set, replace, remove, clear and reset actions.
- [useSelection](https://design.gaudi.site/docs/hooks/use-selection): Multi-select state in a Set, with select-all and indeterminate support.
- [useSessionStorage](https://design.gaudi.site/docs/hooks/use-session-storage): useState persisted to sessionStorage for one tab.

Source: https://design.gaudi.site/docs/hooks/use-read-local-storage (Markdown with example code: https://design.gaudi.site/docs/hooks/use-read-local-storage.md)

---

# useSelection

> Multi-select state in a Set, with select-all and indeterminate support.

Tracks selected ids for lists, tables and bulk actions. Uncontrolled from initialSelectedIds, or controlled with selectedIds and onSelectionChange; every change produces a new Set.

- Category: Hooks · Data
- Import: `@gaudi/design-system/hooks/data/use-selection` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/data/use-selection.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-data-useselection--docs

## Usage

```jsx
import { useSelection } from '@gaudi/design-system/hooks';

const { isSelected, toggleSelection, getSelectAllState, toggleAll, count } = useSelection();
```

## Examples

Examples (rendered from Storybook):

- [Bulk actions with select all](https://storybook.gaudi.site/index.html?path=/story/hooks-data-useselection--bulk-actions)
- [Controlled with a limit](https://storybook.gaudi.site/index.html?path=/story/hooks-data-useselection--controlled)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.selectedIds` | `Set<id>` | — | no | Controlled selection. |
| `options.initialSelectedIds` | `Set<id>` | `new Set()` | no | Initial selection when uncontrolled. |
| `options.onSelectionChange` | `(ids: Set<id>) => void` | — | no | Called with the next selection. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `selectedIds / count` | `Set<id> / number` | The selection and its size. |
| `isSelected(id)` | `boolean` | Whether an id is selected. |
| `getSelectAllState(ids)` | `true \| false \| 'indeterminate'` | State for a select-all checkbox. |
| `toggleSelection / select / deselect` | `(id) => void` | Change one id. |
| `selectAll / toggleAll / clearSelection / setSelection` | `function` | Change many ids at once. |

## Accessibility

Give every checkbox a label naming its row, give the select-all checkbox an indeterminate state, and announce bulk results (for example with useLiveAnnouncer).

## Notes

- DataTable has its own selection; use this hook for custom lists, galleries and cards.

## Related

- [DataTable](https://design.gaudi.site/docs/components/data-table): DataTable is a TanStack table with a compact data anatomy: shared headers that preserve label casing, hairline rows, synced column and row hover, a tinted wash for selected rows, and declarative column alignment, width and pinning.
- [useLiveAnnouncer](https://design.gaudi.site/docs/hooks/use-live-announcer): Polite or assertive screen reader announcements for changes away from focus.
- [useLocalStorage](https://design.gaudi.site/docs/hooks/use-local-storage): useState persisted to localStorage, synced across components and tabs.
- [useMap](https://design.gaudi.site/docs/hooks/use-map): Map state with immutable set, replace, remove, clear and reset actions.
- [useReadLocalStorage](https://design.gaudi.site/docs/hooks/use-read-local-storage): Read-only localStorage subscriptions shared with useLocalStorage.
- [useSessionStorage](https://design.gaudi.site/docs/hooks/use-session-storage): useState persisted to sessionStorage for one tab.

Source: https://design.gaudi.site/docs/hooks/use-selection (Markdown with example code: https://design.gaudi.site/docs/hooks/use-selection.md)

---

# useSessionStorage

> useState persisted to sessionStorage for one tab.

The same API as useLocalStorage over sessionStorage: survives a reload, not a new tab. Good for wizard progress and half-filled forms.

- Category: Hooks · Data
- Import: `@gaudi/design-system/hooks/data/use-session-storage` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/data/use-session-storage.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-data-usesessionstorage--docs

## Usage

```jsx
import { useSessionStorage } from '@gaudi/design-system/hooks';

const [draft, setDraft, clearDraft] = useSessionStorage('contact:draft', { name: '', message: '' });
```

## Examples

Examples (rendered from Storybook):

- [Keep a form draft](https://storybook.gaudi.site/index.html?path=/story/hooks-data-usesessionstorage--form-draft)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `key` | `string` | — | no | Storage key. |
| `initialValue` | `any` | — | no | Value on the server, during hydration and when nothing is stored. |
| `options.serialize` | `(value) => string` | — | no | Custom encoding. |
| `deserialize` | `(raw) => any` | — | no | Custom encoding. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `[0] value` | `any` | Current value. |
| `[1] setValue` | `(value \| (current) => value) => void` | Store a new value. |
| `[2] removeValue` | `() => void` | Delete the key and fall back to initialValue. |

## Accessibility

Restoring a form after a reload helps people who navigate slowly or lose their place; tell them the draft was restored and let them clear it.

## Notes

- Session storage is per tab, so there is no cross-tab sync.

## Related

- [useLocalStorage](https://design.gaudi.site/docs/hooks/use-local-storage): useState persisted to localStorage, synced across components and tabs.
- [useMap](https://design.gaudi.site/docs/hooks/use-map): Map state with immutable set, replace, remove, clear and reset actions.
- [useReadLocalStorage](https://design.gaudi.site/docs/hooks/use-read-local-storage): Read-only localStorage subscriptions shared with useLocalStorage.
- [useSelection](https://design.gaudi.site/docs/hooks/use-selection): Multi-select state in a Set, with select-all and indeterminate support.

Source: https://design.gaudi.site/docs/hooks/use-session-storage (Markdown with example code: https://design.gaudi.site/docs/hooks/use-session-storage.md)

---

# useDocumentTitle

> Set a document title and restore the previous owner on cleanup.

The most recently mounted enabled hook owns the title. Updating that owner updates the title; removing it restores the remaining owner or the original title, even if owners unmount out of order.

- Category: Hooks · Environment
- Import: `@gaudi/design-system/hooks/environment/use-document-title` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/environment/use-document-title.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-environment-usedocumenttitle--docs

## Usage

```jsx
import { useDocumentTitle } from '@gaudi/design-system/hooks';

useDocumentTitle('Draft · Writing room');
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/hooks-environment-usedocumenttitle--playground)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `title` | `string` | — | no | Title to display. |
| `options.enabled` | `boolean` | `true` | no | Disable without changing the document title. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `return` | `undefined` | Title changes happen in effects; server output is unchanged. |

## Accessibility

Use concise page titles that identify the current content. Avoid rapidly changing titles or announcing pointer movement.

## Notes

- Use framework metadata for server-rendered page titles. This hook handles client-owned surfaces.

## Related

- [useIsClient](https://design.gaudi.site/docs/hooks/use-is-client): False on the server and during hydration, true on the client.
- [useIsMobile](https://design.gaudi.site/docs/hooks/use-is-mobile): True below the 768px phone breakpoint.
- [useIsMounted](https://design.gaudi.site/docs/hooks/use-is-mounted): A stable getter for whether this hook is currently mounted.
- [useMediaQuery](https://design.gaudi.site/docs/hooks/use-media-query): Track a CSS media query, SSR-safe.
- [useOnlineStatus](https://design.gaudi.site/docs/hooks/use-online-status): Whether the browser reports a network connection.
- [usePageVisibility](https://design.gaudi.site/docs/hooks/use-page-visibility): Whether the tab is visible, to pause work in the background.

Source: https://design.gaudi.site/docs/hooks/use-document-title (Markdown with example code: https://design.gaudi.site/docs/hooks/use-document-title.md)

---

# useIsClient

> False on the server and during hydration, true on the client.

Defers browser-only output (theme toggles, local times, storage-backed values) without a hydration mismatch, and without the extra render of a mounted flag set in an effect.

- Category: Hooks · Environment
- Import: `@gaudi/design-system/hooks/environment/use-is-client` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/environment/use-is-client.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-environment-useisclient--docs

## Usage

```jsx
import { useIsClient } from '@gaudi/design-system/hooks';

const isClient = useIsClient();
return <time>{isClient ? date.toLocaleTimeString() : '—'}</time>;
```

## Examples

Examples (rendered from Storybook):

- [Browser-only output](https://storybook.gaudi.site/index.html?path=/story/hooks-environment-useisclient--localised-time)

## API

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `isClient` | `boolean` | True once rendering on the client. |

## Accessibility

Render a same-size placeholder on the server so the layout does not jump and focus order does not change when the client value appears.

## Notes

- The ThemeSwitch uses it for its mounted state.

## Related

- [useDocumentTitle](https://design.gaudi.site/docs/hooks/use-document-title): Set a document title and restore the previous owner on cleanup.
- [useIsMobile](https://design.gaudi.site/docs/hooks/use-is-mobile): True below the 768px phone breakpoint.
- [useIsMounted](https://design.gaudi.site/docs/hooks/use-is-mounted): A stable getter for whether this hook is currently mounted.
- [useMediaQuery](https://design.gaudi.site/docs/hooks/use-media-query): Track a CSS media query, SSR-safe.
- [useOnlineStatus](https://design.gaudi.site/docs/hooks/use-online-status): Whether the browser reports a network connection.
- [usePageVisibility](https://design.gaudi.site/docs/hooks/use-page-visibility): Whether the tab is visible, to pause work in the background.

Source: https://design.gaudi.site/docs/hooks/use-is-client (Markdown with example code: https://design.gaudi.site/docs/hooks/use-is-client.md)

---

# useIsMobile

> True below the 768px phone breakpoint.

The breakpoint the AppShell sidebar and DateSelector use to switch to their phone layouts. False during server rendering and hydration.

- Category: Hooks · Environment
- Import: `@gaudi/design-system/hooks/environment/use-mobile` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/environment/use-mobile.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-environment-useismobile--docs

## Usage

```jsx
import { useIsMobile } from '@gaudi/design-system/hooks';

const isMobile = useIsMobile();
return isMobile ? <Drawer>{filters}</Drawer> : <aside>{filters}</aside>;
```

## Examples

Examples (rendered from Storybook):

- [Sidebar or sheet](https://storybook.gaudi.site/index.html?path=/story/hooks-environment-useismobile--filters-panel)

## API

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `isMobile` | `boolean` | True when the viewport is narrower than 768px. |

## Accessibility

Switching layouts must not remove features: the phone layout should reach the same actions, often through a Sheet or Drawer.

## Notes

- Built on useMediaQuery; use that directly for other breakpoints.

## Related

- [App Shell](https://design.gaudi.site/docs/blocks/app-shell): Application frames: a simple AppShell (rail or top bar, header, content, detail rail and status bar) and the Sidebar parts for collapsible icon rails, floating and inset sidebars, nested groups, secondary panels and right-hand inspectors.
- [useMediaQuery](https://design.gaudi.site/docs/hooks/use-media-query): Track a CSS media query, SSR-safe.
- [Sheet](https://design.gaudi.site/docs/components/sheet): A panel that slides in from an edge over a dimmed page, for side tasks such as settings, details, comments, notifications or an assistant, without leaving the current screen.

Source: https://design.gaudi.site/docs/hooks/use-is-mobile (Markdown with example code: https://design.gaudi.site/docs/hooks/use-is-mobile.md)

---

# useIsMounted

> A stable getter for whether this hook is currently mounted.

Returns a getter that is false during server rendering and before its mount effect, true while mounted and false after cleanup. Checking it does not cause a render.

- Category: Hooks · Environment
- Import: `@gaudi/design-system/hooks/environment/use-is-mounted` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/environment/use-is-mounted.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-environment-useismounted--docs

## Usage

```jsx
import { useIsMounted } from '@gaudi/design-system/hooks';

const isMounted = useIsMounted();
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/hooks-environment-useismounted--playground)

## API

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `isMounted()` | `() => boolean` | Read the mount state when an asynchronous callback completes. |

## Accessibility

Keep pending, success and cancellation feedback visible to users.

## Notes

- This does not cancel work or protect against stale responses after props change. Prefer AbortController or request identity for those cases.
- Use useIsClient for a reactive hydration flag. React Strict Mode replays effects in development.

## Related

- [useIsClient](https://design.gaudi.site/docs/hooks/use-is-client): False on the server and during hydration, true on the client.
- [useDocumentTitle](https://design.gaudi.site/docs/hooks/use-document-title): Set a document title and restore the previous owner on cleanup.
- [useIsMobile](https://design.gaudi.site/docs/hooks/use-is-mobile): True below the 768px phone breakpoint.
- [useMediaQuery](https://design.gaudi.site/docs/hooks/use-media-query): Track a CSS media query, SSR-safe.
- [useOnlineStatus](https://design.gaudi.site/docs/hooks/use-online-status): Whether the browser reports a network connection.
- [usePageVisibility](https://design.gaudi.site/docs/hooks/use-page-visibility): Whether the tab is visible, to pause work in the background.

Source: https://design.gaudi.site/docs/hooks/use-is-mounted (Markdown with example code: https://design.gaudi.site/docs/hooks/use-is-mounted.md)

---

# useMediaQuery

> Track a CSS media query, SSR-safe.

Returns whether a media query matches and follows changes. Returns the fallback during server rendering and hydration so markup stays stable; client-only renders read the real value at once. Merges two earlier implementations.

- Category: Hooks · Environment
- Import: `@gaudi/design-system/hooks/environment/use-media-query` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/environment/use-media-query.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-environment-usemediaquery--docs

## Usage

```jsx
import { useMediaQuery } from '@gaudi/design-system/hooks';

const wide = useMediaQuery('(min-width: 1024px)', true);
```

## Examples

Examples (rendered from Storybook):

- [Live queries](https://storybook.gaudi.site/index.html?path=/story/hooks-environment-usemediaquery--queries)
- [Render a different tree](https://storybook.gaudi.site/index.html?path=/story/hooks-environment-usemediaquery--different-tree)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `query` | `string` | — | no | A media query such as '(min-width: 1024px)'. |
| `fallback` | `boolean` | `false` | no | Value during server rendering and hydration. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `matches` | `boolean` | Whether the query matches. |

## Accessibility

Prefer CSS for purely visual changes. Use the hook when the tree really differs (one pane instead of two), and keep the same content and controls reachable in both layouts.

## Notes

- `matchesMediaQuery(query)` and `subscribeMediaQuery(query, notify)` are exported for non-React code.

## Related

- [useDocumentTitle](https://design.gaudi.site/docs/hooks/use-document-title): Set a document title and restore the previous owner on cleanup.
- [useIsClient](https://design.gaudi.site/docs/hooks/use-is-client): False on the server and during hydration, true on the client.
- [useIsMobile](https://design.gaudi.site/docs/hooks/use-is-mobile): True below the 768px phone breakpoint.
- [useIsMounted](https://design.gaudi.site/docs/hooks/use-is-mounted): A stable getter for whether this hook is currently mounted.
- [useOnlineStatus](https://design.gaudi.site/docs/hooks/use-online-status): Whether the browser reports a network connection.
- [usePageVisibility](https://design.gaudi.site/docs/hooks/use-page-visibility): Whether the tab is visible, to pause work in the background.

Source: https://design.gaudi.site/docs/hooks/use-media-query (Markdown with example code: https://design.gaudi.site/docs/hooks/use-media-query.md)

---

# useOnlineStatus

> Whether the browser reports a network connection.

Follows the online and offline events. False is reliable: queue work and say so. True only means 'maybe' (a captive portal reports online), so request errors stay the source of truth.

- Category: Hooks · Environment
- Import: `@gaudi/design-system/hooks/environment/use-online-status` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/environment/use-online-status.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-environment-useonlinestatus--docs

## Usage

```jsx
import { useOnlineStatus } from '@gaudi/design-system/hooks';

const online = useOnlineStatus();
<Button disabled={!online}>Publish</Button>
```

## Examples

Examples (rendered from Storybook):

- [Offline notice](https://storybook.gaudi.site/index.html?path=/story/hooks-environment-useonlinestatus--offline-notice)

## API

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `online` | `boolean` | False when the browser is offline; true during server rendering. |

## Accessibility

Show offline state as text (an Alert or a status region), not only as a colour, and keep entered work.

## Notes

- Do not block reading content offline; disable only the actions that need the network.

## Related

- [useDocumentTitle](https://design.gaudi.site/docs/hooks/use-document-title): Set a document title and restore the previous owner on cleanup.
- [useIsClient](https://design.gaudi.site/docs/hooks/use-is-client): False on the server and during hydration, true on the client.
- [useIsMobile](https://design.gaudi.site/docs/hooks/use-is-mobile): True below the 768px phone breakpoint.
- [useIsMounted](https://design.gaudi.site/docs/hooks/use-is-mounted): A stable getter for whether this hook is currently mounted.
- [useMediaQuery](https://design.gaudi.site/docs/hooks/use-media-query): Track a CSS media query, SSR-safe.
- [usePageVisibility](https://design.gaudi.site/docs/hooks/use-page-visibility): Whether the tab is visible, to pause work in the background.

Source: https://design.gaudi.site/docs/hooks/use-online-status (Markdown with example code: https://design.gaudi.site/docs/hooks/use-online-status.md)

---

# usePageVisibility

> Whether the tab is visible, to pause work in the background.

True while the page is visible. Pause polling, carousels, video and animation loops when the reader switches tabs, and resume when they return.

- Category: Hooks · Environment
- Import: `@gaudi/design-system/hooks/environment/use-page-visibility` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/environment/use-page-visibility.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-environment-usepagevisibility--docs

## Usage

```jsx
import { useInterval, usePageVisibility } from '@gaudi/design-system/hooks';

const visible = usePageVisibility();
useInterval(refresh, visible ? 30000 : null);
```

## Examples

Examples (rendered from Storybook):

- [Pause polling in the background](https://storybook.gaudi.site/index.html?path=/story/hooks-environment-usepagevisibility--pause-polling)

## API

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `visible` | `boolean` | False while the tab is hidden; true during server rendering. |

## Accessibility

Pausing hidden work also stops rotating content from moving on while the reader is away, so they return to what they left.

## Notes

- Combine with useInterval: pass null as the delay while hidden.

## Related

- [useInterval](https://design.gaudi.site/docs/hooks/use-interval): setInterval that can pause and always runs the latest callback.
- [useDocumentTitle](https://design.gaudi.site/docs/hooks/use-document-title): Set a document title and restore the previous owner on cleanup.
- [useIsClient](https://design.gaudi.site/docs/hooks/use-is-client): False on the server and during hydration, true on the client.
- [useIsMobile](https://design.gaudi.site/docs/hooks/use-is-mobile): True below the 768px phone breakpoint.
- [useIsMounted](https://design.gaudi.site/docs/hooks/use-is-mounted): A stable getter for whether this hook is currently mounted.
- [useMediaQuery](https://design.gaudi.site/docs/hooks/use-media-query): Track a CSS media query, SSR-safe.

Source: https://design.gaudi.site/docs/hooks/use-page-visibility (Markdown with example code: https://design.gaudi.site/docs/hooks/use-page-visibility.md)

---

# usePrefersColorScheme

> The operating system colour scheme: 'light' or 'dark'.

Follows the system preference live. This is not the site theme: read the active theme from the theme provider, and use this hook for system-default choices such as an embed or a chart palette.

- Category: Hooks · Environment
- Import: `@gaudi/design-system/hooks/environment/use-prefers-color-scheme` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/environment/use-prefers-color-scheme.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-environment-usepreferscolorscheme--docs

## Usage

```jsx
import { usePrefersColorScheme } from '@gaudi/design-system/hooks';

const scheme = usePrefersColorScheme();
```

## Examples

Examples (rendered from Storybook):

- [System default for an embed](https://storybook.gaudi.site/index.html?path=/story/hooks-environment-usepreferscolorscheme--system-default)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `fallback` | `'light' \| 'dark'` | `'light'` | no | Value during server rendering and hydration. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `scheme` | `'light' \| 'dark'` | The system preference. |

## Accessibility

Both schemes must meet contrast requirements; use Gaudi tokens, which resolve per theme.

## Notes

- Built on useMediaQuery.

## Related

- [useMediaQuery](https://design.gaudi.site/docs/hooks/use-media-query): Track a CSS media query, SSR-safe.
- [useDocumentTitle](https://design.gaudi.site/docs/hooks/use-document-title): Set a document title and restore the previous owner on cleanup.
- [useIsClient](https://design.gaudi.site/docs/hooks/use-is-client): False on the server and during hydration, true on the client.
- [useIsMobile](https://design.gaudi.site/docs/hooks/use-is-mobile): True below the 768px phone breakpoint.
- [useIsMounted](https://design.gaudi.site/docs/hooks/use-is-mounted): A stable getter for whether this hook is currently mounted.
- [useOnlineStatus](https://design.gaudi.site/docs/hooks/use-online-status): Whether the browser reports a network connection.

Source: https://design.gaudi.site/docs/hooks/use-prefers-color-scheme (Markdown with example code: https://design.gaudi.site/docs/hooks/use-prefers-color-scheme.md)

---

# useScreen

> Read a reactive snapshot of the browser screen properties.

Measures after mount and refreshes on window resize and screen-orientation changes. Returns a plain snapshot instead of the browser's mutable Screen object.

- Category: Hooks · Environment
- Import: `@gaudi/design-system/hooks/environment/use-screen` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/environment/use-screen.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-environment-usescreen--docs

## Usage

```jsx
import { useScreen } from '@gaudi/design-system/hooks';

const screen = useScreen();
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/hooks-environment-usescreen--playground)

## API

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `screen` | `object \| undefined` | Undefined on the server. Includes width, height, availWidth, availHeight, colorDepth, pixelDepth, orientation and angle. |

## Accessibility

Use viewport or container size for responsive layout; display size does not describe the space available to your component.

## Notes

- Dimensions are screen CSS pixels and may be reduced or rounded by browser privacy settings. Orientation and angle are null when unavailable.

## Related

- [useDocumentTitle](https://design.gaudi.site/docs/hooks/use-document-title): Set a document title and restore the previous owner on cleanup.
- [useIsClient](https://design.gaudi.site/docs/hooks/use-is-client): False on the server and during hydration, true on the client.
- [useIsMobile](https://design.gaudi.site/docs/hooks/use-is-mobile): True below the 768px phone breakpoint.
- [useIsMounted](https://design.gaudi.site/docs/hooks/use-is-mounted): A stable getter for whether this hook is currently mounted.
- [useMediaQuery](https://design.gaudi.site/docs/hooks/use-media-query): Track a CSS media query, SSR-safe.
- [useOnlineStatus](https://design.gaudi.site/docs/hooks/use-online-status): Whether the browser reports a network connection.

Source: https://design.gaudi.site/docs/hooks/use-screen (Markdown with example code: https://design.gaudi.site/docs/hooks/use-screen.md)

---

# useScript

> Load an explicitly configured script with shared status and ownership.

Callers using the same resolved URL share one script. A null source or disabled hook stays idle. No URL is built in, and Storybook uses a local inert fixture. The copied example includes the public file location and contents to create in your app.

- Category: Hooks · Environment
- Import: `@gaudi/design-system/hooks/environment/use-script` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/environment/use-script.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-environment-usescript--docs

## Usage

```jsx
import { useScript } from '@gaudi/design-system/hooks';

const status = useScript('/scripts/local-preview.js', { enabled: previewOpen });
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/hooks-environment-usescript--playground)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `src` | `string \| null` | — | no | Host-supplied script URL. |
| `options.enabled` | `boolean` | `true` | no | Whether this caller requests the script. |
| `options.removeOnUnmount` | `boolean` | `false` | no | Remove a hook-owned script after its final caller leaves, only if no caller requested retention. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `status` | `'idle' \| 'loading' \| 'ready' \| 'error' \| 'unknown'` | Loading on server for enabled sources; idle for disabled/absent sources. Unknown means a pre-existing script has no observable load status. |

## Accessibility

Provide text for loading/error states and an alternative when an integration is unavailable.

## Notes

- Removing a script tag cannot undo code it already ran. Prefer retaining shared libraries.
- Pre-existing scripts are never removed. Mark known external script state with data-gaudi-script-status="ready" or wait for its load/error event.
- Failed retained scripts stay error; use a new URL or removeOnUnmount to release the failed entry before retrying.

## Related

- [useDocumentTitle](https://design.gaudi.site/docs/hooks/use-document-title): Set a document title and restore the previous owner on cleanup.
- [useIsClient](https://design.gaudi.site/docs/hooks/use-is-client): False on the server and during hydration, true on the client.
- [useIsMobile](https://design.gaudi.site/docs/hooks/use-is-mobile): True below the 768px phone breakpoint.
- [useIsMounted](https://design.gaudi.site/docs/hooks/use-is-mounted): A stable getter for whether this hook is currently mounted.
- [useMediaQuery](https://design.gaudi.site/docs/hooks/use-media-query): Track a CSS media query, SSR-safe.
- [useOnlineStatus](https://design.gaudi.site/docs/hooks/use-online-status): Whether the browser reports a network connection.

Source: https://design.gaudi.site/docs/hooks/use-script (Markdown with example code: https://design.gaudi.site/docs/hooks/use-script.md)

---

# useWindowSize

> Track layout viewport width and height in CSS pixels.

Reads the window after mount and updates on resize. Unchanged dimensions keep the same result object. The server and first client render use the supplied initial dimensions.

- Category: Hooks · Environment
- Import: `@gaudi/design-system/hooks/environment/use-window-size` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/environment/use-window-size.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-environment-usewindowsize--docs

## Usage

```jsx
import { useWindowSize } from '@gaudi/design-system/hooks';

const { width, height } = useWindowSize();
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/hooks-environment-usewindowsize--playground)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.initialWidth` | `number` | `0` | no | Deterministic dimensions before the first client measurement. |
| `initialHeight` | `number` | `0` | no | Deterministic dimensions before the first client measurement. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `size` | `{ width, height }` | Layout viewport dimensions, not device screen or visual viewport dimensions. |

## Accessibility

Prefer CSS responsive layout or useMediaQuery for breakpoints. Avoid hiding essential content based only on viewport size.

## Related

- [useMediaQuery](https://design.gaudi.site/docs/hooks/use-media-query): Track a CSS media query, SSR-safe.
- [useDocumentTitle](https://design.gaudi.site/docs/hooks/use-document-title): Set a document title and restore the previous owner on cleanup.
- [useIsClient](https://design.gaudi.site/docs/hooks/use-is-client): False on the server and during hydration, true on the client.
- [useIsMobile](https://design.gaudi.site/docs/hooks/use-is-mobile): True below the 768px phone breakpoint.
- [useIsMounted](https://design.gaudi.site/docs/hooks/use-is-mounted): A stable getter for whether this hook is currently mounted.
- [useOnlineStatus](https://design.gaudi.site/docs/hooks/use-online-status): Whether the browser reports a network connection.

Source: https://design.gaudi.site/docs/hooks/use-window-size (Markdown with example code: https://design.gaudi.site/docs/hooks/use-window-size.md)

---

# useCopyToClipboard

> Copy text with a temporary copied state and a fallback.

Writes text with the Clipboard API and falls back to a hidden textarea (restoring focus and selection) where the API is blocked. isCopied resets after the timeout. Merges two earlier implementations: copyToClipboard and copy are the same function.

- Category: Hooks · Interaction
- Import: `@gaudi/design-system/hooks/interaction/use-copy-to-clipboard` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/interaction/use-copy-to-clipboard.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-interaction-usecopytoclipboard--docs

## Usage

```jsx
import { useCopyToClipboard } from '@gaudi/design-system/hooks';

const { copy, isCopied } = useCopyToClipboard();

<Button onClick={() => copy(url)}>{isCopied ? 'Copied' : 'Copy link'}</Button>
```

## Examples

Examples (rendered from Storybook):

- [Copy a share link](https://storybook.gaudi.site/index.html?path=/story/hooks-interaction-usecopytoclipboard--share-field)
- [One hook, several copy buttons](https://storybook.gaudi.site/index.html?path=/story/hooks-interaction-usecopytoclipboard--several-targets)
- [Reset pending feedback](https://storybook.gaudi.site/index.html?path=/story/hooks-interaction-usecopytoclipboard--reset-pending-copy)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.timeout` | `number` | `2000` | no | Milliseconds before isCopied resets; 0 keeps it. A number may be passed instead of the options. |
| `options.onCopy / onError` | `(text) => void` | — | no | Called after a successful or failed copy. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `copy(text) / copyToClipboard(text)` | `(text) => Promise<boolean>` | Copy; resolves to whether it worked. |
| `isCopied / copiedText` | `boolean / string \| null` | Feedback state. |
| `reset()` | `function` | Clear the copied state now. |

## Accessibility

Keep the button name stable ("Copy link") and announce the result in a polite status region; swapping only the icon is not announced.

## Notes

- CodeBlock already has a copy button; use this hook for custom copy actions.

## Related

- [CodeBlock](https://design.gaudi.site/docs/components/code-block): CodeBlock renders syntax-highlighted source with an optional header, copy button, line numbers, highlighted and focused lines, diffs, folding and line selection.
- [useEventListener](https://design.gaudi.site/docs/hooks/use-event-listener): Declarative DOM event listener with cleanup.
- [useHotkey](https://design.gaudi.site/docs/hooks/use-hotkey): Keyboard shortcuts with platform-aware mod keys.
- [useHover](https://design.gaudi.site/docs/hooks/use-hover): Pointer hover state with props to spread, ignoring touch.
- [useMousePosition](https://design.gaudi.site/docs/hooks/use-mouse-position): Track viewport, page and optional element-relative pointer coordinates.
- [useOnClickOutside](https://design.gaudi.site/docs/hooks/use-on-click-outside): Run a callback when a press lands outside one or more elements.

Source: https://design.gaudi.site/docs/hooks/use-copy-to-clipboard (Markdown with example code: https://design.gaudi.site/docs/hooks/use-copy-to-clipboard.md)

---

# useEventListener

> Declarative DOM event listener with cleanup.

Attaches a listener to window (default), document, an element or a ref, and removes it on unmount. The latest handler always runs without re-subscribing, and refs are re-read after every commit so the listener follows conditional elements.

- Category: Hooks · Interaction
- Import: `@gaudi/design-system/hooks/interaction/use-event-listener` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/interaction/use-event-listener.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-interaction-useeventlistener--docs

## Usage

```jsx
import { useEventListener } from '@gaudi/design-system/hooks';

useEventListener('resize', () => setWidth(window.innerWidth));
useEventListener('scroll', onScroll, panelRef, { passive: true });
```

## Examples

Examples (rendered from Storybook):

- [Window events](https://storybook.gaudi.site/index.html?path=/story/hooks-interaction-useeventlistener--window-events)
- [Document events](https://storybook.gaudi.site/index.html?path=/story/hooks-interaction-useeventlistener--document-events)
- [An element through a ref](https://storybook.gaudi.site/index.html?path=/story/hooks-interaction-useeventlistener--element-ref)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `eventName` | `string` | — | no | DOM event such as 'keydown', 'scroll' or 'resize'. |
| `handler` | `(event) => void` | — | no | Called for each event; may change on every render. |
| `target` | `'window' \| 'document' \| Element \| RefObject \| null` | `'window'` | no | Where to listen; null detaches. |
| `options` | `boolean \| AddEventListenerOptions` | — | no | capture, passive, once and signal. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `(nothing)` | `void` | The listener lives as long as the component. |

## Accessibility

Keyboard listeners on window or document must not swallow keys that belong to focused controls; check event.target and event.defaultPrevented.

## Notes

- Mark scroll and touch listeners passive so they never delay scrolling.

## Related

- [useCopyToClipboard](https://design.gaudi.site/docs/hooks/use-copy-to-clipboard): Copy text with a temporary copied state and a fallback.
- [useHotkey](https://design.gaudi.site/docs/hooks/use-hotkey): Keyboard shortcuts with platform-aware mod keys.
- [useHover](https://design.gaudi.site/docs/hooks/use-hover): Pointer hover state with props to spread, ignoring touch.
- [useMousePosition](https://design.gaudi.site/docs/hooks/use-mouse-position): Track viewport, page and optional element-relative pointer coordinates.
- [useOnClickOutside](https://design.gaudi.site/docs/hooks/use-on-click-outside): Run a callback when a press lands outside one or more elements.
- [useScrollLock](https://design.gaudi.site/docs/hooks/use-scroll-lock): Lock page scrolling while a custom overlay is open.

Source: https://design.gaudi.site/docs/hooks/use-event-listener (Markdown with example code: https://design.gaudi.site/docs/hooks/use-event-listener.md)

---

# useHotkey

> Keyboard shortcuts with platform-aware mod keys.

Runs a callback for a combination such as 'mod+k' (Command+K on macOS, Control+K elsewhere), 'shift+?' or 'escape'. Skips plain keys while the reader types in a field, and returns aria-keyshortcuts and Kbd keys for the hint.

- Category: Hooks · Interaction
- Import: `@gaudi/design-system/hooks/interaction/use-hotkey` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/interaction/use-hotkey.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-interaction-usehotkey--docs

## Usage

```jsx
import { useHotkey } from '@gaudi/design-system/hooks';

const { ariaKeyShortcuts, kbdKeys } = useHotkey('mod+k', () => setOpen(true));

<Button aria-keyshortcuts={ariaKeyShortcuts} onClick={() => setOpen(true)}>Search <Kbd keys={kbdKeys} /></Button>
```

## Examples

Examples (rendered from Storybook):

- [Platform-aware mod key](https://storybook.gaudi.site/index.html?path=/story/hooks-interaction-usehotkey--command-palette)
- [Single-key shortcuts that can be turned off](https://storybook.gaudi.site/index.html?path=/story/hooks-interaction-usehotkey--single-keys)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `keys` | `string \| string[]` | — | no | One or more combinations: 'mod+k', 'ctrl+shift+p', '/', 'escape'. |
| `callback` | `(event, combo) => void` | — | no | Called when a combination matches. |
| `options.enabled` | `boolean` | `true` | no | When and where to listen. |
| `target` | `target` | `'document'` | no | When and where to listen. |
| `event` | `'keydown' \| 'keyup'` | `'keydown'` | no | When and where to listen. |
| `options.preventDefault` | `boolean` | `true` | no | Stop the browser default for a matched shortcut. |
| `options.enableInInputs / allowRepeat` | `boolean` | `false` | no | Also fire in text fields, and on held-key repeats. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `ariaKeyShortcuts` | `string` | Value for aria-keyshortcuts, e.g. 'Meta+K Control+K'. |
| `kbdKeys` | `string` | Keys for Kbd, e.g. 'command,k' on macOS and 'ctrl,k' elsewhere. |

## Accessibility

Every shortcut needs a visible control that does the same thing. Put aria-keyshortcuts on that control and show the keys with Kbd. Avoid single-key shortcuts unless they can be turned off (WCAG 2.1.4).

## Notes

- `parseHotkey`, `matchHotkey`, `toAriaKeyShortcuts` and `toKbdKeys` are exported for custom handling.

## Related

- [Kbd](https://design.gaudi.site/docs/components/kbd): Kbd renders keyboard keys and multi-key shortcuts.
- [useCopyToClipboard](https://design.gaudi.site/docs/hooks/use-copy-to-clipboard): Copy text with a temporary copied state and a fallback.
- [useEventListener](https://design.gaudi.site/docs/hooks/use-event-listener): Declarative DOM event listener with cleanup.
- [useHover](https://design.gaudi.site/docs/hooks/use-hover): Pointer hover state with props to spread, ignoring touch.
- [useMousePosition](https://design.gaudi.site/docs/hooks/use-mouse-position): Track viewport, page and optional element-relative pointer coordinates.
- [useOnClickOutside](https://design.gaudi.site/docs/hooks/use-on-click-outside): Run a callback when a press lands outside one or more elements.

Source: https://design.gaudi.site/docs/hooks/use-hotkey (Markdown with example code: https://design.gaudi.site/docs/hooks/use-hotkey.md)

---

# useHover

> Pointer hover state with props to spread, ignoring touch.

Tracks pointer hover through onPointerEnter and onPointerLeave. Touch pointers are ignored so a tap does not leave an element stuck in its hover state.

- Category: Hooks · Interaction
- Import: `@gaudi/design-system/hooks/interaction/use-hover` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/interaction/use-hover.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-interaction-usehover--docs

## Usage

```jsx
import { useHover } from '@gaudi/design-system/hooks';

const { isHovered, hoverProps } = useHover();

<Card {...hoverProps}>{isHovered ? 'Paused' : 'Playing'}</Card>
```

## Examples

Examples (rendered from Storybook):

- [Pause rotating content](https://storybook.gaudi.site/index.html?path=/story/hooks-interaction-usehover--pause-on-hover)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.disabled` | `boolean` | `false` | no | Stop tracking and clear the state. |
| `options.onHoverChange` | `(hovered) => void` | — | no | Called when hover starts or ends. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `isHovered` | `boolean` | Whether a mouse or pen is over the element. |
| `hoverProps` | `{ onPointerEnter, onPointerLeave }` | Spread on the element. |

## Accessibility

Hover is an enhancement. Anything revealed on hover must also appear on focus (track :focus-within or onFocus) and be reachable on touch.

## Notes

- Use CSS :hover for purely visual effects; use the hook when hover changes behaviour, such as pausing a carousel.

## Related

- [useCopyToClipboard](https://design.gaudi.site/docs/hooks/use-copy-to-clipboard): Copy text with a temporary copied state and a fallback.
- [useEventListener](https://design.gaudi.site/docs/hooks/use-event-listener): Declarative DOM event listener with cleanup.
- [useHotkey](https://design.gaudi.site/docs/hooks/use-hotkey): Keyboard shortcuts with platform-aware mod keys.
- [useMousePosition](https://design.gaudi.site/docs/hooks/use-mouse-position): Track viewport, page and optional element-relative pointer coordinates.
- [useOnClickOutside](https://design.gaudi.site/docs/hooks/use-on-click-outside): Run a callback when a press lands outside one or more elements.
- [useScrollLock](https://design.gaudi.site/docs/hooks/use-scroll-lock): Lock page scrolling while a custom overlay is open.

Source: https://design.gaudi.site/docs/hooks/use-hover (Markdown with example code: https://design.gaudi.site/docs/hooks/use-hover.md)

---

# useMousePosition

> Track viewport, page and optional element-relative pointer coordinates.

Uses pointermove so mouse and pen work together. Updates at most once per animation frame, and cancels pending work when disabled or unmounted. Attach ref to measure local coordinates against an element's bounding rectangle.

- Category: Hooks · Interaction
- Import: `@gaudi/design-system/hooks/interaction/use-mouse-position` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/interaction/use-mouse-position.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-interaction-usemouseposition--docs

## Usage

```jsx
import { useMousePosition } from '@gaudi/design-system/hooks';

const { ref, elementX, elementY, isInside } = useMousePosition();
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/hooks-interaction-usemouseposition--playground)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.enabled` | `boolean` | `true` | no | Attach tracking listeners; disabling retains the last reading. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `ref` | `callback ref` | Attach to the measured element. |
| `x / y / pageX / pageY` | `number \| null` | Viewport and document coordinates; null before the first move. |
| `elementX / elementY / isInside` | `number \| null / boolean` | Coordinates relative to the bounding rectangle and whether the pointer is inside. |

## Accessibility

Pointer readouts are supplementary. Keep every action available to keyboard and touch users; do not announce each move.

## Notes

- Touch updates occur only while a pointer is moving. Scrolling alone does not refresh the last sample.
- For an animated cursor use the existing Pointer component.

## Related

- [Pointer](https://design.gaudi.site/docs/components/pointer): A pointer effect scoped to its container, with direct, spring and lazy tracking, hover feedback, and native input fallbacks.
- [useCopyToClipboard](https://design.gaudi.site/docs/hooks/use-copy-to-clipboard): Copy text with a temporary copied state and a fallback.
- [useEventListener](https://design.gaudi.site/docs/hooks/use-event-listener): Declarative DOM event listener with cleanup.
- [useHotkey](https://design.gaudi.site/docs/hooks/use-hotkey): Keyboard shortcuts with platform-aware mod keys.
- [useHover](https://design.gaudi.site/docs/hooks/use-hover): Pointer hover state with props to spread, ignoring touch.
- [useOnClickOutside](https://design.gaudi.site/docs/hooks/use-on-click-outside): Run a callback when a press lands outside one or more elements.

Source: https://design.gaudi.site/docs/hooks/use-mouse-position (Markdown with example code: https://design.gaudi.site/docs/hooks/use-mouse-position.md)

---

# useOnClickOutside

> Run a callback when a press lands outside one or more elements.

Listens for pointerdown on the document and calls the handler when the target is outside every ref, for custom panels and inline editors. Pass several refs, such as a trigger and its panel.

- Category: Hooks · Interaction
- Import: `@gaudi/design-system/hooks/interaction/use-on-click-outside` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/interaction/use-on-click-outside.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-interaction-useonclickoutside--docs

## Usage

```jsx
import { useOnClickOutside } from '@gaudi/design-system/hooks';

useOnClickOutside([triggerRef, panelRef], () => setOpen(false), { enabled: open });
```

## Examples

Examples (rendered from Storybook):

- [Commit an inline editor](https://storybook.gaudi.site/index.html?path=/story/hooks-interaction-useonclickoutside--inline-editor)
- [Trigger and panel together](https://storybook.gaudi.site/index.html?path=/story/hooks-interaction-useonclickoutside--trigger-and-panel)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ref` | `RefObject \| RefObject[]` | — | no | Element or elements that count as inside. |
| `handler` | `(event) => void` | — | no | Called on an outside press. |
| `options` | `string \| { event?, enabled? }` | `{ event: 'pointerdown', enabled: true }` | no | Event name ('pointerdown', 'mousedown', 'click', 'focusin'…) or options. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `(nothing)` | `void` | The listener lives as long as the component. |

## Accessibility

An outside click is a pointer shortcut. Also close on Escape and return focus to the trigger, so keyboard users can dismiss the panel.

## Notes

- Popover, Dialog, Select and menus already dismiss themselves.

## Related

- [Popover](https://design.gaudi.site/docs/components/popover): Popover renders compact positioned supporting content next to its trigger.
- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Select](https://design.gaudi.site/docs/components/select): Select renders a styled option picker with searchable combobox behavior and multi-select support.

Source: https://design.gaudi.site/docs/hooks/use-on-click-outside (Markdown with example code: https://design.gaudi.site/docs/hooks/use-on-click-outside.md)

---

# useScrollLock

> Lock page scrolling while a custom overlay is open.

Sets overflow hidden on the body while locked and pads it by the scrollbar width so content does not shift. Locks from several components nest; the last release restores the page.

- Category: Hooks · Interaction
- Import: `@gaudi/design-system/hooks/interaction/use-scroll-lock` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/interaction/use-scroll-lock.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-interaction-usescrolllock--docs

## Usage

```jsx
import { useFocusTrap, useScrollLock } from '@gaudi/design-system/hooks';

useScrollLock(open);
const trapRef = useFocusTrap({ active: open });
```

## Examples

Examples (rendered from Storybook):

- [Full-screen menu](https://storybook.gaudi.site/index.html?path=/story/hooks-interaction-usescrolllock--overlay-menu)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `locked` | `boolean` | `true` | no | Whether scrolling is locked. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `(nothing)` | `void` | The lock is released on unlock or unmount. |

## Accessibility

Lock scrolling together with a focus trap, so neither the pointer nor the keyboard reaches the page behind the overlay.

## Notes

- Dialog, Sheet and Drawer lock scrolling themselves.
- `lockScroll()` returns a release function for non-React code.

## Related

- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Sheet](https://design.gaudi.site/docs/components/sheet): A panel that slides in from an edge over a dimmed page, for side tasks such as settings, details, comments, notifications or an assistant, without leaving the current screen.
- [useCopyToClipboard](https://design.gaudi.site/docs/hooks/use-copy-to-clipboard): Copy text with a temporary copied state and a fallback.
- [useEventListener](https://design.gaudi.site/docs/hooks/use-event-listener): Declarative DOM event listener with cleanup.
- [useHotkey](https://design.gaudi.site/docs/hooks/use-hotkey): Keyboard shortcuts with platform-aware mod keys.
- [useHover](https://design.gaudi.site/docs/hooks/use-hover): Pointer hover state with props to spread, ignoring touch.

Source: https://design.gaudi.site/docs/hooks/use-scroll-lock (Markdown with example code: https://design.gaudi.site/docs/hooks/use-scroll-lock.md)

---

# useCollapsibleSections

> Expanded state for several sections, with expand all and collapse all.

Coordinates individual and bulk disclosure for settings pages, filter sidebars, FAQs and inspectors. The initial expansion is read once; onChange receives the expanded ids after each change. The pure reducer is exported too.

- Category: Hooks · Layout
- Import: `@gaudi/design-system/hooks/layout/use-collapsible-sections` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/layout/use-collapsible-sections.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-layout-usecollapsiblesections--docs

## Usage

```jsx
import { useCollapsibleSections } from '@gaudi/design-system/hooks';

const sections = useCollapsibleSections({ sections: ['profile', 'billing', 'privacy'], initialExpanded: ['profile'] });
```

## Examples

Examples (rendered from Storybook):

- [Settings with expand and collapse all](https://storybook.gaudi.site/index.html?path=/story/hooks-layout-usecollapsiblesections--settings-page)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `config.sections` | `string[]` | — | no | Every section id. |
| `config.initialExpanded` | `string[]` | `[]` | no | Sections open at first, or all of them. |
| `expandAll` | `boolean` | `false` | no | Sections open at first, or all of them. |
| `config.onChange` | `(expanded: string[]) => void` | — | no | Called after each change. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `isExpanded(id)` | `boolean` | Whether a section is open. |
| `expandedSections / expandedCount` | `string[] / number` | The open sections. |
| `allExpanded / allCollapsed` | `boolean` | For the bulk buttons. |
| `toggle / expand / collapse` | `(id) => void` | Change one section. |
| `expandAll / collapseAll / setExpanded` | `function` | Change many at once. |

## Accessibility

Render each section with Collapsible or Accordion so triggers expose aria-expanded. Disable "Expand all" when everything is open rather than hiding it, so the controls do not move.

## Notes

- `collapsibleSectionsReducer`, `createCollapsibleSectionsState` and `areAllSectionsExpanded` are exported.

## Related

- [Accordion](https://design.gaudi.site/docs/components/accordion): Rich disclosure for FAQs, settings, member directories, nested help, and guided setup.
- [useElementSize](https://design.gaudi.site/docs/hooks/use-element-size): An element's size, kept current with a ResizeObserver.
- [useInView](https://design.gaudi.site/docs/hooks/use-in-view): Whether an element is in the viewport, from an IntersectionObserver.
- [useScrollPosition](https://design.gaudi.site/docs/hooks/use-scroll-position): The vertical scroll offset of the page or a scroll container.

Source: https://design.gaudi.site/docs/hooks/use-collapsible-sections (Markdown with example code: https://design.gaudi.site/docs/hooks/use-collapsible-sections.md)

---

# useElementSize

> An element's size, kept current with a ResizeObserver.

Measures the border box and follows resizes, for container-driven layouts, truncation and drawing at real pixel sizes. Returns a callback ref and the size; onResize receives each size without a render.

- Category: Hooks · Layout
- Import: `@gaudi/design-system/hooks/layout/use-element-size` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/layout/use-element-size.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-layout-useelementsize--docs

## Usage

```jsx
import { useElementSize } from '@gaudi/design-system/hooks';

const [ref, { width }] = useElementSize();
<div ref={ref}>{width < 480 ? <CompactCard /> : <WideCard />}</div>
```

## Examples

Examples (rendered from Storybook):

- [Layout from the container width](https://storybook.gaudi.site/index.html?path=/story/hooks-layout-useelementsize--container-layout)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.initialSize` | `{ width, height }` | `{ width: 0, height: 0 }` | no | Size on the server and before the first measurement. |
| `options.onResize` | `(size) => void` | — | no | Called with each measured size. |
| `options.round` | `boolean` | `true` | no | Round to whole pixels. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `[0] ref` | `(node) => void` | Callback ref for the element. |
| `[1] size` | `{ width, height }` | The current size in pixels. |

## Accessibility

Size-driven layouts must still reflow at 400% zoom and keep reading order; prefer CSS container queries when only styles change.

## Notes

- Charts measure themselves; use this for your own canvases and layouts.

## Related

- [useCollapsibleSections](https://design.gaudi.site/docs/hooks/use-collapsible-sections): Expanded state for several sections, with expand all and collapse all.
- [useInView](https://design.gaudi.site/docs/hooks/use-in-view): Whether an element is in the viewport, from an IntersectionObserver.
- [useScrollPosition](https://design.gaudi.site/docs/hooks/use-scroll-position): The vertical scroll offset of the page or a scroll container.

Source: https://design.gaudi.site/docs/hooks/use-element-size (Markdown with example code: https://design.gaudi.site/docs/hooks/use-element-size.md)

---

# useInView

> Whether an element is in the viewport, from an IntersectionObserver.

For lazy sections, "load more" sentinels, reading progress and reveal effects. With once, it stops observing after the element is first seen.

- Category: Hooks · Layout
- Import: `@gaudi/design-system/hooks/layout/use-in-view` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/layout/use-in-view.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-layout-useinview--docs

## Usage

```jsx
import { useInView } from '@gaudi/design-system/hooks';

const [ref, inView] = useInView({ rootMargin: '200px', once: true });
<section ref={ref}>{inView ? <Comments /> : <Skeleton className='h-40' />}</section>
```

## Examples

Examples (rendered from Storybook):

- [Load a section when it is reached](https://storybook.gaudi.site/index.html?path=/story/hooks-layout-useinview--lazy-section)
- ["Load more" sentinel with a button](https://storybook.gaudi.site/index.html?path=/story/hooks-layout-useinview--infinite-list)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.root` | `Element` | `viewport` | no | IntersectionObserver options. |
| `rootMargin` | `string` | `'0px'` | no | IntersectionObserver options. |
| `threshold` | `number \| number[]` | `0` | no | IntersectionObserver options. |
| `options.once` | `boolean` | `false` | no | Stop after the first time the element is in view. |
| `options.initialInView` | `boolean` | `false` | no | Value on the server and without IntersectionObserver. |
| `options.onChange` | `(inView, entry) => void` | — | no | Called on each change. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `[0] ref` | `(node) => void` | Callback ref for the element. |
| `[1] inView` | `boolean` | Whether it intersects. |
| `[2] entry` | `IntersectionObserverEntry \| null` | The latest entry. |

## Accessibility

Never hide content until it scrolls into view for readers without JavaScript or with reduced motion; keep "load more" available as a real button too.

## Notes

- Set initialInView to true for content that must render without JavaScript.

## Related

- [useCollapsibleSections](https://design.gaudi.site/docs/hooks/use-collapsible-sections): Expanded state for several sections, with expand all and collapse all.
- [useElementSize](https://design.gaudi.site/docs/hooks/use-element-size): An element's size, kept current with a ResizeObserver.
- [useScrollPosition](https://design.gaudi.site/docs/hooks/use-scroll-position): The vertical scroll offset of the page or a scroll container.

Source: https://design.gaudi.site/docs/hooks/use-in-view (Markdown with example code: https://design.gaudi.site/docs/hooks/use-in-view.md)

---

# useScrollPosition

> The vertical scroll offset of the page or a scroll container.

Follows window scrolling, or the element in targetRef, with a passive listener. 0 during server rendering.

- Category: Hooks · Layout
- Import: `@gaudi/design-system/hooks/layout/use-scroll-position` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/layout/use-scroll-position.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-layout-usescrollposition--docs

## Usage

```jsx
import { useScrollPosition } from '@gaudi/design-system/hooks';

const scrollY = useScrollPosition();
const compact = scrollY > 64;
```

## Examples

Examples (rendered from Storybook):

- [Reading progress in a scroll container](https://storybook.gaudi.site/index.html?path=/story/hooks-layout-usescrollposition--reading-progress)
- [Page scroll](https://storybook.gaudi.site/index.html?path=/story/hooks-layout-usescrollposition--page-scroll)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.targetRef` | `RefObject<HTMLElement>` | `the page` | no | Scroll container to follow instead of the window. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `scrollY` | `number` | Pixels scrolled from the top. |

## Accessibility

A back-to-top control revealed by scrolling should stay in the tab order (hidden with inert or visibility, not just opacity) and move focus sensibly.

## Notes

- Updates on every scroll event; throttle derived work with useThrottleCallback.

## Related

- [useThrottleCallback](https://design.gaudi.site/docs/hooks/use-throttle-callback): A function that runs at most once per interval.
- [useCollapsibleSections](https://design.gaudi.site/docs/hooks/use-collapsible-sections): Expanded state for several sections, with expand all and collapse all.
- [useElementSize](https://design.gaudi.site/docs/hooks/use-element-size): An element's size, kept current with a ResizeObserver.
- [useInView](https://design.gaudi.site/docs/hooks/use-in-view): Whether an element is in the viewport, from an IntersectionObserver.

Source: https://design.gaudi.site/docs/hooks/use-scroll-position (Markdown with example code: https://design.gaudi.site/docs/hooks/use-scroll-position.md)

---

# useBoolean

> Generic boolean state with stable toggle, enable and disable actions.

Keeps on/off state without disclosure-specific ARIA. Values and functional updates are normalized to booleans; the initial value is also the server value.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-boolean` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-boolean.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-useboolean--docs

## Usage

```jsx
import { useBoolean } from '@gaudi/design-system/hooks';

const { value, toggle, setTrue, setFalse } = useBoolean(false);
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/hooks-state-useboolean--playground)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `initialValue` | `boolean` | `false` | no | Initial on/off value. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `value` | `boolean` | Current state. |
| `setValue / setTrue / setFalse / toggle` | `function` | Set directly or through an updater, enable, disable, or invert the value. |

## Accessibility

Use aria-pressed on toggle buttons or checked on switches. Use useDisclosure for a control that reveals a region.

## Notes

- Covers the boolean useToggle use case with one API.

## Related

- [useDisclosure](https://design.gaudi.site/docs/hooks/use-disclosure): Open, close and toggle state for overlays and disclosures.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.

Source: https://design.gaudi.site/docs/hooks/use-boolean (Markdown with example code: https://design.gaudi.site/docs/hooks/use-boolean.md)

---

# useControllableState

> State that works controlled or uncontrolled, like native inputs.

The component owns the state until its host passes value; then the host accepts, refuses or replaces each change offered through onChange. The setter takes a value or an updater and skips unchanged values. DataTable uses it.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-controllable-state` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-controllable-state.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-usecontrollablestate--docs

## Usage

```jsx
import { useControllableState } from '@gaudi/design-system/hooks';

function Rating({ value, defaultValue = 0, onChange }) {
  const [rating, setRating] = useControllableState({ value, defaultValue, onChange });
}
```

## Examples

Examples (rendered from Storybook):

- [Uncontrolled](https://storybook.gaudi.site/index.html?path=/story/hooks-state-usecontrollablestate--uncontrolled)
- [Controlled, with the host refusing changes](https://storybook.gaudi.site/index.html?path=/story/hooks-state-usecontrollablestate--controlled)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.value` | `any` | — | no | Controlled value; undefined means uncontrolled. |
| `options.defaultValue` | `any` | — | no | Initial value when uncontrolled. |
| `options.onChange` | `(value) => void` | — | no | Called with each change. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `[0] value` | `any` | The current value. |
| `[1] setValue` | `(value \| (current) => value) => void` | Offer a change. |

## Accessibility

Controlled components must still reflect every change visibly and to assistive technology (checked, expanded, selected), even when the host refuses it.

## Notes

- Decide once: switching between controlled and uncontrolled during a component life is not supported.

## Related

- [DataTable](https://design.gaudi.site/docs/components/data-table): DataTable is a TanStack table with a compact data anatomy: shared headers that preserve label casing, hairline rows, synced column and row hover, a tinted wash for selected rows, and declarative column alignment, width and pinning.
- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.

Source: https://design.gaudi.site/docs/hooks/use-controllable-state (Markdown with example code: https://design.gaudi.site/docs/hooks/use-controllable-state.md)

---

# useCountdown

> A pausable countdown or count-up that stops at its target.

Composes useInterval with count state. Changing the interval restarts the timer interval; reset stops it and restores the current countStart. Counts represent ticks, not elapsed wall-clock time.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-countdown` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-countdown.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-usecountdown--docs

## Usage

```jsx
import { useCountdown } from '@gaudi/design-system/hooks';

const { count, isRunning, start, stop, reset } = useCountdown({ countStart: 30 });
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/hooks-state-usecountdown--playground)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.countStart` | `number` | `60` | no | Starting value and terminal value. |
| `countStop` | `number` | `0` | no | Starting value and terminal value. |
| `options.intervalMs` | `number` | `1000` | no | Positive milliseconds per tick; invalid values stop the timer. |
| `options.isIncrement` | `boolean` | `false` | no | Count up toward the target instead of down. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `count / isRunning` | `number / boolean` | Current count and whether the timer is advancing. |
| `start / stop / reset` | `function` | Start or resume, pause, or stop and reset. |

## Accessibility

Keep pause and reset controls available. Avoid announcing every tick; announce completion separately.

## Notes

- Timers can be throttled in background tabs. Use an application deadline for time-critical expiry.
- Starting at or beyond the target does not run.

## Related

- [useInterval](https://design.gaudi.site/docs/hooks/use-interval): setInterval that can pause and always runs the latest callback.
- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.

Source: https://design.gaudi.site/docs/hooks/use-countdown (Markdown with example code: https://design.gaudi.site/docs/hooks/use-countdown.md)

---

# useCounter

> A number with increment, decrement, set and reset actions.

Functional updates compose within one event. Reset returns to the current initialValue argument. The hook imposes no product-specific bounds.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-counter` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-counter.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-usecounter--docs

## Usage

```jsx
import { useCounter } from '@gaudi/design-system/hooks';

const { count, increment, decrement, reset } = useCounter(1);
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/hooks-state-usecounter--playground)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `initialValue` | `number` | `0` | no | Initial and reset value, also used on the server. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `count` | `number` | Current value. |
| `increment / decrement / reset / setCount` | `function` | Change by one, reset, or assign a number or functional update. |

## Accessibility

Give increment and decrement buttons meaningful names; announce changes only when useful.

## Related

- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.
- [useDisclosure](https://design.gaudi.site/docs/hooks/use-disclosure): Open, close and toggle state for overlays and disclosures.

Source: https://design.gaudi.site/docs/hooks/use-counter (Markdown with example code: https://design.gaudi.site/docs/hooks/use-counter.md)

---

# useDebounceCallback

> A debounced function with cancel and flush.

Runs the latest callback once, delay ms after the last call, with the latest arguments: autosave, search requests and resize work. Pending work is cancelled on unmount.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-debounce-callback` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-debounce-callback.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-usedebouncecallback--docs

## Usage

```jsx
import { useDebounceCallback } from '@gaudi/design-system/hooks';

const save = useDebounceCallback((text) => saveDraft(text), 800);
<Textarea onChange={(event) => save(event.target.value)} onBlur={save.flush} />
```

## Examples

Examples (rendered from Storybook):

- [Autosave a draft](https://storybook.gaudi.site/index.html?path=/story/hooks-state-usedebouncecallback--autosave-draft)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `callback` | `(...args) => void` | — | no | The work to run. |
| `delay` | `number` | `300` | no | Milliseconds after the last call. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `debounced(...args)` | `function` | Schedule the work. |
| `debounced.cancel / flush / isPending` | `function` | Drop pending work, run it now, or check for it. |

## Accessibility

For autosave, show and announce the saved state once the debounced save finishes, and flush on blur so work is not lost.

## Notes

- `createDebouncer(callback, delay)` is exported for non-React code.

## Related

- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.
- [useDisclosure](https://design.gaudi.site/docs/hooks/use-disclosure): Open, close and toggle state for overlays and disclosures.

Source: https://design.gaudi.site/docs/hooks/use-debounce-callback (Markdown with example code: https://design.gaudi.site/docs/hooks/use-debounce-callback.md)

---

# useDebounceValue

> A value that updates only after it stops changing.

Delays a fast-changing value, such as a search query, until it has been still for the delay, so filtering and requests do not run on every keystroke.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-debounce-value` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-debounce-value.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-usedebouncevalue--docs

## Usage

```jsx
import { useDebounceValue } from '@gaudi/design-system/hooks';

const debouncedQuery = useDebounceValue(query, 300);
const results = useMemo(() => search(debouncedQuery), [debouncedQuery]);
```

## Examples

Examples (rendered from Storybook):

- [Filter after typing settles](https://storybook.gaudi.site/index.html?path=/story/hooks-state-usedebouncevalue--search-filter)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value` | `any` | — | no | The live value. |
| `delay` | `number` | `300` | no | Milliseconds of stillness before updating. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `debouncedValue` | `any` | The settled value. |

## Accessibility

Announce result counts after the debounced update, not per keystroke, so screen readers are not flooded.

## Notes

- Use useDebounceCallback when you need cancel or flush.

## Related

- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDisclosure](https://design.gaudi.site/docs/hooks/use-disclosure): Open, close and toggle state for overlays and disclosures.

Source: https://design.gaudi.site/docs/hooks/use-debounce-value (Markdown with example code: https://design.gaudi.site/docs/hooks/use-debounce-value.md)

---

# useDisclosure

> Open, close and toggle state for overlays and disclosures.

Open state for dialogs, menus, drawers and custom disclosures, controlled or uncontrolled, with getTriggerProps for a custom trigger.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-disclosure` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-disclosure.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-usedisclosure--docs

## Usage

```jsx
import { useDisclosure } from '@gaudi/design-system/hooks';

const { open, setOpen, onOpen } = useDisclosure();

<Button onClick={onOpen}>Share</Button>
<Dialog open={open} onOpenChange={setOpen} title='Share'>…</Dialog>
```

## Examples

Examples (rendered from Storybook):

- [Drive a Gaudi Dialog](https://storybook.gaudi.site/index.html?path=/story/hooks-state-usedisclosure--with-dialog)
- [Custom disclosure](https://storybook.gaudi.site/index.html?path=/story/hooks-state-usedisclosure--custom-trigger)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.open / defaultOpen` | `boolean` | `— / false` | no | Controlled or initial state. |
| `options.onOpenChange` | `(open) => void` | — | no | Called with each change. |
| `options.id` | `string` | — | no | Id of the controlled region, added as aria-controls by getTriggerProps. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `open` | `boolean` | Whether it is open. |
| `onOpen / onClose / onToggle / setOpen` | `function` | Change the state. |
| `getTriggerProps(props)` | `{ aria-expanded, aria-controls?, onClick }` | Spread on a custom trigger button. |

## Accessibility

A custom trigger must be a button with aria-expanded and, when the region is in the page, aria-controls; getTriggerProps adds both.

## Notes

- Gaudi overlays take open and onOpenChange directly: pass them through.

## Related

- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.

Source: https://design.gaudi.site/docs/hooks/use-disclosure (Markdown with example code: https://design.gaudi.site/docs/hooks/use-disclosure.md)

---

# useEventCallback

> A stable function that always calls the latest callback.

Pass handlers to effects, subscriptions and memoised children without re-running them when an inline callback changes. Call it from events and effects, not during render.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-event-callback` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-event-callback.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-useeventcallback--docs

## Usage

```jsx
import { useEventCallback } from '@gaudi/design-system/hooks';

const onMessage = useEventCallback((message) => setLog((log) => [...log, message]));
useEffect(() => socket.subscribe(onMessage), [onMessage]);
```

## Examples

Examples (rendered from Storybook):

- [Fresh state, stable subscription](https://storybook.gaudi.site/index.html?path=/story/hooks-state-useeventcallback--stable-subscription)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `callback` | `(...args) => any` | — | no | The latest implementation. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `stableCallback` | `(...args) => any` | Same identity for the component lifetime. |

## Accessibility

No direct accessibility impact; it keeps listeners stable so focus and announcements are not reset by re-subscriptions.

## Notes

- Do not call the returned function during render.

## Related

- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.

Source: https://design.gaudi.site/docs/hooks/use-event-callback (Markdown with example code: https://design.gaudi.site/docs/hooks/use-event-callback.md)

---

# useInterval

> setInterval that can pause and always runs the latest callback.

Calls the callback every delay ms. Pass null to pause; the callback can read fresh state without restarting the interval.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-interval` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-interval.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-useinterval--docs

## Usage

```jsx
import { useInterval } from '@gaudi/design-system/hooks';

useInterval(() => setSeconds((s) => s + 1), running ? 1000 : null);
```

## Examples

Examples (rendered from Storybook):

- [A pausable timer](https://storybook.gaudi.site/index.html?path=/story/hooks-state-useinterval--timer)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `callback` | `() => void` | — | no | Called on each tick. |
| `delay` | `number \| null` | — | no | Milliseconds between ticks; null or false pauses. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `(nothing)` | `void` | The interval stops on unmount. |

## Accessibility

Content that moves or updates automatically for more than five seconds needs a pause control (WCAG 2.2.2); pass null while paused.

## Notes

- Pause in hidden tabs with usePageVisibility.

## Related

- [usePageVisibility](https://design.gaudi.site/docs/hooks/use-page-visibility): Whether the tab is visible, to pause work in the background.
- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.

Source: https://design.gaudi.site/docs/hooks/use-interval (Markdown with example code: https://design.gaudi.site/docs/hooks/use-interval.md)

---

# useIsomorphicLayoutEffect

> useLayoutEffect in the browser, useEffect on the server.

For measure-before-paint code in components that also render on the server. CodeBlock, EventCalendar and Flow use it.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-isomorphic-layout-effect` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-isomorphic-layout-effect.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-useisomorphiclayouteffect--docs

## Usage

```jsx
import { useIsomorphicLayoutEffect } from '@gaudi/design-system/hooks';

useIsomorphicLayoutEffect(() => {
  setHeight(ref.current.scrollHeight);
}, [content]);
```

## Examples

Examples (rendered from Storybook):

- [Measure before paint](https://storybook.gaudi.site/index.html?path=/story/hooks-state-useisomorphiclayouteffect--measure-before-paint)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `effect, deps` | `EffectCallback, DependencyList` | — | no | The same arguments as useLayoutEffect. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `(nothing)` | `void` | Runs the effect. |

## Accessibility

Measuring before paint avoids visible jumps that can disorient readers and move focus targets.

## Notes

- Prefer useEffect unless you must read layout before the browser paints.

## Related

- [CodeBlock](https://design.gaudi.site/docs/components/code-block): CodeBlock renders syntax-highlighted source with an optional header, copy button, line numbers, highlighted and focused lines, diffs, folding and line selection.
- [EventCalendar](https://design.gaudi.site/docs/components/event-calendar): Schedule events across day, week, month, agenda and resource views.
- [Flow](https://design.gaudi.site/docs/components/flow): A node-and-edge canvas for workflows, pipelines, agent trees and driver maps, themed with Gaudi tokens and built on React Flow.

Source: https://design.gaudi.site/docs/hooks/use-isomorphic-layout-effect (Markdown with example code: https://design.gaudi.site/docs/hooks/use-isomorphic-layout-effect.md)

---

# useMergedRefs

> Combine a forwarded ref with your own refs.

One stable callback ref that forwards the node to every ref passed, object or callback, including React 19 ref cleanups.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-merged-refs` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-merged-refs.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-usemergedrefs--docs

## Usage

```jsx
import { useMergedRefs } from '@gaudi/design-system/hooks';

function SearchField({ ref, ...props }) {
  const inputRef = useRef(null);
  return <Input ref={useMergedRefs(ref, inputRef)} {...props} />;
}
```

## Examples

Examples (rendered from Storybook):

- [Forward a ref and keep your own](https://storybook.gaudi.site/index.html?path=/story/hooks-state-usemergedrefs--forwarded-and-own-ref)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `...refs` | `Ref[]` | — | no | Object refs, callback refs or undefined. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `ref` | `(node) => void` | Callback ref to attach. |

## Accessibility

Lets a component keep its own ref for focus management while still forwarding the host ref.

## Notes

- `mergeRefs(...refs)` is exported for use outside components.

## Related

- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.

Source: https://design.gaudi.site/docs/hooks/use-merged-refs (Markdown with example code: https://design.gaudi.site/docs/hooks/use-merged-refs.md)

---

# usePrevious

> The value a prop or state held before it last changed.

For "went up / went down" indicators, transition direction and change detection. Tracked in state, so it is safe under concurrent rendering, and unchanged re-renders keep the same previous value.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-previous` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-previous.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-useprevious--docs

## Usage

```jsx
import { usePrevious } from '@gaudi/design-system/hooks';

const previous = usePrevious(count);
const trend = previous === undefined ? 'flat' : count > previous ? 'up' : 'down';
```

## Examples

Examples (rendered from Storybook):

- [Change since the last value](https://storybook.gaudi.site/index.html?path=/story/hooks-state-useprevious--trend)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value` | `any` | — | no | The value to track. |
| `initial` | `any` | `undefined` | no | Returned until the value first changes. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `previous` | `any` | The value before the last change. |

## Accessibility

When a change direction is shown with colour or an arrow, also state it in text ("up 12%").

## Notes

- Comparison uses Object.is; pass primitives or stable objects.

## Related

- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.

Source: https://design.gaudi.site/docs/hooks/use-previous (Markdown with example code: https://design.gaudi.site/docs/hooks/use-previous.md)

---

# useSliderInput

> Keep a range slider and its number inputs in sync.

For a two-thumb range with min and max inputs: slider moves update the inputs, and typed values are clamped against the bounds and the other thumb when committed.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-slider-input` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-slider-input.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-usesliderinput--docs

## Usage

```jsx
import { useSliderInput } from '@gaudi/design-system/hooks';

const price = useSliderInput({ minValue: 0, maxValue: 500, initialValue: [50, 300] });
```

## Examples

Examples (rendered from Storybook):

- [Range slider with exact inputs](https://storybook.gaudi.site/index.html?path=/story/hooks-state-usesliderinput--range-with-inputs)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.minValue` | `number` | — | no | Bounds and the starting range. |
| `maxValue` | `number` | — | no | Bounds and the starting range. |
| `initialValue` | `[number, number]` | — | no | Bounds and the starting range. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `sliderValues / inputValues` | `[number, number] / [number \| "", number \| ""]` | Committed range and editable input drafts. A draft may be empty while replacing a value. |
| `handleSliderChange(values)` | `function` | Pass to the Slider onValueChange. |
| `handleInputChange(event, index)` | `function` | Pass to each input onChange. |
| `validateAndUpdateValue(value, index)` | `function` | Commit a typed value on blur or Enter. |

## Accessibility

Label both inputs ("Minimum price", "Maximum price") and both slider thumbs; the inputs give keyboard and screen reader users an exact entry.

## Notes

- Commit typed values on blur or Enter, not on every keystroke. Use parseFloat so an empty or invalid draft restores the previous committed value.

## Related

- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.

Source: https://design.gaudi.site/docs/hooks/use-slider-input (Markdown with example code: https://design.gaudi.site/docs/hooks/use-slider-input.md)

---

# useStep

> Zero-based step state for wizards and multi-page forms.

The current step with next, previous, goTo and reset, clamped to the step count, controlled or uncontrolled. Pairs with Stepper and Progress.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-step` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-step.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-usestep--docs

## Usage

```jsx
import { useStep } from '@gaudi/design-system/hooks';

const { step, next, previous, canGoNext, canGoPrevious } = useStep({ count: 4 });
```

## Examples

Examples (rendered from Storybook):

- [Wizard with progress](https://storybook.gaudi.site/index.html?path=/story/hooks-state-usestep--wizard)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options.count` | `number` | — | no | Number of steps. |
| `options.step / defaultStep` | `number` | `— / 0` | no | Controlled or initial step. |
| `options.onStepChange` | `(step) => void` | — | no | Called with each change. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `step / count` | `number` | The current step and the total. |
| `isFirst / isLast / canGoPrevious / canGoNext` | `boolean` | For button state. |
| `next / previous / goTo(step) / reset` | `function` | Move between steps; goTo clamps. |

## Accessibility

Move focus to the new step heading after Next or Back, and state the position in text ("Step 2 of 4").

## Notes

- Validate the current step before calling next; the hook does not know your rules.

## Related

- [Stepper](https://design.gaudi.site/docs/components/stepper): Show progress through a sequence of labelled steps.
- [Progress](https://design.gaudi.site/docs/components/progress): Determinate and indeterminate progress with a readable task label.
- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.

Source: https://design.gaudi.site/docs/hooks/use-step (Markdown with example code: https://design.gaudi.site/docs/hooks/use-step.md)

---

# useThrottleCallback

> A function that runs at most once per interval.

Keeps scroll, pointer and resize handlers responsive without running on every event: the first call runs at once and later calls fold into one trailing call with the latest arguments.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-throttle-callback` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-throttle-callback.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-usethrottlecallback--docs

## Usage

```jsx
import { useThrottleCallback } from '@gaudi/design-system/hooks';

const onScroll = useThrottleCallback(() => setProgress(readProgress()), 100);
```

## Examples

Examples (rendered from Storybook):

- [Throttle pointer moves](https://storybook.gaudi.site/index.html?path=/story/hooks-state-usethrottlecallback--pointer-moves)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `callback` | `(...args) => void` | — | no | The work to run. |
| `wait` | `number` | `200` | no | Minimum milliseconds between runs. |
| `options.leading / trailing` | `boolean` | `true / true` | no | Run on the first call, and once more after the window. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `throttled(...args)` | `function` | Call as often as you like. |
| `throttled.cancel / flush` | `function` | Drop or run the pending trailing call. |

## Accessibility

Keep the final state accurate (trailing: true) so progress indicators and announcements end on the real value.

## Notes

- `createThrottler(callback, wait, options)` is exported for non-React code.

## Related

- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.

Source: https://design.gaudi.site/docs/hooks/use-throttle-callback (Markdown with example code: https://design.gaudi.site/docs/hooks/use-throttle-callback.md)

---

# useTimeout

> A one-off timer with reset and clear.

Calls the callback once, delay ms after mount or after the delay changes. Pass null to hold it; reset restarts it and clear cancels it.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-timeout` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-timeout.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-usetimeout--docs

## Usage

```jsx
import { useTimeout } from '@gaudi/design-system/hooks';

const { clear, reset } = useTimeout(() => setVisible(false), visible ? 5000 : null);
```

## Examples

Examples (rendered from Storybook):

- [Auto-dismiss that pauses](https://storybook.gaudi.site/index.html?path=/story/hooks-state-usetimeout--auto-dismiss)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `callback` | `() => void` | — | no | Called when the timer fires. |
| `delay` | `number \| null` | — | no | Milliseconds; null holds the timer. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `reset / clear` | `() => void` | Restart or cancel the timer. |

## Accessibility

Auto-dismissed messages must stay long enough to read, pause while hovered or focused, and stay available elsewhere (WCAG 2.2.1).

## Notes

- Clear on hover and focus, reset on leave and blur, for dismissible notices.

## Related

- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.

Source: https://design.gaudi.site/docs/hooks/use-timeout (Markdown with example code: https://design.gaudi.site/docs/hooks/use-timeout.md)

---

# useUnmount

> Run the latest committed callback when an effect is cleaned up.

Keeps a fresh callback without recreating the subscription. Runs during unmount and React Strict Mode effect probes; callbacks must tolerate repeated setup/cleanup.

- Category: Hooks · State
- Import: `@gaudi/design-system/hooks/state/use-unmount` (also `@gaudi/design-system/hooks`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/hooks/state/use-unmount.js
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/hooks-state-useunmount--docs

## Usage

```jsx
import { useUnmount } from '@gaudi/design-system/hooks';

useUnmount(() => releasePreview());
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/hooks-state-useunmount--playground)

## API

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `callback` | `() => void` | — | no | Latest committed cleanup callback. |

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `return` | `undefined` | No state or actions. |

## Accessibility

Do not announce routine cleanup or steal focus. Restore focus through the owning overlay component.

## Notes

- For resource acquisition, prefer a normal effect that returns the cleanup for that exact resource.

## Related

- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value): A value that updates only after it stops changing.

Source: https://design.gaudi.site/docs/hooks/use-unmount (Markdown with example code: https://design.gaudi.site/docs/hooks/use-unmount.md)

---

# Animations

> Text and background effects with scoped rendering, reduced motion and visibility-aware playback.

28 pages · 0 live examples, generated from the design system metadata.

## Backgrounds

- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth. Hold the pointer to gather the stream, then release to unfurl it.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.
- [FloatingLines](https://design.gaudi.site/docs/animations/floating-lines): Three layered families of glowing lines cross the surface and bend around the pointer.
- [GradientWaves](https://design.gaudi.site/docs/animations/gradient-waves): Broad, softly lit swells roll toward a hazy horizon, with atmospheric depth and subtle pointer parallax.
- [Grainient](https://design.gaudi.site/docs/animations/grainient): A slowly warped three-color gradient with fine animated grain.
- [GridScan](https://design.gaudi.site/docs/animations/grid-scan): A perspective grid corridor illuminated by a traveling scan pulse.
- [Hyperspeed](https://design.gaudi.site/docs/animations/hyperspeed): Paired light trails travel along a curving road and accelerate while the background is held.
- [LightPillar](https://design.gaudi.site/docs/animations/light-pillar): Irregular luminous ribbons flow through a broad diagonal column with bright cores and soft bloom.
- [LightRays](https://design.gaudi.site/docs/animations/light-rays): Soft overhead shafts overlap in an atmospheric cone and dissolve before reaching the lower surface.
- [LiquidEther](https://design.gaudi.site/docs/animations/liquid-ether): Colored dye follows pointer movement, curls through a retained velocity field, and gradually dissipates.
- [MicroSlats](https://design.gaudi.site/docs/animations/micro-slats): Rounded 10×25px slats catch broad rolling swells, crest glints and a fading pointer wake.
- [Particle Sea](https://design.gaudi.site/docs/animations/particle-sea): A rolling sea of fine points seen in perspective; crests catch the light and glitter.
- [PatternWaves](https://design.gaudi.site/docs/animations/pattern-waves): A nine-pixel dot lattice shades folded fabric with narrow illuminated creases and localized ripples.
- [PixelBlast](https://design.gaudi.site/docs/animations/pixel-blast): Separate square pixels form drifting dithered patterns; clicks send circular waves through the field.
- [Plasma](https://design.gaudi.site/docs/animations/plasma): Translucent plasma folds flow across the surface, with soft illuminated edges.
- [ShapeWaves](https://design.gaudi.site/docs/animations/shape-waves): Ten-pixel cells cycle through triangle, circle and square bands, with optional text carved out of the field.
- [SideRays](https://design.gaudi.site/docs/animations/side-rays): Broad, diffuse shafts cascade from the upper-right corner and fade rapidly into the surface.
- [WebThreads](https://design.gaudi.site/docs/animations/web-threads): Six luminous strands fan outward from one bright central pinch, with soft glow around each thread.

## Text

- [CipherReveal](https://design.gaudi.site/docs/animations/cipher-reveal): Scrambled characters resolve progressively into readable text on view, hover or focus.
- [GlyphInspector](https://design.gaudi.site/docs/animations/glyph-inspector): Inspect animated letter outlines with a gliding frame, floating square particles, measurement guides and a live readout. Hover to take control; drag and release a letter to return it to its slot.
- [PhraseCycle](https://design.gaudi.site/docs/animations/phrase-cycle): A sequence of phrases rotates vertically in a stable space, without moving the surrounding line.
- [Typewriter](https://design.gaudi.site/docs/animations/typewriter): Types, pauses and deletes a sequence of phrases while reserving space for the longest one.
- [WarpText](https://design.gaudi.site/docs/animations/warp-text): Text gently undulates at rest and bends beneath a moving pointer lens. Hover magnifies a local area, adds a soft ripple and optional RGB refraction, then eases back on exit.
- [WordSpotlight](https://design.gaudi.site/docs/animations/word-spotlight): A moving set of corner marks brings one word into focus while the surrounding words soften.

Source: https://design.gaudi.site/docs/animations (Markdown with example code: https://design.gaudi.site/docs/animations.md)

---

# AeroShards

> Faceted shards flow through a curved stream in layers of depth.

Hold the pointer to gather the stream, then release to unfurl it.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/AeroShards` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/AeroShards/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-aero-shards--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { AeroShards } from '@gaudi/design-system/animations/AeroShards';
```

## Usage

```jsx
import { AeroShards } from '@gaudi/design-system/animations/AeroShards';

<AeroShards height={500} paused={paused} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-aero-shards--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, hidden tabs and offscreen containers also stop animation. |
| `speed` | `number` | `1` | no | Playback multiplier from 0 to 5. Zero freezes time. |
| `intensity` | `number` | `1` | no | Visibility of the shards, clamped to 0–2. Zero shows only the background color. |
| `scale` | `number` | `1` | no | Spatial scale from 0.25 to 4. Larger values produce larger details. |
| `colors` | `string[]` | `Gaudi theme colors` | no | Up to three CSS colors. Omit to follow the current Gaudi theme. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect, also used by the static fallback. |
| `interactive` | `boolean` | `true` | no | The pointer repels nearby shards. Press and hold to gather a rotating cloud; release to unfurl. Input stops while paused. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Accessible foreground content layered above the decorative canvas. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer div. Standard DOM attributes and handlers are forwarded. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Foreground children remain readable and interactive. Provide a pause control for continuous motion, and place text on a contrasting surface. Reduced motion displays a still frame; unavailable WebGL uses a static color fallback.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Shard size varies with depth. Hold/release changes the stream envelope without resetting its retained phase.
- Visual idea inspired by AeroShards from React Bits. Independently implemented for Gaudi from the rendered visual reference; no React Bits source code, shaders or assets are included.

## Related

- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.

Source: https://design.gaudi.site/docs/animations/aero-shards (Markdown with example code: https://design.gaudi.site/docs/animations/aero-shards.md)

---

# Aurora

> Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/layout/Borealis` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/Borealis/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/layout-borealis--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Aurora from '@gaudi/design-system/layout/Borealis';
```

## Usage

```jsx
import Borealis from '@gaudi/design-system/animations/Borealis';

<Borealis variant="soft" height={500}>{content}</Borealis>
```

## Examples

Examples (rendered from Storybook):

- [Aurora](https://storybook.gaudi.site/index.html?path=/story/layout-components--borealis-surface)
- [Soft Aurora](https://storybook.gaudi.site/index.html?path=/story/layout-borealis--soft-aurora)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `variant` | `"aurora" \| "soft"` | `aurora` | no | Top-lit curtains or a soft horizontal ribbon. Unknown values fall back to aurora. |
| `amplitude` | `number` | `1` | no | Height variation of the light, clamped to 0–2. |
| `blend` | `number` | `0.5` | no | Softness of the glow, clamped to 0–1. |
| `fadeEdges` | `boolean` | `true` | no | Fade the decorative layer into the page at its lower edge. |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, offscreen containers and hidden tabs also stop animation. |
| `speed` | `number` | `1` | no | Animation speed multiplier, clamped to 0–5. Zero holds a static frame. |
| `intensity` | `number` | `1` | no | Effect strength, clamped to 0–2. Zero reveals the background color. |
| `scale` | `number` | `1` | no | Spatial scale of the effect, clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi theme tokens` | no | Up to three CSS colors. Omitted colors inherit the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect and its static fallback. |
| `height` | `number \| string` | `content / viewport` | no | Optional fixed height in pixels or CSS length. Without it, the existing page wrapper grows with content and fills at least the viewport; decoration is capped at 48rem. |
| `children` | `ReactNode` | — | no | Optional semantic content layered above the decorative canvas. |
| `className / style / ref / DOM props` (pass-through) | `DOM props` | — | no | Forwarded to the outer container. |

### Variants

- `variant`: `aurora`, `soft`

## Accessibility

The canvas is decorative and hidden from assistive technology. Keep important content in children and provide a pause control for continuous animation. Reduced motion renders a static frame; unsupported WebGL retains the styled container and content.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Borealis remains the public component name. Existing layout imports, direct children, outer ref, and page layout are preserved. Soft Aurora is selected with variant="soft".
- Visual ideas inspired by React Bits Aurora and Soft Aurora (MIT + Commons Clause). Independently authored for Gaudi; no upstream source, shaders or assets are included.

## Related

- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.
- [FloatingLines](https://design.gaudi.site/docs/animations/floating-lines): Three layered families of glowing lines cross the surface and bend around the pointer.

Source: https://design.gaudi.site/docs/animations/aurora (Markdown with example code: https://design.gaudi.site/docs/animations/aurora.md)

---

# CRTWarp

> Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/CRTWarp` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/CRTWarp/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-crt-warp--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { CRTWarp } from '@gaudi/design-system/animations/CRTWarp';
```

## Usage

```jsx
import { CRTWarp } from '@gaudi/design-system/animations/CRTWarp';

<CRTWarp height={360} paused={false} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-crt-warp--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, offscreen containers and hidden tabs also stop animation. |
| `speed` | `number` | `1` | no | Animation speed multiplier, clamped to 0–5. Zero holds a static frame. |
| `intensity` | `number` | `1` | no | Effect strength, clamped to 0–2. Zero reveals the background color. |
| `scale` | `number` | `1` | no | Spatial scale of the effect, clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi theme tokens` | no | Up to three CSS colors. Omitted colors inherit the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect and its static fallback. |
| `interactive` | `boolean` | `false` | no | Let pointer position influence the effect without capturing clicks or scrolling. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Optional semantic content layered above the decorative canvas. |
| `className / style / ref / DOM props` (pass-through) | `DOM props` | — | no | Forwarded to the outer container. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Keep important content in children and provide a pause control for continuous animation. Reduced motion renders a static frame; unsupported WebGL retains the styled container and content.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- The plasma signal has stepped contours and separated phosphor channels. Coarse signal cells keep their size in CSS pixels while fine scanlines and grain retain the analog texture.
- Visual idea inspired by CRT Warp from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits source, shaders or assets are included.

## Related

- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.
- [FloatingLines](https://design.gaudi.site/docs/animations/floating-lines): Three layered families of glowing lines cross the surface and bend around the pointer.

Source: https://design.gaudi.site/docs/animations/crt-warp (Markdown with example code: https://design.gaudi.site/docs/animations/crt-warp.md)

---

# DarkVeil

> Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/DarkVeil` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/DarkVeil/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-dark-veil--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { DarkVeil } from '@gaudi/design-system/animations/DarkVeil';
```

## Usage

```jsx
import { DarkVeil } from '@gaudi/design-system/animations/DarkVeil';

<DarkVeil height={360} paused />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-dark-veil--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, hidden tabs and offscreen surfaces also stop motion. |
| `speed` | `number` | `1` | no | Motion multiplier, clamped to 0–5. Zero keeps the current frame still. |
| `intensity` | `number` | `1` | no | Strength of the effect, clamped to 0–2. Zero shows only the background color. |
| `scale` | `number` | `1` | no | Scale changes the breadth of the folded sheets. When interactive, pointer movement gently offsets the folds. Clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi chart colors 1–3` | no | Up to three CSS colors, including CSS variables. Omitted colors use the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | Base CSS color beneath the effect. Follows the current theme by default. |
| `interactive` | `boolean` | `false` | no | Let pointer movement influence the decorative effect. No interaction is needed to use the content. |
| `height` | `number \| string` | `360` | no | Surface height in pixels or a CSS length. Numeric values are clamped to 1–4096. |
| `children` | `ReactNode` | — | no | Optional content rendered above the decorative canvas. Keep text and controls on a contrasting surface. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer div along with other DOM props and pointer handlers. |

## Accessibility

The canvas is decorative and hidden from assistive technology; children remain accessible. Reduced motion shows a still frame, and unavailable graphics use a static color fallback. Provide a visible pause control when motion continues beside meaningful content. Keep text contrast independent of the moving artwork.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Smooth, asymmetric sheets gather light along their creases and remain dark on the opposite side.
- Visual idea inspired by Dark Veil from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits code or assets are included.

## Related

- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.
- [FloatingLines](https://design.gaudi.site/docs/animations/floating-lines): Three layered families of glowing lines cross the surface and bend around the pointer.

Source: https://design.gaudi.site/docs/animations/dark-veil (Markdown with example code: https://design.gaudi.site/docs/animations/dark-veil.md)

---

# Dither

> Flowing waves rendered with ordered dithering and a limited tonal palette.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/Dither` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/Dither/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-dither--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Dither } from '@gaudi/design-system/animations/Dither';
```

## Usage

```jsx
import { Dither } from '@gaudi/design-system/animations/Dither';

<Dither height={500} paused={false} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-dither--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `pixelSize` | `number` | `2` | no | Dither pixel size in CSS pixels, clamped to 1–8. |
| `levels` | `number` | `3` | no | Number of tonal levels, rounded and clamped to 2–8. |
| `amplitude` | `number` | `1` | no | Wave displacement, clamped to 0–2. |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, offscreen containers and hidden tabs also stop animation. |
| `speed` | `number` | `1` | no | Animation speed multiplier, clamped to 0–5. Zero holds a static frame. |
| `intensity` | `number` | `1` | no | Effect strength, clamped to 0–2. Zero reveals the background color. |
| `scale` | `number` | `1` | no | Spatial scale of the effect, clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi theme tokens` | no | The first CSS color supplies the tint; omitted colors inherit Gaudi theme tokens. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect and its static fallback. |
| `interactive` | `boolean` | `true` | no | Let pointer position influence the effect without capturing clicks or scrolling. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Optional semantic content layered above the decorative canvas. |
| `className / style / ref / DOM props` (pass-through) | `DOM props` | — | no | Forwarded to the outer container. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Keep important content in children and provide a pause control for continuous animation. Reduced motion renders a static frame; unsupported WebGL retains the styled container and content.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- An 8×8 ordered threshold pattern quantizes a continuous wave field. The first colors entry supplies its tint; background supplies the other end of the tonal range. Pointer movement reveals a brighter local region.
- Visual idea inspired by Dither from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits source, shaders or assets are included.

## Related

- [Pointer](https://design.gaudi.site/docs/components/pointer): A pointer effect scoped to its container, with direct, spring and lazy tracking, hover feedback, and native input fallbacks.
- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.

Source: https://design.gaudi.site/docs/animations/dither (Markdown with example code: https://design.gaudi.site/docs/animations/dither.md)

---

# FaultyTerminal

> A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/FaultyTerminal` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/FaultyTerminal/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-faulty-terminal--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { FaultyTerminal } from '@gaudi/design-system/animations/FaultyTerminal';
```

## Usage

```jsx
import { FaultyTerminal } from '@gaudi/design-system/animations/FaultyTerminal';

<FaultyTerminal height={500} paused={false} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-faulty-terminal--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `digitSize` | `number` | `1` | no | Glyph cell size multiplier, clamped to 0.5–3. |
| `curvature` | `number` | `0.1` | no | CRT curvature, clamped to 0–1. |
| `scanlines` | `number` | `0.5` | no | Scanline contrast, clamped to 0–1. |
| `glitch` | `number` | `1` | no | Intermittent horizontal displacement, clamped to 0–2. |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, offscreen containers and hidden tabs also stop animation. |
| `speed` | `number` | `1` | no | Animation speed multiplier, clamped to 0–5. Zero holds a static frame. |
| `intensity` | `number` | `1` | no | Effect strength, clamped to 0–2. Zero reveals the background color. |
| `scale` | `number` | `1` | no | Spatial scale of the effect, clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi theme tokens` | no | The first CSS color supplies the tint; omitted colors inherit Gaudi theme tokens. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect and its static fallback. |
| `interactive` | `boolean` | `true` | no | Let pointer position influence the effect without capturing clicks or scrolling. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Optional semantic content layered above the decorative canvas. |
| `className / style / ref / DOM props` (pass-through) | `DOM props` | — | no | Forwarded to the outer container. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Keep important content in children and provide a pause control for continuous animation. Reduced motion renders a static frame; unsupported WebGL retains the styled container and content.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Procedural squares, crosses and diamonds change with a moving field. The first colors entry supplies the phosphor tint. Pointer proximity brightens local glyphs; the canvas is decorative, not a terminal emulator.
- Visual idea inspired by FaultyTerminal from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits source, shaders or assets are included.

## Related

- [Pointer](https://design.gaudi.site/docs/components/pointer): A pointer effect scoped to its container, with direct, spring and lazy tracking, hover feedback, and native input fallbacks.
- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.

Source: https://design.gaudi.site/docs/animations/faulty-terminal (Markdown with example code: https://design.gaudi.site/docs/animations/faulty-terminal.md)

---

# FloatingLines

> Three layered families of glowing lines cross the surface and bend around the pointer.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/FloatingLines` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/FloatingLines/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-floating-lines--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { FloatingLines } from '@gaudi/design-system/animations/FloatingLines';
```

## Usage

```jsx
import { FloatingLines } from '@gaudi/design-system/animations/FloatingLines';

<FloatingLines height={360} paused />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-floating-lines--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, hidden tabs and offscreen surfaces also stop motion. |
| `speed` | `number` | `1` | no | Motion multiplier, clamped to 0–5. Zero keeps the current frame still. |
| `intensity` | `number` | `1` | no | Strength of the effect, clamped to 0–2. Zero shows only the background color. |
| `scale` | `number` | `1` | no | Scale changes the sweep of the curves and the pointer lens. Clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi chart colors 1–3` | no | Up to three CSS colors, including CSS variables. Omitted colors use the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | Base CSS color beneath the effect. Follows the current theme by default. |
| `interactive` | `boolean` | `true` | no | Bend nearby line families around the pointer, with a smooth return on leave. No interaction is needed to use the content. |
| `height` | `number \| string` | `360` | no | Surface height in pixels or a CSS length. Numeric values are clamped to 1–4096. |
| `children` | `ReactNode` | — | no | Optional content rendered above the decorative canvas. Keep text and controls on a contrasting surface. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer div along with other DOM props and pointer handlers. |

## Accessibility

The canvas is decorative and hidden from assistive technology; children remain accessible. Reduced motion shows a still frame, and unavailable graphics use a static color fallback. Provide a visible pause control when motion continues beside meaningful content. Keep text contrast independent of the moving artwork.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Eight curves in each family converge and separate at different angles and brightnesses. The local pointer lens relaxes smoothly after the pointer leaves.
- Visual idea inspired by Floating Lines from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits code or assets are included.

## Related

- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.

Source: https://design.gaudi.site/docs/animations/floating-lines (Markdown with example code: https://design.gaudi.site/docs/animations/floating-lines.md)

---

# GradientWaves

> Broad, softly lit swells roll toward a hazy horizon, with atmospheric depth and subtle pointer parallax.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/GradientWaves` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/GradientWaves/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-gradient-waves--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { GradientWaves } from '@gaudi/design-system/animations/GradientWaves';
```

## Usage

```jsx
import { GradientWaves } from '@gaudi/design-system/animations/GradientWaves';

<GradientWaves height={360} paused={false} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-gradient-waves--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, offscreen containers and hidden tabs also stop animation. |
| `speed` | `number` | `1` | no | Animation speed multiplier, clamped to 0–5. Zero holds a static frame. |
| `intensity` | `number` | `1` | no | Effect strength, clamped to 0–2. Zero reveals the background color. |
| `scale` | `number` | `1` | no | Spatial scale of the effect, clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi theme tokens` | no | Up to three CSS colors. Omitted colors inherit the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect and its static fallback. |
| `interactive` | `boolean` | `false` | no | Let pointer position influence the effect without capturing clicks or scrolling. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Optional semantic content layered above the decorative canvas. |
| `className / style / ref / DOM props` (pass-through) | `DOM props` | — | no | Forwarded to the outer container. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Keep important content in children and provide a pause control for continuous animation. Reduced motion renders a static frame; unsupported WebGL retains the styled container and content.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- The shader traces a continuous height field with broad foreground swells. Surface lighting and distance haze soften receding crests; pointer movement subtly shifts the viewpoint.
- Visual idea inspired by Gradient Waves from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits source, shaders or assets are included.

## Related

- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.

Source: https://design.gaudi.site/docs/animations/gradient-waves (Markdown with example code: https://design.gaudi.site/docs/animations/gradient-waves.md)

---

# Grainient

> A slowly warped three-color gradient with fine animated grain.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/Grainient` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/Grainient/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-grainient--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Grainient } from '@gaudi/design-system/animations/Grainient';
```

## Usage

```jsx
import { Grainient } from '@gaudi/design-system/animations/Grainient';

<Grainient height={500} paused={false} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-grainient--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `grain` | `number` | `0.3` | no | Grain strength, clamped to 0–1. |
| `warp` | `number` | `1` | no | Gradient distortion, clamped to 0–3. |
| `contrast` | `number` | `1.2` | no | Gradient contrast, clamped to 0.25–3. |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, offscreen containers and hidden tabs also stop animation. |
| `speed` | `number` | `1` | no | Animation speed multiplier, clamped to 0–5. Zero holds a static frame. |
| `intensity` | `number` | `1` | no | Blend strength, clamped to 0–2 and visually saturated at 1. Zero reveals the background color. |
| `scale` | `number` | `1` | no | Spatial scale of the effect, clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi theme tokens` | no | Up to three CSS colors. Omitted colors inherit the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect and its static fallback. |
| `interactive` | `boolean` | `false` | no | Let pointer position influence the effect without capturing clicks or scrolling. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Optional semantic content layered above the decorative canvas. |
| `className / style / ref / DOM props` (pass-through) | `DOM props` | — | no | Forwarded to the outer container. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Keep important content in children and provide a pause control for continuous animation. Reduced motion renders a static frame; unsupported WebGL retains the styled container and content.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Three continuous color fields blend across the whole container. Grain follows CSS pixels and freezes with the gradient.
- Visual idea inspired by Grainient from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits source, shaders or assets are included.

## Related

- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.

Source: https://design.gaudi.site/docs/animations/grainient (Markdown with example code: https://design.gaudi.site/docs/animations/grainient.md)

---

# GridScan

> A perspective grid corridor illuminated by a traveling scan pulse.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/GridScan` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/GridScan/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-grid-scan--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { GridScan } from '@gaudi/design-system/animations/GridScan';
```

## Usage

```jsx
import { GridScan } from '@gaudi/design-system/animations/GridScan';

<GridScan height={500} paused={false} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-grid-scan--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `lineWidth` | `number` | `1` | no | Grid line thickness, clamped to 0.25–3. |
| `scanWidth` | `number` | `1.4` | no | Depth of the scan band, clamped to 0.2–5. |
| `scanGlow` | `number` | `1` | no | Scan brightness, clamped to 0–2. |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, offscreen containers and hidden tabs also stop animation. |
| `speed` | `number` | `1` | no | Animation speed multiplier, clamped to 0–5. Zero holds a static frame. |
| `intensity` | `number` | `1` | no | Effect strength, clamped to 0–2. Zero reveals the background color. |
| `scale` | `number` | `1` | no | Spatial scale of the effect, clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi theme tokens` | no | First CSS color for the lines, second for the scan; omitted colors inherit Gaudi theme tokens. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect and its static fallback. |
| `interactive` | `boolean` | `true` | no | Let pointer position influence the effect without capturing clicks or scrolling. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Optional semantic content layered above the decorative canvas. |
| `className / style / ref / DOM props` (pass-through) | `DOM props` | — | no | Forwarded to the outer container. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Keep important content in children and provide a pause control for continuous animation. Reduced motion renders a static frame; unsupported WebGL retains the styled container and content.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Four gridded planes converge into a tunnel. The scan pulse travels through its depth; pointer movement changes the vanishing point. Colors use the first entry for grid lines and the second for the scan.
- Visual idea inspired by GridScan from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits source, shaders or assets are included.

## Related

- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.

Source: https://design.gaudi.site/docs/animations/grid-scan (Markdown with example code: https://design.gaudi.site/docs/animations/grid-scan.md)

---

# Hyperspeed

> Paired light trails travel along a curving road and accelerate while the background is held.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/Hyperspeed` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/Hyperspeed/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-hyperspeed--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Hyperspeed } from '@gaudi/design-system/animations/Hyperspeed';
```

## Usage

```jsx
import { Hyperspeed } from '@gaudi/design-system/animations/Hyperspeed';

<Hyperspeed height={500} paused={false} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-hyperspeed--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `curvature` | `number` | `1` | no | Road bend strength, clamped to 0–2. |
| `trailLength` | `number` | `1.5` | no | Light trail length, clamped to 0.25–4. |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, offscreen containers and hidden tabs also stop animation. |
| `speed` | `number` | `1` | no | Animation speed multiplier, clamped to 0–5. Zero holds a static frame. |
| `intensity` | `number` | `1` | no | Effect strength, clamped to 0–2. Zero reveals the background color. |
| `scale` | `number` | `1` | no | Spatial scale of the effect, clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi theme tokens` | no | Up to three CSS colors. Omitted colors inherit the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect and its static fallback. |
| `interactive` | `boolean` | `true` | no | Let pointer position influence the effect without capturing clicks or scrolling. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Optional semantic content layered above the decorative canvas. |
| `className / style / ref / DOM props` (pass-through) | `DOM props` | — | no | Forwarded to the outer container. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Keep important content in children and provide a pause control for continuous animation. Reduced motion renders a static frame; unsupported WebGL retains the styled container and content.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Two opposing streams of paired lights follow a perspective road. Hold a non-interactive part of the background to accelerate smoothly; releasing slows it down without jumping its position. Use speed for a keyboard-accessible or controlled alternative.
- Visual idea inspired by Hyperspeed from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits source, shaders or assets are included.

## Related

- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.

Source: https://design.gaudi.site/docs/animations/hyperspeed (Markdown with example code: https://design.gaudi.site/docs/animations/hyperspeed.md)

---

# LightPillar

> Irregular luminous ribbons flow through a broad diagonal column with bright cores and soft bloom.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/LightPillar` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/LightPillar/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-light-pillar--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { LightPillar } from '@gaudi/design-system/animations/LightPillar';
```

## Usage

```jsx
import { LightPillar } from '@gaudi/design-system/animations/LightPillar';

<LightPillar height={360} paused />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-light-pillar--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, hidden tabs and offscreen surfaces also stop motion. |
| `speed` | `number` | `1` | no | Motion multiplier, clamped to 0–5. Zero keeps the current frame still. |
| `intensity` | `number` | `1` | no | Strength of the effect, clamped to 0–2. Zero shows only the background color. |
| `scale` | `number` | `1` | no | Scale changes the column width. When interactive, pointer movement moves the column sideways. Clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi chart colors 1–3` | no | Up to three CSS colors, including CSS variables. Omitted colors use the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | Base CSS color beneath the effect. Follows the current theme by default. |
| `interactive` | `boolean` | `false` | no | Let pointer movement influence the decorative effect. No interaction is needed to use the content. |
| `height` | `number \| string` | `360` | no | Surface height in pixels or a CSS length. Numeric values are clamped to 1–4096. |
| `children` | `ReactNode` | — | no | Optional content rendered above the decorative canvas. Keep text and controls on a contrasting surface. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer div along with other DOM props and pointer handlers. |

## Accessibility

The canvas is decorative and hidden from assistive technology; children remain accessible. Reduced motion shows a still frame, and unavailable graphics use a static color fallback. Provide a visible pause control when motion continues beside meaningful content. Keep text contrast independent of the moving artwork.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- The ribbons continually change shape; their uneven highlights merge into the surrounding glow.
- Visual idea inspired by Light Pillar from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits code or assets are included.

## Related

- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.

Source: https://design.gaudi.site/docs/animations/light-pillar (Markdown with example code: https://design.gaudi.site/docs/animations/light-pillar.md)

---

# LightRays

> Soft overhead shafts overlap in an atmospheric cone and dissolve before reaching the lower surface.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/LightRays` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/LightRays/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-light-rays--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { LightRays } from '@gaudi/design-system/animations/LightRays';
```

## Usage

```jsx
import { LightRays } from '@gaudi/design-system/animations/LightRays';

<LightRays height={360} paused />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-light-rays--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, hidden tabs and offscreen surfaces also stop motion. |
| `speed` | `number` | `1` | no | Motion multiplier, clamped to 0–5. Zero keeps the current frame still. |
| `intensity` | `number` | `1` | no | Strength of the effect, clamped to 0–2. Zero shows only the background color. |
| `scale` | `number` | `1` | no | Scale changes the spread and reach of the shafts. Clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi chart colors 1–3` | no | Up to three CSS colors, including CSS variables. Omitted colors use the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | Base CSS color beneath the effect. Follows the current theme by default. |
| `interactive` | `boolean` | `true` | no | Steer the overhead shafts subtly with the pointer. No interaction is needed to use the content. |
| `height` | `number \| string` | `360` | no | Surface height in pixels or a CSS length. Numeric values are clamped to 1–4096. |
| `children` | `ReactNode` | — | no | Optional content rendered above the decorative canvas. Keep text and controls on a contrasting surface. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer div along with other DOM props and pointer handlers. |

## Accessibility

The canvas is decorative and hidden from assistive technology; children remain accessible. Reduced motion shows a still frame, and unavailable graphics use a static color fallback. Provide a visible pause control when motion continues beside meaningful content. Keep text contrast independent of the moving artwork.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Pointer movement subtly steers the light direction. The source remains overhead, and the response relaxes on leave.
- Visual idea inspired by Light Rays from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits code or assets are included.

## Related

- [Pointer](https://design.gaudi.site/docs/components/pointer): A pointer effect scoped to its container, with direct, spring and lazy tracking, hover feedback, and native input fallbacks.
- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.

Source: https://design.gaudi.site/docs/animations/light-rays (Markdown with example code: https://design.gaudi.site/docs/animations/light-rays.md)

---

# LiquidEther

> Colored dye follows pointer movement, curls through a retained velocity field, and gradually dissipates.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/LiquidEther` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/LiquidEther/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-liquid-ether--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { LiquidEther } from '@gaudi/design-system/animations/LiquidEther';
```

## Usage

```jsx
import { LiquidEther } from '@gaudi/design-system/animations/LiquidEther';

<LiquidEther height={360} paused={false} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-liquid-ether--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, offscreen containers and hidden tabs also stop animation. |
| `speed` | `number` | `1` | no | Animation speed multiplier, clamped to 0–5. Zero holds a static frame. |
| `intensity` | `number` | `1` | no | Effect strength, clamped to 0–2. Zero reveals the background color. |
| `scale` | `number` | `1` | no | Spatial scale of the effect, clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi theme tokens` | no | Up to three CSS colors. Omitted colors inherit the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect and its static fallback. |
| `interactive` | `boolean` | `true` | no | Inject persistent dye and momentum along pointer movement. Holding the pointer adds more dye while moving; clicks and scrolling remain available to content. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Optional semantic content layered above the decorative canvas. |
| `className / style / ref / DOM props` (pass-through) | `DOM props` | — | no | Forwarded to the outer container. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Keep important content in children and provide a pause control for continuous animation. Reduced motion renders a static frame; unsupported WebGL retains the styled container and content.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- A bounded velocity and dye simulation retains, transports, and dissipates each plume. Pointer movement adds dye and momentum; an autonomous drifting source runs when the pointer is absent. Pausing and zero-delta redraws preserve the field, and a seeded plume provides a deterministic reduced-motion still.
- Visual idea inspired by Liquid Ether from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits source, shaders or assets are included.

## Related

- [Pointer](https://design.gaudi.site/docs/components/pointer): A pointer effect scoped to its container, with direct, spring and lazy tracking, hover feedback, and native input fallbacks.
- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.

Source: https://design.gaudi.site/docs/animations/liquid-ether (Markdown with example code: https://design.gaudi.site/docs/animations/liquid-ether.md)

---

# MicroSlats

> Rounded 10×25px slats catch broad rolling swells, crest glints and a fading pointer wake.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/MicroSlats` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/MicroSlats/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-micro-slats--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { MicroSlats } from '@gaudi/design-system/animations/MicroSlats';
```

## Usage

```jsx
import { MicroSlats } from '@gaudi/design-system/animations/MicroSlats';

<MicroSlats height={500} paused={paused} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-micro-slats--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, hidden tabs and offscreen containers also stop animation. |
| `speed` | `number` | `0.6` | no | Playback multiplier from 0 to 5. Zero freezes time. |
| `intensity` | `number` | `1` | no | Brightness of the slats, clamped to 0–2. Zero shows only the background color. |
| `scale` | `number` | `1` | no | Spatial scale from 0.25 to 4. Larger values produce larger details. |
| `colors` | `string[]` | `Gaudi theme colors` | no | Up to three CSS colors. Omit to follow the current Gaudi theme. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect, also used by the static fallback. |
| `interactive` | `boolean` | `true` | no | Moving the pointer leaves fading light; clicking sends a spreading ripple. Input stops while motion is paused. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Accessible foreground content layered above the decorative canvas. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer div. Standard DOM attributes and handlers are forwarded. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Foreground children remain readable and interactive. Provide a pause control for continuous motion, and place text on a contrasting surface. Reduced motion displays a still frame; unavailable WebGL uses a static color fallback.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Scale changes slat dimensions; slat height stays fixed through each swell.
- Visual idea inspired by MicroSlats from React Bits. Independently implemented for Gaudi from the rendered visual reference; no React Bits source code, shaders or assets are included.

## Related

- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.

Source: https://design.gaudi.site/docs/animations/micro-slats (Markdown with example code: https://design.gaudi.site/docs/animations/micro-slats.md)

---

# Particle Sea

> A rolling sea of fine points seen in perspective; crests catch the light and glitter.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/ParticleSea` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/ParticleSea/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-particle-sea--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ParticleSea } from '@gaudi/design-system/animations/ParticleSea';
```

## Usage

```jsx
import { ParticleSea } from '@gaudi/design-system/animations/ParticleSea';

<ParticleSea height={500} waveHeight={1.2} colors={['var(--ds-color-warning)']} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-particle-sea--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `waveHeight` | `number` | `1` | no | Swell height, clamped to 0–2. Higher seas light more crests. |
| `density` | `number` | `1` | no | Points per unit of water, clamped to 0.25–2. |
| `horizon` | `number` | `0.75` | no | Horizon position from the bottom of the container, clamped to 0.3–1. The area above it shows the background. |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, offscreen containers and hidden tabs also stop animation. |
| `speed` | `number` | `1` | no | Animation speed multiplier, clamped to 0–5. Zero holds a static frame. |
| `intensity` | `number` | `1` | no | Brightness of the lit points, clamped to 0–2. Zero reveals the background color. |
| `scale` | `number` | `1` | no | Spatial scale of the sea, clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi theme tokens` | no | Up to three CSS colors for the points. Omitted colors inherit the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect and its static fallback. |
| `interactive` | `boolean` | `false` | no | Lift the sea under the pointer without capturing clicks or scrolling. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Optional semantic content layered above the decorative canvas. |
| `className / style / ref / DOM props` (pass-through) | `DOM props` | — | no | Forwarded to the outer container. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Keep important content in children and provide a pause control for continuous animation. Reduced motion renders a static frame; unsupported WebGL retains the styled container and content.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Points are spaced evenly across the water, so they shrink and crowd towards the horizon. Only crests are lit, and each point twinkles on its own phase. Points too small to resolve fade out instead of shimmering.

## Related

- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.

Source: https://design.gaudi.site/docs/animations/particle-sea (Markdown with example code: https://design.gaudi.site/docs/animations/particle-sea.md)

---

# PatternWaves

> A nine-pixel dot lattice shades folded fabric with narrow illuminated creases and localized ripples.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/PatternWaves` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/PatternWaves/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-pattern-waves--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { PatternWaves } from '@gaudi/design-system/animations/PatternWaves';
```

## Usage

```jsx
import { PatternWaves } from '@gaudi/design-system/animations/PatternWaves';

<PatternWaves height={500} paused={paused} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-pattern-waves--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, hidden tabs and offscreen containers also stop animation. |
| `speed` | `number` | `0.35` | no | Playback multiplier from 0 to 5. Zero freezes time. |
| `intensity` | `number` | `1` | no | Surface deformation and ink strength, clamped to 0–2. Zero shows only the background color. |
| `scale` | `number` | `1` | no | Spatial scale from 0.25 to 4. Larger values produce larger details. |
| `colors` | `string[]` | `Gaudi theme colors` | no | Up to three CSS colors. Omit to follow the current Gaudi theme. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect, also used by the static fallback. |
| `interactive` | `boolean` | `true` | no | Moving the pointer leaves fading light; clicking sends a spreading ripple. Input stops while motion is paused. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Accessible foreground content layered above the decorative canvas. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer div. Standard DOM attributes and handlers are forwarded. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Foreground children remain readable and interactive. Provide a pause control for continuous motion, and place text on a contrasting surface. Reduced motion displays a still frame; unavailable WebGL uses a static color fallback.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Scale changes the CSS-pixel spacing of the dots; light and shadow describe the fabric folds.
- Visual idea inspired by PatternWaves from React Bits. Independently implemented for Gaudi from the rendered visual reference; no React Bits source code, shaders or assets are included.

## Related

- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.

Source: https://design.gaudi.site/docs/animations/pattern-waves (Markdown with example code: https://design.gaudi.site/docs/animations/pattern-waves.md)

---

# PixelBlast

> Separate square pixels form drifting dithered patterns; clicks send circular waves through the field.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/PixelBlast` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/PixelBlast/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-pixel-blast--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { PixelBlast } from '@gaudi/design-system/animations/PixelBlast';
```

## Usage

```jsx
import { PixelBlast } from '@gaudi/design-system/animations/PixelBlast';

<PixelBlast height={360} paused />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-pixel-blast--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, hidden tabs and offscreen surfaces also stop motion. |
| `speed` | `number` | `1` | no | Motion multiplier, clamped to 0–5. Zero keeps the current frame still. |
| `intensity` | `number` | `1` | no | Strength of the effect, clamped to 0–2. Zero shows only the background color. |
| `scale` | `number` | `1` | no | Scale changes the square size and spacing in CSS pixels, independent of device pixel ratio. Clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi chart colors 1–3` | no | Up to three CSS colors, including CSS variables. Omitted colors use the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | Base CSS color beneath the effect. Follows the current theme by default. |
| `interactive` | `boolean` | `true` | no | Create an outward-decaying ripple at each click or tap. No interaction is needed to use the content. |
| `height` | `number \| string` | `360` | no | Surface height in pixels or a CSS length. Numeric values are clamped to 1–4096. |
| `children` | `ReactNode` | — | no | Optional content rendered above the decorative canvas. Keep text and controls on a contrasting surface. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer div along with other DOM props and pointer handlers. |

## Accessibility

The canvas is decorative and hidden from assistive technology; children remain accessible. Reduced motion shows a still frame, and unavailable graphics use a static color fallback. Provide a visible pause control when motion continues beside meaningful content. Keep text contrast independent of the moving artwork.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Squares keep the same size as density changes. A click creates an outward-moving wave that fades; paused and reduced-motion surfaces do not respond.
- Visual idea inspired by Pixel Blast from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits code or assets are included.

## Related

- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.

Source: https://design.gaudi.site/docs/animations/pixel-blast (Markdown with example code: https://design.gaudi.site/docs/animations/pixel-blast.md)

---

# Plasma

> Translucent plasma folds flow across the surface, with soft illuminated edges.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/Plasma` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/Plasma/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-plasma--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Plasma } from '@gaudi/design-system/animations/Plasma';
```

## Usage

```jsx
import { Plasma } from '@gaudi/design-system/animations/Plasma';

<Plasma height={500} paused={false} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-plasma--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `direction` | `"forward" \| "reverse"` | `forward` | no | Direction of the flowing folds. |
| `turbulence` | `number` | `1` | no | Fold distortion, clamped to 0–2. |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, offscreen containers and hidden tabs also stop animation. |
| `speed` | `number` | `1` | no | Animation speed multiplier, clamped to 0–5. Zero holds a static frame. |
| `intensity` | `number` | `1` | no | Effect strength, clamped to 0–2. Zero reveals the background color. |
| `scale` | `number` | `1` | no | Spatial scale of the effect, clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi theme tokens` | no | Up to three CSS colors. Omitted colors inherit the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect and its static fallback. |
| `interactive` | `boolean` | `false` | no | Let pointer position influence the effect without capturing clicks or scrolling. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Optional semantic content layered above the decorative canvas. |
| `className / style / ref / DOM props` (pass-through) | `DOM props` | — | no | Forwarded to the outer container. |

### Variants

- `direction`: `forward`, `reverse`

## Accessibility

The canvas is decorative and hidden from assistive technology. Keep important content in children and provide a pause control for continuous animation. Reduced motion renders a static frame; unsupported WebGL retains the styled container and content.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- The flowing field uses broad folds with narrow illuminated rims. Pointer interaction adds subtle parallax.
- Visual idea inspired by Plasma from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits source, shaders or assets are included.

## Related

- [Pointer](https://design.gaudi.site/docs/components/pointer): A pointer effect scoped to its container, with direct, spring and lazy tracking, hover feedback, and native input fallbacks.
- [Direction](https://design.gaudi.site/docs/components/direction): Scopes text direction for Gaudi controls that need directional keyboard and placement behavior.
- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.

Source: https://design.gaudi.site/docs/animations/plasma (Markdown with example code: https://design.gaudi.site/docs/animations/plasma.md)

---

# ShapeWaves

> Ten-pixel cells cycle through triangle, circle and square bands, with optional text carved out of the field.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/ShapeWaves` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/ShapeWaves/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-shape-waves--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { ShapeWaves } from '@gaudi/design-system/animations/ShapeWaves';
```

## Usage

```jsx
import { ShapeWaves } from '@gaudi/design-system/animations/ShapeWaves';

<ShapeWaves height={500} paused={paused} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-shape-waves--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `text` | `string` | `''` | no | Optional text cut out of the decorative canvas and exposed once to assistive technology. Foreground children remain unmasked. |
| `textSize` | `number` | `0.6` | no | Cutout height relative to the surface, clamped to 0.1–1. Long text shrinks to fit. |
| `cellSize` | `number` | `10` | no | Grid pitch in CSS pixels, clamped to 4–40. |
| `dotSize` | `number` | `0.75` | no | Glyph size as a fraction of a cell, clamped to 0.1–0.95. |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, hidden tabs and offscreen containers also stop animation. |
| `speed` | `number` | `1` | no | Playback multiplier from 0 to 5. Zero freezes time. |
| `intensity` | `number` | `1` | no | Visibility of the geometric marks, clamped to 0–2. Zero shows only the background color. |
| `scale` | `number` | `1` | no | Spatial scale from 0.25 to 4. Larger values produce larger details. |
| `colors` | `string[]` | `Gaudi theme colors` | no | Up to three CSS colors. Omit to follow the current Gaudi theme. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect, also used by the static fallback. |
| `interactive` | `boolean` | `true` | no | Moving the pointer leaves fading light; clicking sends a spreading ripple. Input stops while motion is paused. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Accessible foreground content layered above the decorative canvas. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer div. Standard DOM attributes and handlers are forwarded. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Foreground children remain readable and interactive. Provide a pause control for continuous motion, and place text on a contrasting surface. Reduced motion displays a still frame; unavailable WebGL uses a static color fallback.

## Notes

- The text cutout is empty by default. Set the text control to add your own cutout.
- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Scale changes wave size while cellSize controls glyph density. Dark bands are triangles, middle bands circles and bright bands squares.
- Visual idea inspired by ShapeWaves from React Bits. Independently implemented for Gaudi from the rendered visual reference; no React Bits source code, shaders or assets are included.

## Related

- [Input](https://design.gaudi.site/docs/components/input): Text, search, numeric and date inputs with prefix and suffix slots.
- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.

Source: https://design.gaudi.site/docs/animations/shape-waves (Markdown with example code: https://design.gaudi.site/docs/animations/shape-waves.md)

---

# SideRays

> Broad, diffuse shafts cascade from the upper-right corner and fade rapidly into the surface.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/SideRays` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/SideRays/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-side-rays--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { SideRays } from '@gaudi/design-system/animations/SideRays';
```

## Usage

```jsx
import { SideRays } from '@gaudi/design-system/animations/SideRays';

<SideRays height={360} paused />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-side-rays--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, hidden tabs and offscreen surfaces also stop motion. |
| `speed` | `number` | `1` | no | Motion multiplier, clamped to 0–5. Zero keeps the current frame still. |
| `intensity` | `number` | `1` | no | Strength of the effect, clamped to 0–2. Zero shows only the background color. |
| `scale` | `number` | `1` | no | Scale changes ray width and reach. When interactive, pointer movement subtly shifts the corner source. Clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi chart colors 1–3` | no | Up to three CSS colors, including CSS variables. Omitted colors use the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | Base CSS color beneath the effect. Follows the current theme by default. |
| `interactive` | `boolean` | `false` | no | Let pointer movement influence the decorative effect. No interaction is needed to use the content. |
| `height` | `number \| string` | `360` | no | Surface height in pixels or a CSS length. Numeric values are clamped to 1–4096. |
| `children` | `ReactNode` | — | no | Optional content rendered above the decorative canvas. Keep text and controls on a contrasting surface. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer div along with other DOM props and pointer handlers. |

## Accessibility

The canvas is decorative and hidden from assistive technology; children remain accessible. Reduced motion shows a still frame, and unavailable graphics use a static color fallback. Provide a visible pause control when motion continues beside meaningful content. Keep text contrast independent of the moving artwork.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Four overlapping shafts vary softly in brightness while most of the surface remains quiet.
- Visual idea inspired by Side Rays from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits code or assets are included.

## Related

- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.

Source: https://design.gaudi.site/docs/animations/side-rays (Markdown with example code: https://design.gaudi.site/docs/animations/side-rays.md)

---

# WebThreads

> Six luminous strands fan outward from one bright central pinch, with soft glow around each thread.

- Category: Animations · Backgrounds
- Import: `@gaudi/design-system/animations/WebThreads` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/WebThreads/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-backgrounds-web-threads--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { WebThreads } from '@gaudi/design-system/animations/WebThreads';
```

## Usage

```jsx
import { WebThreads } from '@gaudi/design-system/animations/WebThreads';

<WebThreads height={360} paused={false} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-backgrounds-web-threads--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `paused` | `boolean` | `false` | no | Freeze the current frame. Reduced motion, offscreen containers and hidden tabs also stop animation. |
| `speed` | `number` | `1` | no | Animation speed multiplier, clamped to 0–5. Zero holds a static frame. |
| `intensity` | `number` | `1` | no | Effect strength, clamped to 0–2. Zero reveals the background color. |
| `scale` | `number` | `1` | no | Spatial scale of the effect, clamped to 0.25–4. |
| `colors` | `string[]` | `Gaudi theme tokens` | no | Up to three CSS colors. Omitted colors inherit the current Gaudi palette. |
| `background` | `string` | `var(--ds-color-surface)` | no | CSS color behind the effect and its static fallback. |
| `interactive` | `boolean` | `false` | no | Let pointer position influence the effect without capturing clicks or scrolling. |
| `height` | `number \| string` | `360` | no | Container height in pixels or a CSS length. Numeric values are clamped to 1–4096; width fills the available container. |
| `children` | `ReactNode` | — | no | Optional semantic content layered above the decorative canvas. |
| `className / style / ref / DOM props` (pass-through) | `DOM props` | — | no | Forwarded to the outer container. |

## Accessibility

The canvas is decorative and hidden from assistive technology. Keep important content in children and provide a pause control for continuous animation. Reduced motion renders a static frame; unsupported WebGL retains the styled container and content.

## Notes

- The playground layers a Gaudi header, hero and working documentation links above the effect. The Demo content switch hides only this foreground; canvas size, animation phase and pause state are retained.
- Six curves meet at one compact luminous knot and fan broadly toward the edges. Pointer movement adds a local light and a subtle horizontal drift; scale changes the curve frequency.
- Visual idea inspired by Web Threads from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits source, shaders or assets are included.

## Related

- [Pointer](https://design.gaudi.site/docs/components/pointer): A pointer effect scoped to its container, with direct, spring and lazy tracking, hover feedback, and native input fallbacks.
- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora): Theme-aware Aurora light curtains, with a Soft Aurora variant that forms a narrow glowing ribbon.
- [CRTWarp](https://design.gaudi.site/docs/animations/crt-warp): Coarse phosphor cells form evolving plasma shapes beneath fine scanlines, analog grain, and local pointer distortion.
- [DarkVeil](https://design.gaudi.site/docs/animations/dark-veil): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither): Flowing waves rendered with ordered dithering and a limited tonal palette.

Source: https://design.gaudi.site/docs/animations/web-threads (Markdown with example code: https://design.gaudi.site/docs/animations/web-threads.md)

---

# CipherReveal

> Scrambled characters resolve progressively into readable text on view, hover or focus.

- Category: Animations · Text
- Import: `@gaudi/design-system/animations/CipherReveal` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/CipherReveal/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-text-cipherreveal--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { CipherReveal } from '@gaudi/design-system/animations/CipherReveal';
```

## Usage

```jsx
import { CipherReveal } from '@gaudi/design-system/animations/CipherReveal';

<CipherReveal text="Gaudi" />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-text-cipherreveal--playground)
- [Reveal from the center](https://storybook.gaudi.site/index.html?path=/story/animations-text-cipherreveal--variant)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `text` | `string` | `"Ideas into interfaces"` | no | Text to display. Short phrases work best; long text can wrap. |
| `duration` | `number` | `1200` | no | Reveal duration in milliseconds, clamped to 100–10000. |
| `direction` | `start \| end \| center` | `"start"` | no | Order in which the original letters are revealed. |
| `trigger` | `view \| hover` | `"view"` | no | Begin on entering view, or wait for hover/focus. Hover and focus can replay either mode. |
| `characterSet` | `string` | `"ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"` | no | Glyphs used for the decorative character rendering. Empty input uses a safe fallback. |
| `paused` | `boolean` | `false` | no | Stop nonessential motion. System reduced motion, hidden tabs and offscreen containers also stop it. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer span. Typography is inherited. |

### Variants

- `direction`: `start`, `end`, `center`
- `trigger`: `view`, `hover`

## Accessibility

The complete text is exposed once; scrambled characters are hidden from assistive technology. Pausing or reduced motion reveals the complete text. The outer span has no tab stop by default; focus replay applies when it receives focus.

## Notes

- Visual idea inspired by [Decrypted Text](https://reactbits.dev/text-animations/decrypted-text) from [React Bits](https://reactbits.dev) (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits code or assets are included.

## Related

- [GlyphInspector](https://design.gaudi.site/docs/animations/glyph-inspector): Inspect animated letter outlines with a gliding frame, floating square particles, measurement guides and a live readout.
- [PhraseCycle](https://design.gaudi.site/docs/animations/phrase-cycle): A sequence of phrases rotates vertically in a stable space, without moving the surrounding line.
- [Typewriter](https://design.gaudi.site/docs/animations/typewriter): Types, pauses and deletes a sequence of phrases while reserving space for the longest one.
- [WarpText](https://design.gaudi.site/docs/animations/warp-text): Text gently undulates at rest and bends beneath a moving pointer lens.
- [WordSpotlight](https://design.gaudi.site/docs/animations/word-spotlight): A moving set of corner marks brings one word into focus while the surrounding words soften.

Source: https://design.gaudi.site/docs/animations/cipher-reveal (Markdown with example code: https://design.gaudi.site/docs/animations/cipher-reveal.md)

---

# GlyphInspector

> Inspect animated letter outlines with a gliding frame, floating square particles, measurement guides and a live readout.

Hover to take control; drag and release a letter to return it to its slot.

- Category: Animations · Text
- Import: `@gaudi/design-system/animations/GlyphInspector` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/GlyphInspector/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-text-glyphinspector--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { GlyphInspector } from '@gaudi/design-system/animations/GlyphInspector';
```

## Usage

```jsx
import { GlyphInspector } from '@gaudi/design-system/animations/GlyphInspector';

<GlyphInspector text="Gaudi" paused activeIndex={2} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-text-glyphinspector--playground)
- [Pointer exploration](https://storybook.gaudi.site/index.html?path=/story/animations-text-glyphinspector--variant)
- [Area reveal](https://storybook.gaudi.site/index.html?path=/story/animations-text-glyphinspector--area-reveal)
- [Paused at an index](https://storybook.gaudi.site/index.html?path=/story/animations-text-glyphinspector--paused)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `text` | `string` | `"Gaudi"` | no | Text to display. Keep it short enough for the chosen font size. |
| `autoplay` | `boolean` | `true` | no | Step the inspector through the letters while no letter is hovered or held. |
| `draggable` | `boolean` | `true` | no | Allow decorative letters to be lifted a short distance; release returns them to their slot. Does not change the text. |
| `readout` | `boolean` | `true` | no | Show the inspected character, its code point and its measured size (or drag offset) below the frame. |
| `guides` | `boolean` | `true` | no | Draw faint horizontal guides along the top and bottom of the inspected letter across the line. |
| `interval` | `number` | `900` | no | Milliseconds between automatic steps, clamped to 200–10000 before applying tempo. |
| `outline` | `dashed \| dotted \| solid` | `"dashed"` | no | Stroke style of the inspected letter outline. |
| `accent` | `string` | `"currentColor"` | no | Color of the frame, guides and readout. |
| `particles` | `number` | `12` | no | Number of drifting square particles around the frame, rounded and clamped to 0–40. Set 0 to hide them. |
| `tempo` | `number` | `1` | no | Speed multiplier for automatic inspection, outline tracing and particles, clamped to 0.25–3. |
| `reveal` | `letter \| area \| none` | `"letter"` | no | Outline the inspected letter, softly reveal nearby letter outlines around the pointer, or keep all letters filled. |
| `radius` | `number` | `120` | no | Area reveal radius in CSS pixels, clamped to 20–400. Only used with reveal="area". |
| `paused` | `boolean` | `false` | no | Stop motion and dragging while keeping the inspector visible at activeIndex, even with autoplay disabled. System reduced motion, hidden tabs and offscreen containers also stop motion. |
| `activeIndex` | `number` | `0` | no | Zero-based character index to inspect when paused. Counts Unicode code points, including spaces. Out-of-range, non-integer or non-finite values fall back to 0. Empty text shows no inspector. Ignored while running. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer span. Typography is inherited. |

### Variants

- `outline`: `dashed`, `dotted`, `solid`
- `reveal`: `letter`, `area`, `none`

## Accessibility

The complete text is exposed once; decorative letters are hidden from assistive technology. Hover and drag do not change the text. Reduced motion removes animated inspection and dragging; an explicitly paused inspector remains visible without motion. Provide a pause control for continuous autoplay.

## Notes

- Visual idea inspired by Tech Text from React Bits (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits code or assets are included.
- Typography is inherited and shrinks to fit the available width. The component reserves space for its particles, readout and bounded drag movement.

## Related

- [CipherReveal](https://design.gaudi.site/docs/animations/cipher-reveal): Scrambled characters resolve progressively into readable text on view, hover or focus.
- [PhraseCycle](https://design.gaudi.site/docs/animations/phrase-cycle): A sequence of phrases rotates vertically in a stable space, without moving the surrounding line.
- [Typewriter](https://design.gaudi.site/docs/animations/typewriter): Types, pauses and deletes a sequence of phrases while reserving space for the longest one.
- [WarpText](https://design.gaudi.site/docs/animations/warp-text): Text gently undulates at rest and bends beneath a moving pointer lens.
- [WordSpotlight](https://design.gaudi.site/docs/animations/word-spotlight): A moving set of corner marks brings one word into focus while the surrounding words soften.

Source: https://design.gaudi.site/docs/animations/glyph-inspector (Markdown with example code: https://design.gaudi.site/docs/animations/glyph-inspector.md)

---

# PhraseCycle

> A sequence of phrases rotates vertically in a stable space, without moving the surrounding line.

- Category: Animations · Text
- Import: `@gaudi/design-system/animations/PhraseCycle` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/PhraseCycle/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-text-phrasecycle--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { PhraseCycle } from '@gaudi/design-system/animations/PhraseCycle';
```

## Usage

```jsx
import { PhraseCycle } from '@gaudi/design-system/animations/PhraseCycle';

<PhraseCycle texts={["Create", "Explore"]} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-text-phrasecycle--playground)
- [Downward rotation](https://storybook.gaudi.site/index.html?path=/story/animations-text-phrasecycle--variant)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `texts` | `string[]` | `["thoughtfully", "boldly", "together"]` | no | Phrases to display in order. All phrases are included once in the accessible text. |
| `interval` | `number` | `2200` | no | Milliseconds between phrase changes, clamped to 700–30000. Each transition uses the focal motion duration (560 ms). |
| `direction` | `up \| down` | `"up"` | no | Direction of the vertical transition. |
| `paused` | `boolean` | `false` | no | Stop nonessential motion. System reduced motion, hidden tabs and offscreen containers also stop it. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer span. Typography is inherited. |

### Variants

- `direction`: `up`, `down`

## Accessibility

All phrases are exposed once as stable text, without a live region. Reduced motion shows the first phrase. Pausing keeps the current phrase visible. Provide a pause control for continuous cycling.

## Notes

- Visual idea inspired by [Rotating Text](https://reactbits.dev/text-animations/rotating-text) from [React Bits](https://reactbits.dev) (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits code or assets are included.

## Related

- [Direction](https://design.gaudi.site/docs/components/direction): Scopes text direction for Gaudi controls that need directional keyboard and placement behavior.
- [CipherReveal](https://design.gaudi.site/docs/animations/cipher-reveal): Scrambled characters resolve progressively into readable text on view, hover or focus.
- [GlyphInspector](https://design.gaudi.site/docs/animations/glyph-inspector): Inspect animated letter outlines with a gliding frame, floating square particles, measurement guides and a live readout.
- [Typewriter](https://design.gaudi.site/docs/animations/typewriter): Types, pauses and deletes a sequence of phrases while reserving space for the longest one.
- [WarpText](https://design.gaudi.site/docs/animations/warp-text): Text gently undulates at rest and bends beneath a moving pointer lens.
- [WordSpotlight](https://design.gaudi.site/docs/animations/word-spotlight): A moving set of corner marks brings one word into focus while the surrounding words soften.

Source: https://design.gaudi.site/docs/animations/phrase-cycle (Markdown with example code: https://design.gaudi.site/docs/animations/phrase-cycle.md)

---

# Typewriter

> Types, pauses and deletes a sequence of phrases while reserving space for the longest one.

- Category: Animations · Text
- Import: `@gaudi/design-system/animations/Typewriter` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/Typewriter/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-typewriterwriter--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Typewriter } from '@gaudi/design-system/animations/Typewriter';
```

## Usage

```jsx
import { Typewriter } from '@gaudi/design-system/animations/Typewriter';

<Typewriter texts={["Create", "Explore"]} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-typewriterwriter--playground)
- [One sentence](https://storybook.gaudi.site/index.html?path=/story/animations-typewriterwriter--variant)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `texts` | `string[]` | `["Make something memorable.", "Make it yours."]` | no | Phrases to display in order. All phrases are included once in the accessible text. |
| `typeDelay` | `number` | `80` | no | Milliseconds between typed characters, 16–3000. |
| `eraseDelay` | `number` | `40` | no | Milliseconds between deleted characters, 16–3000. |
| `holdDelay` | `number` | `1600` | no | Milliseconds to hold the complete phrase, 100–30000. |
| `repeat` | `boolean` | `true` | no | Repeat the phrases; false leaves the final sentence visible. |
| `caret` | `boolean` | `true` | no | Show a caret; it blinks only while animation is enabled. |
| `paused` | `boolean` | `false` | no | Stop nonessential motion. System reduced motion, hidden tabs and offscreen containers also stop it. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer span. Typography is inherited. |

## Accessibility

All phrases are exposed once as stable text, without a live region. Reduced motion shows the complete current phrase. Pausing freezes the current typed fragment. Provide a pause control for repeating sequences.

## Notes

- Visual idea inspired by [Text Type](https://reactbits.dev/text-animations/text-type) from [React Bits](https://reactbits.dev) (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits code or assets are included.

## Related

- [CipherReveal](https://design.gaudi.site/docs/animations/cipher-reveal): Scrambled characters resolve progressively into readable text on view, hover or focus.
- [GlyphInspector](https://design.gaudi.site/docs/animations/glyph-inspector): Inspect animated letter outlines with a gliding frame, floating square particles, measurement guides and a live readout.
- [PhraseCycle](https://design.gaudi.site/docs/animations/phrase-cycle): A sequence of phrases rotates vertically in a stable space, without moving the surrounding line.
- [WarpText](https://design.gaudi.site/docs/animations/warp-text): Text gently undulates at rest and bends beneath a moving pointer lens.
- [WordSpotlight](https://design.gaudi.site/docs/animations/word-spotlight): A moving set of corner marks brings one word into focus while the surrounding words soften.

Source: https://design.gaudi.site/docs/animations/typewriter (Markdown with example code: https://design.gaudi.site/docs/animations/typewriter.md)

---

# WarpText

> Text gently undulates at rest and bends beneath a moving pointer lens.

Hover magnifies a local area, adds a soft ripple and optional RGB refraction, then eases back on exit.

- Category: Animations · Text
- Import: `@gaudi/design-system/animations/WarpText` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/WarpText/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-text-warptext--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { WarpText } from '@gaudi/design-system/animations/WarpText';
```

## Usage

```jsx
import { WarpText } from '@gaudi/design-system/animations/WarpText';

<div style={{ fontSize: 96, fontWeight: 700 }}>
  <WarpText text="Bend the moment" />
</div>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-text-warptext--playground)
- [Hover lens](https://storybook.gaudi.site/index.html?path=/story/animations-text-warptext--hover-only)
- [Multiline refraction](https://storybook.gaudi.site/index.html?path=/story/animations-text-warptext--multiline)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `text` | `string` | `"Bend the moment"` | no | Text to render; newline characters create multiple centered lines. |
| `warpStrength` | `number` | `0.08` | no | Ambient distortion, clamped to 0–0.25. Set 0 for hover-only warping. |
| `warpScale` | `number` | `1.7` | no | Size of the ambient distortion field, clamped to 0.5–5. |
| `speed` | `number` | `0.55` | no | Ambient and ripple speed, clamped to 0–3. Zero holds the field still; pointer interaction remains available. |
| `pointerRadius` | `number` | `0.42` | no | Lens radius as a fraction of the container height, clamped to 0.1–1. |
| `pointerStrength` | `number` | `0.38` | no | Pointer-driven bending and magnification, clamped to 0–1. Zero disables the lens. |
| `refraction` | `number` | `0.018` | no | RGB edge separation, clamped to 0–0.06. Set 0 for a clean lens. Most visible on light text against a dark surface. |
| `ripple` | `boolean` | `true` | no | Add a soft radial ripple inside the pointer lens. |
| `paused` | `boolean` | `false` | no | Render undistorted text and stop pointer effects and frame updates. Also respects reduced motion, hidden tabs and offscreen containers. |
| `className / style / ref` | `DOM props` | — | no | Applied to the root. Typography and color are inherited; text shrinks to fit. Set height through style or className. |

## Accessibility

The full text is exposed once. The canvas is decorative and does not change the accessible text. Paused and reduced-motion states are undistorted. Touch does not latch hover, and no extra keyboard stop is added for a decorative effect. Provide a pause control for continuous motion.

## Notes

- Typography and color come from the host. The text texture fits its container and refreshes when fonts or themes change.
- WebGL unavailable or lost: the readable HTML text remains visible. Forced colors uses the HTML fallback.
- Visual behavior inspired by Warp Text from React Bits. Independently implemented for Gaudi; no upstream source or assets are included.

## Related

- [Pointer](https://design.gaudi.site/docs/components/pointer): A pointer effect scoped to its container, with direct, spring and lazy tracking, hover feedback, and native input fallbacks.
- [CipherReveal](https://design.gaudi.site/docs/animations/cipher-reveal): Scrambled characters resolve progressively into readable text on view, hover or focus.
- [GlyphInspector](https://design.gaudi.site/docs/animations/glyph-inspector): Inspect animated letter outlines with a gliding frame, floating square particles, measurement guides and a live readout.
- [PhraseCycle](https://design.gaudi.site/docs/animations/phrase-cycle): A sequence of phrases rotates vertically in a stable space, without moving the surrounding line.
- [Typewriter](https://design.gaudi.site/docs/animations/typewriter): Types, pauses and deletes a sequence of phrases while reserving space for the longest one.
- [WordSpotlight](https://design.gaudi.site/docs/animations/word-spotlight): A moving set of corner marks brings one word into focus while the surrounding words soften.

Source: https://design.gaudi.site/docs/animations/warp-text (Markdown with example code: https://design.gaudi.site/docs/animations/warp-text.md)

---

# WordSpotlight

> A moving set of corner marks brings one word into focus while the surrounding words soften.

- Category: Animations · Text
- Import: `@gaudi/design-system/animations/WordSpotlight` (also `@gaudi/design-system/animations`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/animations/WordSpotlight/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/animations-text-wordspotlight--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { WordSpotlight } from '@gaudi/design-system/animations/WordSpotlight';
```

## Usage

```jsx
import { WordSpotlight } from '@gaudi/design-system/animations/WordSpotlight';

<WordSpotlight text="Gaudi" />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/animations-text-wordspotlight--playground)
- [Gentle focus](https://storybook.gaudi.site/index.html?path=/story/animations-text-wordspotlight--variant)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `text` | `string` | `"Focus on what matters"` | no | Words to display. Whitespace separates words, which wrap within the container. |
| `interval` | `number` | `1800` | no | Milliseconds between automatic word changes, clamped to 400–30000. Hover holds the selected word. |
| `blur` | `number` | `4` | no | Blur radius of unfocused words in pixels, 0–10. Reduced motion renders all words clearly. |
| `paused` | `boolean` | `false` | no | Stop automatic word changes; hover can still select a word. Reduced motion, hidden tabs and offscreen containers also stop automatic changes. |
| `className / style / ref` | `DOM props` | — | no | Applied to the outer span. Typography is inherited. |

## Accessibility

The complete text is exposed once; decorative words are hidden from assistive technology. Reduced motion removes blur and corner marks. Pausing stops automatic changes while retaining the current visual focus. Provide a pause control for continuous cycling.

## Notes

- Visual idea inspired by [True Focus](https://reactbits.dev/text-animations/true-focus) from [React Bits](https://reactbits.dev) (MIT + Commons Clause). Independently implemented for Gaudi; no React Bits code or assets are included.

## Related

- [CipherReveal](https://design.gaudi.site/docs/animations/cipher-reveal): Scrambled characters resolve progressively into readable text on view, hover or focus.
- [GlyphInspector](https://design.gaudi.site/docs/animations/glyph-inspector): Inspect animated letter outlines with a gliding frame, floating square particles, measurement guides and a live readout.
- [PhraseCycle](https://design.gaudi.site/docs/animations/phrase-cycle): A sequence of phrases rotates vertically in a stable space, without moving the surrounding line.
- [Typewriter](https://design.gaudi.site/docs/animations/typewriter): Types, pauses and deletes a sequence of phrases while reserving space for the longest one.
- [WarpText](https://design.gaudi.site/docs/animations/warp-text): Text gently undulates at rest and bends beneath a moving pointer lens.

Source: https://design.gaudi.site/docs/animations/word-spotlight (Markdown with example code: https://design.gaudi.site/docs/animations/word-spotlight.md)

---

# MDX

> Article primitives for MDX content and the compiled MDX runtime.

20 pages · 7 live examples, generated from the design system metadata.

- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.
- [Details](https://design.gaudi.site/docs/mdx/details): Expandable article details with an explicit summary.
- [FAQ](https://design.gaudi.site/docs/mdx/faq): Article questions and answers with semantic disclosure controls and configurable heading hierarchy.
- [FileTree](https://design.gaudi.site/docs/mdx/file-tree): Static file and folder listings for technical documentation.
- [Footnote](https://design.gaudi.site/docs/mdx/footnote): Footnote hydrates generated markdown footnote references with hover and focus popover previews.
- [Highlight](https://design.gaudi.site/docs/mdx/highlight): Inline emphasis within article text.
- [Image](https://design.gaudi.site/docs/mdx/image): Image renders editorial MDX images with caption, dark-mode source, fallback source, and click-to-open modal behavior.
- [ImageModal](https://design.gaudi.site/docs/mdx/image-modal): A focused view of an article image with a caption and dismiss action.
- [LatexText](https://design.gaudi.site/docs/mdx/latex-text): Render inline mathematical notation inside text.
- [Mermaid](https://design.gaudi.site/docs/mdx/mermaid): Renders host-supplied Mermaid source as a labelled diagram with a local loading and error state. Diagram colors and typography use Gaudi tokens and update when the surrounding theme or local tokens change. Wide diagrams keep readable labels and scroll within a keyboard-focusable figure.
- [Preview](https://design.gaudi.site/docs/mdx/preview): Preview renders inline link previews for markdown links transformed by the blog MDX pipeline. It is the MDX adapter over the Core LinkPreview, which owns the rich, type-aware rendering.
- [Quote](https://design.gaudi.site/docs/mdx/quote): An editorial quotation with attribution and an optional portrait.
- [Table](https://design.gaudi.site/docs/mdx/table): Semantic article tables with contained horizontal scrolling.
- [Tooltip](https://design.gaudi.site/docs/mdx/tooltip): Supplementary explanations for a term in article prose.
- [Video](https://design.gaudi.site/docs/mdx/video): Video renders a video thumbnail that opens an embedded video in an accessible modal dialog.

Source: https://design.gaudi.site/docs/mdx (Markdown with example code: https://design.gaudi.site/docs/mdx.md)

---

# Aside

> Supporting article content outside the main reading flow.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Aside` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Aside/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-aside--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Aside from '@gaudi/design-system/mdx/Aside';
```

## Usage

```jsx
<Aside>
  Additional context for the article that should sit outside the main argument.
</Aside>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-aside--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Keep the aside understandable in document order and give distinct sections headings when needed.

## Related

- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.
- [Details](https://design.gaudi.site/docs/mdx/details): Expandable article details with an explicit summary.

Source: https://design.gaudi.site/docs/mdx/aside (Markdown with example code: https://design.gaudi.site/docs/mdx/aside.md)

---

# Callout

> Highlight an article note, tip, warning or error while preserving readable prose.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Callout` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Callout/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-callout--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Callout from '@gaudi/design-system/mdx/Callout';
```

## Usage

```jsx
<Callout type='info'>
  Useful article context that readers should notice before continuing.
</Callout>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-callout--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `type` | `info \| warning \| error` | `info` | no | Semantic message tone. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |
| `classNames` | `Record<string, string>` | `{}` | no | Slot class overrides. |

### Variants

- `type`: `info`, `warning`, `error`

## Accessibility

Text carries the meaning; color and icons support it.

## Related

- [Highlight](https://design.gaudi.site/docs/mdx/highlight): Inline emphasis within article text.
- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.

Source: https://design.gaudi.site/docs/mdx/callout (Markdown with example code: https://design.gaudi.site/docs/mdx/callout.md)

---

# Chart

> Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Chart` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Chart/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-chart--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import { Chart } from '@gaudi/design-system/mdx/Chart';
```

## Usage

```jsx
<Chart
  type='line'
  title='Readers by channel'
  ariaLabel='Monthly readers by channel'
  data={[
    { label: 'Jan', search: 1840 },
    { label: 'Feb', search: 2110 }
  ]}
  yKey='search'
/>

<DonutChart title='Essays by topic' data={[{ label: 'Data', value: 42 }, { label: 'Engineering', value: 28 }]} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-chart--playground)
- [Writing a chart in MDX](https://storybook.gaudi.site/index.html?path=/story/mdx-chart--in-mdx)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `type` | `bar \| line \| area \| composed \| pie \| donut \| scatter \| bubble \| radar \| radial \| sparkline \| range \| waterfall \| bar-list \| funnel \| sankey \| treemap \| box-plot \| histogram \| gauge \| heatmap` | `bar` | no | Picks the chart from the Charts collection; every other prop goes to that chart. |
| `data` | `Array<Record<string, unknown>> \| number[]` | `[]` | no | Records for the chart; the data shape follows the type (series, slices, steps, cells, groups). |
| `xKey` | `string` | `label` | no | Category field and value fields for series charts; composed series take type and axis. |
| `yKey` | `string` | `value` | no | Category field and value fields for series charts; composed series take type and axis. |
| `series` | `Array<{ key, label, type?, axis?, dashed? }>` | — | no | Category field and value fields for series charts; composed series take type and axis. |
| `title / description` | `ReactNode` | — | no | Figure caption. |
| `ariaLabel` | `string` | `title or Chart` | no | Accessible name of the plot. |
| `height` | `number \| auto` | `320 (type-specific)` | no | Plot height; list-shaped charts default to auto. |
| `state` | `loading \| error \| empty \| invalid` | `from data` | no | Force a state; otherwise empty and invalid are detected from the data. |
| `labels` | `Partial<typeof DEFAULT_CHART_LABELS>` | `English copy` | no | Copy for states, the keyboard hint, the data table and its toggle. |
| `locale` | `string` | `runtime` | no | Number formatting for axes, tooltips, the readout and the table. |
| `formatValue` | `Intl.NumberFormatOptions \| (value) => string` | `default number` | no | Number formatting for axes, tooltips, the readout and the table. |
| `showData` | `hidden \| toggle \| visible` | `hidden` | no | Data table visibility; hidden keeps it available to assistive technology. |
| `onActivate` | `(point, index) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `onActiveChange` | `(index \| null) => void` | — | no | Click, Enter or Space on a point; the active point changed. |
| `references` | `Array<{ x?, y?, label, tone? }>` | — | no | Labelled guide lines and point notes on category and scatter charts. |
| `annotations` | `Array<{ x, y, label, tone? }>` | — | no | Labelled guide lines and point notes on category and scatter charts. |
| `stacked / showGrid / showLegend / showTooltip` | `boolean` | `false / true / false / true` | no | Series chart presentation. |
| `selectedIndex` | `number \| null` | — | no | Donut selection; the centre summary shows the selected slice. |
| `defaultSelectedIndex` | `number \| null` | `null` | no | Donut selection; the centre summary shows the selected slice. |
| `onSelect` | `(slice, index) => void` | — | no | Donut selection; the centre summary shows the selected slice. |
| `otherThreshold` | `number` | — | no | Fold small slices into Other; the donut centre caption. |
| `maxSlices` | `number` | — | no | Fold small slices into Other; the donut centre caption. |
| `centerLabel` | `string` | `Total` | no | Fold small slices into Other; the donut centre caption. |
| `toolbar` | `ReactNode` | — | no | Controls beside the caption; the figure border and padding. |
| `framed` | `boolean` | `true (false for Sparkline)` | no | Controls beside the caption; the figure border and padding. |
| `colors` | `string[]` | `Gaudi categorical palette` | no | Override the series or slice colours. |
| `className` | `string` | — | no | Root figure class override. |

### Variants

- `type`: `bar`, `line`, `area`, `composed`, `pie`, `donut`, `scatter`, `bubble`, `radar`, `radial`, `sparkline`, `range`, `waterfall`, `bar-list`, `funnel`, `sankey`, `treemap`, `box-plot`, `histogram`, `gauge`, `heatmap`
- `state`: `loading`, `error`, `empty`, `invalid`
- `showData`: `hidden`, `toggle`, `visible`

## Accessibility

Every chart is a captioned figure whose plot is one tab stop with a name and the role description "chart". The arrow keys walk the points (Up and Down move between rows on a heatmap), Home and End jump to the ends, Enter or Space activates the point, and Escape clears it; the active point is drawn on the chart and read out in a polite live region. Every value is also in a data table, hidden by default and shown with showData. Loading sets aria-busy, invalid and error states are alerts, and the SVG itself is hidden from assistive technology because the table carries the same data.

## Related

- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.
- [Details](https://design.gaudi.site/docs/mdx/details): Expandable article details with an explicit summary.

Source: https://design.gaudi.site/docs/mdx/chart (Markdown with example code: https://design.gaudi.site/docs/mdx/chart.md)

---

# Citation

> Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.

- Category: MDX
- Import: `@gaudi/design-system/mdx/CitationPopover` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/CitationPopover/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-citation--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Citation from '@gaudi/design-system/mdx/CitationPopover';
```

## Usage

```jsx
---
title: 'An Introduction to Knowledge Graphs'
bibliography: ['meta/bibliography/references.bib', 'meta/bibliography/kg.bib']
---

A heterogeneous graph [@HusseinYC18; @WangJSWYCY19; @YangXJWHW20] assigns types to nodes and edges.

The same source can be cited again later [@HusseinYC18].

<!-- Do not hand-write citation anchors, popover data attributes, or references markup. -->
```

## Usage rules

Do:

- Add BibTeX files to `data/meta/bibliography` in the blog repo.
- List the BibTeX files in post frontmatter with `bibliography: ['meta/bibliography/references.bib', 'meta/bibliography/kg.bib']`.
- Cite one source with `[@HusseinYC18]` and grouped sources with `[@HusseinYC18; @WangJSWYCY19; @YangXJWHW20]`.
- Let `rehypeSimpleCitations` generate numbered anchors, popover data attributes, and the References section.
- Use `CitationPopover` and `CitationTracker` only as runtime hydration for the generated citation markup.

Don't:

- Do not hand-write `<sup>`, `citation-link` classes, `data-citation-*` attributes, or References markup in MDX.
- Do not import `CitationPopover` or `CitationTracker` inside individual MDX posts.
- Do not use `CitationPopover` as a manual popover for arbitrary text; it expects generated citation anchors.

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-citation--playground)

## Accessibility

Generated citation links are real anchors with readable labels. Popovers open on hover or focus, grouped references remain individually reachable, and CitationTracker keeps bibliography back-links pointed at the most recent citation instance.

## Notes

- The authoring API is markdown citation syntax, not a React component API.
- `rehypeSimpleCitations` is the blog rehype plugin. It loads BibTeX through `citation-js`, assigns first-use numbers, supports grouped citations, emits citation anchors, and appends the References list.
- `CitationPopover` binds to generated anchors marked with `data-citation-popover` and reads the generated citation keys, numbers, and reference text from data attributes.
- `CitationTracker` updates bibliography back-links so a reference points back to the most recent citation instance the reader used.

## Related

- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.
- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.
- [Details](https://design.gaudi.site/docs/mdx/details): Expandable article details with an explicit summary.

Source: https://design.gaudi.site/docs/mdx/citation (Markdown with example code: https://design.gaudi.site/docs/mdx/citation.md)

---

# CitationTracker

> Keep bibliography back-links associated with the last visited citation.

- Category: MDX
- Import: `@gaudi/design-system/mdx/CitationTracker` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/CitationTracker/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-citationtracker--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import CitationTracker from '@gaudi/design-system/mdx/CitationTracker';
```

## Usage

```jsx
import { CitationTracker } from '@gaudi/design-system/mdx';

// Mount once alongside the host's generated article markup.
<CitationTracker />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-citationtracker--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `Generated citation attributes` (pass-through) | `data-citation-popover / data-citation-keys / data-citation-key` | — | no | Metadata written by the consuming markdown pipeline. |

## Accessibility

Use real citation and bibliography links with unique IDs. Back-links must return to a valid citation.

## Notes

- The consuming markdown pipeline creates citation markup. Gaudi handles its runtime behavior; do not author generated attributes by hand.

## Related

- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.
- [Details](https://design.gaudi.site/docs/mdx/details): Expandable article details with an explicit summary.

Source: https://design.gaudi.site/docs/mdx/citation-tracker (Markdown with example code: https://design.gaudi.site/docs/mdx/citation-tracker.md)

---

# Code

> Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Code` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Code/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-code--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Code from '@gaudi/design-system/mdx/Code';
```

## Usage

````jsx
```tsx title="app/page.tsx" {2} showLineNumbers
export default function Page() {
  return <main>Article</main>;
}
```

::: code-group labels=[pnpm, npm]

```bash
pnpm add @gaudi/design-system
```

```bash
npm install @gaudi/design-system
```

:::
````

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-code--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `CodeFence` (sub-component) | `MDX pre props` | — | no | Reads code, language and the remarkCode data-title, data-highlight, data-line-numbers, data-start-line and data-words attributes. |
| `CodeGroup.children` | `CodeFence elements` | — | no | One tab per fence, titled by data-title or the language. |
| `CodeGroup.label` | `string` | `Code examples` | no | Accessible name for the tab list. |
| `remarkCode` | `remark plugin` | — | no | From @gaudi/design-system/mdx/remark; turns fence meta and ::: code-group blocks into what CodeFence and CodeGroup read. |

## Accessibility

Fences are keyboard-scrollable regions with a labelled copy button; groups are Gaudi Tabs with roving focus and labelled panels.

## Notes

- Map pre to CodeFence and CodeGroup to CodeGroup in the MDX components; add remarkCode to the remark plugins.

## Related

- [Article](https://design.gaudi.site/docs/layout/article): A complete blog article with Gaudi journal navigation, PostHeader metadata, reading progress, TableOfContents section navigation, expandable images, a gallery, and captioned video.
- [CodeBlock](https://design.gaudi.site/docs/components/code-block): CodeBlock renders syntax-highlighted source with an optional header, copy button, line numbers, highlighted and focused lines, diffs, folding and line selection.
- [Map](https://design.gaudi.site/docs/components/map): An interactive geographic map with selectable markers, route lines, and camera controls.
- [Tabs](https://design.gaudi.site/docs/components/tabs): Switch between related panels with keyboard-accessible tab controls.

Source: https://design.gaudi.site/docs/mdx/code (Markdown with example code: https://design.gaudi.site/docs/mdx/code.md)

---

# Details

> Expandable article details with an explicit summary.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Details` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Details/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-details--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Details from '@gaudi/design-system/mdx/Details';
```

## Usage

```jsx
<Details title='Implementation detail'>
  Expanded article content that is useful but not required for the main reading path.
</Details>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-details--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `title` | `ReactNode` | — | no | Disclosure summary. |
| `headingLevel` | `number` | `2` | no | Level of the heading that wraps the disclosure button; the title renders once. |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `HTML div props` (pass-through) | `HTMLAttributes<HTMLDivElement>` | — | no | Additional attributes on the content region. |

## Accessibility

The summary button exposes its expanded state and supports keyboard disclosure. Keep the summary descriptive when the content is collapsed.

## Related

- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.

Source: https://design.gaudi.site/docs/mdx/details (Markdown with example code: https://design.gaudi.site/docs/mdx/details.md)

---

# FAQ

> Article questions and answers with semantic disclosure controls and configurable heading hierarchy.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Faq` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Faq/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-faq--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import FAQ from '@gaudi/design-system/mdx/Faq';
```

## Usage

```jsx
<Faq questions={[
  {
    question: 'Why use FAQ blocks?',
    answer: 'They structure repeated article answers.'
  }
]} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-faq--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `questions` | `Array<{ question, answer }>` | — | no | Question and answer disclosures. |
| `heading` | `ReactNode` | `FAQ` | no | Visible section heading. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` | no | Semantic level for the section heading. |

### Variants

- `headingLevel`: `2`, `3`, `4`, `5`, `6`

## Accessibility

Faq uses a semantic definition list and native disclosure buttons. Choose a headingLevel that follows the surrounding article heading without skipping a level.

## Related

- [Article](https://design.gaudi.site/docs/layout/article): A complete blog article with Gaudi journal navigation, PostHeader metadata, reading progress, TableOfContents section navigation, expandable images, a gallery, and captioned video.
- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.

Source: https://design.gaudi.site/docs/mdx/faq (Markdown with example code: https://design.gaudi.site/docs/mdx/faq.md)

---

# FileTree

> Static file and folder listings for technical documentation.

- Category: MDX
- Import: `@gaudi/design-system/mdx/FileTree` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/FileTree/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-filetree--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import FileTree from '@gaudi/design-system/mdx/FileTree';
```

## Usage

```jsx
<FileTree data={[
  { name: 'content', isFolder: true, childrenProp: [{ name: 'post.mdx' }] },
  { name: 'package.json' }
]} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-filetree--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `data` | `Array<{ name, isFolder?, childrenProp?, isOpen? }>` | `[]` | no | Recursive file and folder records. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

The listing composes Core Card and Item, preserves nested list semantics and has a named keyboard-scrollable region. isOpen controls which authored branches are shown; use Core/Tree for an interactive file explorer.

## Related

- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Item](https://design.gaudi.site/docs/components/item): Flexible rows for people, settings, integrations, navigation and activity lists, composed from media, text, actions and optional header and footer rows.
- [Tree](https://design.gaudi.site/docs/components/tree): Browse hierarchical content with expansion, selection, checkboxes and drag feedback.

Source: https://design.gaudi.site/docs/mdx/file-tree (Markdown with example code: https://design.gaudi.site/docs/mdx/file-tree.md)

---

# Footnote

> Footnote hydrates generated markdown footnote references with hover and focus popover previews.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Footnote` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Footnote/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-footnote--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Footnote from '@gaudi/design-system/mdx/Footnote';
```

## Usage

```jsx
Inline prose can use a normal markdown footnote reference.[^model-note]

[^model-note]: This explanatory note can include links, emphasis, and short supporting context.

<!-- Runtime wiring lives outside the post:
app layout/page shell: <MDXLayoutRenderer ... />
article runtime: <Footnote />
-->

<!-- The blog pipeline generates anchors with data-footnote-popover, data-footnote-number, and data-footnote-content. -->
```

## Usage rules

Do:

- Write standard markdown footnotes with `[^id]` references and `[^id]: note text` definitions.
- Let `remarkFootnoteData` extract note content and let `rehypeFootnotePopoverV2` attach popover data to generated reference links.
- Use `Footnote` as a page-level runtime binder after the article has rendered.
- Keep footnote copy short enough for a compact popover; long supporting material belongs in the visible footnotes section.

Don't:

- Do not hand-write `data-footnote-*` attributes in article MDX.
- Do not use `<Footnote />` as an inline MDX component or wrapper around footnote text.
- Do not hide the underlying footnote references without preserving anchor navigation and focus behavior.

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-footnote--playground)

## Accessibility

Generated footnote references are real anchors, so readers can still jump to the notes list. `Footnote` adds hover and focus previews without replacing the underlying link or removing the accessible footnote relationship.

## Notes

- `Footnote` listens for `mouseenter`, `mouseleave`, `focusin`, and `focusout` on generated links marked with `data-footnote-popover="true"`.
- The popover body is read from generated `data-footnote-content`, so the plugin must sanitize and serialize the note content before runtime.
- The component positions the popover next to the reference and flips left when it would overflow the viewport.
- The visible footnotes list remains the source of truth; the popover is a reading convenience.

## Related

- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.

Source: https://design.gaudi.site/docs/mdx/footnote (Markdown with example code: https://design.gaudi.site/docs/mdx/footnote.md)

---

# Highlight

> Inline emphasis within article text.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Highlight` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Highlight/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-highlight--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Highlight from '@gaudi/design-system/mdx/Highlight';
```

## Usage

```jsx
Use <Highlight>inline emphasis</Highlight> inside normal article prose.
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-highlight--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |

## Accessibility

Highlighted text stays in the normal reading order; do not rely on color alone for meaning.

## Related

- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.

Source: https://design.gaudi.site/docs/mdx/highlight (Markdown with example code: https://design.gaudi.site/docs/mdx/highlight.md)

---

# Image

> Image renders editorial MDX images with caption, dark-mode source, fallback source, and click-to-open modal behavior.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Image` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Image/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-image--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Image from '@gaudi/design-system/mdx/Image';
```

## Usage

```jsx
<Image
  src='/static/images/art/0.svg'
  fallback='/static/images/art/1.svg'
  darkSrc='/static/images/art/5.svg'
  alt='Lavender gradient artwork'
  caption='A study in lavender and light.'
  width={420}
  height={236}
/>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-image--playground)
- [Fallback](https://storybook.gaudi.site/index.html?path=/story/mdx-image--fallback)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `src` | `string` | — | no | Primary image source. |
| `fallback` | `string` | — | no | Fallback image source used after load failure. |
| `darkSrc` | `string` | — | no | Optional image source shown in dark mode. |
| `alt` | `string` | `post-image` | no | Accessible alt text for informative images. |
| `caption` | `ReactNode` | — | no | Optional visible figure caption. |
| `width` | `number` | — | no | Image width for Next image rendering unless fill is supplied. |
| `height` | `number` | — | no | Image height for Next image rendering unless fill is supplied. |
| `fill` | `boolean` | `false` | no | Uses the parent box instead of explicit dimensions. |
| `sizes` | `string` | — | no | Responsive image sizes hint passed to Next image. |
| `className` | `string` | — | no | Image class override. |

## Accessibility

Image keeps article images semantic with alt text, figure captions, and a button trigger for the modal preview.

## Related

- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.

Source: https://design.gaudi.site/docs/mdx/image (Markdown with example code: https://design.gaudi.site/docs/mdx/image.md)

---

# ImageModal

> A focused view of an article image with a caption and dismiss action.

- Category: MDX
- Import: `@gaudi/design-system/mdx/ImageModal` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/ImageModal/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-imagemodal--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import ImageModal from '@gaudi/design-system/mdx/ImageModal';
```

## Usage

```jsx
<ImageModal src='/static/images/art/0.svg' alt='Lavender gradient artwork' />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-imagemodal--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `isOpen` | `boolean` | — | no | Controlled modal visibility. |
| `onClose` | `() => void` | — | no | Close request from the modal. |
| `src / alt` | `string` | — | no | Image source and descriptive alternative text. |
| `caption` | `ReactNode` | — | no | Supporting image context. |

## Accessibility

Provide alternative text, preserve focus containment and return focus to the image trigger on dismissal.

## Related

- [Image](https://design.gaudi.site/docs/mdx/image): Image renders editorial MDX images with caption, dark-mode source, fallback source, and click-to-open modal behavior.
- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.

Source: https://design.gaudi.site/docs/mdx/image-modal (Markdown with example code: https://design.gaudi.site/docs/mdx/image-modal.md)

---

# LatexText

> Render inline mathematical notation inside text.

- Category: MDX
- Import: `@gaudi/design-system/mdx/LatexText` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/LatexText/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-latextext--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import LatexText from '@gaudi/design-system/mdx/LatexText';
```

## Usage

```jsx
<LatexText>11$^{th}$ International Conference</LatexText>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-latextext--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |
| `style` | `CSSProperties` | — | no | Additional inline styling. |

## Accessibility

Provide surrounding prose that explains the notation and preserves the reading flow.

## Related

- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.

Source: https://design.gaudi.site/docs/mdx/latex-text (Markdown with example code: https://design.gaudi.site/docs/mdx/latex-text.md)

---

# Mermaid

> Renders host-supplied Mermaid source as a labelled diagram with a local loading and error state.

Diagram colors and typography use Gaudi tokens and update when the surrounding theme or local tokens change. Wide diagrams keep readable labels and scroll within a keyboard-focusable figure.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Mermaid` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Mermaid/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-mermaid--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Mermaid from '@gaudi/design-system/mdx/Mermaid';
```

## Usage

```jsx
<Mermaid
  id='architecture-flow'
  description='Draft moves to review before publication.'
  chart={`flowchart TD
  A[Draft] --> B[Review]`}
/>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-mermaid--playground)
- [Invalid Diagram](https://storybook.gaudi.site/index.html?path=/story/mdx-mermaid--invalid-diagram)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `chart` | `string` | — | no | Mermaid chart definition. |
| `description` | `string` | `Diagram` | no | Accessible text alternative for the rendered diagram. |
| `id` | `string` | `generated` | no | Stable Mermaid render identifier. |
| `className` | `string` | — | no | Root figure class override. |

## Accessibility

Mermaid exposes the rendered diagram as one labelled figure. Provide a concise description that communicates the diagram meaning without relying on shape, position, or color.

## Related

- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.

Source: https://design.gaudi.site/docs/mdx/mermaid (Markdown with example code: https://design.gaudi.site/docs/mdx/mermaid.md)

---

# Preview

> Preview renders inline link previews for markdown links transformed by the blog MDX pipeline.

It is the MDX adapter over the Core LinkPreview, which owns the rich, type-aware rendering.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Preview` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Preview/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-preview--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Preview from '@gaudi/design-system/mdx/Preview';
```

## Usage

```jsx
[assaf.website](https://assaf.website)

[Unavailable link](https://this-link-will-not-work.invalid)

[Internal blog link](/blog/engineering/gaudi-my-bash-framework)

<!-- Generated by the blog pipeline:
<Preview url='https://assaf.website' title='assaf.website' />
<Preview url='https://this-link-will-not-work.invalid' title='Unavailable link' />
<Preview internal url='/blog/engineering/gaudi-my-bash-framework' title='Internal blog link' />
-->

<!-- Direct component usage is reserved for React pages and deterministic Storybook examples. -->
```

## Usage rules

Do:

- Write normal markdown links such as `[assaf.website](https://assaf.website)` in MDX posts.
- Use direct `<Preview />` only in React pages, custom layouts, or deterministic docs examples with `previewData`.
- Use `internal` for local blog links that should render internal metadata without remote preview fetching.
- Provide `title` when the source text is not enough or when deterministic rendering matters.

Don't:

- Do not rewrite ordinary article links by hand when markdown syntax can express the link.
- Do not rely on the hover card as the only place a title or destination appears.
- Do not fetch external preview metadata inside the design-system package; the consuming app owns the API route.

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-preview--playground)
- [States](https://storybook.gaudi.site/index.html?path=/story/mdx-preview--states)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `url` | `string` | — | no | Target URL to link to and preview. |
| `title` | `string` | — | no | Optional custom title that overrides fetched preview metadata. |
| `className` | `string` | — | no | Root class override. |
| `defaultOpen` | `boolean` | `false` | no | Starts the hover card open for deterministic demos and visual tests. |
| `internal` | `boolean` | `false` | no | Renders a local app link and skips remote preview fetching. |
| `previewData` | `object` | `null` | no | Preloaded metadata for deterministic docs, tests, or server-provided previews. |
| `showImage` | `boolean` | `true` | no | Controls whether the hover card can show image preview metadata. |
| `timeout` | `number` | `10000` | no | Preview metadata request timeout in milliseconds. |
| `onLoad` | `(data) => void` | — | no | Called when preview metadata loads successfully. |
| `onError` | `(error) => void` | — | no | Called when preview metadata fails to load. |
| `fallback` | `ReactNode` | — | no | Custom fallback UI for unavailable preview metadata. |
| `variant` | `inline \| card \| compact` | `inline` | no | LinkPreview presentation, for React pages that want a card or a row. |
| `endpoint` | `string \| (url) => string \| null` | `SiteConfig preview.endpoint` | no | App-owned preview endpoint; with none configured nothing is fetched. |
| `resolveImage` | `(link) => string \| null \| template map` | `SiteConfig preview.resolveImage` | no | Image for links whose metadata has none (thumbnails, screenshots); Gaudi ships no image services. |

### Variants

- `variant`: `inline`, `card`, `compact`

## Accessibility

Preview renders a real link with a readable label. The hover card is supplemental; the target URL remains reachable without JavaScript, images, or preview metadata.

## Notes

- `remarkLinks` converts external `http` and `https` markdown links into `Preview` MDX text elements with `url` and optional `title` attributes.
- `rehypeInternalLinks` converts matching internal blog anchors like `/blog/category/slug` into `Preview internal` elements after markdown has become HAST.
- External previews call the configured endpoint; without one nothing is fetched. Unavailable URLs render a red fallback link instead of breaking article content.
- Internal previews skip remote fetching and can use local metadata supplied by the app or generated pipeline.
- What each link shows (repository stars and language, video channel and duration, article author and date, post author and counts, Wikipedia excerpts) is decided by `normalizeLinkPreview` in Core/LinkPreview; the adapter only keeps the pipeline props. Images the payload lacks come from the app's `resolveImage`.
- The endpoint resolves from the `endpoint` prop, then `SiteConfigProvider preview={{ endpoint }}`; with neither, links render from `previewData` or as plain links without fetching.

## Related

- [LinkPreview](https://design.gaudi.site/docs/components/link-preview): A link enriched with what the destination is.
- [Image](https://design.gaudi.site/docs/mdx/image): Image renders editorial MDX images with caption, dark-mode source, fallback source, and click-to-open modal behavior.
- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.

Source: https://design.gaudi.site/docs/mdx/preview (Markdown with example code: https://design.gaudi.site/docs/mdx/preview.md)

---

# Quote

> An editorial quotation with attribution and an optional portrait.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Quote` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Quote/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-quote--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Quote from '@gaudi/design-system/mdx/Quote';
```

## Usage

```jsx
<Quote text='Good component systems make product code calmer.' author='Design System' />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-quote--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `text / author / title` | `string` | — | no | Quotation and attribution. |
| `image / imageAlt` | `string` | — | no | Optional portrait source and alternative text. |

## Accessibility

The quotation uses blockquote semantics. Keep attribution readable and avoid repeating the author in decorative image text.

## Related

- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.
- [Code](https://design.gaudi.site/docs/mdx/code): Article code rendered through the Core CodeBlock: CodeFence maps MDX pre, CodeGroup renders ::: code-group fences as tabs.

Source: https://design.gaudi.site/docs/mdx/quote (Markdown with example code: https://design.gaudi.site/docs/mdx/quote.md)

---

# Table

> Semantic article tables with contained horizontal scrolling.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Table` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Table/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-table--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Table from '@gaudi/design-system/mdx/Table';
```

Copy an example into your project with the shadcn CLI: `npx shadcn@latest add https://design.gaudi.site/r/table-api-keys.json`.

## Usage

```jsx
| Component | Status |
| --- | --- |
| Callout | Documented |
| Chart | Ready for article embeds |
```

## Examples

### API keys and permissions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/table-api-keys.json`

### Simple data table

Registry: `npx shadcn@latest add https://design.gaudi.site/r/table-basic.json`

### Editable cells

Registry: `npx shadcn@latest add https://design.gaudi.site/r/table-editable.json`

### Leaderboard

Registry: `npx shadcn@latest add https://design.gaudi.site/r/table-leaderboard.json`

### Records with avatars, status and actions

Registry: `npx shadcn@latest add https://design.gaudi.site/r/table-records.json`

### Projects with team avatars

Registry: `npx shadcn@latest add https://design.gaudi.site/r/table-team-projects.json`

### Vertical details

Registry: `npx shadcn@latest add https://design.gaudi.site/r/table-vertical-details.json`

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | — | no | Content composed from the exported parts. |
| `className` | `string` | — | no | Additional classes on the outer element. |
| `density` | `compact \| normal \| comfortable` | `normal` | no | Shared table spacing; header type and supplied casing stay unchanged. |
| `TableHeaderCell.variant` | `muted \| plain` | `muted` | no | Shared header fill, including opaque sticky cells. |
| `Native table props` (pass-through) | `TableHTMLAttributes<HTMLTableElement>` | — | no | Additional table attributes; row and cell parts forward their native attributes. |

### Variants

- `density`: `compact`, `normal`, `comfortable`

## Accessibility

Include column or row headers and an accessible caption. Wide data scrolls inside the table region.

## Related

- [Avatar](https://design.gaudi.site/docs/components/avatar): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Card](https://design.gaudi.site/docs/components/card): Card frames reusable content with title, subtitle, and optional children.
- [Pill](https://design.gaudi.site/docs/components/pill): Pill renders compact category and status labels.
- [DropdownMenu](https://design.gaudi.site/docs/components/dropdown-menu): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [NumberField](https://design.gaudi.site/docs/components/number-field): Numeric entry with increment buttons, bounds, locale formatting and scrubbing.
- [useCopyToClipboard](https://design.gaudi.site/docs/hooks/use-copy-to-clipboard): Copy text with a temporary copied state and a fallback.

Source: https://design.gaudi.site/docs/mdx/table (Markdown with example code: https://design.gaudi.site/docs/mdx/table.md)

---

# Tooltip

> Supplementary explanations for a term in article prose.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Tooltip` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Tooltip/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-tooltip--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Tooltip from '@gaudi/design-system/mdx/Tooltip';
```

## Usage

```jsx
A <Tooltip message='Compact supporting context.'>technical term</Tooltip> can carry a short explanation.
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-tooltip--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `message` | `ReactNode` | — | no | Tooltip explanation. |
| `text / children` | `ReactNode` | — | no | Visible trigger text. |

## Accessibility

Keep essential information in the article. The trigger must remain discoverable and keyboard accessible.

## Related

- [Tooltip](https://design.gaudi.site/docs/components/tooltip): Brief contextual help attached to an independently labelled control.
- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.

Source: https://design.gaudi.site/docs/mdx/tooltip (Markdown with example code: https://design.gaudi.site/docs/mdx/tooltip.md)

---

# Video

> Video renders a video thumbnail that opens an embedded video in an accessible modal dialog.

- Category: MDX
- Import: `@gaudi/design-system/mdx/Video` (also `@gaudi/design-system/mdx`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/mdx/Video/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/mdx-video--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Video from '@gaudi/design-system/mdx/Video';
```

## Usage

```jsx
<Video
  animationStyle='from-center'
  videoSrc='/static/media/video-player.html'
  thumbnailSrc='/static/images/og-card.jpg'
  thumbnailAlt='Video preview'
  title='Video walkthrough'
/>
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/mdx-video--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `videoSrc` | `YouTube embed URL or embeddable URL` | — | no | Source URL converted to an embeddable iframe URL when possible. |
| `thumbnailSrc` | `string` | — | no | Optional thumbnail image source. |
| `thumbnailAlt` | `string` | `Video thumbnail` | no | Accessible alt text for the thumbnail image or fallback thumbnail label. |
| `animationStyle` | `from-center \| from-bottom \| from-top \| from-left \| from-right \| fade \| top-in-bottom-out \| left-in-right-out` | `from-center` | no | Dialog entrance animation. |
| `title` | `string` | `Video` | no | Dialog heading and iframe title. |
| `ariaLabel` | `string` | `playLabel` | no | Accessible label for the thumbnail trigger. |
| `autoplay` | `boolean` | `true` | no | Adds autoplay to the iframe URL when the dialog opens. |
| `playLabel` | `string` | `Play video` | no | Fallback accessible label for the thumbnail trigger. |
| `className` | `string` | — | no | Thumbnail trigger class override. |
| `classNames` | `{ trigger, thumbnail, playWrapper, playButton, panel, title, video }` | — | no | Slot-level class overrides. |

### Variants

- `animationStyle`: `from-center`, `from-bottom`, `from-top`, `from-left`, `from-right`, `fade`, `top-in-bottom-out`, `left-in-right-out`

## Accessibility

Video uses a native button for the thumbnail trigger, an aria-modal dialog, Escape-to-close behavior, labelled close controls, and returns focus to the trigger when closed.

## Related

- [Dialog](https://design.gaudi.site/docs/components/dialog): Modal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.
- [Aside](https://design.gaudi.site/docs/mdx/aside): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart): Chart is the MDX adapter for the Charts collection: authors write <Chart type=…> (or a chart by name) in an article and get the same framed, accessible chart an application renders from @gaudi/design-system/charts.
- [Citation](https://design.gaudi.site/docs/mdx/citation): Citation documents the blog citation authoring flow and the Gaudi runtime components that hydrate generated citation links.
- [CitationTracker](https://design.gaudi.site/docs/mdx/citation-tracker): Keep bibliography back-links associated with the last visited citation.

Source: https://design.gaudi.site/docs/mdx/video (Markdown with example code: https://design.gaudi.site/docs/mdx/video.md)

---

# Post & Layout

> Blog post page parts: header, navigation, series box and table of contents. Site layout: containers, wrappers, footer, search and newsletter.

9 pages · 0 live examples, generated from the design system metadata.

## Post

- [Post lists](https://design.gaudi.site/docs/layout/post-lists): Blog-post sections using the same Post summaries and article data as the blog pages. Image cards, featured articles, horizontal rows, and compact archives reuse one component.
- [PostHeader](https://design.gaudi.site/docs/layout/post-header): Article title, metadata, timestamps and supporting header controls.
- [PostNavigation](https://design.gaudi.site/docs/layout/post-navigation): Previous and next article links at the end of a post.
- [PostSeriesBox](https://design.gaudi.site/docs/layout/post-series-box): List the articles in a series and identify the current entry.
- [TableOfContents](https://design.gaudi.site/docs/layout/table-of-contents): Responsive article navigation with active sections, expandable heading branches, and an optional diagram and table index. Reuses Scrollspy, Collapsible, Link and the shared expansion hook.

## Layout

- [Article](https://design.gaudi.site/docs/layout/article): A complete blog article with Gaudi journal navigation, PostHeader metadata, reading progress, TableOfContents section navigation, expandable images, a gallery, and captioned video. The main Blog article is joined by a centered Focused essay, a Technical tutorial with nested navigation and code, a wider Photo essay with a gallery, and a Series article with PostSeriesBox navigation across three parts. Each workflow reuses the same scroll boundary, header, media controls, and layout component. Contents-enabled examples use the shared TableOfContents block for links, active sections, and nested branch controls.
- [Footers](https://design.gaudi.site/docs/layout/footers): Site footer with host-supplied navigation, social links, copyright, and optional newsletter form.
- [LayoutContainer](https://design.gaudi.site/docs/layout/layout-container): Async server layout that composes theme context, navigation, a skip link, article content, footer, and host-provided structured data.
- [Newsletter](https://design.gaudi.site/docs/layout/newsletter): Newsletter sections built from one email subscription form, with an explicit host endpoint and local pending, success, and error feedback.

Source: https://design.gaudi.site/docs/layout (Markdown with example code: https://design.gaudi.site/docs/layout.md)

---

# Post lists

> Blog-post sections using the same Post summaries and article data as the blog pages.

Image cards, featured articles, horizontal rows, and compact archives reuse one component.

- Category: Post
- Import: `@gaudi/design-system/post/Post` (also `@gaudi/design-system/post`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/post/Post/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/post-post--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Postlists from '@gaudi/design-system/post/Post';
```

## Usage

```jsx
import { Post } from '@gaudi/design-system';

<ul>
  <Post frontMatter={frontMatter} />
</ul>
```

## Examples

Examples (rendered from Storybook):

- [Post metadata](https://storybook.gaudi.site/index.html?path=/story/post-post--playground)
- [Image cards](https://storybook.gaudi.site/index.html?path=/story/post-post--image-cards)
- [Featured and recent](https://storybook.gaudi.site/index.html?path=/story/post-post--featured)
- [Horizontal rows](https://storybook.gaudi.site/index.html?path=/story/post-post--horizontal)
- [Compact list](https://storybook.gaudi.site/index.html?path=/story/post-post--compact)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `frontMatter` | `Article metadata` | `{}` | no | Title, prepared href, date, subtitle and category { id, label, href }. String categories remain unlinked labels; absent hrefs never create a route. |
| `layout` | `list \| stacked \| horizontal` | `list` | no | Post presentation. Horizontal media stacks in narrow containers. |
| `media` | `ReactNode` | — | no | Optional image or media before the summary. |
| `footer` | `ReactNode` | — | no | Optional byline and reading-time composition. |
| `className` | `string` | — | no | Classes on the list item. |
| `locale` | `string` | — | no | Date formatting locale. |
| `titleVariant` | `string` | `index-list-title` | no | Shared Typography variant; use heading-md for a featured article. |
| `titleAs` | `ElementType` | `h3` | no | Heading element appropriate to the surrounding list. |

### Variants

- `layout`: `list`, `stacked`, `horizontal`

## Accessibility

Use a meaningful linked title and an appropriate heading level. Content and routing remain application-owned.

## Related

- [Image](https://design.gaudi.site/docs/mdx/image): Image renders editorial MDX images with caption, dark-mode source, fallback source, and click-to-open modal behavior.
- [PostHeader](https://design.gaudi.site/docs/layout/post-header): Article title, metadata, timestamps and supporting header controls.
- [PostNavigation](https://design.gaudi.site/docs/layout/post-navigation): Previous and next article links at the end of a post.
- [PostSeriesBox](https://design.gaudi.site/docs/layout/post-series-box): List the articles in a series and identify the current entry.
- [TableOfContents](https://design.gaudi.site/docs/layout/table-of-contents): Responsive article navigation with active sections, expandable heading branches, and an optional diagram and table index.

Source: https://design.gaudi.site/docs/layout/post-lists (Markdown with example code: https://design.gaudi.site/docs/layout/post-lists.md)

---

# PostHeader

> Article title, metadata, timestamps and supporting header controls.

- Category: Post
- Import: `@gaudi/design-system/post/PostHeader` (also `@gaudi/design-system/post`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/post/PostHeader/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/post-postheader--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import PostHeader from '@gaudi/design-system/post/PostHeader';
```

## Usage

```jsx
import { PostHeader } from '@gaudi/design-system';

<PostHeader frontMatter={frontMatter} siteMetadata={siteMetadata} tocControl={tocControl} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/post-postheader--playground)
- [Prepared share and source actions](https://storybook.gaudi.site/index.html?path=/story/post-postheader--sharing-actions)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `frontMatter / siteMetadata` | `object` | `{}` | no | Article id, title, category and tags as { id, label, href }, prepared seriesPosts, and site locale. String category/tag labels remain unlinked. |
| `titleLevel` | `number` | `1` | no | Article heading level. |
| `titleVariant` | `keyof typographyVariants` | `post-title` | no | Shared Typography style for the title, independent of titleLevel. Blog page and article titles use title-md; featured articles use heading-md. |
| `subtitleVariant` | `keyof typographyVariants` | `post-subtitle` | no | Shared Typography style for the subtitle. Blog compositions use paragraph-md. |
| `tocControl` | `ReactNode` | — | no | Optional table-of-contents control. |
| `classNames` | `Record<string, string>` | `{}` | no | Header slot classes. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Preserve one clear article heading and machine-readable dates.

## Related

- [Article](https://design.gaudi.site/docs/layout/article): A complete blog article with Gaudi journal navigation, PostHeader metadata, reading progress, TableOfContents section navigation, expandable images, a gallery, and captioned video.
- [Post lists](https://design.gaudi.site/docs/layout/post-lists): Blog-post sections using the same Post summaries and article data as the blog pages.
- [PostNavigation](https://design.gaudi.site/docs/layout/post-navigation): Previous and next article links at the end of a post.
- [PostSeriesBox](https://design.gaudi.site/docs/layout/post-series-box): List the articles in a series and identify the current entry.
- [TableOfContents](https://design.gaudi.site/docs/layout/table-of-contents): Responsive article navigation with active sections, expandable heading branches, and an optional diagram and table index.

Source: https://design.gaudi.site/docs/layout/post-header (Markdown with example code: https://design.gaudi.site/docs/layout/post-header.md)

---

# PostNavigation

> Previous and next article links at the end of a post.

- Category: Post
- Import: `@gaudi/design-system/post/PostNavigation` (also `@gaudi/design-system/post`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/post/PostNavigation/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/post-postnavigation--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import PostNavigation from '@gaudi/design-system/post/PostNavigation';
```

## Usage

```jsx
import { PostNavigation } from '@gaudi/design-system';

<PostNavigation prev={previousPost} next={nextPost} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/post-postnavigation--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `prev / next` | `Article metadata` | — | no | Prepared { id, title, href } articles. Entries without href are omitted; type changes labels only. |
| `headingLevel` | `number` | `2` | no | Heading level for navigation. |
| `type` | `string` | `Post` | no | Content type used by navigation labels. |

## Accessibility

Links name their destinations. Do not render empty links when one adjacent article is unavailable.

## Related

- [Post lists](https://design.gaudi.site/docs/layout/post-lists): Blog-post sections using the same Post summaries and article data as the blog pages.
- [PostHeader](https://design.gaudi.site/docs/layout/post-header): Article title, metadata, timestamps and supporting header controls.
- [PostSeriesBox](https://design.gaudi.site/docs/layout/post-series-box): List the articles in a series and identify the current entry.
- [TableOfContents](https://design.gaudi.site/docs/layout/table-of-contents): Responsive article navigation with active sections, expandable heading branches, and an optional diagram and table index.

Source: https://design.gaudi.site/docs/layout/post-navigation (Markdown with example code: https://design.gaudi.site/docs/layout/post-navigation.md)

---

# PostSeriesBox

> List the articles in a series and identify the current entry.

- Category: Post
- Import: `@gaudi/design-system/post/PostSeriesBox` (also `@gaudi/design-system/post`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/post/PostSeriesBox/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/post-postseriesbox--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import PostSeriesBox from '@gaudi/design-system/post/PostSeriesBox';
```

## Usage

```jsx
import { PostSeriesBox } from '@gaudi/design-system';

<PostSeriesBox series={seriesPosts} currentId='components' />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/post-postseriesbox--playground)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `series` | `Article metadata[]` | — | no | Prepared { id, title, href, series, order? } entries in reading order. No routes or completion state are inferred. |
| `currentId` | `string \| number` | — | no | Current article stable ID, including zero. Position in the supplied series drives the progress display. |
| `classNames` | `Record<string, string>` | `{}` | no | Slot classes. |
| `className` | `string` | — | no | Additional classes on the outer element. |

## Accessibility

Identify the current article and use descriptive links for other entries.

## Related

- [Post lists](https://design.gaudi.site/docs/layout/post-lists): Blog-post sections using the same Post summaries and article data as the blog pages.
- [PostHeader](https://design.gaudi.site/docs/layout/post-header): Article title, metadata, timestamps and supporting header controls.
- [PostNavigation](https://design.gaudi.site/docs/layout/post-navigation): Previous and next article links at the end of a post.
- [TableOfContents](https://design.gaudi.site/docs/layout/table-of-contents): Responsive article navigation with active sections, expandable heading branches, and an optional diagram and table index.

Source: https://design.gaudi.site/docs/layout/post-series-box (Markdown with example code: https://design.gaudi.site/docs/layout/post-series-box.md)

---

# TableOfContents

> Responsive article navigation with active sections, expandable heading branches, and an optional diagram and table index.

Reuses Scrollspy, Collapsible, Link and the shared expansion hook.

- Category: Post
- Import: `@gaudi/design-system/post/TableOfContents` (also `@gaudi/design-system/post`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/post/TableOfContents/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/post-tableofcontents--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import TableOfContents from '@gaudi/design-system/post/TableOfContents';
```

## Usage

```jsx
import TableOfContents from '@gaudi/design-system/post/TableOfContents';

<TableOfContents toc={toc} contentRef={articleRef} targetRef={readingViewportRef} offset={24} />
```

## Examples

Examples (rendered from Storybook):

- [Playground](https://storybook.gaudi.site/index.html?path=/story/post-tableofcontents--playground)
- [Four or fewer sections](https://storybook.gaudi.site/index.html?path=/story/post-tableofcontents--compact-toc)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `toc` | `Array<{ id, url?, value, depth?, children? }>` | `[]` | no | Prepared heading IDs and labels. Nest children to describe the hierarchy; top-level count controls initial expansion regardless of heading depth. |
| `contentRef` | `RefObject<HTMLElement>` | — | no | Article to index. Defaults to the first article on the page. |
| `targetRef` | `RefObject<HTMLElement>` | — | no | Document or nested scroll viewport used by shared Scrollspy. Omit for document scrolling. |
| `offset` | `number` | `24` | no | Space above the selected heading for sticky navigation or decorative edges. |
| `smooth` | `boolean` | `true` | no | Smooth section navigation; respects reduced motion. |
| `indexVisuals` | `boolean` | `true` | no | Index captioned diagrams and tables in the article. Image and video figures are excluded. |
| `className` | `string` | — | no | Root layout classes. Sticky placement and mobile disclosure belong to the surrounding layout. |
| `aria-label` | `string` | `Table of contents` | no | Accessible navigation name when several contents lists share a page. |

## Accessibility

Uses real links and marks the active heading with aria-current. Branch toggles have descriptive names and aria-expanded. Modified link clicks remain native; section navigation respects reduced motion and does not steal focus. Hidden branches keep their targets indexed and expand when a descendant becomes active.

## Related

- [Scrollspy](https://design.gaudi.site/docs/components/scrollspy): Track the visible section and navigate a long document using anchor links.
- [Link](https://design.gaudi.site/docs/components/link): Link centralizes navigation semantics for internal, anchor, and external links.
- [Article](https://design.gaudi.site/docs/layout/article): A complete blog article with Gaudi journal navigation, PostHeader metadata, reading progress, TableOfContents section navigation, expandable images, a gallery, and captioned video.
- [Image](https://design.gaudi.site/docs/mdx/image): Image renders editorial MDX images with caption, dark-mode source, fallback source, and click-to-open modal behavior.

Source: https://design.gaudi.site/docs/layout/table-of-contents (Markdown with example code: https://design.gaudi.site/docs/layout/table-of-contents.md)

---

# Article

> A complete blog article with Gaudi journal navigation, PostHeader metadata, reading progress, TableOfContents section navigation, expandable images, a gallery, and captioned video.

The main Blog article is joined by a centered Focused essay, a Technical tutorial with nested navigation and code, a wider Photo essay with a gallery, and a Series article with PostSeriesBox navigation across three parts. Each workflow reuses the same scroll boundary, header, media controls, and layout component. Contents-enabled examples use the shared TableOfContents block for links, active sections, and nested branch controls.

- Category: Layout
- Import: `@gaudi/design-system/layout/ArticleContentLayout` (also `@gaudi/design-system/layout`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/layout/ArticleContentLayout/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/layout-article-content-layout--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Article from '@gaudi/design-system/layout/ArticleContentLayout';
```

## Usage

```jsx
import ArticleContentLayout from '@gaudi/design-system/layout/ArticleContentLayout';
import TableOfContents from '@gaudi/design-system/post/TableOfContents';
import PostHeader from '@gaudi/design-system/post/PostHeader';

<ArticleContentLayout aside={<TableOfContents toc={toc} contentRef={articleRef} targetRef={readingViewportRef} />} collapsibleAside>
  <PostHeader frontMatter={article} titleVariant='title-md' subtitleVariant='paragraph-md' />
  {articleContent}
</ArticleContentLayout>
```

## Examples

Examples (rendered from Storybook):

- [Blog article](https://storybook.gaudi.site/index.html?path=/story/layout-article-content-layout--blog-article)
- [Series article](https://storybook.gaudi.site/index.html?path=/story/layout-article-content-layout--series-article)
- [Focused essay](https://storybook.gaudi.site/index.html?path=/story/layout-article-content-layout--focused-essay)
- [Technical tutorial](https://storybook.gaudi.site/index.html?path=/story/layout-article-content-layout--technical-tutorial)
- [Photo essay](https://storybook.gaudi.site/index.html?path=/story/layout-article-content-layout--photo-essay)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children / aside` | `ReactNode` | — | no | Article body and supporting contents or metadata. |
| `hasAside` | `boolean` | `Boolean(aside)` | no | Reserve the supporting column. |
| `collapsibleAside` | `boolean` | `false` | no | Enable the aside disclosure. |
| `asideOpen / defaultAsideOpen` | `boolean` | `— / true` | no | Controlled or initial aside visibility. |
| `onAsideOpenChange` | `(open: boolean) => void` | — | no | Host notification when visibility changes. |
| `showAsideToggleControl` | `boolean` | `true` | no | Built-in toggle and its accessible name suffix. |
| `asideToggleLabel` | `string` | `Table of contents` | no | Built-in toggle and its accessible name suffix. |
| `padding` | `md \| lg` | `md` | no | Vertical prose spacing. |
| `className / contentClassName` | `string` | — | no | Root and article prose classes. |

### Variants

- `padding`: `md`, `lg`

## Accessibility

The aside toggle is a named button with aria-expanded. Supply a labelled nav or aside and keep heading order in the article body. The Blog article demo's optional Blur edges treatment is decorative, does not intercept input, and clears for keyboard focus, reduced motion, and forced colors. Its scroll destinations and sticky contents remain outside the blur bands.

## Notes

- Article is the Storybook composition name. The supported layout component remains ArticleContentLayout, with its public import and props unchanged.
- The Blog article preview's contents control selects visible, none, collapsible, or collapsed navigation. Its smooth control changes wheel scrolling; keyboard, touch, and reduced-motion reading remain native. The other stories demonstrate distinct reading workflows; table-of-contents visibility remains a control in the main Blog article example.

## Related

- [PostHeader](https://design.gaudi.site/docs/layout/post-header): Article title, metadata, timestamps and supporting header controls.
- [TableOfContents](https://design.gaudi.site/docs/layout/table-of-contents): Responsive article navigation with active sections, expandable heading branches, and an optional diagram and table index.
- [PostSeriesBox](https://design.gaudi.site/docs/layout/post-series-box): List the articles in a series and identify the current entry.

Source: https://design.gaudi.site/docs/layout/article (Markdown with example code: https://design.gaudi.site/docs/layout/article.md)

---

# Footers

> Site footer with host-supplied navigation, social links, copyright, and optional newsletter form.

- Category: Layout
- Import: `@gaudi/design-system/layout/Footer` (also `@gaudi/design-system/layout`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/layout/Footer/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/layout-footer--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Footers from '@gaudi/design-system/layout/Footer';
```

## Usage

```jsx
import Footer from '@gaudi/design-system/layout/Footer';

<Footer sections={footerLinks} copyrightName='Example Studio' newsletterProps={{ endpoint: '/api/subscribe' }} />
```

## Examples

Examples (rendered from Storybook):

- [Blog with link columns](https://storybook.gaudi.site/index.html?path=/story/layout-footer--blog)
- [With newsletter](https://storybook.gaudi.site/index.html?path=/story/layout-footer--newsletter)
- [Centered](https://storybook.gaudi.site/index.html?path=/story/layout-footer--centered)
- [Compact inline](https://storybook.gaudi.site/index.html?path=/story/layout-footer--compact)
- [Newsletter unavailable](https://storybook.gaudi.site/index.html?path=/story/layout-components--footer-layout)
- [Newsletter error](https://storybook.gaudi.site/index.html?path=/story/layout-footer--submission-error)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `variant` | `standard \| editorial \| centered \| compact` | `standard` | no | Link columns with a newsletter, blog branding, centered navigation, or compact inline navigation. |
| `sections` | `Array<{ title, links: Array<{ href, label }> }>` | `[]` | no | Navigation groups from the host. |
| `socialLinks` | `Array<{ kind, href }>` | `[]` | no | Social destinations; missing URLs are omitted. |
| `copyrightName` | `string \| { name?, author? }` | — | no | Host-owned attribution. |
| `brandTitle` | `ReactNode` | — | no | Host-supplied name or brand component. |
| `brandDescription` | `string` | — | no | Short description beneath the brand. |
| `className` | `string` | — | no | Additional classes on the footer landmark. |
| `newsletterProps` | `NewsletterForm props` | — | no | Explicit endpoint and subscription copy. |

### Variants

- `variant`: `standard`, `editorial`, `centered`, `compact`

## Accessibility

Retains the footer landmark and uniquely named navigation regions. Supply descriptive link labels and a configured newsletter endpoint before allowing subscription.

## Related

- [Link](https://design.gaudi.site/docs/components/link): Link centralizes navigation semantics for internal, anchor, and external links.
- [Navigation](https://design.gaudi.site/docs/blocks/navigation): The site header block: brand, primary NavigationMenu with a two-block Blog panel (categories beside recent posts) or a Categories panel on the supplied blog route, search, theme switch, and a phone sheet below lg.
- [Article](https://design.gaudi.site/docs/layout/article): A complete blog article with Gaudi journal navigation, PostHeader metadata, reading progress, TableOfContents section navigation, expandable images, a gallery, and captioned video.
- [Newsletter](https://design.gaudi.site/docs/layout/newsletter): Newsletter sections built from one email subscription form, with an explicit host endpoint and local pending, success, and error feedback.
- [LayoutContainer](https://design.gaudi.site/docs/layout/layout-container): Async server layout that composes theme context, navigation, a skip link, article content, footer, and host-provided structured data.

Source: https://design.gaudi.site/docs/layout/footers (Markdown with example code: https://design.gaudi.site/docs/layout/footers.md)

---

# LayoutContainer

> Async server layout that composes theme context, navigation, a skip link, article content, footer, and host-provided structured data.

- Category: Layout
- Import: `@gaudi/design-system/layout/LayoutContainer` (also `@gaudi/design-system/layout`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/layout/LayoutContainer/

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import LayoutContainer from '@gaudi/design-system/layout/LayoutContainer';
```

## Usage

```jsx
import LayoutContainer from '@gaudi/design-system/layout/LayoutContainer';

export default function RootLayout({ children }) {
  return <LayoutContainer metadata={metadata} navigation={navigation} jsonLd={loadJsonLd}>
    {children}
  </LayoutContainer>;
}
```

## Examples

Examples (rendered from Storybook):



## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | — | no | Page content inside the main landmark. |
| `metadata / navigation / preview` | `SiteConfigProvider values` | `{} / — / —` | no | Host site, theme, navigation, and link-preview configuration. |
| `menuProps / footerProps` | `object` | — | no | Navigation and footer presentation props. |
| `jsonLd` | `object \| (() => object \| Promise<object>)` | — | no | Prepared JSON-LD or an async resolver; invalid values are omitted. |
| `analytics` | `ReactNode` | `null` | no | Explicit app-owned analytics element. |

## Accessibility

Keep the skip target and the single main landmark. Supply accessible navigation and footer content; analytics and JSON-LD must come from the host.

## Notes

- Import the async component directly from @gaudi/design-system/layout/LayoutContainer in a server component. Resolve request cookies in the host and pass metadata.theme; Gaudi does not read request cookies.

## Related

- [Navigation](https://design.gaudi.site/docs/blocks/navigation): The site header block: brand, primary NavigationMenu with a two-block Blog panel (categories beside recent posts) or a Categories panel on the supplied blog route, search, theme switch, and a phone sheet below lg.
- [Article](https://design.gaudi.site/docs/layout/article): A complete blog article with Gaudi journal navigation, PostHeader metadata, reading progress, TableOfContents section navigation, expandable images, a gallery, and captioned video.
- [Footers](https://design.gaudi.site/docs/layout/footers): Site footer with host-supplied navigation, social links, copyright, and optional newsletter form.
- [Newsletter](https://design.gaudi.site/docs/layout/newsletter): Newsletter sections built from one email subscription form, with an explicit host endpoint and local pending, success, and error feedback.

Source: https://design.gaudi.site/docs/layout/layout-container (Markdown with example code: https://design.gaudi.site/docs/layout/layout-container.md)

---

# Newsletter

> Newsletter sections built from one email subscription form, with an explicit host endpoint and local pending, success, and error feedback.

- Category: Layout
- Import: `@gaudi/design-system/layout/NewsletterForm` (also `@gaudi/design-system/layout`)
- Source: https://github.com/ahmadassaf/design-system/tree/main/src/components/layout/NewsletterForm/
- Storybook: https://storybook.gaudi.site/index.html?path=/docs/layout-newsletter-form--docs

## Installation

```bash
pnpm add github:ahmadassaf/design-system
```

Import from `@gaudi/design-system`. Load `@gaudi/design-system/global.css` once and add `transpilePackages: ['@gaudi/design-system']` in Next.js.

```jsx
import Newsletter from '@gaudi/design-system/layout/NewsletterForm';
```

## Usage

```jsx
import NewsletterForm from '@gaudi/design-system/layout/NewsletterForm';

<NewsletterForm title='Monthly field notes' endpoint='/api/newsletter' />
```

## Examples

Examples (rendered from Storybook):

- [Form and availability](https://storybook.gaudi.site/index.html?path=/story/layout-components--newsletter)
- [Centered](https://storybook.gaudi.site/index.html?path=/story/layout-newsletter-form--playground)
- [Split](https://storybook.gaudi.site/index.html?path=/story/layout-newsletter-form--split)
- [Image panel](https://storybook.gaudi.site/index.html?path=/story/layout-newsletter-form--image-panel)
- [Compact](https://storybook.gaudi.site/index.html?path=/story/layout-newsletter-form--compact)
- [Submission error](https://storybook.gaudi.site/index.html?path=/story/layout-newsletter-form--submission-error)

## API

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `endpoint` | `string` | — | no | Host endpoint that receives a POST; absent endpoints disable signup. |
| `title` | `ReactNode` | `Subscribe to the newsletter` | no | Visible form heading. Pass null to omit it. |
| `description` | `ReactNode` | `Get new articles and resources in your inbox.` | no | Supporting copy. Pass null to omit it. |
| `headingAs` | `string` | `h3` | no | Heading level in the host page. |
| `titleVariant` | `string` | — | no | Shared Typography variant; omitted preserves the compact form heading. |
| `children` | `ReactNode` | — | no | Supporting content below the form and feedback, such as a privacy note. |
| `className` | `string` | — | no | Root layout classes. |
| `classNames` | `{ root?, header?, body?, title?, description?, form?, input?, action?, button?, message? }` | `{}` | no | Part-specific classes. |

## Accessibility

Uses EmailInput with single-address pattern validation and the default smooth caret. Names the email input, preserves the submitted address on failure, disables duplicate submissions, and announces feedback beside the field.

## Related

- [Article](https://design.gaudi.site/docs/layout/article): A complete blog article with Gaudi journal navigation, PostHeader metadata, reading progress, TableOfContents section navigation, expandable images, a gallery, and captioned video.
- [Footers](https://design.gaudi.site/docs/layout/footers): Site footer with host-supplied navigation, social links, copyright, and optional newsletter form.
- [LayoutContainer](https://design.gaudi.site/docs/layout/layout-container): Async server layout that composes theme context, navigation, a skip link, article content, footer, and host-provided structured data.

Source: https://design.gaudi.site/docs/layout/newsletter (Markdown with example code: https://design.gaudi.site/docs/layout/newsletter.md)

---

# Credits

> The projects this site and the design system build on.

## This site

- Site layout inspired by [beUI](https://beui.dev) (for example its [project folder block page](https://beui.dev/components/blocks/project-folder)).
- Routing, MDX content, the search index and the table of contents by [Fumadocs](https://fumadocs.dev) (MIT).
- Built with [Next.js](https://nextjs.org) (MIT), [React](https://react.dev) (MIT) and [Tailwind CSS](https://tailwindcss.com) (MIT).
- Every component in the chrome (app shell, tabs, code blocks, command palette, menus, buttons) is [Gaudi](https://github.com/ahmadassaf/design-system) itself.

## The design system

Gaudi's dependencies, adapted code, assets and inspirations are listed in its README: [Credits & acknowledgements](https://github.com/ahmadassaf/design-system#credits--acknowledgements) and [Third-party notices](https://github.com/ahmadassaf/design-system#third-party-notices).

Theme authoring credits go to [StyleGlide](https://www.styleglide.ai/themes), [tweakcn](https://tweakcn.com) and [shadcn/ui](https://ui.shadcn.com/themes); the AI setup is inspired by [reui](https://reui.io).

### Orbs

The orb visuals build on three MIT-licensed projects:

- [orb-ui](https://orb-ui.com) ([source](https://github.com/exprmntl/orb-ui)): the circle, bars, cloud and radial variants.
- [Thinking Orbs](https://libraries.dev/orbs) on libraries.dev ([source](https://github.com/Jakubantalik/Libraries.dev)): the activity orb.
- [VoiceOrbs](https://voiceorbs.vercel.app) ([source](https://github.com/amunozdev/voiceorbs)): the iridescent, mercury and waveform orbs.

## Useful resources

Component libraries, blocks and registries worth browsing alongside Gaudi:

- [React Bits](https://reactbits.dev): animated React components, text effects and backgrounds.
- [reui](https://reui.io): components, blocks and agent tooling for shadcn/ui.
- [shadcn.io](https://www.shadcn.io): community components, blocks and tools for shadcn/ui.
- [registry.directory](https://registry.directory): a directory of shadcn/ui registries.
- [Shadcnblocks](https://www.shadcnblocks.com): ready-made blocks for shadcn/ui.
- [shadcncraft](https://shadcncraft.com): shadcn/ui components and blocks.
- [Shadcn UI Kit](https://shadcnuikit.com): dashboards, templates and components.
- [shadcn/studio](https://shadcnstudio.com): components, blocks and a theme generator.
- [Skiper UI](https://skiper-ui.com): animated components for shadcn/ui.
- [cult/ui](https://www.cult-ui.com): animated components and blocks for shadcn/ui.
- [AI SDK Agents](https://www.aisdkagents.com): agent building blocks for the [AI SDK](https://ai-sdk.dev).

## Licence

This site is released under the [MIT licence](https://github.com/ahmadassaf/design-system), matching the design system.

Source: https://design.gaudi.site/docs/credits (Markdown with example code: https://design.gaudi.site/docs/credits.md)