Working with AI · amezquita design system

The files

After an install, the same files are in node_modules/@amezquita/design-system/, which is where an agent working in your project should read them.

URL	What it is	In the package
`/.well-known/skills/index.json`	Index of the agent skills (1), in the well-known location agents look for.	`skills/index.json`
`/.well-known/skills/amezquita-design-system/SKILL.md`	Build UI with @amezquita/design-system — React components, DTCG design tokens, and a shadcn-spec component registry.	`skills/amezquita-design-system/SKILL.md`
`/llms.txt`	A short index of the package: install, reference links, one line per component.	`llms.txt`
`/llms-full.txt`	The same index with every component inlined, for one fetch.	`llms-full.txt`
`/tokens.json`	Every token with its value in all four theme and mode combinations. If a token isn’t here, it doesn’t exist.	`tokens.json`
`/r/registry.json`	The shadcn-spec registry: a theme item and 34 components.	`registry/registry.json`
`/components/avatar.md`	One Markdown doc per component and sub-component (57): props, tokens, usage, accessibility.	`docs/components/*.md`

The links inside these files still point at amezquita.dk, where the docs used to live. They move to this site in a later release of the package.

The skill

The skill is a short guide for agents: how to install the package, where each component’s docs are, and a list of tokens and props that look plausible but don’t exist. It was tested on fresh agents with no memory of the repo before it shipped.

Point your agent at it

Read node_modules/@amezquita/design-system/skills/amezquita-design-system/SKILL.md before writing any UI.

The registry

Any shadcn-spec client can install a component from the registry. It adds the package as a dependency and writes the component’s tokens into your CSS. It’s the same npm package either way, not a copy of the source.

bash

npx shadcn add https://design.amezquita.dk/r/avatar.json

On Next.js you still need transpilePackages, as in Getting started. The registry installs the dependency, not your bundler config.

The MCP server

A read-only MCP server gives the same data live, one call instead of a file path to remember. It isn’t in the npm package; it runs from the library repo(opens in a new tab). Everything it answers is also in the files above.

Tool	What it returns
`list_components`	List every public component in the design system, optionally filtered by tier (primitives, composition, patterns).
`get_component`	Get the compiled documentation for one public component — full prop table with literal unions expanded, its token list, and a usage example.
`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.
`get_token`	Get the full entry for one exact token — raw value, resolved value on each theme axis, and which components use it.
`validate_token`	Check whether a var(--x) reference or bare token name is real, before using it in CSS.
`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.
`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.

Rules an agent must follow

From the package’s AGENTS.md, as shipped in this version. They apply to people too.

No raw hex colors in component CSS (#0A0A0A) — use a semantic token.
No primitive tokens in component CSS (--color-warm-500, --color-black, --color-teal-*) — go through the semantic layer.
No var(--token, fallback) two-argument form — a token either exists or it doesn't; a fallback hides the difference instead of failing loud.
No hardcoded motion (transition: 200ms) — use a --duration-* token.
No hardcoded spacing (padding: 16px) — use a --space-* token.
No hardcoded line-height values (bare 1/0 excepted for tight single-line/icon-only controls) — use a --line-height-* token.
No @media width that isn't a breakpoint token (768px tablet, 1024px desktop), and no max-width queries — write the literal, mobile-first: @media (min-width: 1024px). JS reads the same values from lib/breakpoints.ts. See ADR 0018.

npm run tokens:lint enforces all seven, plus no-fabricated-token (any var(--x) that doesn't resolve to something real in tokens/), no-deep-bem-nesting, and no-missing-reduced-motion — 10 rules total, itemized in docs/quality.md §2. Read the errors — they tell you the fix and how to suppress a genuine exception (/* lint-ignore: rule-id */, with a one-line reason), which is different from working around a real one.