# Quill Design System > Warm neutral grounds, moss accents, Fraunces display type, and ink-toned type. A low-contrast editorial theme for digital products. A self-hosted shadcn registry with a five-theme, four-accent token layer, WCAG 2.1 AA targets, and 51 composable blocks. Version 0.9.40. Install any item with the shadcn CLI against `https://www.quilldesignsystem.com/r/.json` (e.g. `npx shadcn@latest add https://www.quilldesignsystem.com/r/quill.json` for the theme, then blocks). Primitives are stock shadcn restyled by the theme layer — Quill ships the theme, an icon component, and the blocks below, not re-copied primitives. ## Agent quick start 1. Install the token layer: `npx shadcn@latest add https://www.quilldesignsystem.com/r/quill.json` — or add `"@quill": "https://www.quilldesignsystem.com/r/{name}.json"` to `components.json` `registries` and run `npx shadcn@latest add @quill/quill`. Read what the CLI prints: it is the theming contract. 2. Install the rules file for AI agents: `npx shadcn@latest add @quill/agent-rules` writes `.claude/rules/quill.md` at the project root, which Claude Code loads every session (theming contract, foundations, principles, icon names, block index). 3. Set `data-theme` and `data-accent` on `` (see Theming). The `theme-selector` block owns both at runtime. 4. Before hand-building a section, pick a block from Components below by its intent and install it: `npx shadcn@latest add @quill/`. Primitives (button, card, input…) come from shadcn itself and are restyled by the theme. 5. Read the usage guide for everything you use — `https://www.quilldesignsystem.com/usage/.md` — for the rules, what to reach for instead, and the accessibility notes. 6. Update an item with `npx shadcn@latest add @quill/ --overwrite`. `--yes` does not overwrite a changed file: it prompts in a terminal and silently skips when non-interactive. 7. Verify in the app: `npx tsc --noEmit`, `npm run lint`; then switch `data-theme` and `data-accent` and confirm both take effect. Machine-readable: the registry index at `https://www.quilldesignsystem.com/r/registry.json`, one item per `https://www.quilldesignsystem.com/r/.json`. ## Theming - **Themes** — set `data-theme` on ``: `light` → Dawn (default), `dark` → Dusk, `classic-light` → Classic Light, `classic-dark` → Classic Dark, `intelligent` → Intelligent. Consumers must match one of these values; the token layer re-declares aliases so scoped `data-theme` islands work, not just the root switch. - **Accents** — set `data-accent` on ``: terracotta, moss (default), indigo, gold. The accent drives links, eyebrows, focus rings (`--ring`), and accent italics; it defaults to moss when unset. - Both attributes are independent of the color-scheme; dark grounds and accent are separate axes. ## Tokens - **Semantic contract** — the shadcn variables map onto Quill pigments: `--background`, `--foreground`, `--card`, `--primary`, `--muted`, `--muted-foreground`, `--destructive`, `--border`, `--input`, `--ring`. - **Accent-driven** — `--link`, `--ring`, and accent text follow `data-accent` (default moss-deep). Never hardcode a pigment for these. - **Charts** — use the chart tokens, never raw pigments (raw pigments fail colorblind-safety as data marks): - Categorical: `--chart-1`…`--chart-5` (5 colorblind-safe series cuts). **Assign in fixed order; never cycle or repaint survivors when a series is filtered out.** - Magnitude: `--chart-seq-1`…`--chart-seq-5` (one-hue sequential ramp). - Polarity: `--chart-div-1`…`--chart-div-5` (diverging ramp, neutral midpoint — never red/green). - **Accessibility** — WCAG 2.1 AA: text cuts clear 4.5:1 on every theme ground; interactive control borders clear non-text 3:1. ## Foundations Type, spacing, radii, elevation and motion, rendered from the token source. Every custom property named here ships in the theme item; a name that does not exist cannot appear. ### Type Two voices. **Fraunces** (variable display serif) is the brand voice; **Raleway** does the work. #### Families - `--font-display`: `"Fraunces", Georgia, serif` — headings, wordmark, captions. `--font-heading` is the same face, behind the `font-heading` utility. - `--font-sans`: `"Raleway", -apple-system, BlinkMacSystemFont, sans-serif` — body, UI, labels. - `--font-mono`: `ui-monospace, "SF Mono", Menlo, monospace` — code and token specimens. - `--font-ui` / `--font-data` — the Intelligent theme's instrument faces (`"Inter"`, `"JetBrains Mono"`); leave them to that theme. Loaded from Google Fonts by the `@import` at the top of the shipped theme file. Never load the families again under another name: the theme matches them by their literal names. Weights used: **400 / 500 / 600**. #### Fraunces variable axes - `opsz` 9–144 matches optical size to render size · `SOFT` 0–100 rounds terminals as size grows · `WONK` 0 | 1 is the off-kilter glyph set, **accents only**. - Presets: `--fraunces-display` (`"opsz" 144, "SOFT" 50, "WONK" 0`) · `--fraunces-accent` (`"opsz" 144, "SOFT" 100, "WONK" 1`, the italic emphasis) · `--fraunces-text` (`"opsz" 24, "SOFT" 50`) · `--fraunces-caption` (`"opsz" 14, "SOFT" 100`). #### Type scale | Token | Size | Use | |---|---|---| | `--text-2xs` | 0.7rem (11.2px) | micro labels, tag pills | | `--text-xs` | 0.75rem (12px) | meta, eyebrows | | `--text-sm` | 0.85rem (13.6px) | captions, fine print | | `--text-base` | 0.95rem (15.2px) | UI text, buttons | | `--text-lg` | 1.15rem (18.4px) | lead paragraphs | | `--text-xl` | 1.5rem (24px) | card titles | | `--text-2xl` | 2rem (32px) | sub-headings | | `--text-3xl` | 3rem (48px) | section titles | | `--text-4xl` | 4rem (64px) | page heads | | `--text-5xl` | 5.5rem (88px) | hero display | #### Leading, tracking, rules - No leading or tracking tokens ship; set them as values. Leading: 1.05 display · 1.2 snug · 1.5 UI · 1.7 reading copy (`leading-[1.7]`). Tracking: −0.03em display · −0.02em tight · 0.1em wide · 0.15em eyebrows (`tracking-[0.15em]`) · 0.2em section labels. - **Headings** — Fraunces at weight 400 (never heavy or bold), tight tracking, `--fraunces-display`. - **The one accent word** — italicize exactly one word per headline in the accent (`--accent-pigment-text`, moss by default) with `--fraunces-accent`. Never two. - **Body / UI** — Raleway 400/500/600; relaxed leading for reading copy. - **Eyebrows / labels** — Raleway, uppercase, `--text-xs`, 0.15em tracking, `--ink-muted`; the accent variant carries a short leading dash. - **Captions** — small Fraunces italic in `--ink-muted` with `--fraunces-caption`. - Sentence case in prose and headings; uppercase only for eyebrows. ### Spacing & layout A **4px base step** (`--space-1` = 0.25rem). Editorial rhythm — sections breathe. `--space-1` 4px · `--space-2` 8px · `--space-3` 12px · `--space-4` 16px · `--space-5` 20px · `--space-6` 24px · `--space-7` 28px · `--space-8` 32px · `--space-9` 36px · `--space-10` 40px · `--space-12` 48px · `--space-16` 64px · `--space-20` 80px · `--space-24` 96px Components sit on `--space-4` / `--space-6`; sections breathe with `--space-24`. #### Layout No layout tokens ship; use the values the site uses. Marketing max-width **1400px** (`max-w-[1400px]`), reading column **800px**, side padding **48px** on desktop (`px-12`) and **24px** on mobile (`px-6`), vertical section rhythm **96px** (`py-24`; `py-14` on mobile). #### Composition - Recurring section header: eyebrow → headline (one accent word) → right-aligned italic caption. - One idea per section: a heading plus one composition (a grid of cards, a table, a form), never a stack of unrelated widgets. - No hero-metric row above an identical card grid — that is the generic dashboard Quill exists to avoid. Lead with the thing the page is about; let numbers sit inside it. ### Effects #### Corner radii `--radius-xs` 2px · `--radius-sm` 4px · `--radius-md` 6px · `--radius-lg` 8px · `--radius-xl` 16px · `--radius-2xl` 24px · `--radius-3xl` 32px · `--radius-4xl` 40px; `--radius` (0.5rem) is the shadcn base. Cards use `rounded-xl`, buttons and inputs `rounded-lg`, pills `rounded-full`. #### Elevation Shadows are ink-tinted, layered and re-cut per theme — never a hard black drop. `--shadow-xs` hairline lift · `--shadow-sm` low surfaces · `--shadow` raised popovers and menus · `--shadow-lg` dialogs · `--shadow-pop` the strongest lifted state. Cards sit flat on the paper with a hairline ring, no shadow. #### Motion House easing `--ease-out` (`cubic-bezier(0.4, 0, 0.2, 1)`); soft `--ease-soft` (`cubic-bezier(0.22, 1, 0.36, 1)`). Durations `--dur-fast` 0.2s · `--dur` 0.3s · `--dur-slow` 0.5s. Lifts `--lift` (translateY(-4px)) and `--lift-sm` (translateY(-2px)) for hover on interactive surfaces; presses settle 1px down. Nothing bounces, nothing loops; respect `prefers-reduced-motion`. ## Principles Three principles name the point of view; the rules underneath are how they show up in code. - **Paper first.** Every surface, a texture you can almost feel, with a typeset that has an unhurried editorial rhythm. Everything sits on digital paper (`--paper`, `--paper-warm`, `--paper-deep`); warmth comes from the material, not decoration. - **One italic word.** Emphasis is earned. A single accented italic per headline — never two, never shouted. - **A gentle settle.** Hovers lift, presses set down. Nothing bounces, nothing loops, nothing hurries you along. ### Rules - **Author against semantic tokens** — `--paper`, `--ink`, `--card`, `--primary`, `--ring` and the rest; never the per-theme `dk-*` / `cl-*` / `cd-*` / `int-*` sets and never a raw hex. That is what makes every theme free. - **Ink for actions, accent for meaning** — primary actions are ink (`--primary`). The accent pigment (moss by default; `--accent-pigment-text` for text, `--link`, `--ring`) is reserved for the one accent word, eyebrows, links and the focus ring. Terracotta is the danger pigment: never a hover colour, and a focus ring only when it is the chosen accent. - **Reach for a block before building one** — the registry ships 51 composable blocks (activity feed, empty state, page header, theme selector, data table…). A hand-built copy drifts from the AA-checked tokens the moment it lands. - **Made for people** — WCAG 2.1 AA is a feature, not a checkbox: text cuts clear 4.5:1 on every theme ground, interactive borders clear 3:1, charts use the CVD-safe chart tokens in fixed order, motion has a reduced-motion path. - **Content** — sentence case everywhere (uppercase only for eyebrows); state the decision, then the reason; no hype punctuation, no emoji. ### Do / Don't **Do** — sit everything on digital paper; reserve the accent for the one accent word, eyebrows, links and the focus ring; use ink for primary actions; warm layered shadows; Fraunces light and tight for headings. **Don't** — pure white or pure black in Dawn and Dusk (the Classic themes use them by design); a hand-set focus colour (`--ring` belongs to the accent axis); terracotta on hover; blue-purple gradients; glassmorphism or purple-glow dark mode; emoji; heavy or bold Fraunces; tight body leading; bouncy or looping motion. ### Anti-references - The generic SaaS/shadcn default look: white cards, blue accents, hero-metric rows, identical card grids. - The cold gray enterprise dashboard — a dashboard where a notebook belongs. - Loud startup maximalism: neon gradients, glassmorphism, purple-glow dark mode. ## Component intents Blocks are tagged with an intent vocabulary so you can pick by the job to be done: - `auth` — Authentication and account access — sign-in, sign-up, recovery, verification. - `form` — Structured data entry and validation. - `data-display` — Presenting records, lists, and metrics for reading. - `data-viz` — Charts and quantitative visuals. - `navigation` — Moving around an app — bars, breadcrumbs, tabs, command menus. - `app-shell` — Full-page layout scaffolding for application screens. - `feedback` — System status — alerts, notifications, empty and error states. - `marketing` — Landing-page and promotional sections. - `commerce` — Purchase, checkout, and billing. - `messaging` — Conversational and inbox interfaces. - `scheduling` — Dates, calendars, and bookings. - `productivity` — Task and workflow management. - `content` — Editorial and informational blocks. - `settings` — Configuration and preferences. ## Components Each block is a composition of restyled primitives. `intent` lists its jobs; `use_when` says when to reach for it. - [Activity feed](https://www.quilldesignsystem.com/r/activity-feed.json) — _[data-display]_ You need to show a chronological history of what happened — recent events with who, what, and when. · [usage guide](https://www.quilldesignsystem.com/usage/activity-feed.md) - [Alert stack](https://www.quilldesignsystem.com/r/alerts.json) — _[feedback]_ You need to surface inline status messages of varying severity (info, success, destructive) within a page. · [usage guide](https://www.quilldesignsystem.com/usage/alerts.md) - [Analytics charts](https://www.quilldesignsystem.com/r/analytics-charts.json) — _[data-viz, data-display]_ You need a dashboard view of trends over time — an area chart plus a bar chart on card surfaces. · [usage guide](https://www.quilldesignsystem.com/usage/analytics-charts.md) - [Announcement banners](https://www.quilldesignsystem.com/r/announcement-banner.json) — _[feedback, marketing]_ You need to announce something site-wide with a dismissible banner, either inline or full-bleed. · [usage guide](https://www.quilldesignsystem.com/usage/announcement-banner.md) - [Badges on card](https://www.quilldesignsystem.com/r/badge-on-card.json) — _[data-display]_ You need to show status or category badges attached to a content card. · [usage guide](https://www.quilldesignsystem.com/usage/badge-on-card.md) - [Calendar page](https://www.quilldesignsystem.com/r/calendar-page.json) — _[scheduling]_ You need to pick a single date and show what's scheduled that day. · [usage guide](https://www.quilldesignsystem.com/usage/calendar-page.md) - [Calendar range picker](https://www.quilldesignsystem.com/r/calendar-range.json) — _[scheduling, form]_ You need to book a span of days with a two-month range picker and confirm/clear actions. · [usage guide](https://www.quilldesignsystem.com/usage/calendar-range.md) - [Chat panel](https://www.quilldesignsystem.com/r/chat.json) — _[messaging]_ You need a one-on-one messaging panel with a contact header, bubbles, and a composer. · [usage guide](https://www.quilldesignsystem.com/usage/chat.md) - [Checkout](https://www.quilldesignsystem.com/r/checkout.json) — _[commerce, form]_ You need to collect payment and card details alongside an order summary. · [usage guide](https://www.quilldesignsystem.com/usage/checkout.md) - [Command palette](https://www.quilldesignsystem.com/r/command-palette.json) — _[navigation]_ You need a searchable ⌘K launcher for actions and quick navigation. · [usage guide](https://www.quilldesignsystem.com/usage/command-palette.md) - [Contact form](https://www.quilldesignsystem.com/r/contact-form.json) — _[form]_ You need a get-in-touch form with name, email, topic, and message fields. · [usage guide](https://www.quilldesignsystem.com/usage/contact-form.md) - [Cookie consent](https://www.quilldesignsystem.com/r/cookie-consent.json) — _[feedback]_ You need a compliance banner offering accept, reject, and preferences choices. · [usage guide](https://www.quilldesignsystem.com/usage/cookie-consent.md) - [Dashboard shell](https://www.quilldesignsystem.com/r/dashboard.json) — _[app-shell, data-display]_ You need a full application home — sidebar, search header, and KPI cards. · [usage guide](https://www.quilldesignsystem.com/usage/dashboard.md) - [Data table](https://www.quilldesignsystem.com/r/data-table.json) — _[data-display]_ You need a filterable, actionable table of records with tone-mapped status pills and row actions. · [usage guide](https://www.quilldesignsystem.com/usage/data-table.md) - [Empty state](https://www.quilldesignsystem.com/r/empty-state.json) — _[feedback]_ You need to explain why a view is empty and offer the primary action to fill it. · [usage guide](https://www.quilldesignsystem.com/usage/empty-state.md) - [404 page](https://www.quilldesignsystem.com/r/error-404.json) — _[feedback]_ You need a full-page not-found state with recovery actions. · [usage guide](https://www.quilldesignsystem.com/usage/error-404.md) - [FAQ section](https://www.quilldesignsystem.com/r/faq.json) — _[content, marketing]_ You need to answer common questions in an accordion with a contact fallback. · [usage guide](https://www.quilldesignsystem.com/usage/faq.md) - [Feature section](https://www.quilldesignsystem.com/r/feature-section.json) — _[marketing]_ You need to present product features in an editorial multi-column grid. · [usage guide](https://www.quilldesignsystem.com/usage/feature-section.md) - [File upload](https://www.quilldesignsystem.com/r/file-upload.json) — _[form]_ You need drag-and-drop asset upload with a progress-tracked queue. · [usage guide](https://www.quilldesignsystem.com/usage/file-upload.md) - [Site footer](https://www.quilldesignsystem.com/r/footer.json) — _[marketing, navigation]_ You need a site-wide footer with link columns, a brand blurb, and legal links. · [usage guide](https://www.quilldesignsystem.com/usage/footer.md) - [Forgot password](https://www.quilldesignsystem.com/r/forgot-password.json) — _[auth]_ You need a password-reset request card that sends a recovery link. · [usage guide](https://www.quilldesignsystem.com/usage/forgot-password.md) - [Hero](https://www.quilldesignsystem.com/r/hero.json) — _[marketing]_ You need the top-of-page marketing statement — headline, supporting copy, and calls to action. · [usage guide](https://www.quilldesignsystem.com/usage/hero.md) - [Invoice](https://www.quilldesignsystem.com/r/invoice.json) — _[commerce, data-display]_ You need a printable invoice with parties, line-item totals, and a download action. · [usage guide](https://www.quilldesignsystem.com/usage/invoice.md) - [Kanban board](https://www.quilldesignsystem.com/r/kanban.json) — _[productivity]_ You need to manage work across status columns with draggable, tagged task cards. · [usage guide](https://www.quilldesignsystem.com/usage/kanban.md) - [List + detail](https://www.quilldesignsystem.com/r/list-detail.json) — _[messaging, app-shell]_ You need an inbox-style split view pairing a selectable list with a detail pane. · [usage guide](https://www.quilldesignsystem.com/usage/list-detail.md) - [Login](https://www.quilldesignsystem.com/r/login.json) — _[auth]_ You need the standard email-and-password sign-in with remember-me and reset links. · [usage guide](https://www.quilldesignsystem.com/usage/login.md) - [Minimal login](https://www.quilldesignsystem.com/r/login-minimal.json) — _[auth]_ You need the leanest possible sign-in — a single field for one-time-code entry. · [usage guide](https://www.quilldesignsystem.com/usage/login-minimal.md) - [Login with OAuth providers](https://www.quilldesignsystem.com/r/login-oauth.json) — _[auth]_ Identity comes from a provider (Google, GitHub, Apple) rather than a password you store. · [usage guide](https://www.quilldesignsystem.com/usage/login-oauth.md) - [Login with split panel](https://www.quilldesignsystem.com/r/login-split-panel.json) — _[auth, marketing]_ You need a branded full-page sign-in with a testimonial side panel and magic-link option. · [usage guide](https://www.quilldesignsystem.com/usage/login-split-panel.md) - [Mail inbox shell](https://www.quilldesignsystem.com/r/mail-shell.json) — _[messaging, app-shell]_ You need a two-pane mail client — searchable list plus a reading pane with toolbar and reply. · [usage guide](https://www.quilldesignsystem.com/usage/mail-shell.md) - [Navbar](https://www.quilldesignsystem.com/r/navbar.json) — _[navigation]_ You need a top navigation bar with wordmark, links, and sign-in / get-started actions. · [usage guide](https://www.quilldesignsystem.com/usage/navbar.md) - [Theme selector](https://www.quilldesignsystem.com/r/theme-selector.json) — _[settings]_ You need to let users switch among Quill's five themes and four accents, persisted to localStorage. · [usage guide](https://www.quilldesignsystem.com/usage/theme-selector.md) - [Newsletter signup](https://www.quilldesignsystem.com/r/newsletter.json) — _[marketing, form]_ You need an email-capture section with social proof to grow a list. · [usage guide](https://www.quilldesignsystem.com/usage/newsletter.md) - [Notifications](https://www.quilldesignsystem.com/r/notifications.json) — _[feedback, data-display]_ You need a notifications center with unread indicators and a mark-all-read action. · [usage guide](https://www.quilldesignsystem.com/usage/notifications.md) - [Onboarding checklist](https://www.quilldesignsystem.com/r/onboarding.json) — _[productivity]_ You need a setup checklist that tracks progress and links to remaining steps. · [usage guide](https://www.quilldesignsystem.com/usage/onboarding.md) - [Order summary](https://www.quilldesignsystem.com/r/order-summary.json) — _[commerce]_ You need a cart-review card with line items, a promo field, a total, and a pay button. · [usage guide](https://www.quilldesignsystem.com/usage/order-summary.md) - [OTP verification](https://www.quilldesignsystem.com/r/otp-verification.json) — _[auth]_ You need to verify an email with a six-digit one-time passcode and resend. · [usage guide](https://www.quilldesignsystem.com/usage/otp-verification.md) - [Page header](https://www.quilldesignsystem.com/r/page-header.json) — _[navigation, app-shell]_ You need a screen header with breadcrumbs, title, description, and primary actions. · [usage guide](https://www.quilldesignsystem.com/usage/page-header.md) - [Pricing](https://www.quilldesignsystem.com/r/pricing.json) — _[marketing, commerce]_ You need a tiered pricing grid with a highlighted plan and feature checklists. · [usage guide](https://www.quilldesignsystem.com/usage/pricing.md) - [Profile card](https://www.quilldesignsystem.com/r/profile-card.json) — _[data-display]_ You need a compact user profile with avatar, role, stats, and follow / message actions. · [usage guide](https://www.quilldesignsystem.com/usage/profile-card.md) - [Search results](https://www.quilldesignsystem.com/r/search-results.json) — _[navigation, data-display]_ You need a search panel with a query input, result count, and a linked result list. · [usage guide](https://www.quilldesignsystem.com/usage/search-results.md) - [Settings form](https://www.quilldesignsystem.com/r/settings.json) — _[settings, form]_ You need a profile settings form with name, bio, and notification preferences. · [usage guide](https://www.quilldesignsystem.com/usage/settings.md) - [Sidebar navigation shell](https://www.quilldesignsystem.com/r/sidebar-nav.json) — _[app-shell, navigation]_ You need a collapsible icon-sidebar app shell with grouped menus and a content area. · [usage guide](https://www.quilldesignsystem.com/usage/sidebar-nav.md) - [Sign up](https://www.quilldesignsystem.com/r/signup.json) — _[auth]_ You need standard account creation — name, email, password, and a sign-in link. · [usage guide](https://www.quilldesignsystem.com/usage/signup.md) - [Signup — social first](https://www.quilldesignsystem.com/r/signup-social.json) — _[auth]_ You need signup that leads with OAuth providers and falls back to email/password. · [usage guide](https://www.quilldesignsystem.com/usage/signup-social.md) - [Stat cards](https://www.quilldesignsystem.com/r/stat-cards.json) — _[data-display]_ You need a row of KPI cards showing values with period-over-period deltas. · [usage guide](https://www.quilldesignsystem.com/usage/stat-cards.md) - [Stats band](https://www.quilldesignsystem.com/r/stats-band.json) — _[marketing]_ You need a marketing band of headline statistics separated by dividers. · [usage guide](https://www.quilldesignsystem.com/usage/stats-band.md) - [Tabs page](https://www.quilldesignsystem.com/r/tabs-page.json) — _[navigation, settings]_ You need a settings screen split into account, notifications, and security tabs. · [usage guide](https://www.quilldesignsystem.com/usage/tabs-page.md) - [Team section](https://www.quilldesignsystem.com/r/team-section.json) — _[marketing]_ You need a marketing team grid with member cards, roles, and contact actions. · [usage guide](https://www.quilldesignsystem.com/usage/team-section.md) - [Testimonial](https://www.quilldesignsystem.com/r/testimonial.json) — _[marketing, content]_ You need a customer-quote card with a serif pull-quote and attribution. · [usage guide](https://www.quilldesignsystem.com/usage/testimonial.md) - [Setup wizard step](https://www.quilldesignsystem.com/r/wizard.json) — _[form, productivity]_ You need a multi-step setup flow with a progress stepper and back/continue navigation. · [usage guide](https://www.quilldesignsystem.com/usage/wizard.md) ## Examples — start from a page, not from scratch Each example is a whole page composed from the blocks above; its docs carry the composition order and the spacing rules. Install one and replace the sample content: `npx shadcn@latest add @quill/`. - [Example: app page](https://www.quilldesignsystem.com/r/example-app-page.json) — An example showing how to compose an app page: the sidebar-nav shell wrapping a page-header, then stat-cards, then a data-table — the page leads with what it is about, and the numbers sit inside it. Composition: sidebar-nav → page-header → stat-cards → data-table. - [Example: marketing page](https://www.quilldesignsystem.com/r/example-marketing-page.json) — An example showing how to compose a marketing page: navbar, hero, feature-section, pricing, testimonial and footer — one idea per section, breathing at the 96px rhythm. Composition: navbar → hero → feature-section → pricing → testimonial → footer. - [Example: auth page](https://www.quilldesignsystem.com/r/example-auth-page.json) — An example showing how to compose an auth page: login-split-panel alone at full viewport — one task, nothing competing with it. Composition: login-split-panel. ## Primitive usage guides Per-primitive usage rules — when to use, what to reach for instead, do/don't, accessibility: - [accordion](https://www.quilldesignsystem.com/usage/accordion.md) — A vertically stacked set of expand/collapse sections — one open at a time by default, with an option to allow several. - [alert](https://www.quilldesignsystem.com/usage/alert.md) — A single inline status box for a message tied to a specific area of the page. `alerts` is this primitive already assembled into a vertical stack of several. - [alert-dialog](https://www.quilldesignsystem.com/usage/alert-dialog.md) — A modal that forces an explicit response to a destructive or irreversible action — unlike Dialog, it cannot be dismissed by clicking outside. - [aspect-ratio](https://www.quilldesignsystem.com/usage/aspect-ratio.md) — Constrains any child to a fixed width-to-height ratio — a CSS-only box, most often used to reserve space for images, video embeds, and thumbnails. - [avatar](https://www.quilldesignsystem.com/usage/avatar.md) — A round image, initials, or icon representing a person or entity — reserves its shape immediately and swaps in the real photo once it loads. - [badge](https://www.quilldesignsystem.com/usage/badge.md) — A small, non-interactive label for status, category, or count — not a button or a link on its own. - [breadcrumb](https://www.quilldesignsystem.com/usage/breadcrumb.md) — A trail of links showing the current page's position in a hierarchy — the last crumb is always the current, non-link page. - [button](https://www.quilldesignsystem.com/usage/button.md) — Buttons trigger actions. The default (primary) variant is the single most important action on a surface. - [button-group](https://www.quilldesignsystem.com/usage/button-group.md) — A structural wrapper that merges adjacent Buttons into one visually connected control — shared borders, no owned selection state. - [calendar](https://www.quilldesignsystem.com/usage/calendar.md) — The date-picker primitive built on react-day-picker — supports single, multiple, and range selection modes. `calendar-page` and `calendar-range` are this primitive already composed into full scheduling and booking patterns. - [card](https://www.quilldesignsystem.com/usage/card.md) — A bounded content container with header, body, and footer slots — paper-warm surface with a soft ring instead of a box-shadow border. - [carousel](https://www.quilldesignsystem.com/usage/carousel.md) — A horizontally or vertically scrolling item viewport built on Embla Carousel, with Previous/Next controls and keyboard arrow-key support. - [chart](https://www.quilldesignsystem.com/usage/chart.md) — A themeable wrapper around Recharts — ChartContainer wires a config object to CSS custom properties per series, plus a matching ChartTooltip and ChartLegend. - [checkbox](https://www.quilldesignsystem.com/usage/checkbox.md) — A single independent yes/no selection — check it or leave it, with no relation to any other Checkbox. - [collapsible](https://www.quilldesignsystem.com/usage/collapsible.md) — A single open/closed disclosure toggle — the lower-level primitive behind Accordion, with no item/trigger/content grouping or built-in styling. - [combobox](https://www.quilldesignsystem.com/usage/combobox.md) — A searchable dropdown — type to filter a list, or multi-select with removable chips. - [command](https://www.quilldesignsystem.com/usage/command.md) — A keyboard-first search palette — embed inline for settings search, or wrap in CommandDialog for a ⌘K-style command palette. - [context-menu](https://www.quilldesignsystem.com/usage/context-menu.md) — A menu that appears at the pointer on right-click or long-press — a secondary, discoverable-only-by-trying affordance, not a replacement for a visible trigger. - [dialog](https://www.quilldesignsystem.com/usage/dialog.md) — A modal window over the page for focused, non-destructive tasks — forms, details, reversible confirmations. - [drawer](https://www.quilldesignsystem.com/usage/drawer.md) — A bottom- or edge-anchored panel built on Vaul, with drag-to-dismiss — a mobile-first alternative to Dialog's centered modal. - [dropdown-menu](https://www.quilldesignsystem.com/usage/dropdown-menu.md) — A click-triggered list of actions anchored to a visible button, with full keyboard navigation and typeahead. - [empty](https://www.quilldesignsystem.com/usage/empty.md) — An empty-state block for zero-data surfaces — icon, title, description, and a primary action, centered in the available space. - [field](https://www.quilldesignsystem.com/usage/field.md) — A form field wrapper that connects a Label, FieldDescription, and FieldError to a control. - [hover-card](https://www.quilldesignsystem.com/usage/hover-card.md) — A glanceable preview that opens after a brief hover-intent delay on a link — a visual enhancement for sighted mouse and keyboard users, informational only. - [icon](https://www.quilldesignsystem.com/usage/icon.md) — The Quill icon component — Material Symbols Outlined at weight 400, shipped as a self-contained core set of 91 names covering every icon the Quill blocks use. - [input](https://www.quilldesignsystem.com/usage/input.md) — A styled native text input for free-form single-line entry — email, name, search, URL. - [input-group](https://www.quilldesignsystem.com/usage/input-group.md) — Merges an input (or textarea) with prefix/suffix addons — icons, buttons, plain text — inside one bordered control. - [input-otp](https://www.quilldesignsystem.com/usage/input-otp.md) — Digit-by-digit secure code entry — email verification, 2FA, PIN. - [item](https://www.quilldesignsystem.com/usage/item.md) — A general-purpose list row — compose ItemMedia (icon or avatar), ItemContent (title + description), and ItemActions (trailing button) into a consistent row for lists, search results, and settings. - [kbd](https://www.quilldesignsystem.com/usage/kbd.md) — A keyboard key badge — a single label rendered as Kbd, or a compound shortcut via KbdGroup — for hotkeys in tooltips, menus, and shortcut references. - [label](https://www.quilldesignsystem.com/usage/label.md) — The accessible name for a form control — always associate it via htmlFor/id or co-location. - [menubar](https://www.quilldesignsystem.com/usage/menubar.md) — A desktop application-style menu strip — a row of always-visible top-level menus, each opening its own dropdown on click. - [native-select](https://www.quilldesignsystem.com/usage/native-select.md) — The browser's own `