# @amezquita/design-system — full reference

> Token-first, multi-brand design system — DTCG tokens, Style Dictionary, CI-enforced linting/contrast/accessibility, Figma sync, and agent-safe governance.

## Install

```bash
npm install @amezquita/design-system
```

## Fonts

The package ships no font files. Load the fonts a brand names from Google Fonts; `tokens/fonts.json` has the same links, machine-readable.

- base: JetBrains Mono. `<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700;800&display=swap">`
- portfolio: Schibsted Grotesk and JetBrains Mono. `<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Schibsted+Grotesk:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600;700;800&display=swap">`

## Tokens

373 tokens total, resolved across base/portfolio × light/dark. Full values: https://design.amezquita.dk/tokens.json

- primitive: 126
- component: 106
- color: 43
- typography: 39
- spacing: 19
- size: 13
- motion: 7
- elevation: 7
- shadow: 5
- radius: 4
- opacity: 2
- border: 2

## Primitives

### Avatar

User profile picture with fallback to initials when no image is provided

- Import: `import { Avatar } from '@amezquita/design-system/components/primitives/Avatar'`
- Token prefix: `avatar-*` (8 tokens)
- Storybook: Components/Avatar
- Stories: WithImage, WithFallback, WithCustomFallback, AllSizes, Group, GroupWithOverflow, DarkMode

### Badge

Small status indicator or numeric count overlay attached to another element

- Import: `import { Badge } from '@amezquita/design-system/components/primitives/Badge'`
- Token prefix: `badge-*` (5 tokens)
- Storybook: Components/Badge
- Stories: Default, Count, Dot, AllVariants, AllShapes, AllVariantsAllShapes, DarkMode

### Button

Trigger for user actions; renders as `<button>` or `<a>` depending on context

- Import: `import { Button } from '@amezquita/design-system/components/primitives/Button'`
- Token prefix: `button-*` (17 tokens)
- Storybook: Components/Button
- Stories: Primary, Secondary, Ghost, Link, Loading, LoadingSecondary, FullWidth, WithIcon, Disabled, WithArrow, Motion, AllVariants, AllStates, DarkMode

### Checkbox

Single boolean selection with an associated label; supports indeterminate state

- Import: `import { Checkbox } from '@amezquita/design-system/components/primitives/Checkbox'`
- Token prefix: `checkbox-*` (1 tokens)
- Storybook: Components/Checkbox
- Stories: Default, Checked, Indeterminate, Disabled, DisabledChecked, Controlled, AllStates, NoLabel, DarkMode

### Heading

Semantic heading element (H1–H5 visual sizes, any `<h1>`–`<h6>` tag) with a visual size decoupled from its document-outline level

- Import: `import { Heading } from '@amezquita/design-system/components/primitives/Heading'`
- Token prefix: `heading-*` (0 tokens)
- Storybook: Components/Heading
- Stories: H1, H2, H3, H4, H5, AllLevels, LevelAsDecoupling, DarkMode

### Input

Labelled single-line text entry with hint and error states

- Import: `import { Input } from '@amezquita/design-system/components/primitives/Input'`
- Token prefix: `input-*` (0 tokens)
- Storybook: Components/Input
- Stories: Default, WithHint, WithError, Disabled, NoLabel, WithPrefix, WithSuffix, Clearable, Search, AllStates, DarkMode

### Label

Standalone form label element — used when a label must be decoupled from its input

- Import: `import { Label } from '@amezquita/design-system/components/primitives/Label'`
- Token prefix: `label-*` (0 tokens)
- Storybook: Components/Label
- Stories: Default, Required, Disabled, AllVariants, DarkMode

### Link

Navigation to another page or resource; use Link for navigation and Button for actions

- Import: `import { Link } from '@amezquita/design-system/components/primitives/Link'`
- Token prefix: `link-*` (0 tokens)
- Storybook: Primitives/Link
- Stories: Default, Standalone, External, AsChild, AllVariants, DarkMode

### Radio

Single-selection control within a mutually exclusive group

- Import: `import { Radio } from '@amezquita/design-system/components/primitives/Radio'`
- Token prefix: `radio-*` (2 tokens)
- Storybook: Components/Radio
- Stories: Default, WithDefault, Horizontal, Disabled, WithDisabledOption, Controlled, AllStates, DarkMode

### Select

Dropdown for choosing a single value from a list; supports grouped options

- Import: `import { Select } from '@amezquita/design-system/components/primitives/Select'`
- Token prefix: `select-item-padding-*` (2 tokens)
- Storybook: Components/Select
- Stories: Default, WithDefaultValue, Grouped, Disabled, DarkMode

### Skeleton

Placeholder loading state that mirrors the geometry of the content it replaces

- Import: `import { Skeleton } from '@amezquita/design-system/components/primitives/Skeleton'`
- Token prefix: `skeleton-*` (3 tokens)
- Storybook: Components/Skeleton
- Stories: Text, MultiLine, Circle, Rect, CardSkeleton, DarkMode

### SkipLink

First Tab stop on the page that lets keyboard users jump past the header to the main content

- Import: `import { SkipLink } from '@amezquita/design-system/components/primitives/SkipLink'`
- Token prefix: `skiplink-*` (0 tokens)
- Storybook: Primitives/SkipLink
- Stories: Default, Focused, CustomTarget, DarkMode

### Spinner

Indeterminate loading indicator for in-progress operations

- Import: `import { Spinner } from '@amezquita/design-system/components/primitives/Spinner'`
- Token prefix: `spinner-stroke-*` (1 tokens)
- Storybook: Components/Spinner
- Stories: Default, AllSizes, OnColoredBackground, DarkMode

### Switch

Binary toggle for on/off settings; renders as a styled checkbox under the hood

- Import: `import { Switch } from '@amezquita/design-system/components/primitives/Switch'`
- Token prefix: `switch-*` (3 tokens)
- Storybook: Components/Switch
- Stories: Default, Checked, Disabled, DisabledChecked, NoLabel, Controlled, AllStates, DarkMode

### Tag

Inline label for categorising or annotating content — non-interactive

- Import: `import { Tag } from '@amezquita/design-system/components/primitives/Tag'`
- Token prefix: `tag-*` (4 tokens)
- Storybook: Components/Tag
- Stories: Default, Accent, Muted, WithIcon, Removable, AllVariants, InContext, DarkMode

### Textarea

Multi-line text entry with label, hint, and error states — mirrors Input API

- Import: `import { Textarea } from '@amezquita/design-system/components/primitives/Textarea'`
- Token prefix: `textarea-*` (0 tokens)
- Storybook: Components/Textarea
- Stories: Default, WithHint, WithError, Disabled, WithCharacterCount, AllStates, DarkMode

## Composition

### Alert

Contextual inline feedback message with semantic severity levels (info, success, warning, error)

- Import: `import { Alert } from '@amezquita/design-system/components/composition/Alert'`
- Token prefix: `alert-*` (4 tokens)
- Storybook: Components/Alert
- Stories: Default, AllVariants, Dismissible, NoTitle, NoIcon, DarkMode

### AlertDialog

Confirmation gate for an action the user must explicitly accept or decline — real `alertdialog` role, no outside-click/close-button dismiss, unlike Dialog

- Import: `import { AlertDialog } from '@amezquita/design-system/components/composition/AlertDialog'`
- Token prefix: `alertdialog-*` (0 tokens)
- Storybook: Components/AlertDialog
- Stories: Default, WithBody, NoDescription, AllSizes, DarkMode

### Card

Compound container for grouped content — composed from named sub-components

- Import: `import { Card } from '@amezquita/design-system/components/composition/Card'`
- Token prefix: `card-horizontal-media-*` (1 tokens)
- Storybook: Components/Card
- Stories: Default, Ghost, Interactive, Horizontal, Compact, Featured, WithBody, WithMedia, AllVariants, DarkMode

### Dialog

Overlay for tasks or information requiring focused attention

- Import: `import { Dialog } from '@amezquita/design-system/components/composition/Dialog'`
- Token prefix: `dialog-*` (6 tokens)
- Storybook: Components/Dialog
- Stories: Default, Small, Large, Scrollable, WithForm, NoDescription, AllSizes, DarkMode

### Drawer

Side-anchored slide-in panel for supplemental content or secondary navigation

- Import: `import { Drawer } from '@amezquita/design-system/components/composition/Drawer'`
- Token prefix: `drawer-*` (9 tokens)
- Storybook: Components/Drawer
- Stories: Default, FilterPanel, AllSides, Sizes, DarkMode

### Menu

Dropdown list of actions opened from a trigger: account menus, overflow ("more") menus, row actions

- Import: `import { Menu } from '@amezquita/design-system/components/composition/Menu'`
- Token prefix: `menu-*` (0 tokens)
- Storybook: Composition/Menu
- Stories: Default, Open, WithGroupLabelsAndIcons, Overflow, DarkMode

### NavigationMenu

The site's header navigation: top-level links, plus groups that open a dropdown of links. Hidden below 1024px, where SideNav's drawer carries the same links (its `headerItems`)

- Import: `import { NavigationMenu } from '@amezquita/design-system/components/composition/NavigationMenu'`
- Token prefix: `navigationmenu-*` (0 tokens)
- Storybook: Composition/NavigationMenu
- Stories: Default, Open, WithIcons, NoCurrentPage, DarkMode

### ThemeScope

Gives one part of a page its own brand, mode, or both; overlays opened inside it (Dialog, Drawer, AlertDialog, Menu, Select, Tooltip) take the same, although they render at the end of the page

- Import: `import { ThemeScope } from '@amezquita/design-system/components/composition/ThemeScope'`
- Token prefix: `themescope-*` (0 tokens)
- Storybook: Composition/ThemeScope
- Stories: Default, MenuOpen, Nested, DarkMode

### Toast

Ephemeral notification pushed to a corner of the viewport; auto-dismisses after a timeout

- Import: `import { Toast } from '@amezquita/design-system/components/composition/Toast'`
- Token prefix: `toast-*` (6 tokens)
- Storybook: Components/Toast
- Stories: Default, AllVariants, TitleOnly, DarkMode

### Tooltip

Contextual label revealed on hover or focus — supplements an icon or truncated text

- Import: `import { Tooltip } from '@amezquita/design-system/components/composition/Tooltip'`
- Token prefix: `tooltip-*` (6 tokens)
- Storybook: Components/Tooltip
- Stories: Default, AllSides, IconButtons, LongContent, NoDelay, DarkMode

## Patterns

### Accordion

Collapsible content sections with animated expand/collapse; supports single or multi-open modes

- Import: `import { Accordion } from '@amezquita/design-system/components/patterns/Accordion'`
- Token prefix: `accordion-*` (4 tokens)
- Storybook: Components/Accordion
- Stories: Default, Multiple, WithDisabledItem, DefaultOpen, DarkMode

### Breadcrumb

Hierarchical page location trail; the last item is the current page (non-linked)

- Import: `import { Breadcrumb } from '@amezquita/design-system/components/patterns/Breadcrumb'`
- Token prefix: `breadcrumb-*` (3 tokens)
- Storybook: Components/Breadcrumb
- Stories: Default, TwoLevels, SingleLevel, CustomSeparator, LongLabels, DarkMode

### DataTable

Sortable, filterable, paginated table for structured datasets

- Import: `import { DataTable } from '@amezquita/design-system/components/patterns/DataTable'`
- Token prefix: `datatable-*` (3 tokens)
- Storybook: Components/DataTable
- Stories: Default, Sortable, WithSelection, WithPagination, WithPaginationAndSelection, WithColumnFilters, WithToolbarAndFilters, WithFiltersAndSelection, Striped, Compact, Empty, DarkMode

### EmptyState

Placeholder for zero-content states — icon, heading, supporting text, and an optional action

- Import: `import { EmptyState } from '@amezquita/design-system/components/patterns/EmptyState'`
- Token prefix: `emptystate-padding-*` (2 tokens)
- Storybook: Components/EmptyState
- Stories: Default, AllVariants, Compact, DarkMode

### Hero

Page-level section header with eyebrow, title, lead text, and an action slot

- Import: `import { Hero } from '@amezquita/design-system/components/patterns/Hero'`
- Token prefix: `hero-*` (8 tokens)
- Storybook: Components/Hero
- Stories: Default, WithEyebrowAndLead, Centered, TitleOnly, PageHeader, DarkMode

### Pagination

Page navigation controls for multi-page data sets; exposes current page and total page count

- Import: `import { Pagination } from '@amezquita/design-system/components/patterns/Pagination'`
- Token prefix: `pagination-button-*` (4 tokens)
- Storybook: Components/Pagination
- Stories: Default, EdgeCases, Compact, DarkMode

### SideNav

Section navigation: inline beside the content (240px wide) from 1024px up; below that, in a left Drawer opened by `SideNavTrigger`, which hides itself from 1024px up. Wrap both in `SideNavProvider`

- Import: `import { SideNav } from '@amezquita/design-system/components/patterns/SideNav'`
- Token prefix: `side-nav-*` (1 tokens)
- Storybook: Patterns/SideNav
- Stories: Default, WithIcons, Collapsed, MobileDrawer, DrawerOnly, PageShell, DarkMode, CollapsedWithoutIcons

### Table

Static data table with semantic header, body, and row structure

- Import: `import { Table } from '@amezquita/design-system/components/patterns/Table'`
- Token prefix: `table-header-font-*` (1 tokens)
- Storybook: Components/Table
- Stories: Default, Striped, Bordered, Compact, AllVariants, WithCaption, WithFoot, HorizontalScroll, DarkMode

### Tabs

Segmented view switcher with full keyboard navigation; built on Radix Tabs

- Import: `import { Tabs } from '@amezquita/design-system/components/patterns/Tabs'`
- Token prefix: `tabs-*` (2 tokens)
- Storybook: Components/Tabs
- Stories: Default, AllVariants, Sizes, WithDisabledTab, DarkMode

## MCP server

Read-only tools over the same files this package ships, read live instead of from a snapshot. The server isn't in the npm package: clone [the repo](https://github.com/anto-amezquita/design-system) and run `node scripts/mcp-server.mjs` (stdio).

### list_components

List every public component in the design system, optionally filtered by tier (primitives, composition, patterns). Excludes internal-only components (e.g. BaseSheet) and compound sub-components (e.g. CardHeader) — those ride along with their parent's own usage example and resolve individually via get_component/get_registry_item by name (e.g. "CardHeader"), but aren't separate top-level components in their own right. tokenCount 0 means the component has no component-scoped tokens of its own (it styles entirely through inherited semantic tokens) — not that its tokens are unindexed.

### get_component

Get the compiled documentation for one public component — full prop table with literal unions expanded, its token list, and a usage example. Also resolves a compound sub-component directly by its own name (e.g. "CardHeader", "TableCell") even though list_components doesn't enumerate those separately — its doc twin points back to the parent's usage example rather than repeating one. Reads docs/components/<slug>.md, the same artifact generated for and served to agents elsewhere in this system.

### search_tokens

Search all design tokens (primitive, semantic, and component-scoped) by a substring match on name or CSS variable, optionally narrowed to one category. Returns name, cssVar, type, and the resolved value on each of the 4 theme axes (base-light, base-dark, portfolio-light, portfolio-dark).

### get_token

Get the full entry for one exact token — raw value, resolved value on each theme axis, and which components use it. Call search_tokens first if you don't know the exact name.

### validate_token

Check whether a var(--x) reference or bare token name is real, before using it in CSS. Reuses two of this repo's actual lint rules from scripts/lint-tokens.mjs — no-fabricated-token and no-token-fallback, the same checks npm run validate enforces for those two rules specifically. Does NOT check no-primitive-tokens (a primitive like --color-warm-500 is a real token and validates true here, but is still banned in component CSS — call get_component or check tokens/global.json's "primitive" category if you need that distinction) or any of the other CSS-structural lint rules (no-raw-hex, hardcoded motion/spacing, etc.), and can't see a CSS file's own locally-declared custom properties (a legitimate component-private value like --button-glow-color reads as fabricated here, same as it would to no-fabricated-token run without that file's context).

### get_registry_item

Get the shadcn-spec registry-item.json for one public component — its npm dependency, cross-component registryDependencies, and the CSS custom properties it needs. Use this to decide whether to `npx shadcn add` a component or hand-write it. Reads registry/<slug>.json, generated by scripts/build-registry-manifests.mjs.

### get_skill

Get the current agent skill content (SKILL.md) — the same file served from /.well-known/skills/ for agents that read the skill format instead of calling MCP tools directly. Useful to compare what the skill claims against what these tools actually return.