# Gaudi Design System (@gaudi/design-system)

> A curated React design system for blogs and applications, with shared foundations, rich components, and reusable interface patterns. React 19 source components with Tailwind CSS v4, semantic tokens, accessibility, RTL-aware layout and copy-in blocks. Version 0.1.7.

Install from GitHub: `pnpm add github:ahmadassaf/design-system`. Import from `@gaudi/design-system` (root), category entries (`/core`, `/chat`, `/charts`, `/animations`, `/blocks`, `/hooks`, `/mdx`, `/post`, `/layout`) or owner leaf entries such as `@gaudi/design-system/core/Button`. Load `@gaudi/design-system/global.css` once (or `styles.css` when the app owns its Tailwind entry). In Next.js add `transpilePackages: ['@gaudi/design-system']`. Peers: react, react-dom, next, next-themes, tailwindcss; optional recharts (charts) and @xyflow/react (Flow). A JS Tailwind preset is available at `@gaudi/design-system/tailwind-preset`.

Every page of this site is available as Markdown at the links below (append `.md` to any docs URL, or request one with `Accept: text/markdown`). [llms-full.txt](https://design.gaudi.site/llms-full.txt) concatenates every page.

## Docs

- [Introduction](https://design.gaudi.site/docs.md): Gaudi is a curated React design system for blogs and applications, with shared foundations, rich components and reusable interface patterns.
- [Credits](https://design.gaudi.site/docs/credits.md): The projects this site and the design system build on.

## Getting started

- [Installation](https://design.gaudi.site/docs/getting-started.md): Install @gaudi/design-system and render your first component.
- [Setup with Next.js](https://design.gaudi.site/docs/getting-started/nextjs.md): Configure the App Router for Gaudi's React source, stylesheet and themes.
- [Tailwind preset](https://design.gaudi.site/docs/getting-started/tailwind.md): Use Gaudi's colours, radii, typography and prose theme in your own Tailwind utilities.
- [styles.css](https://design.gaudi.site/docs/getting-started/styles.md): Which stylesheet to import, and how corner radius and density are configured.
- [Fonts](https://design.gaudi.site/docs/getting-started/fonts.md): Gaudi never downloads fonts; load them with next/font or @fontsource and put them first in the stack.

## Foundations

- [Foundations](https://design.gaudi.site/docs/foundations.md): Tokens, typography, icons, motion, accessibility and state conventions shared by every Gaudi owner.
- [Colours & tokens](https://design.gaudi.site/docs/foundations/colours.md): The semantic --ds-* contract. Every swatch below reads the live theme, so switch presets or modes to compare.
- [Typography](https://design.gaudi.site/docs/foundations/typography.md): Font stacks, line heights and the prose scale used by articles and docs.
- [Icons](https://design.gaudi.site/docs/foundations/icons.md): The icon registry behind Icon, plus brand marks and animated icons.
- [Accessibility](https://design.gaudi.site/docs/foundations/accessibility.md): The accessibility, keyboard, motion, RTL and responsive conventions every owner follows.
- [States & recovery](https://design.gaudi.site/docs/foundations/states.md): Loading, empty, error, disabled and read-only states, and how components recover.

## Theming

- [Theming](https://design.gaudi.site/docs/theming.md): One semantic contract, eight WCAG AA presets, a runtime provider and lossless import/export.
- [Theming guide](https://design.gaudi.site/docs/theming/guide.md): The theme contract, runtime API, Next.js setup, fonts, import/export and contrast, rendered from the design system THEMING.md.
- [Presets](https://design.gaudi.site/docs/theming/presets.md): gaudi, folio, graphite, contrast, pastel, midnight, grove and ember, each passing WCAG AA in both modes.
- [Theme Studio](https://design.gaudi.site/docs/theming/studio.md): The Storybook page that puts the gallery, editor, generator, contrast report and import/export together.

## AI & agents

- [AI & agents](https://design.gaudi.site/docs/ai.md): Machine-readable docs, an agent skill, a local MCP server and a copy-in registry, all generated from the sources of truth.
- [llms.txt](https://design.gaudi.site/docs/ai/llms-txt.md): A package summary, setup and an index of every docs page as Markdown, for language models.
- [Agent skill](https://design.gaudi.site/docs/ai/skill.md): Install the Gaudi skill into your coding agent's rules or skills folder.
- [MCP server](https://design.gaudi.site/docs/ai/mcp.md): A local stdio Model Context Protocol server that reads the shipped metadata, with no network access.
- [Registry](https://design.gaudi.site/docs/ai/registry.md): A shadcn-compatible registry of blocks and patterns whose components stay package imports.
- [AI reference](https://design.gaudi.site/docs/ai/reference.md): llms.txt, the agent skill installer, the MCP server and the copy-in registry, rendered from the design system README.

## Components

- [Components](https://design.gaudi.site/docs/components.md): Controls, inputs, overlays, data display, feedback and navigation primitives.
- [AspectRatio](https://design.gaudi.site/docs/components/aspect-ratio.md): Keep media at a stable aspect ratio as its container resizes.
- [Avatar](https://design.gaudi.site/docs/components/avatar.md): Profile images, resilient initials, presence, verification, account menus and collaborator groups.
- [Button](https://design.gaudi.site/docs/components/button.md): Button renders the Gaudi action and link-button variants.
- [ButtonGroup](https://design.gaudi.site/docs/components/button-group.md): Group related actions with joined borders and consistent sizing.
- [Card](https://design.gaudi.site/docs/components/card.md): Card frames reusable content with title, subtitle, and optional children.
- [Checkbox](https://design.gaudi.site/docs/components/checkbox.md): Checkbox renders a token-styled binary control.
- [Field](https://design.gaudi.site/docs/components/field.md): Field composes form label, description, error, and input building blocks.
- [Icon](https://design.gaudi.site/docs/components/icon.md): Static and interactive artwork from Gaudi’s centralized icon registry.
- [ImageGallery](https://design.gaudi.site/docs/components/image-gallery.md): A responsive masonry or grid collection with an accessible image viewer.
- [Input](https://design.gaudi.site/docs/components/input.md): Text, search, numeric and date inputs with prefix and suffix slots.
- [Kbd](https://design.gaudi.site/docs/components/kbd.md): Kbd renders keyboard keys and multi-key shortcuts.
- [Link](https://design.gaudi.site/docs/components/link.md): Link centralizes navigation semantics for internal, anchor, and external links.
- [Loader](https://design.gaudi.site/docs/components/loader.md): An accessible loading indicator with arcs, dots, expanding rings, and an indeterminate bar.
- [Map](https://design.gaudi.site/docs/components/map.md): An interactive geographic map with selectable markers, route lines, and camera controls.
- [Pill](https://design.gaudi.site/docs/components/pill.md): Pill renders compact category and status labels.
- [Pointer](https://design.gaudi.site/docs/components/pointer.md): 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.md): Determinate and indeterminate progress with a readable task label.
- [RadioGroup](https://design.gaudi.site/docs/components/radio-group.md): Choose one option using native radio controls or selectable cards.
- [ReadingIndicator](https://design.gaudi.site/docs/components/reading-indicator.md): 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.md): Select renders a styled option picker with searchable combobox behavior and multi-select support.
- [Separator](https://design.gaudi.site/docs/components/separator.md): Separate related content with a horizontal or vertical rule.
- [Slider](https://design.gaudi.site/docs/components/slider.md): Adjust one value or a range with pointer and keyboard input.
- [Switch](https://design.gaudi.site/docs/components/switch.md): Switch renders a token-styled boolean preference control.
- [Tabs](https://design.gaudi.site/docs/components/tabs.md): Switch between related panels with keyboard-accessible tab controls.
- [Textarea](https://design.gaudi.site/docs/components/textarea.md): Multiline text entry that composes with the same labels and errors as Input.
- [TextHighlight](https://design.gaudi.site/docs/components/text-highlight.md): TextHighlight emphasizes short inline phrases inside prose.
- [ToggleGroup](https://design.gaudi.site/docs/components/toggle-group.md): Single or multiple pressed choices for view modes and compact formatting controls.
- [Tooltip](https://design.gaudi.site/docs/components/tooltip.md): Brief contextual help attached to an independently labelled control.
- [VideoPlayer](https://design.gaudi.site/docs/components/video-player.md): A native video player with a complete toolbar, an elastic minimal timeline, and a poster that opens a focused viewing dialog.
- [Accordion](https://design.gaudi.site/docs/components/accordion.md): Rich disclosure for FAQs, settings, member directories, nested help, and guided setup.
- [Carousel](https://design.gaudi.site/docs/components/carousel.md): Carousel renders standard feature slides and editorial card rails.
- [Direction](https://design.gaudi.site/docs/components/direction.md): Scopes text direction for Gaudi controls that need directional keyboard and placement behavior.
- [Resizable](https://design.gaudi.site/docs/components/resizable.md): Resizable panes with accessible separators and bounded panel sizes.
- [ScrollArea](https://design.gaudi.site/docs/components/scroll-area.md): Contained scrolling with themed scrollbars and optional smooth wheel motion for article reading.
- [Sortable](https://design.gaudi.site/docs/components/sortable.md): Reorder lists and grids with drag handles, keyboard controls and cancellation.
- [Attachment](https://design.gaudi.site/docs/components/attachment.md): File attachments with metadata, previews, actions and upload states.
- [Banner](https://design.gaudi.site/docs/components/banner.md): Banner renders a compact announcement strip.
- [EmptyState](https://design.gaudi.site/docs/components/empty-state.md): Explain empty collections, unavailable results and the next useful action.
- [Skeleton](https://design.gaudi.site/docs/components/skeleton.md): Skeleton renders non-semantic loading placeholders on the theme border token, so blocks read clearly in light and dark themes.
- [Breadcrumb](https://design.gaudi.site/docs/components/breadcrumb.md): Breadcrumb renders hierarchical page trails for navigation context.
- [FloatingMenu](https://design.gaudi.site/docs/components/floating-menu.md): 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.md): NavigationMenu renders grouped site navigation with dropdown panels for categories, sections, and related destinations.
- [Pagination](https://design.gaudi.site/docs/components/pagination.md): Pagination renders blog-style previous/status/next navigation.
- [Scrollspy](https://design.gaudi.site/docs/components/scrollspy.md): Track the visible section and navigate a long document using anchor links.
- [Stepper](https://design.gaudi.site/docs/components/stepper.md): Show progress through a sequence of labelled steps.
- [Tree](https://design.gaudi.site/docs/components/tree.md): Browse hierarchical content with expansion, selection, checkboxes and drag feedback.
- [Calendar](https://design.gaudi.site/docs/components/calendar.md): Date selection for single dates, ranges, bookings and localized calendars.
- [Cascader](https://design.gaudi.site/docs/components/cascader.md): Select items from hierarchical data using drill-down, columns, search and multiple selection.
- [ColorPicker](https://design.gaudi.site/docs/components/color-picker.md): An inline color canvas with hue, opacity, an eyedropper, and HEX/RGB/HSL/CSS editors.
- [FileUpload](https://design.gaudi.site/docs/components/file-upload.md): Choose or drop attachments with validation, upload progress and recovery actions.
- [InputOtp](https://design.gaudi.site/docs/components/input-otp.md): One-time code entry with grouped slots, paste support and completion feedback.
- [NumberField](https://design.gaudi.site/docs/components/number-field.md): Numeric entry with increment buttons, bounds, locale formatting and scrubbing.
- [PhoneInput](https://design.gaudi.site/docs/components/phone-input.md): International phone entry with country selection and formatted numbers.
- [Questionnaire](https://design.gaudi.site/docs/components/questionnaire.md): A sequence of form questions with selection, validation and progress.
- [Rating](https://design.gaudi.site/docs/components/rating.md): Display a rating or let people select a score using labelled stars.
- [SignaturePad](https://design.gaudi.site/docs/components/signature-pad.md): A composable signature input with pressure-aware SVG ink, undo and redo, native forms, saved previews, and image or JSON export.
- [CodeBlock](https://design.gaudi.site/docs/components/code-block.md): 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.md): 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.md): 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.md): 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.md): 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.md): Terminal renders mac-style shell examples with typed commands and structured output lines.
- [Timeline](https://design.gaudi.site/docs/components/timeline.md): Display dated activity and milestones with readable descriptions and optional actions.
- [Commander](https://design.gaudi.site/docs/components/commander.md): 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.md): 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.md): Action menus with keyboard navigation, checkbox choices and destructive actions.
- [Popover](https://design.gaudi.site/docs/components/popover.md): Popover renders compact positioned supporting content next to its trigger.
- [Sheet](https://design.gaudi.site/docs/components/sheet.md): 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.md): Transient feedback for completed actions, errors and recoverable background work.
- [Embed](https://design.gaudi.site/docs/components/embed.md): The shared preview vocabulary for messages and content: one switch that hands each piece of content to its owner.
- [LinkPreview](https://design.gaudi.site/docs/components/link-preview.md): A link enriched with what the destination is.
- [WebPreview](https://design.gaudi.site/docs/components/web-preview.md): 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.
- [EventCalendar](https://design.gaudi.site/docs/components/event-calendar.md): Schedule events across day, week, month, agenda and resource views.
- [Flow](https://design.gaudi.site/docs/components/flow.md): 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.md): A timeline board for scheduled work, dependencies and resource planning.
- [Kanban](https://design.gaudi.site/docs/components/kanban.md): Move work items between columns while retaining an accessible move action.

## Blocks

- [Blocks](https://design.gaudi.site/docs/blocks.md): Composed application blocks: app shells, auth and onboarding screens, dashboards, forms, scheduling, stat cards and wizards.
- [App Shell](https://design.gaudi.site/docs/blocks/app-shell.md): 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.md): 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.md): 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.md): 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.md): 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.md): 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.
- [Onboarding](https://design.gaudi.site/docs/blocks/onboarding.md): 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.md): 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.md): 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.md): 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.
- [Settings](https://design.gaudi.site/docs/blocks/settings.md): 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.md): 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.md): A guided multi-step form with validation, progress and recoverable completion.
- [Heroes](https://design.gaudi.site/docs/blocks/heroes.md): Responsive hero sections for product, editorial, and marketing pages.

## Chat & Agents

- [Chat & Agents](https://design.gaudi.site/docs/chat.md): Chat and agent interface owners (every export is Chat-prefixed).
- [ChatActivityHistory](https://design.gaudi.site/docs/chat/chat-activity-history.md): What happened in a conversation, newest last.
- [ChatActivityIndicator](https://design.gaudi.site/docs/chat/chat-activity-indicator.md): What the assistant is doing: idle, thinking, streaming, tool, done or error.
- [ChatAgentMark](https://design.gaudi.site/docs/chat/chat-agent-mark.md): 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.md): The surface around a message, with seven variants and reactions.
- [ChatDelegation](https://design.gaudi.site/docs/chat/chat-delegation.md): 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.md): How hard the assistant should think, as a stepped slider over named levels.
- [ChatFeedback](https://design.gaudi.site/docs/chat/chat-feedback.md): Copy, rate and regenerate a finished reply.
- [ChatFileExplorer](https://design.gaudi.site/docs/chat/chat-file-explorer.md): A searchable file hierarchy for shared files, uploads and agent outputs, built on Core Tree.
- [ChatInput](https://design.gaudi.site/docs/chat/chat-input.md): The composer: ChatPromptComposer with mentions, commands, attachments and send or stop; ChatPromptQueue; ChatModelSelect.
- [ChatMessage](https://design.gaudi.site/docs/chat/chat-message.md): 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.md): 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.md): 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.md): The assistant’s plan for the current request, with progress.
- [ChatReasoning](https://design.gaudi.site/docs/chat/chat-reasoning.md): 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.md): Session navigation inside a complete chat: grouped conversations with title search, new chat, rename and delete.
- [ChatSources](https://design.gaudi.site/docs/chat/chat-sources.md): 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.md): Previous, next and a menu of every prompt in a long thread.
- [ChatTool](https://design.gaudi.site/docs/chat/chat-tool.md): 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.md): 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.md): A context panel that connects the agent roster to each agent’s files, with a return to the complete workspace.

## Charts

- [Charts](https://design.gaudi.site/docs/charts.md): Recharts-based charts framed by ChartFrame. Not in the root entry; install the optional `recharts` peer.
- [AreaChart](https://design.gaudi.site/docs/charts/area-chart.md): Filled areas per series over categories, stacked into a total or overlapping from zero.
- [BarChart](https://design.gaudi.site/docs/charts/bar-chart.md): 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.md): 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.md): 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.md): 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.md): 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.md): 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.md): One reading against threshold bands with a target tick, on any scale.
- [HeatmapChart](https://design.gaudi.site/docs/charts/heatmap-chart.md): 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.md): 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.md): Lines per series over categories, with projections, references, annotations and a choice of curve.
- [OrgChart](https://design.gaudi.site/docs/charts/org-chart.md): A connected organization hierarchy with person cards, expandable reporting lines, and contained scrolling.
- [RadarChart](https://design.gaudi.site/docs/charts/radar-chart.md): 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.md): Progress against a full 0–100 track, one ring per record (RadialBarChart).
- [RangeChart](https://design.gaudi.site/docs/charts/range-chart.md): 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.md): 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.md): 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.md): 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.md): 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.md): A knockout bracket with connected match cards, round paging, scores, penalties, and explicit winners.
- [TreemapChart](https://design.gaudi.site/docs/charts/treemap-chart.md): Nested rectangles sized by value, tinted by group or shaded on the heat ramp.
- [WaterfallChart](https://design.gaudi.site/docs/charts/waterfall-chart.md): How a starting value becomes an ending one through increases and decreases, with running totals and subtotals.

## Hooks

- [Hooks](https://design.gaudi.site/docs/hooks.md): Shared React hooks for accessibility, data, environment, interaction, layout and state.
- [useArrowKeyNav](https://design.gaudi.site/docs/hooks/use-arrow-key-nav.md): Arrow-key navigation with a roving tabindex for toolbars, lists and grids.
- [useFocusTrap](https://design.gaudi.site/docs/hooks/use-focus-trap.md): Keep Tab focus inside a custom overlay and restore it on close.
- [useLiveAnnouncer](https://design.gaudi.site/docs/hooks/use-live-announcer.md): Polite or assertive screen reader announcements for changes away from focus.
- [usePrefersReducedMotion](https://design.gaudi.site/docs/hooks/use-prefers-reduced-motion.md): Whether the reader asked to reduce motion.
- [useLocalStorage](https://design.gaudi.site/docs/hooks/use-local-storage.md): useState persisted to localStorage, synced across components and tabs.
- [useMap](https://design.gaudi.site/docs/hooks/use-map.md): Map state with immutable set, replace, remove, clear and reset actions.
- [useReadLocalStorage](https://design.gaudi.site/docs/hooks/use-read-local-storage.md): Read-only localStorage subscriptions shared with useLocalStorage.
- [useSelection](https://design.gaudi.site/docs/hooks/use-selection.md): Multi-select state in a Set, with select-all and indeterminate support.
- [useSessionStorage](https://design.gaudi.site/docs/hooks/use-session-storage.md): useState persisted to sessionStorage for one tab.
- [useDocumentTitle](https://design.gaudi.site/docs/hooks/use-document-title.md): Set a document title and restore the previous owner on cleanup.
- [useIsClient](https://design.gaudi.site/docs/hooks/use-is-client.md): False on the server and during hydration, true on the client.
- [useIsMobile](https://design.gaudi.site/docs/hooks/use-is-mobile.md): True below the 768px phone breakpoint.
- [useIsMounted](https://design.gaudi.site/docs/hooks/use-is-mounted.md): A stable getter for whether this hook is currently mounted.
- [useMediaQuery](https://design.gaudi.site/docs/hooks/use-media-query.md): Track a CSS media query, SSR-safe.
- [useOnlineStatus](https://design.gaudi.site/docs/hooks/use-online-status.md): Whether the browser reports a network connection.
- [usePageVisibility](https://design.gaudi.site/docs/hooks/use-page-visibility.md): Whether the tab is visible, to pause work in the background.
- [usePrefersColorScheme](https://design.gaudi.site/docs/hooks/use-prefers-color-scheme.md): The operating system colour scheme: 'light' or 'dark'.
- [useScreen](https://design.gaudi.site/docs/hooks/use-screen.md): Read a reactive snapshot of the browser screen properties.
- [useScript](https://design.gaudi.site/docs/hooks/use-script.md): Load an explicitly configured script with shared status and ownership.
- [useWindowSize](https://design.gaudi.site/docs/hooks/use-window-size.md): Track layout viewport width and height in CSS pixels.
- [useCopyToClipboard](https://design.gaudi.site/docs/hooks/use-copy-to-clipboard.md): Copy text with a temporary copied state and a fallback.
- [useEventListener](https://design.gaudi.site/docs/hooks/use-event-listener.md): Declarative DOM event listener with cleanup.
- [useHotkey](https://design.gaudi.site/docs/hooks/use-hotkey.md): Keyboard shortcuts with platform-aware mod keys.
- [useHover](https://design.gaudi.site/docs/hooks/use-hover.md): Pointer hover state with props to spread, ignoring touch.
- [useMousePosition](https://design.gaudi.site/docs/hooks/use-mouse-position.md): Track viewport, page and optional element-relative pointer coordinates.
- [useOnClickOutside](https://design.gaudi.site/docs/hooks/use-on-click-outside.md): Run a callback when a press lands outside one or more elements.
- [useScrollLock](https://design.gaudi.site/docs/hooks/use-scroll-lock.md): Lock page scrolling while a custom overlay is open.
- [useCollapsibleSections](https://design.gaudi.site/docs/hooks/use-collapsible-sections.md): Expanded state for several sections, with expand all and collapse all.
- [useElementSize](https://design.gaudi.site/docs/hooks/use-element-size.md): An element's size, kept current with a ResizeObserver.
- [useInView](https://design.gaudi.site/docs/hooks/use-in-view.md): Whether an element is in the viewport, from an IntersectionObserver.
- [useScrollPosition](https://design.gaudi.site/docs/hooks/use-scroll-position.md): The vertical scroll offset of the page or a scroll container.
- [useBoolean](https://design.gaudi.site/docs/hooks/use-boolean.md): Generic boolean state with stable toggle, enable and disable actions.
- [useControllableState](https://design.gaudi.site/docs/hooks/use-controllable-state.md): State that works controlled or uncontrolled, like native inputs.
- [useCountdown](https://design.gaudi.site/docs/hooks/use-countdown.md): A pausable countdown or count-up that stops at its target.
- [useCounter](https://design.gaudi.site/docs/hooks/use-counter.md): A number with increment, decrement, set and reset actions.
- [useDebounceCallback](https://design.gaudi.site/docs/hooks/use-debounce-callback.md): A debounced function with cancel and flush.
- [useDebounceValue](https://design.gaudi.site/docs/hooks/use-debounce-value.md): A value that updates only after it stops changing.
- [useDisclosure](https://design.gaudi.site/docs/hooks/use-disclosure.md): Open, close and toggle state for overlays and disclosures.
- [useEventCallback](https://design.gaudi.site/docs/hooks/use-event-callback.md): A stable function that always calls the latest callback.
- [useInterval](https://design.gaudi.site/docs/hooks/use-interval.md): setInterval that can pause and always runs the latest callback.
- [useIsomorphicLayoutEffect](https://design.gaudi.site/docs/hooks/use-isomorphic-layout-effect.md): useLayoutEffect in the browser, useEffect on the server.
- [useMergedRefs](https://design.gaudi.site/docs/hooks/use-merged-refs.md): Combine a forwarded ref with your own refs.
- [usePrevious](https://design.gaudi.site/docs/hooks/use-previous.md): The value a prop or state held before it last changed.
- [useSliderInput](https://design.gaudi.site/docs/hooks/use-slider-input.md): Keep a range slider and its number inputs in sync.
- [useStep](https://design.gaudi.site/docs/hooks/use-step.md): Zero-based step state for wizards and multi-page forms.
- [useThrottleCallback](https://design.gaudi.site/docs/hooks/use-throttle-callback.md): A function that runs at most once per interval.
- [useTimeout](https://design.gaudi.site/docs/hooks/use-timeout.md): A one-off timer with reset and clear.
- [useUnmount](https://design.gaudi.site/docs/hooks/use-unmount.md): Run the latest committed callback when an effect is cleaned up.

## Animations

- [Animations](https://design.gaudi.site/docs/animations.md): Text and background effects with scoped rendering, reduced motion and visibility-aware playback.
- [AeroShards](https://design.gaudi.site/docs/animations/aero-shards.md): Faceted shards flow through a curved stream in layers of depth.
- [Aurora](https://design.gaudi.site/docs/animations/aurora.md): 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.md): 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.md): Broad illuminated folds drift across a dark surface, with sharp creases and deep intervening shadows.
- [Dither](https://design.gaudi.site/docs/animations/dither.md): Flowing waves rendered with ordered dithering and a limited tonal palette.
- [FaultyTerminal](https://design.gaudi.site/docs/animations/faulty-terminal.md): A curved phosphor display of changing pixel glyphs, scanlines and intermittent signal faults.
- [FloatingLines](https://design.gaudi.site/docs/animations/floating-lines.md): Three layered families of glowing lines cross the surface and bend around the pointer.
- [GradientWaves](https://design.gaudi.site/docs/animations/gradient-waves.md): Broad, softly lit swells roll toward a hazy horizon, with atmospheric depth and subtle pointer parallax.
- [Grainient](https://design.gaudi.site/docs/animations/grainient.md): A slowly warped three-color gradient with fine animated grain.
- [GridScan](https://design.gaudi.site/docs/animations/grid-scan.md): A perspective grid corridor illuminated by a traveling scan pulse.
- [Hyperspeed](https://design.gaudi.site/docs/animations/hyperspeed.md): Paired light trails travel along a curving road and accelerate while the background is held.
- [LightPillar](https://design.gaudi.site/docs/animations/light-pillar.md): Irregular luminous ribbons flow through a broad diagonal column with bright cores and soft bloom.
- [LightRays](https://design.gaudi.site/docs/animations/light-rays.md): Soft overhead shafts overlap in an atmospheric cone and dissolve before reaching the lower surface.
- [LiquidEther](https://design.gaudi.site/docs/animations/liquid-ether.md): Colored dye follows pointer movement, curls through a retained velocity field, and gradually dissipates.
- [MicroSlats](https://design.gaudi.site/docs/animations/micro-slats.md): 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.md): A rolling sea of fine points seen in perspective; crests catch the light and glitter.
- [PatternWaves](https://design.gaudi.site/docs/animations/pattern-waves.md): A nine-pixel dot lattice shades folded fabric with narrow illuminated creases and localized ripples.
- [PixelBlast](https://design.gaudi.site/docs/animations/pixel-blast.md): Separate square pixels form drifting dithered patterns; clicks send circular waves through the field.
- [Plasma](https://design.gaudi.site/docs/animations/plasma.md): Translucent plasma folds flow across the surface, with soft illuminated edges.
- [ShapeWaves](https://design.gaudi.site/docs/animations/shape-waves.md): 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.md): Broad, diffuse shafts cascade from the upper-right corner and fade rapidly into the surface.
- [WebThreads](https://design.gaudi.site/docs/animations/web-threads.md): Six luminous strands fan outward from one bright central pinch, with soft glow around each thread.
- [CipherReveal](https://design.gaudi.site/docs/animations/cipher-reveal.md): Scrambled characters resolve progressively into readable text on view, hover or focus.
- [GlyphInspector](https://design.gaudi.site/docs/animations/glyph-inspector.md): 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.md): A sequence of phrases rotates vertically in a stable space, without moving the surrounding line.
- [Typewriter](https://design.gaudi.site/docs/animations/typewriter.md): Types, pauses and deletes a sequence of phrases while reserving space for the longest one.
- [WarpText](https://design.gaudi.site/docs/animations/warp-text.md): Text gently undulates at rest and bends beneath a moving pointer lens.
- [WordSpotlight](https://design.gaudi.site/docs/animations/word-spotlight.md): A moving set of corner marks brings one word into focus while the surrounding words soften.

## MDX

- [MDX](https://design.gaudi.site/docs/mdx.md): Article primitives for MDX content and the compiled MDX runtime.
- [Aside](https://design.gaudi.site/docs/mdx/aside.md): Supporting article content outside the main reading flow.
- [Callout](https://design.gaudi.site/docs/mdx/callout.md): Highlight an article note, tip, warning or error while preserving readable prose.
- [Chart](https://design.gaudi.site/docs/mdx/chart.md): 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.md): 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.md): Keep bibliography back-links associated with the last visited citation.
- [Code](https://design.gaudi.site/docs/mdx/code.md): 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.md): Expandable article details with an explicit summary.
- [FAQ](https://design.gaudi.site/docs/mdx/faq.md): Article questions and answers with semantic disclosure controls and configurable heading hierarchy.
- [FileTree](https://design.gaudi.site/docs/mdx/file-tree.md): Static file and folder listings for technical documentation.
- [Footnote](https://design.gaudi.site/docs/mdx/footnote.md): Footnote hydrates generated markdown footnote references with hover and focus popover previews.
- [Highlight](https://design.gaudi.site/docs/mdx/highlight.md): Inline emphasis within article text.
- [Image](https://design.gaudi.site/docs/mdx/image.md): 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.md): A focused view of an article image with a caption and dismiss action.
- [LatexText](https://design.gaudi.site/docs/mdx/latex-text.md): Render inline mathematical notation inside text.
- [Mermaid](https://design.gaudi.site/docs/mdx/mermaid.md): Renders host-supplied Mermaid source as a labelled diagram with a local loading and error state.
- [Preview](https://design.gaudi.site/docs/mdx/preview.md): Preview renders inline link previews for markdown links transformed by the blog MDX pipeline.
- [Quote](https://design.gaudi.site/docs/mdx/quote.md): An editorial quotation with attribution and an optional portrait.
- [Table](https://design.gaudi.site/docs/mdx/table.md): Semantic article tables with contained horizontal scrolling.
- [Tooltip](https://design.gaudi.site/docs/mdx/tooltip.md): Supplementary explanations for a term in article prose.
- [Video](https://design.gaudi.site/docs/mdx/video.md): Video renders a video thumbnail that opens an embedded video in an accessible modal dialog.

## Post & Layout

- [Post & Layout](https://design.gaudi.site/docs/layout.md): Blog post page parts: header, navigation, series box and table of contents. Site layout: containers, wrappers, footer, search and newsletter.
- [Post lists](https://design.gaudi.site/docs/layout/post-lists.md): Blog-post sections using the same Post summaries and article data as the blog pages.
- [PostHeader](https://design.gaudi.site/docs/layout/post-header.md): Article title, metadata, timestamps and supporting header controls.
- [PostNavigation](https://design.gaudi.site/docs/layout/post-navigation.md): Previous and next article links at the end of a post.
- [PostSeriesBox](https://design.gaudi.site/docs/layout/post-series-box.md): List the articles in a series and identify the current entry.
- [TableOfContents](https://design.gaudi.site/docs/layout/table-of-contents.md): Responsive article navigation with active sections, expandable heading branches, and an optional diagram and table index.
- [Article](https://design.gaudi.site/docs/layout/article.md): 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.md): Site footer with host-supplied navigation, social links, copyright, and optional newsletter form.
- [LayoutContainer](https://design.gaudi.site/docs/layout/layout-container.md): 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.md): Newsletter sections built from one email subscription form, with an explicit host endpoint and local pending, success, and error feedback.