Agent skill
v0.11.1One command gives your AI assistant everything it needs to build with Avesk: every component, the rules, page recipes and how to set up a project. Claude Code, Codex and other agents that read skills load it on their own, so they use the real components instead of making lookalikes.
Install
Run it from the root of the project that should get the skill.
npx avesk-ui@latest skillInstalls to .claude/skills/avesk-ui in the project you run it from. Commit it so everyone's agent gets it.
Starting a new project
In a fresh create-next-app project (TypeScript, Tailwind, src/, the @/* alias), init copies the design system into src/design-system, adds the cn() helper, the Figma icons and an audit:ds script, sets up the tokens and the Inter font, installs clsx and tailwind-merge, and installs the skill.
npx avesk-ui@latest initWhat's inside
A short SKILL.md the agent always reads, and reference files it opens only when the task needs them, so it stays fast.
| File | What it holds |
|---|---|
| SKILL.md | Always loaded: the build workflow, the rules in short, gotchas and when to read each reference. |
| references/choosing.md | “I need to… → Use → Not this” for every job, from the design system's README. |
| references/components.md | All 50 components: import line, use when, not when, rules, accessibility and an example. Built from the registry. |
| references/patterns.md | Page recipes with real imports: page frame, dashboard, table page, form in a dialog, settings, auth, AI surfaces. |
| references/rules.md | The full playbook: tokens, text roles, spacing, radius, shadows, motion, accessibility, adding a component. |
| references/setup.md | How to add the design system to a new Next.js project, for when it isn't there yet. |
| references/theming.md | Changing the primary and secondary colour, tinted greys and the font with a theme.css from the Playground; motion tokens. |
Where it goes
| Client | Folder |
|---|---|
| Claude Code | .claude/skills/ in the project, or ~/.claude/skills/ for every project |
| Codex, Gemini CLI and other agents | ~/.agents/skills/ |
| Anything else | Wherever it reads skills from: use --path |
Agents load skills when a session starts, so restart the agent or open a new chat after installing.
Updating
The skill carries the design system's version (the latest Changelog entry) and is rebuilt from the component registry every time you install, so new components show up on their own. Re-run with --force to replace an older copy; it prints the old and new version. To update the components too, run npx avesk-ui@latest init --force.
npx avesk-ui@latest skill --forceSKILL.md
---
name: avesk-ui
description: Build screens with the Avesk design system (React + Tailwind v4, 50 components). Use whenever you create or edit UI in a project that has src/design-system — pages, forms, tables, dialogs, drawers, charts, settings, empty and loading states, or any styling — and whenever the user mentions Avesk, the design system, a component by name, or asks to "use our components".
version: 0.11.1
---
# Avesk UI
Avesk is a design system of 50 React components on Tailwind v4 tokens (colours, text roles, 4px spacing, radius, shadows), built from the Figma file "Brandi". Your job is to build with the **real** components, never lookalikes.
Skill version 0.11.1, built 2026-11-18.
## Workflow
1. **Detect the setup.** Check that `src/design-system/components/` exists, `src/app/globals.css` imports `../design-system/tokens.css`, `src/lib/utils.ts` exports `cn`, and `tsconfig.json` maps `@/*` to `./src/*`. If any is missing, follow [references/setup.md](references/setup.md) before writing UI.
2. **Pick components.** Find the job in [references/choosing.md](references/choosing.md) ("I need to… → Use → Not this"). Then read that component's entry in [references/components.md](references/components.md): import line, exports, rules, example. For every prop, open the project's `src/design-system/docs/components/<id>.md`.
3. **Compose the screen** from those components and the rules below. For whole pages (dashboard, table page, settings, auth, form), start from [references/patterns.md](references/patterns.md).
4. **Cover every state:** loading (`Skeleton`, `TableSkeletonRows`, `StatCardSkeleton`), empty (`EmptyState`, or `TableEmptyState` in a table's `renderEmptyState`) and filled.
5. **Verify.** Run `npm run audit:ds` if the script exists (the design system must stay at 0 violations), then `npm run typecheck` (or `npx tsc --noEmit`) and the tests. Look at the screen in the browser at desktop and phone width.
## Rules (the short version)
- **Only design-system parts.** Never a raw `<button>`, `<input>`, `<select>`, `<textarea>` or inline `<svg>` in a screen. Use `Button`, `Pressable`, `Field` + `Input`/`Select`/`Textarea`, `Icon`, `Glyph`.
- **Text roles, not sizes.** `type-title-h1…h6`, `type-label-lg/md/sm`, `type-paragraph-lg/md/sm/xs`, `type-subheading-md/sm`. Never `text-sm`, `text-[15px]`, `leading-*`, `font-semibold` or `font-bold`. Add colour separately: `text-neutral-900/700/600/500`.
- **Token colours only.** `brand-*` (the primary: orange by default, whatever the project's `theme.css` sets), `secondary-*` (optional second accent; grey until a theme sets it), `neutral-*`, `slate-*`, `red/yellow/green/sky/blue/purple/pink/rose-*`, `bg-page`. Never a hex value; a new colour goes into `tokens.css` or `theme.css` first. Don't assume the brand is orange.
- **4px grid.** Spacing in multiples of 4 (`gap-2`, `p-4`, `gap-8`). Half steps only inside components. No `p-[9px]`.
- **One loud thing per screen.** One `variant="primary"` button per view or dialog; everything else is the default secondary.
- **Pass options, don't override.** Use `variant`, `size`, `tone` props. Never restyle a component's size or colour with `className`.
- **Shadows only on things that float.** `shadow-popover` / `shadow-dialog` / `shadow-sheet` are for dropdowns, select lists, tooltips, toasts, dialogs and drawers. Anything that sits on the page (cards, panels, forms, an inline picker) gets a border or `shadow-xs` at most. `ColorPicker` placed on the page takes `surface="inline"`.
- **Meaning never lives in colour alone.** Badges carry a word; errors carry text.
- **Accessible by default.** Every input has a visible label through `Field`; icon-only buttons have `aria-label`; one `h1` per page; motion only under `motion-safe:`.
- **Nothing fits?** Don't build it inside the screen. Add a component to `src/design-system/components/` (one per file, typed `variant`/`size` props mapped with `cn()`), document it, then use it.
## Gotchas
- **Field wiring:** `Field id` must equal the `Input id`, and the input needs `aria-describedby={fieldDescribedBy(id, error)}` plus `aria-invalid` when there's an error.
- **Links that look like buttons:** `<Link href="…" className={buttonClasses("md")}>`, not a `Button` wrapped in a link.
- **Icon vs Glyph:** `Icon` is a product icon exported from Figma (an image from `public/figma/icons/`, only names in `iconNames`). `Glyph` is a generic UI mark (close, chevron, tick). Copying the system without `public/figma/` gives broken icons.
- **Tables** are React Aria grids: `Table aria-label` > `TableHeader` (`TableColumn id`, one with `isRowHeader`) + `TableBody` > `TableRow id` > `TableCell`. Selection and sorting are Table props (`selectionMode`, `selectedKeys`, `sortDescriptor`); never hand-build checkbox columns or sort buttons. Needs `react-aria-components` (the CLI installs it).
- **Toasts** need `<ToastProvider>` once around the area; then `const { toast } = useToast()`.
- **Dialog and Drawer are controlled:** `open` + `onOpenChange`. Put `data-autofocus` on the field that should get focus. `Sheet` is deprecated; use `Drawer`.
- **Dialog or Drawer?** A short form or confirmation → `Dialog`. Reading details beside a list, or filtering it → `Drawer`. Content that deserves a URL → a page.
- **Checkbox or Switch?** Applies after Save → `Checkbox`. Applies immediately → `Switch`.
- **Tabs, Filter pills, Segmented control or Choice chip?** Sections of a page → `Tabs`. Narrowing a list with counts → `SegmentedFilter`. 2–5 short periods or views → `SegmentedControl`. An answer in a form → `ChoiceChip`.
- **New floating panels** (a custom menu or popover) use `useFloating` from `@/design-system/components/floating`: top layer so parents can't crop them, flips above the trigger when there's no room below. Never `absolute top-full`.
- **Motion:** use `ease-smooth` and the tokens (`animate-menu-in` for anything that pops up, `DIALOG_MOTION` from `@/design-system/components/dialog` for a native `<dialog>`), never `ease-out` or a hand-written cubic-bezier. Drawers have no animation. Always behind `motion-safe:`.
- **Dark mode** is `data-theme="dark"` on `<html>`. Every token flips by itself, so never write `dark:` classes.
- **Charts:** the main series is `color: "brand"`, a second one `"secondary"` (it stays grey without a secondary colour), a quiet one `"neutral"`. Amounts over periods (cash in and out by month) → `BarChartCard` (`variant="stacked"` or `"grouped"`); a trend → `AreaChartCard`; an amount and a rate → `ComboChartCard`; ranking items → `BarListCard`.
- **Narrow areas:** inside a panel or preview that's narrower than the window, size grids with container queries (`@container` on the wrapper, `@3xl:grid-cols-4`), not `lg:`/`xl:` breakpoints.
- **Theme and font changes** go in the project's `theme.css` and root layout, never in components: see [references/theming.md](references/theming.md).
- **Money and roles:** components never decide to show money; the screen does.
## References
| File | Read it when |
| --- | --- |
| [references/choosing.md](references/choosing.md) | Picking a component for a job |
| [references/components.md](references/components.md) | Using a component: import, exports, rules, example |
| [references/patterns.md](references/patterns.md) | Building a whole page |
| [references/rules.md](references/rules.md) | Tokens, type scale, spacing, radius, shadows, motion, accessibility, adding a component |
| [references/theming.md](references/theming.md) | Changing the primary or secondary colour, the greys or the font |
| [references/setup.md](references/setup.md) | The project doesn't have the design system yet |