Changelog

What's new in the Avesk design system.

  1. v0.11.1Latest

    Component audit fixes

    • ImprovedDark mode: checkbox ticks, Apple and X logos, the switch thumb, file-format tags and status marks all stay readable.
    • ImprovedForms: ChoiceChip looks selected with defaultChecked, NumberField submits the plain number, Select keeps onChange with a ref (react-hook-form), and "Last 7 days" covers exactly 7 days.
    • ImprovedOne focus outline everywhere, one CloseButton, and tooltips and the notification bell in the top layer so nothing crops them.
    • ImprovedToasts show above open dialogs and drawers, queue instead of dropping, wait for you when they have an action, and announce errors at once.
    • ImprovedKeyboard: Tabs always keep a tab stop, filter pills use arrow keys, Pagination shows the first and last page, and the command menu's "See all" can be reached.
    • NewDateRangePicker surface="inline", Rating half stars, DialogBody, and npm run registry:sync, which keeps the registry in step with the code.
    • ChangedAtomic levels corrected (NumberField is a molecule; Table, ColorPicker, Pagination and the settings, notification, auth and agent-limits cards are organisms). audit:ds now checks that no component uses a higher level.
    • Improvednpx avesk-ui init now copies scripts/registry-sync.mjs, so npm run audit:ds works in new projects.
  2. v0.11.0

    Table on React Aria

  3. v0.10.0

    Playground, Bar chart card and smoother motion

  4. v0.9.0

    Install components one at a time

    • Newnpx avesk-ui add <component>: copies a component plus only the files it imports, its docs page and icons if needed; sets up tokens, cn() and packages the first time.
    • Newnpx avesk-ui list shows every component you can add, by category.
    • NewInstallation section on every component page: the add command for npm, pnpm, yarn and bun, or the exact files to copy by hand.
  5. v0.8.2

    Theme tokens audit

    • ImprovedShadows now change with the theme: focus rings, popovers, dialogs and the slider thumb are built from colour variables.
    • ImprovedStronger dark tints, so focus borders and medium badges read clearly on dark.
    • ImprovedChart colours, the row highlight and the neutral gradients follow the theme too; no literal colours left outside tokens.
  6. v0.8.1

    Security headers

    • ImprovedThe site sends a Content Security Policy: only its own scripts, styles, images and fonts, no framing by other sites.
    • ImprovedStandard security headers (nosniff, referrer policy, camera/mic/location off, HSTS in production); the X-Powered-By header is gone.
    • ChangedTests run on Vitest 5, which clears six security advisories in the test tools; Node 22.12 or newer is now required.
  7. v0.8.0

    Dark mode

  8. v0.7.0
  9. v0.6.0
  10. v0.5.0

    New docs site

  11. v0.4.0
  12. v0.1.0

    First release

    • NewAvesk design system: tokens, components, playbook and docs.

Menu

Agent skill

v0.11.1

One 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 skill

Installs 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 init

What'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.

FileWhat it holds
SKILL.mdAlways 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.mdAll 50 components: import line, use when, not when, rules, accessibility and an example. Built from the registry.
references/patterns.mdPage recipes with real imports: page frame, dashboard, table page, form in a dialog, settings, auth, AI surfaces.
references/rules.mdThe full playbook: tokens, text roles, spacing, radius, shadows, motion, accessibility, adding a component.
references/setup.mdHow to add the design system to a new Next.js project, for when it isn't there yet.
references/theming.mdChanging the primary and secondary colour, tinted greys and the font with a theme.css from the Playground; motion tokens.

Where it goes

ClientFolder
Claude Code.claude/skills/ in the project, or ~/.claude/skills/ for every project
Codex, Gemini CLI and other agents~/.agents/skills/
Anything elseWherever 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 --force

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