# 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.