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

Documentation

Which component to use for which job, how to use it, and where it is already used. 50 components. Built from docs/guidance.json and docs/registry.json.

Actions · I need to…UseOn screens
Any action with a label: save, create, cancel, openButton19
A whole card, tile or row is clickablePressable7
Sign-in and sign-up screens that offer a third-party accountSocial button–
Forms · I need to…UseOn screens
Agreeing to termsCheckbox1
Short answers in onboarding or forms: team size, servicesChoice chip1
Editing a palette colour or a brand colourColour picker–
A deadline, start date or due date (DatePicker)Date picker–
Every single-line text, number, email, URL or search inputField and inputs7
Attaching files to a project or brief (FileUpload + FileCard)File upload–
An exact number matters: seats, quantity, hours, a price, a percentageNumber field–
2–5 mutually exclusive options that should all be visibleRadio–
Collecting or showing a 1–5 scoreRating–
Switching between 2–5 short, mutually exclusive periods or views: Weekly / Monthly / Yearly, List / BoardSegmented control–
An approximate value in a known range: opacity, volume, budget share, hoursSlider–
Turning a setting on or off with immediate effect (notifications, visibility)Switch–
Data display · I need to…UseOn screens
Status of a row or card: Active, Draft, PaidBadge6
Showing who owns or is assigned to somethingPerson avatar5
Team lists and member panelsProfile card–
Summary numbers at the top of a dashboard or reportStat card1
Comparing rows of the same kind across columns: projects, invoices, peopleTable1
Feedback · I need to…UseOn screens
The assistant is drafting a reply, proposal, invoice or brief and the wait is open-endedAgent thinking–
Something the person should know while they stay on the page: an overdue invoice, a failed save, a tipAlert–
A short list of things someone must act on, like Home's "Needs your attention"Callout card1
A screen or section has no data yet (required on every screen)Empty state2
The loading state of every screenSkeleton17
Confirming an action: saved, copied, archived (with Undo)Toast–
Explaining what an icon-only control does (it still needs its own aria-label)Tooltip–
Overlays · I need to…UseOn screens
Global search across people, files and actionsCommand menu–
A short form: create, rename, addDialog3
Three or more actions on a row or page that don't all deserve a buttonDropdown menu–
Filtering a list without leaving itDrawer2
Navigation · I need to…UseOn screens
Detail pages two or more levels deep: Projects & Clients › ProjectBreadcrumbs1
Under a table or list with more rows than one pagePagination1
Narrowing a list by status inside a page or tab: All / Due / PaidFilter pills2
Switching between views of the same data (All / Active / Completed) with countsTabs5
Layout · I need to…UseOn screens
FAQs and long settings that would crowd a pageAccordion–
Wide lists or tables that scroll sidewaysScroll area6
Icons · I need to…UseOn screens
A component or screen needs a close, chevron, tick, plus, bin, search, cloud, home or calendar iconGlyph4
Navigation and product icons that exist in the Figma file: dashboard, users, pencil, bell, search…Icon11
Patterns · I need to…UseOn screens
The login and sign-up pagesAuth card–

Component documentation

40 of 40 components

Button

atomUsed in 19 files

Triggers an action. Seven hierarchies, four heights, destructive and icon-only forms.

@/design-system/components/button · exports buttonIconSize buttonClasses Button CloseButton · Figma 108:10903, 108:12452, 108:10850

Use it when

  • Any action with a label: save, create, cancel, open
  • Icon-only actions (edit, close, add) with iconOnly and an aria-label
  • A link that should look like a button: buttonClasses() on <Link>

Don’t use it when

  • The clickable thing is a card, tile, row or custom chip → pressable
  • Navigating between views of one page → tabs
  • Choosing one of several options in a form → radio or choice-chip
  • A list of actions behind one trigger → dropdown-menu

Rules

  • One primary button per view or dialog; everything else secondary-gray (the default)
  • Text is 14px at every size (12px for sm); sizes change height only: sm 28, md 36, lg 40, xl 44
  • destructive only for actions that delete or can't be undone
  • Never override size or colour with className

Accessibility

  • iconOnly needs aria-label
  • Focus shows a 4px ring; disabled removes it from the tab order

Example

<Button variant="primary">Create project</Button>
<Button>Cancel</Button>
<Button variant="tertiary-gray" iconOnly aria-label="Edit project">
  <Icon name="pencil" size={20} />
</Button>
<Link href="/projects" className={buttonClasses("md")}>View project</Link>

Properties · Button

PropTypeDefault
size"sm" | "md" | "lg" | "xl""md"
variant"primary" | "secondary-color" | "secondary-gray" | "tertiary-color" | "tertiary-gray" | "link-color" | "link-gray""secondary-gray"
dotbooleanfalse
destructivebooleanfalse
iconOnlybooleanfalse

Blocks · how it connects

Built from
Glyph
Used by components
Agent limits card, Alert, Auth card, Bar list card, Colour picker, Command menu, Dropdown menu, File upload, Notification Center, Pagination, Drawer, Settings Modal, Toast
Used on screens
Dashboard, Projects & Clients, Finance & Growth, Design Inspiration, Proposals & Scope, Onboarding, App shell
Show 19 files
  • app/(app)/_components/dashboard/dashboard-projects.tsx
  • app/(app)/_components/dashboard/needs-attention.tsx
  • app/(app)/_components/dashboard/overview-header.tsx
  • app/(app)/_components/projects/projects-empty.tsx
  • app/(app)/_components/projects/projects-table.tsx
  • app/(app)/finance/_components/finance-gate.tsx
  • app/(app)/finance/_components/overview-view.tsx
  • app/(app)/finance/_components/payments-view.tsx
  • app/(app)/library/_components/add-site-dialog.tsx
  • app/(app)/library/_components/library-view.tsx
  • app/(app)/projects/_components/add-client-dialog.tsx
  • app/(app)/projects/_components/client-cards.tsx
  • app/(app)/projects/_components/create-project-dialog.tsx
  • app/(app)/projects/_components/projects-clients-view.tsx
  • app/(app)/projects/_components/projects-grouped-list.tsx
  • app/(app)/projects/[id]/_components/project-detail-view.tsx
  • app/(app)/proposals/_components/proposals-view.tsx
  • app/(onboarding)/onboarding/_components/onboarding-view.tsx
  • components/layout/topbar.tsx

Pressable

atomUsed in 7 files

Unstyled button for clickable surfaces: cards, tiles, list rows, chips with custom content.

@/design-system/components/pressable · exports Pressable

Use it when

  • A whole card, tile or row is clickable
  • A chip or swatch with custom content toggles something

Don’t use it when

  • The action is a label or an icon → button
  • It navigates to another page → next/link

Rules

  • Never write a raw <button> in a screen; use Button or Pressable
  • The surface supplies its own look; Pressable supplies cursor, focus ring and disabled handling

Accessibility

  • Set aria-pressed, aria-expanded or aria-current when the surface has state

Example

<Pressable aria-current={selected ? "true" : undefined} onClick={select} className="rounded-xl border p-3">
  …card content…
</Pressable>

Blocks · how it connects

Built from
Tokens only
Used by components
None yet
Used on screens
Design Inspiration, Projects & Clients, Proposals & Scope, Onboarding, App shell
Show 7 files
  • app/(app)/library/_components/library-view.tsx
  • app/(app)/projects/_components/client-cards.tsx
  • app/(app)/projects/_components/create-project-dialog.tsx
  • app/(app)/projects/_components/projects-grouped-list.tsx
  • app/(app)/proposals/_components/proposals-view.tsx
  • app/(onboarding)/onboarding/_components/onboarding-steps.tsx
  • components/layout/sidebar.tsx

Social button

atomNot used on a screen yet

"Sign in with …" button for Google, Facebook, Apple, X, Figma and Dribbble.

@/design-system/components/social-button · exports SocialButton SocialButtonGroup · Figma 108:11967, 108:12238

Use it when

  • Sign-in and sign-up screens that offer a third-party account

Don’t use it when

  • Any other action → button

Rules

  • Use SocialButtonGroup for a stack (buttons) or a row (icons)
  • 40px tall, the same as inputs

Accessibility

  • iconOnly keeps the full "Sign in with X" accessible name

Example

<SocialButtonGroup>
  <SocialButton provider="google" />
  <SocialButton provider="apple" />
</SocialButtonGroup>

Properties · SocialButton

PropTypeDefault
provider *"google" | "facebook" | "apple" | "x" | "figma" | "dribbble"–
theme"brand" | "color-with-brand" | "color""brand"
iconOnlybooleanfalse
labelstring–

Properties · SocialButtonGroup

PropTypeDefault
layout"buttons" | "icons""buttons"
classNamestring–
children *ReactNode–

Blocks · how it connects

Built from
Tokens only
Used by components
Auth card
Used on screens
Not used on a screen yet

Checkbox

atomUsed in 1 file

Tick box with checked and mixed states.

@/design-system/components/checkbox · exports Checkbox CheckboxMark

Use it when

  • Agreeing to terms
  • Selecting several rows or options
  • "Select all" with the indeterminate state

Don’t use it when

  • A setting that turns on immediately → switch
  • Only one option can be chosen → radio
  • Pill-shaped multi-choice in a form → choice-chip

Rules

  • Wrap it in a <label> with its text

Accessibility

  • Native checkbox; label gives the name

Example

<label className="flex items-center gap-2 type-paragraph-sm">
  <Checkbox checked={agreed} onChange={(e) => setAgreed(e.target.checked)} /> I agree
</label>

Blocks · how it connects

Built from
Glyph
Used by components
Auth card, Table
Used on screens
Onboarding
Show 1 file
  • app/(onboarding)/onboarding/_components/onboarding-view.tsx

Choice chip

atomUsed in 1 file

Pill-shaped answer in a form: a radio for one, a checkbox (with tick) for several.

@/design-system/components/choice-chip · exports ChoiceChip

Use it when

  • Short answers in onboarding or forms: team size, services

Don’t use it when

  • Filtering a list on a page → segmented-filter
  • Options need descriptions → radio (RadioCard)

Rules

  • Group chips under a visible question label

Accessibility

  • Real radio or checkbox inside a label

Example

<ChoiceChip type="checkbox" label="Branding" checked={on} onChange={toggle} />

Properties · ChoiceChip

PropTypeDefault
type *"radio" | "checkbox"–
label *string–

Blocks · how it connects

Built from
Glyph
Used by components
None yet
Used on screens
Onboarding
Show 1 file
  • app/(onboarding)/onboarding/_components/onboarding-view.tsx

Colour picker

organismNot used on a screen yet

Panel for choosing a solid colour or gradient: shade area, hue strip, hex and opacity.

@/design-system/components/color-picker · exports normalizeHex colorValueToCss ColorPicker

Use it when

  • Editing a palette colour or a brand colour

Don’t use it when

  • Choosing from a fixed set of colours → radio or pressable swatches

Rules

  • Controlled: pass value and onChange; use colorValueToCss() to preview
  • Opened from a swatch → the default card with its shadow; placed on the page or in a panel → surface="inline" (no card, no shadow)

Accessibility

  • Shade area is a slider with arrow keys (Shift = ×10); hue is a native range

Example

<ColorPicker value={{ kind: "solid", hex: "#ea580c", alpha: 100 }} onChange={setColor} modes={["solid"]} />

Properties · ColorPicker

PropTypeDefault
value *ColorValue–
onChange *(value: ColorValue) => void–
modesColorPickerMode[]["image", "solid", "gradient"]
onRemove() => void–
onAdd() => void–
disabledboolean–
idstring"color-picker"
surface"popover" | "inline""popover"
classNamestring–

Blocks · how it connects

Built from
Button, Tabs, Glyph
Used by components
None yet
Used on screens
Not used on a screen yet

Date picker

moleculeNot used on a screen yet

DatePicker is a field that opens a calendar; DateRangePicker is a panel with quick presets; Calendar is the grid they share.

@/design-system/components/date-picker · exports formatDate Calendar DatePicker defaultRangePresets DateRangePicker

Use it when

  • A deadline, start date or due date (DatePicker)
  • A reporting period: last 7 days, month to date (DateRangePicker)

Don’t use it when

  • Only a month or year → field (Select)
  • A time of day → field (Input type=time)

Rules

  • Values are ISO strings "YYYY-MM-DD"; show them with formatDate()
  • Wrap DatePicker in Field for the label
  • The calendar opens below the field, or above when there's no room, in the top layer so no scrolling parent crops it (useFloating)
  • DateRangePicker on the page takes surface="inline" (no shadow); the default popover surface is for one opened from a button

Accessibility

  • Grid with arrow keys, PageUp/PageDown for months; Escape closes and returns focus

Example

<Field id="due" label="Due date" required>
  <DatePicker id="due" value={due} onChange={setDue} />
</Field>
<DateRangePicker value={range} onChange={setRange} />

Properties · DatePicker

PropTypeDefault
id *string–
value *string | null–
onChange *(value: string | null) => void–
placeholderstring"Select date"
disabledbooleanfalse
minstring–
maxstring–
namestring–
aria-invalidboolean–
aria-describedbystring–
classNamestring–

Properties · DateRangePicker

PropTypeDefault
value *DateRange–
onChange *(range: DateRange) => void–
presetsDateRangePreset[]defaultRangePresets
minstring–
maxstring–
classNamestring–

Blocks · how it connects

Built from
Glyph
Used by components
None yet
Used on screens
Not used on a screen yet

Field and inputs

moleculeUsed in 7 files

Field wraps a control with a label and a hint or error. Input, Select, Textarea, InputSelect and InputButton are the controls.

@/design-system/components/field · exports frame controlStates Field fieldDescribedBy Input InputButton InputSelect Select Textarea · Figma 108:4958, 108:5897, 108:4945, 108:4840

Use it when

  • Every single-line text, number, email, URL or search input
  • A dropdown of fewer than ~15 options (Select)
  • Multi-line text (Textarea)

Don’t use it when

  • Picking a date → date-picker
  • Yes/no that applies immediately → switch
  • 2–5 visible choices → radio or choice-chip
  • Uploading a file → file-upload

Rules

  • Always wrap a control in Field so it has a visible label
  • Mark errors with aria-invalid on the control and error on Field; link with fieldDescribedBy()
  • Optional fields say "(optional)"; required ones say nothing
  • Inputs are 40px tall
  • Select's list opens below, or above when there's no room, in the top layer so a scrolling panel or dialog can't crop it

Accessibility

  • Label is tied by id/htmlFor
  • Hint and error are announced through aria-describedby
  • help text on Input becomes the help icon's accessible name

Example

<Field id="site-url" label="Web address" required error={error}>
  <Input
    id="site-url"
    leadingText="https://"
    aria-invalid={error ? true : undefined}
    aria-describedby={fieldDescribedBy("site-url", error)}
  />
</Field>

Properties · Field

PropTypeDefault
id *string–
label *string–
requiredboolean–
hintstring–
errorstring–
children *ReactNode–

Properties · Input

PropTypeDefault
leadingIconIconName–
leadingGraphicReactNode–
leadingTextstring–
leadingSelectReactNode–
prefixstring–
trailingSelectReactNode–
trailingButtonReactNode–
helpstring–

Blocks · how it connects

Built from
Icon, Glyph
Used by components
Auth card, Number field
Used on screens
Finance & Growth, Design Inspiration, Projects & Clients, Onboarding, App shell
Show 7 files
  • app/(app)/finance/_components/subscriptions-view.tsx
  • app/(app)/library/_components/add-site-dialog.tsx
  • app/(app)/projects/_components/add-client-dialog.tsx
  • app/(app)/projects/_components/create-project-dialog.tsx
  • app/(app)/projects/[id]/_components/project-detail-view.tsx
  • app/(onboarding)/onboarding/_components/onboarding-view.tsx
  • components/layout/topbar.tsx

File upload

moleculeNot used on a screen yet

FileUpload (drop area), FileCard (one file with status), FileFormatIcon, ImageUpload (avatar or logo) and UploadSource.

@/design-system/components/file-upload · exports formatBytes fileFormatFor FileFormatIcon FileUpload UploadSource FileCard ImageUpload

Use it when

  • Attaching files to a project or brief (FileUpload + FileCard)
  • Setting a profile picture or company logo (ImageUpload)
  • Showing a file's type in a list (FileFormatIcon)

Don’t use it when

  • Pasting a link to a file → field (Input type=url)

Rules

  • The component never uploads: the screen sends files and feeds progress and status into FileCard
  • Always state accepted formats and the size limit in hint

Accessibility

  • Real file input; Enter or Space opens the picker; FileCard progress is a progressbar

Example

<FileUpload accept=".pdf,image/*" maxSize={50 * 1024 * 1024} hint="PDF or images, up to 50 MB." onFiles={add} />
<FileCard name="brief.pdf" size={122880} progress={40} status="uploading" onRemove={cancel} />

Properties · FileFormatIcon

PropTypeDefault
labelstring"PDF"
color"red" | "orange" | "yellow" | "green" | "sky" | "blue" | "purple" | "pink" | "gray""red"
size"sm" | "md""md"
classNamestring–

Properties · FileUpload

PropTypeDefault
idstring–
acceptstring"image/png,image/jpeg"
maxSizenumber–
multiplebooleanfalse
disabledbooleanfalse
titleReactNode"Choose a file or drag & drop it here."
hintReactNode"Min 400×400px, PNG or JPEG"
iconReactNode–
buttonLabelstring | null"Browse File"
shape"box" | "circle""box"
childrenReactNode–
onFiles *(files: File[]) => void–
onReject(files: RejectedFile[]) => void–
aria-describedbystring–
classNamestring–

Properties · FileCard

PropTypeDefault
name *string–
size *number–
progressnumber0
status *"uploading" | "complete" | "error"–
errorstring–
onRemove() => void–
onRetry() => void–
classNamestring–

Properties · ImageUpload

PropTypeDefault
srcstring | null–
kind"person" | "company""person"
titlestring"Upload image"
hintstring"Min 400×400px, PNG or JPEG"
compactbooleanfalse
acceptstring"image/png,image/jpeg"
disabledbooleanfalse
onUpload *(file: File) => void–
onRemove() => void–
classNamestring–

Blocks · how it connects

Built from
Button, Glyph
Used by components
None yet
Used on screens
Not used on a screen yet

Number field

moleculeNot used on a screen yet

Type an exact number, or nudge it with − / + steppers.

@/design-system/components/number-field · exports NumberField

Use it when

  • An exact number matters: seats, quantity, hours, a price, a percentage
  • Small changes around a known value, where − / + saves typing

Don’t use it when

  • An approximate value in a range is enough → slider
  • The "number" is an ID, phone or card number (never stepped or summed) → field (Input)

Rules

  • Set minValue / maxValue whenever the domain has limits; the steppers disable there
  • Show units with formatOptions (unit, percent, currency), not in the label or a prefix
  • Store plain numbers: a percent field holds 0.25 for 25%, a currency field holds 49.5
  • Pass step when typed values must land on a grid (whole seats, half stars)

Accessibility

  • Text input with role="spinbutton" plus aria-valuenow / min / max; aria-valuetext carries the formatted value ("12 kg", "25%")
  • Up/Down arrows step, Home/End jump to min/max; the − / + buttons are out of the tab order (tabIndex -1) and named "Decrease" / "Increase"
  • Pass label or aria-label; hint and error are linked with aria-describedby and error sets aria-invalid
  • The scroll wheel only steps while the field has focus, so scrolling the page never changes a value

Example

<NumberField label="Seats" value={seats} onValueChange={setSeats} minValue={1} maxValue={50} step={1} hint="Between 1 and 50 people." />

Properties · NumberField

PropTypeDefault
labelstring–
hintstring–
errorstring–
requiredboolean–
valuenumber | null–
defaultValuenumber | nullnull
onValueChange(value: number | null) => void–
minValuenumber–
maxValuenumber–
stepnumber–
formatOptionsIntl.NumberFormatOptions–
localestring"en-US"
disabledboolean–
size"sm" | "md""md"
wheelDisabledboolean–
placeholderstring–
namestring–
idstring–
classNamestring–
aria-labelstring–

Blocks · how it connects

Built from
Field and inputs, Glyph
Used by components
None yet
Used on screens
Not used on a screen yet

Radio

atomNot used on a screen yet

One choice from a short list. RadioCard is the large card version.

@/design-system/components/radio · exports Radio RadioGroup RadioCard

Use it when

  • 2–5 mutually exclusive options that should all be visible
  • Big, described choices such as a role or plan (RadioCard)

Don’t use it when

  • More than ~6 options → field (Select)
  • Several can be chosen → checkbox or choice-chip
  • Filtering a list → segmented-filter

Rules

  • Always inside RadioGroup so the question (legend) is announced

Accessibility

  • fieldset + legend; arrow keys move between options

Example

<RadioGroup legend="Payment terms">
  <Radio name="terms" value="7" label="Within 7 days" />
  <Radio name="terms" value="15" label="Within 15 days" />
</RadioGroup>

Properties · Radio

PropTypeDefault
size"sm" | "md""sm"
labelReactNode–
hintReactNode–

Properties · RadioGroup

PropTypeDefault
legend *ReactNode–
hideLegendboolean–
orientation"vertical" | "horizontal""vertical"
hintReactNode–
errorReactNode–
children *ReactNode–

Properties · RadioCard

PropTypeDefault
title *ReactNode–
descriptionReactNode–
iconReactNode–

Blocks · how it connects

Built from
Tokens only
Used by components
None yet
Used on screens
Not used on a screen yet

Rating

atomNot used on a screen yet

Star score, as an input or read-only.

@/design-system/components/rating · exports Rating

Use it when

  • Collecting or showing a 1–5 score

Don’t use it when

  • Status or progress → badge

Rules

  • label is required: it is the accessible name

Accessibility

  • Radio group when interactive; one labelled image when readOnly

Example

<Rating label="Client satisfaction" value={4} readOnly />

Properties · Rating

PropTypeDefault
label *string–
valuenumber–
defaultValuenumber0
onValueChange(value: number) => void–
maxnumber5
size"sm" | "md""md"
readOnlyboolean–
disabledboolean–
namestring–
classNamestring–

Blocks · how it connects

Built from
Tokens only
Used by components
None yet
Used on screens
Not used on a screen yet

Segmented control

atomNot used on a screen yet

Pick exactly one of a few short options (a period or a view) on a grey track with a sliding white thumb.

@/design-system/components/segmented-control · exports SegmentedControl

Use it when

  • Switching between 2–5 short, mutually exclusive periods or views: Weekly / Monthly / Yearly, List / Board
  • A compact choice in a toolbar or card header that changes what is shown right away

Don’t use it when

  • Filtering a list where each option shows a count → segmented-filter
  • Switching between sections of a page → tabs
  • Choosing one of several options in a form → radio or choice-chip

Rules

  • 2–5 options with one- or two-word labels; one is always selected
  • Use size sm in toolbars and card headers, md (default) elsewhere
  • Icons only lead a label (color="current"); never icon-only without a label
  • fullWidth inside narrow containers such as cards and side panels

Accessibility

  • role="radiogroup" with aria-label; items are role="radio" with aria-checked
  • Roving tabindex: only the selected item is tabbable; arrows move and select (wrapping, skipping disabled), Home/End jump to the ends
  • The sliding thumb is aria-hidden and its motion is off under prefers-reduced-motion

Example

<SegmentedControl
  aria-label="Reporting period"
  value={period}
  onValueChange={setPeriod}
  options={[
    { id: "weekly", label: "Weekly" },
    { id: "monthly", label: "Monthly" },
    { id: "yearly", label: "Yearly" },
  ]}
/>

Properties · SegmentedControl

PropTypeDefault
aria-label *string–
options *SegmentedControlOption<T>[]–
valueT–
defaultValueT–
onValueChange(id: T) => void–
size"sm" | "md""md"
fullWidthbooleanfalse
classNamestring–

Blocks · how it connects

Built from
Icon
Used by components
Area chart card, Bar list card, Bar chart card, Combo chart card, Funnel chart card, Notification Center, Radar chart card, Radial chart card
Used on screens
Not used on a screen yet

Slider

atomNot used on a screen yet

Pick a number, or a low–high range, by dragging.

@/design-system/components/slider · exports Slider RangeSlider

Use it when

  • An approximate value in a known range: opacity, volume, budget share, hours
  • A low–high filter such as a price or a delivery window (RangeSlider)

Don’t use it when

  • An exact number matters → field (Input type=number)
  • Two values that don't form a range → two Sliders

Rules

  • Show the value (showValue or showTooltip) when it isn't obvious
  • Format with formatValue so the bubble, the label row and screen readers agree
  • Save on onValueCommit (pointer up, key press), not on every onValueChange
  • RangeSlider thumbs can't cross; they can meet

Accessibility

  • One native range input per thumb: arrows, Page Up/Down, Home/End, forms and screen readers work
  • Pass label or aria-label; formatValue feeds aria-valuetext
  • RangeSlider thumbs are named "<label> Minimum" and "<label> Maximum"

Example

<RangeSlider label="Price range" min={0} max={1000} step={50} value={price} onValueChange={setPrice} formatValue={(n) => `$${n}`} />

Properties · Slider

PropTypeDefault
valuenumber–
defaultValuenumber–
minnumber0
maxnumber100
stepnumber–
onValueChange(value: number) => void–
onValueCommit(value: number) => void–
onChangeComponentProps<"input">["onChange"]–
labelReactNode–
showValueboolean–
showMinMaxboolean–
showTooltipbooleanfalse
formatValue(value: number) => stringString

Properties · RangeSlider

PropTypeDefault
value[number, number]–
defaultValue[number, number][min, max]
minnumber0
maxnumber100
stepnumber1
onValueChange(value: [number, number]) => void–
onValueCommit(value: [number, number]) => void–
labelReactNode–
aria-labelstring–
showTooltipbooleantrue
formatValue(value: number) => stringString
disabledboolean–
idstring–
namestring–
classNamestring–

Blocks · how it connects

Built from
Tokens only
Used by components
None yet
Used on screens
Not used on a screen yet

Switch

atomNot used on a screen yet

On/off control for a setting that applies at once.

@/design-system/components/switch · exports Switch SwitchField

Use it when

  • Turning a setting on or off with immediate effect (notifications, visibility)

Don’t use it when

  • The choice only applies after Save → checkbox
  • More than two states → radio or segmented-filter

Rules

  • Use SwitchField when it has a label and hint

Accessibility

  • role="switch" with aria-checked; the SwitchField label toggles it

Example

<SwitchField label="Email me when a client comments" checked={on} onCheckedChange={setOn} />

Properties · Switch

PropTypeDefault
checkedboolean–
defaultCheckedbooleanfalse
onCheckedChange(checked: boolean) => void–
size"sm" | "md""sm"

Properties · SwitchField

PropTypeDefault
label *ReactNode–
hintReactNode–
checkedboolean–
defaultCheckedboolean–
onCheckedChange(checked: boolean) => void–
size"sm" | "md""sm"

Blocks · how it connects

Built from
Tokens only
Used by components
None yet
Used on screens
Not used on a screen yet

Badge

atomUsed in 6 files

Small label pill for a status or category.

@/design-system/components/badge · exports Badge

Use it when

  • Status of a row or card: Active, Draft, Paid
  • A short tag such as PRO or "Most popular"

Don’t use it when

  • It should be clickable → pressable or choice-chip
  • A message with an action → alert

Rules

  • The word carries the meaning; never colour alone
  • Map each status to one tone and keep it everywhere

Accessibility

  • Text is read as-is; the dot is decorative

Example

<Badge tone="emerald">Paid</Badge>

Properties · Badge

PropTypeDefault
tone"slate" | "neutral" | "blue" | "violet" | "amber" | "emerald" | "red""slate"
dotbooleanfalse

Blocks · how it connects

Built from
Tokens only
Used by components
Area chart card, Bar list card, Bar chart card, Combo chart card, Funnel chart card, Radar chart card, Radial chart card
Used on screens
Projects & Clients, Finance & Growth, Proposals & Scope
Show 6 files
  • app/(app)/_components/projects/status-badge.tsx
  • app/(app)/finance/_components/payments-view.tsx
  • app/(app)/finance/_components/payroll-view.tsx
  • app/(app)/projects/_components/member-sheet.tsx
  • app/(app)/projects/_components/projects-grouped-list.tsx
  • app/(app)/proposals/_components/proposals-view.tsx

Person avatar

atomUsed in 5 files

Photo or initials avatar with a stable tint per person; AvatarStack overlaps several.

@/design-system/components/person-avatar · exports tintFor PersonAvatar AvatarStack

Use it when

  • Showing who owns or is assigned to something

Don’t use it when

  • Uploading or changing the picture → file-upload (ImageUpload)

Rules

  • 2xs in table cells, xs in lists, sm in stacks, md on cards, lg on profile panels
  • Pass src for a photo; without it the initials show

Accessibility

  • Pair with the person's name in text

Example

<PersonAvatar member={{ id: "m-1", name: "Sita Gurung" }} src="/figma/avatar.png" size="2xs" />

Properties · PersonAvatar

PropTypeDefault
member *Person–
sizekeyof typeof sizes"sm"
srcstring–
classNamestring–

Properties · AvatarStack

PropTypeDefault
members *Person[]–
onSelect *(id: string) => void–
maxnumber3

Blocks · how it connects

Built from
Tokens only
Used by components
Notification Center, Profile card
Used on screens
Projects & Clients, Finance & Growth
Show 5 files
  • app/(app)/_components/projects/projects-table.tsx
  • app/(app)/finance/_components/payroll-view.tsx
  • app/(app)/projects/_components/member-sheet.tsx
  • app/(app)/projects/_components/projects-grouped-list.tsx
  • app/(app)/projects/[id]/_components/project-detail-view.tsx

Profile card

moleculeNot used on a screen yet

A person: avatar, name, role, optional stats and actions.

@/design-system/components/profile-card · exports ProfileCard

Use it when

  • Team lists and member panels

Don’t use it when

  • Only a name and picture inline → person-avatar

Rules

  • Never show productivity rankings or activity tracking (product brief)

Accessibility

  • Stats are a description list

Example

<ProfileCard name="Sita Gurung" role="Project manager" email="sita@studio.com" variant="compact" />

Properties · ProfileCard

PropTypeDefault
name *string–
rolestring–
emailstring–
idstring–
avatarReactNode–
statsProfileStat[]–
actionsReactNode–
variant"full" | "compact""full"
classNamestring–

Blocks · how it connects

Built from
Person avatar
Used by components
None yet
Used on screens
Not used on a screen yet

Stat card

moleculeUsed in 1 file

A label, one big number and a short note. StatGrid lays several out.

@/design-system/components/stat-card · exports StatCard StatCardSkeleton StatGrid · Figma 106:72

Use it when

  • Summary numbers at the top of a dashboard or report

Don’t use it when

  • More than one number per card → table

Rules

  • Respect role visibility: the screen decides which stats a role may see
  • Use StatGrid loading for the skeleton state

Accessibility

  • Rendered as a list; numbers use tabular figures

Example

<StatGrid stats={[{ label: "Outstanding", value: "$15,800", note: "4 open invoices" }]} />

Properties · StatGrid

PropTypeDefault
statsStat[]–
loadingbooleanfalse
countnumber4

Blocks · how it connects

Built from
Skeleton
Used by components
None yet
Used on screens
Dashboard
Show 1 file
  • app/(app)/_components/dashboard/dashboard-view.tsx

Table

organismUsed in 1 file

Data table on React Aria: a card with an optional toolbar and pagination footer, a grey header band, keyboard navigation, sortable columns, row selection, row actions, two densities and skeleton loading.

@/design-system/components/table · exports TableCard TableToolbar Table TableHeader TableColumn TableBody TableRow TableCell TableActions TableSkeletonRows TableEmptyState CellText · Figma 118:23546

Use it when

  • Comparing rows of the same kind across columns: projects, invoices, people
  • Picking several rows for a bulk action (checkbox selection)
  • Long lists that need sorting, a filter and pages

Don’t use it when

  • Fewer than 3 columns or rich cards → pressable cards in a grid
  • Layout → CSS grid or flex
  • There is no data at all yet → empty-state

Rules

  • Compose Table > TableHeader (TableColumn…) + TableBody (TableRow > TableCell…); every TableRow needs an id, and the Table an aria-label
  • Mark the column that names each row with isRowHeader
  • Column widths come from TableColumn width; set Table minWidth so it scrolls inside TableCard
  • Put the title, filters and search in TableCard toolbar (TableToolbar) and Pagination in footer
  • md density by default; size="sm" for dense lists or when people ask for compact
  • Sorting: allowsSorting on the column, sortDescriptor + onSortChange on the Table; sort the rows yourself
  • Selection: selectionMode="multiple" (or "single") on the Table adds the checkbox column; control it with selectedKeys + onSelectionChange
  • Row actions are small icon-only Buttons in TableActions, each with an aria-label naming the row
  • Use TableSkeletonRows while loading, TableBody renderEmptyState with TableEmptyState when a filter matches nothing, EmptyState when there is no data at all

Accessibility

  • A real ARIA grid (React Aria): Tab enters it, arrow keys move between rows and cells, Home/End jump
  • Sortable headers sort on click or Enter and carry aria-sort; the chevron shows the direction
  • Space toggles a row's selection; Shift-click and Shift-arrows select a range; the select-all checkbox shows a dash for some
  • isRowHeader makes screen readers announce each row by its name; textValue names rows whose first cell isn't plain text
  • The scroll area is focusable, so keyboard users can scroll a wide table with the arrow keys
  • Set aria-busy on the Table while TableSkeletonRows show; the bars are hidden from screen readers

Example

<TableCard
  toolbar={<TableToolbar caption="Total results" title="48 invoices">{filters}</TableToolbar>}
  footer={<Pagination … />}
>
  <Table aria-label="Invoices" selectionMode="multiple" sortDescriptor={sort} onSortChange={setSort}>
    <TableHeader>
      <TableColumn id="client" isRowHeader>Client</TableColumn>
      <TableColumn id="due" width={144} allowsSorting>Due</TableColumn>
    </TableHeader>
    <TableBody renderEmptyState={() => <TableEmptyState>No invoices match.</TableEmptyState>}>
      <TableRow id="INV-1042">
        <TableCell><CellText primary="Denzing" secondary="INV-1042" /></TableCell>
        <TableCell>Nov 02</TableCell>
      </TableRow>
    </TableBody>
  </Table>
</TableCard>

Properties · TableCard

PropTypeDefault
toolbarReactNode–
ReactNode–
classNamestring–

Properties · TableToolbar

PropTypeDefault
captionReactNode–
titleReactNode–
childrenReactNode–
classNamestring–

Properties · Table

PropTypeDefault
aria-label *string–
minWidthnumber720
size"sm" | "md""md"
selectionMode"none" | "single" | "multiple""none"
selectedKeysSelection–
onSelectionChange(keys: Selection) => void–
sortDescriptorSortDescriptor–
onSortChange(descriptor: SortDescriptor) => void–
onRowAction(key: Key) => void–
classNamestring–

Properties · TableColumn

PropTypeDefault
id *Key–
isRowHeaderboolean–
allowsSortingboolean–
widthnumber | string–
indexbooleanfalse
align"start" | "end""start"
classNamestring–

Properties · TableBody

PropTypeDefault
renderEmptyState() => ReactNode–
itemsIterable<T>–

Properties · TableRow

PropTypeDefault
id *Key–
highlightbooleanfalse
textValuestring–
onAction() => void–
isDisabledboolean–
classNamestring–

Properties · TableCell

PropTypeDefault
indexbooleanfalse
align"start" | "end""start"
classNamestring–

Properties · TableSkeletonRows

PropTypeDefault
rowsnumber5
columns *number–

Properties · TableEmptyState

PropTypeDefault
children *ReactNode–

Properties · CellText

PropTypeDefault
primary *ReactNode–
secondaryReactNode–
leadingReactNode–

Blocks · how it connects

Built from
Checkbox, Glyph, Scroll area, Skeleton
Used by components
None yet
Used on screens
Projects & Clients
Show 1 file
  • app/(app)/_components/projects/projects-table.tsx

Agent thinking

moleculeNot used on a screen yet

The one-line "assistant is working" status above a chat composer: an animated indicator, a shimmering label and an elapsed timer.

@/design-system/components/agent-thinking · exports AgentThinking

Use it when

  • The assistant is drafting a reply, proposal, invoice or brief and the wait is open-ended
  • Showing which step the assistant is on ("Reading the brief", "Drafting the proposal")
  • Any agent work that may take more than a second

Don’t use it when

  • Loading a page or a list whose layout is known → skeleton
  • Progress with a known end (an upload, an import) → a progress bar
  • Telling people the work finished or failed → toast

Rules

  • Keep the label short, in the present tense and specific: "Drafting the invoice", not "Please wait…"
  • Change the label as the work moves on; keep the same element mounted so the timer keeps running
  • Use wave (default) or spin in chat, stars for quiet background work, infinity for long runs, burst to match Avesk's other loaders
  • Leave the tone to the variant; use tone="accent" only when it is the one thing on screen to watch
  • Remove it when the reply arrives; never leave it running without work behind it

Accessibility

  • role="status" (polite live region): the label is read when it changes, without interrupting
  • The ticking timer and the indicator are hidden from screen readers
  • Under prefers-reduced-motion every animation stops: the indicator holds a still frame and the label is plain text
  • The default tone (neutral-600) keeps the label above 4.5:1 on white and neutral-100; subtle (neutral-500) reaches it on white

Example

<AgentThinking label="Drafting the proposal" />
<AgentThinking variant="spin" label="Reading the Lumen brief" />
<AgentThinking variant="infinity" tone="accent" showTimer={false} />

Properties · AgentThinking

PropTypeDefault
variant"wave" | "spin" | "stars" | "infinity" | "burst""wave"
labelstring"Thinking"
showTimerbooleantrue
shimmerbooleantrue
tone"default" | "subtle" | "accent"–
startedAtnumber–
classNamestring–

Blocks · how it connects

Built from
Glyph
Used by components
None yet
Used on screens
Not used on a screen yet

Alert

moleculeNot used on a screen yet

A message in the page with an icon, optional actions and a close button.

@/design-system/components/alert · exports Alert

Use it when

  • Something the person should know while they stay on the page: an overdue invoice, a failed save, a tip
  • A banner at the top of a section

Don’t use it when

  • Confirming an action that just happened → toast
  • An error on one form field → field (error)
  • It must be answered before continuing → dialog
  • A status label on a row → badge

Rules

  • Tone: error = something failed, warning = needs attention, success = done, info = neutral fact, neutral = feature or tip
  • Default style is lighter; use filled sparingly
  • xs and sm are one line; lg has a description and up to two actions

Accessibility

  • Errors use role="alert"; others role="status"
  • The tone is also announced in words

Example

<Alert tone="warning" title="2 invoices are overdue" action={{ label: "Open invoices", href: "/finance/payments" }} />

Properties · Alert

PropTypeDefault
title *ReactNode–
descriptionReactNode–
tone"error" | "warning" | "success" | "info" | "neutral""info"
variant"filled" | "light" | "lighter" | "stroke""lighter"
size"xs" | "sm" | "lg""sm"
actionAlertAction–
secondaryActionAlertAction–
onClose() => void–
role"alert" | "status" | "group"–
classNamestring–

Blocks · how it connects

Built from
Button, Glyph
Used by components
None yet
Used on screens
Not used on a screen yet

Callout card

moleculeUsed in 1 file

Tinted card that asks for one decision: kind of issue, what happened, one action.

@/design-system/components/callout-card · exports CalloutCard CalloutCardSkeleton · Figma 248:5287

Use it when

  • A short list of things someone must act on, like Home's "Needs your attention"

Don’t use it when

  • A message about the whole page or form → alert
  • A passing confirmation → toast
  • A number to scan → stat-card

Rules

  • One action per card, as a secondary button or a link styled with buttonClasses
  • Tone says the kind of issue: red money late, yellow effort or risk, purple waiting on a client
  • Use CalloutCardSkeleton while loading so nothing jumps

Accessibility

  • The label is text, not colour alone
  • Put cards in a list (ul/li) under a heading

Example

<CalloutCard tone="red" label="Overdue invoice" action={<Link href="/finance" className={buttonClasses("md")}>Open invoices</Link>}>
  INV-045 · Patan Museum · $2,900 · 26 days late
</CalloutCard>

Properties · CalloutCard

PropTypeDefault
tone"red" | "yellow" | "purple" | "blue" | "emerald" | "neutral""neutral"
label *string–
children *ReactNode–
actionReactNode–
classNamestring–

Blocks · how it connects

Built from
Skeleton
Used by components
None yet
Used on screens
Dashboard
Show 1 file
  • app/(app)/_components/dashboard/needs-attention.tsx

Empty state

moleculeUsed in 2 files

Says what belongs here and offers one clear next action.

@/design-system/components/empty-state · exports EmptyState

Use it when

  • A screen or section has no data yet (required on every screen)

Don’t use it when

  • A filter matches nothing in a table → table (TableEmptyState)
  • Content is loading → skeleton

Rules

  • One primary action; an optional link as the second
  • size md fills a page or table; size sm fits a small section

Accessibility

  • Title is a heading

Example

<EmptyState title="No projects yet" body="Projects keep your brief and scope together." actions={<Button variant="primary">Create project</Button>} />

Properties · EmptyState

PropTypeDefault
iconIconName"text-select"
title *string–
bodyReactNode–
actionsReactNode–
size"sm" | "md""md"

Blocks · how it connects

Built from
Icon
Used by components
Notification Center
Used on screens
Dashboard, Projects & Clients
Show 2 files
  • app/(app)/_components/dashboard/needs-attention.tsx
  • app/(app)/_components/projects/projects-empty.tsx

Skeleton

atomUsed in 17 files

Loading placeholder shaped like the real content.

@/design-system/components/skeleton · exports Skeleton

Use it when

  • The loading state of every screen

Don’t use it when

  • A file or action is in progress → file-upload (FileCard) or glyph (burst)

Rules

  • Keep the real layout so nothing jumps when data arrives

Accessibility

  • aria-hidden; set aria-busy on the region

Example

<Skeleton className="h-4 w-24" />

Blocks · how it connects

Built from
Tokens only
Used by components
Callout card, Stat card, Table, Tabs
Used on screens
Dashboard, Projects & Clients, Finance & Growth, Design Inspiration, Proposals & Scope, Onboarding
Show 17 files
  • app/(app)/_components/dashboard/dashboard-banner.tsx
  • app/(app)/_components/dashboard/overview-header.tsx
  • app/(app)/_components/projects/projects-section.tsx
  • app/(app)/_components/projects/projects-table.tsx
  • app/(app)/finance/_components/finance-ui.tsx
  • app/(app)/finance/_components/overview-view.tsx
  • app/(app)/finance/_components/payments-view.tsx
  • app/(app)/finance/_components/payroll-view.tsx
  • app/(app)/finance/_components/subscriptions-view.tsx
  • app/(app)/library/_components/library-view.tsx
  • app/(app)/projects/_components/client-cards.tsx
  • app/(app)/projects/_components/projects-clients-view.tsx
  • app/(app)/projects/_components/projects-grouped-list.tsx
  • app/(app)/projects/[id]/_components/project-detail-view.tsx
  • app/(app)/proposals/_components/proposals-view.tsx
  • app/(onboarding)/onboarding/_components/onboarding-steps.tsx
  • app/(onboarding)/onboarding/_components/onboarding-view.tsx

Toast

moleculeNot used on a screen yet

A notification that floats in a corner and leaves by itself: tinted icon or avatar, title, a line of text and up to two buttons.

@/design-system/components/toast · exports Toast ToastProvider useToast

Use it when

  • Confirming an action: saved, copied, archived (with Undo)
  • Activity from a person: a comment, a mention, an approval (with avatar)

Don’t use it when

  • The message must stay visible → alert
  • It needs a decision → dialog

Rules

  • Wrap the app once in ToastProvider; call toast() from useToast()
  • Keep the title under ~6 words; put the detail in description
  • At most two actions: the main one is primary and comes last
  • Use duration: 0 only when it needs an answer; it then stays until closed
  • Rises in over 300ms ease-smooth (animate-toast-in); reduced motion fades

Accessibility

  • Polite live region; errors use role=alert when shown on their own
  • The countdown pauses on hover or focus; the default is 5 seconds
  • The close button is labelled Dismiss

Example

const { toast } = useToast();
toast({ title: "Changes saved", description: "Your workspace settings were updated.", tone: "success" });

Properties · Toast

PropTypeDefault
title *string–
descriptionReactNode–
tone"error" | "warning" | "success" | "info" | "neutral""neutral"
iconReactNode–
avatarReactNode–
timestampstring–
action{ label: string; onClick: () => void }–
secondaryAction{ label: string; onClick: () => void }–
onClose() => void–
countdownnumber–
pausedbooleanfalse
role"status" | "alert" | "group"–
classNamestring–

Properties · ToastProvider

PropTypeDefault
children *ReactNode–
position"top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right""bottom-right"

Properties · toast() options

PropTypeDefault
title *string–
descriptionReactNode–
tone"error" | "warning" | "success" | "info" | "neutral""neutral"
iconReactNode–
avatarReactNode–
timestampstring–
action{ label: string; onClick: () => void }–
secondaryAction{ label: string; onClick: () => void }–
durationnumber5000

Blocks · how it connects

Built from
Button, Glyph
Used by components
None yet
Used on screens
Not used on a screen yet

Tooltip

atomNot used on a screen yet

Short help that appears on hover or keyboard focus.

@/design-system/components/tooltip · exports Tooltip

Use it when

  • Explaining what an icon-only control does (it still needs its own aria-label)
  • One short sentence of extra help

Don’t use it when

  • The information is essential or contains a link → field (hint) or alert

Rules

  • Never the only place important information lives
  • Fades in and out over 200ms ease-smooth

Accessibility

  • Linked with aria-describedby, so it describes the trigger but never names it: an icon-only button still needs aria-label. Escape hides it, hovered or focused

Example

<Tooltip content="Visible to owners only"><Button iconOnly aria-label="Info">…</Button></Tooltip>

Properties · Tooltip

PropTypeDefault
children *ReactElement<{ "aria-describedby"?: string }>–
content *ReactNode–
titleReactNode–
placement"top" | "bottom""top"
variant"dark" | "light""dark"
openboolean–
classNamestring–

Blocks · how it connects

Built from
Tokens only
Used by components
Accordion, Agent limits card
Used on screens
Not used on a screen yet

Command menu

organismNot used on a screen yet

⌘K search and quick actions from any page, with filter chips, history and counted results.

@/design-system/components/command-menu · exports Kbd CommandMenu useCommandMenuShortcut

Use it when

  • Global search across people, files and actions

Don’t use it when

  • Filtering the list on the current page → field (Input type=search) or segmented-filter

Rules

  • Bind it once with useCommandMenuShortcut()
  • Give items a category so the filter chips work
  • Opens and closes like Dialog (DIALOG_MOTION, 280ms ease-smooth)

Accessibility

  • Combobox with a listbox; arrows move, Enter runs, Escape closes

Example

useCommandMenuShortcut(() => setOpen(true));
<CommandMenu open={open} onOpenChange={setOpen} groups={groups} filters={filters} />

Properties · CommandMenu

PropTypeDefault
open *boolean–
onOpenChange *(open: boolean) => void–
groups *CommandGroup[]–
placeholderstring"Search"
filtersCommandFilter[]–
ReactNode–
labelstring"Command menu"
classNamestring–

Blocks · how it connects

Built from
Dialog, Button, Glyph
Used by components
None yet
Used on screens
Not used on a screen yet

Dialog

moleculeUsed in 3 files

Centred modal for a short form or a confirmation. DialogFooter holds the actions.

@/design-system/components/dialog · exports DIALOG_MOTION Dialog DialogBody DialogFooter

Use it when

  • A short form: create, rename, add
  • Confirming a destructive action

Don’t use it when

  • Showing details beside the page → drawer
  • A list of actions → dropdown-menu
  • Just a message → alert or toast

Rules

  • Footer: Cancel (secondary) then the one primary action
  • Put data-autofocus on the first field
  • size lg for longer forms: the body scrolls, the footer stays
  • size xl (880px) and hideTitle are for two-pane layouts such as settings-modal, which draw their own heading
  • Opens and closes with motion: it fades, rises 8px and grows from 97% (280ms ease-smooth) and leaves the same way; reduced motion fades only. Reuse DIALOG_MOTION for any other native <dialog>

Accessibility

  • Native <dialog>: focus stays inside, Escape closes, focus returns to the trigger

Example

<Dialog open={open} onOpenChange={setOpen} title="Add client">
  <form>…<DialogFooter><Button onClick={close}>Cancel</Button><Button type="submit" variant="primary">Add</Button></DialogFooter></form>
</Dialog>

Properties · Dialog

PropTypeDefault
open *boolean–
onOpenChange *(open: boolean) => void–
title *string–
descriptionReactNode–
children *ReactNode–
size"md" | "lg" | "xl""md"
hideTitlebooleanfalse
classNamestring–

Blocks · how it connects

Built from
Tokens only
Used by components
Command menu, Settings Modal
Used on screens
Design Inspiration, Projects & Clients
Show 3 files
  • app/(app)/library/_components/add-site-dialog.tsx
  • app/(app)/projects/_components/add-client-dialog.tsx
  • app/(app)/projects/_components/create-project-dialog.tsx

Drawer

moleculeUsed in 2 files

Panel on an edge of the screen for filters, details and short tasks, without leaving the page.

@/design-system/components/drawer · exports Drawer DrawerHeader DrawerBody DrawerFooter useDrawer

Use it when

  • Filtering a list without leaving it
  • Reading the details of a row: a member, an invoice, a proposal's scope
  • A bottom sheet of actions on a phone

Don’t use it when

  • A short form or a confirmation → dialog
  • The content deserves its own URL → a page
  • A short list of actions → dropdown-menu

Rules

  • Always give it a DrawerHeader: its title names the drawer for screen readers
  • Put the main action last in DrawerFooter; it sits on the right, and on top on phones
  • Use placement="bottom" for action sheets on phones; side drawers for filters and details
  • Pick the width for the content: sm for lists, md (default) for forms, lg for details
  • No open or close animation: it appears and leaves at once

Accessibility

  • Native <dialog>: focus moves inside and is trapped, Escape and the backdrop close it, focus returns to the trigger
  • The page behind stops scrolling while it is open
  • No open or close motion: it appears and leaves at once
  • data-autofocus picks the element that gets focus on open

Example

<Drawer open={open} onOpenChange={setOpen}>
  <DrawerHeader title="Filters" description="Narrow the invoice list." />
  <DrawerBody>…</DrawerBody>
  <DrawerFooter>
    <Button onClick={reset}>Reset</Button>
    <Button variant="primary" onClick={apply}>Show 24 invoices</Button>
  </DrawerFooter>
</Drawer>

Properties · Drawer

PropTypeDefault
open *boolean–
onOpenChange *(open: boolean) => void–
placement"start" | "end" | "top" | "bottom""end"
size"sm" | "md" | "lg""md"
aria-labelstring–
classNamestring–
children *ReactNode–

Properties · DrawerHeader

PropTypeDefault
title *ReactNode–
descriptionReactNode–
closeLabelstring"Close"
classNamestring–

Properties · DrawerBody

PropTypeDefault
children *ReactNode–
classNamestring–

Properties · DrawerFooter

PropTypeDefault
children *ReactNode–
classNamestring–

Blocks · how it connects

Built from
Button
Used by components
None yet
Used on screens
Projects & Clients, Proposals & Scope
Show 2 files
  • app/(app)/projects/_components/member-sheet.tsx
  • app/(app)/proposals/_components/proposals-view.tsx

Pagination

organismUsed in 1 file

Previous / next, rows per page and page numbers.

@/design-system/components/pagination · exports pageList Pagination

Use it when

  • Under a table or list with more rows than one page

Don’t use it when

  • Fewer than ~10 rows → show them all

Rules

  • Reset to page 1 when a filter or tab changes

Accessibility

  • nav labelled Pagination; current page has aria-current

Example

<Pagination page={page} pageCount={8} pageSize={10} onPageChange={setPage} onPageSizeChange={setSize} />

Properties · Pagination

PropTypeDefault
page *number–
pageCount *number–
pageSize *number–
onPageChange *(page: number) => void–
onPageSizeChange *(size: number) => void–

Blocks · how it connects

Built from
Icon, Button, Dropdown menu
Used by components
None yet
Used on screens
Projects & Clients
Show 1 file
  • app/(app)/_components/projects/projects-section.tsx

Filter pills

moleculeUsed in 2 files

Pill filter with a count per option; one choice at a time.

@/design-system/components/segmented-filter · exports SegmentedFilter

Use it when

  • Narrowing a list by status inside a page or tab: All / Due / Paid

Don’t use it when

  • The top-level views of a page → tabs
  • An answer in a form → choice-chip or radio

Rules

  • Always include an "All" option first

Accessibility

  • radiogroup with aria-checked

Example

<SegmentedFilter label="Invoice status" options={options} value={value} onChange={setValue} />

Properties · SegmentedFilter

PropTypeDefault
label *string–
options *FilterOption<T>[]–
value *T–
onChange *(id: T) => void–

Blocks · how it connects

Built from
Tokens only
Used by components
None yet
Used on screens
Finance & Growth
Show 2 files
  • app/(app)/finance/_components/payments-view.tsx
  • app/(app)/finance/_components/subscriptions-view.tsx

Tabs

moleculeUsed in 5 files

Tabs: underline (default), pill or neutral pill, with optional icons and counts and a sliding indicator. Tabs switch content on the page; LinkTabs when each tab is its own page.

@/design-system/components/tabs · exports tabPanelProps Tabs LinkTabs

Use it when

  • Switching between views of the same data (All / Active / Completed) with counts
  • Sections of a detail page (Overview / Tasks / Files)
  • Sibling pages of one area (Finance: Overview / Payments) with LinkTabs
  • Switching local views (Board / Timeline) or scopes (All / Mine) with the pill variants

Don’t use it when

  • Narrowing a list by one attribute inside a tab → segmented-filter
  • Picking one of 2–5 settings or periods (Weekly / Monthly) → segmented-control
  • Steps that must be done in order → a stepper (not in the system yet)

Rules

  • Use LinkTabs when a tab should be linkable or survive reload
  • Pass idBase and tabPanelProps() when tabs control panels
  • Underline for page sections and filters; pill for local view switchers; pill-neutral for quiet scope rows
  • Icons are optional; if one tab has an icon, give them all one
  • Counts are plain numbers; 1000 and up show as 1.2k

Accessibility

  • tablist with roving tabindex: arrow keys move and select (wrapping), Home and End jump to the ends (Tabs)
  • nav with aria-current="page" on the active link (LinkTabs)
  • Icons are hidden from screen readers; the label names the tab
  • Reduced motion stops the indicator sliding

Example

<Tabs
  label="Filter projects"
  items={[{ id: "all", label: "All", count: 34, icon: <Icon name="layout-dashboard" size={16} color="current" /> }]}
  value={tab}
  onChange={setTab}
/>

Properties · Tabs

PropTypeDefault
items *TabItem[]–
value *string–
onChange *(id: string) => void–
label *string–
variant"underline" | "pill" | "pill-neutral""underline"
loadingbooleanfalse
actionReactNode–
idBasestring–

Properties · LinkTabs

PropTypeDefault
items *LinkTabItem[]–
current *string–
label *string–
variant"underline" | "pill" | "pill-neutral""underline"
hrefSuffixstring""
actionReactNode–

Blocks · how it connects

Built from
Skeleton
Used by components
Bar list card, Colour picker
Used on screens
Projects & Clients, Finance & Growth, Design Inspiration, Proposals & Scope
Show 5 files
  • app/(app)/_components/projects/projects-section.tsx
  • app/(app)/finance/_components/finance-tabs.tsx
  • app/(app)/library/_components/library-view.tsx
  • app/(app)/projects/[id]/_components/project-detail-view.tsx
  • app/(app)/proposals/_components/proposals-view.tsx

Accordion

moleculeNot used on a screen yet

Expandable sections. With status and badge it becomes a setup checklist; AccordionGroup adds a heading.

@/design-system/components/accordion · exports Accordion AccordionGroup AccordionItem

Use it when

  • FAQs and long settings that would crowd a page
  • A setup checklist with done / in progress / to do steps

Don’t use it when

  • Content people must always see → plain sections
  • Switching between views → tabs

Rules

  • Give items the same name to keep one open at a time
  • size lg for checklists; md for lists and FAQs

Accessibility

  • Native <details>/<summary>: keyboard and find-in-page work; status is also announced in words

Example

<Accordion size="lg">
  <AccordionItem status="complete" title="Add your first client" badge={<Badge tone="emerald">Ready</Badge>}>…</AccordionItem>
</Accordion>

Properties · Accordion

PropTypeDefault
variant"bordered" | "card""bordered"
size"md" | "lg""md"
classNamestring–
children *ReactNode–

Properties · AccordionGroup

PropTypeDefault
title *ReactNode–
infoReactNode–
classNamestring–
children *ReactNode–

Properties · AccordionItem

PropTypeDefault
title *ReactNode–
descriptionReactNode–
status"complete" | "current" | "pending"–
badgeReactNode–
namestring–
defaultOpenboolean–
classNamestring–
children *ReactNode–

Blocks · how it connects

Built from
Tooltip, Glyph
Used by components
None yet
Used on screens
Not used on a screen yet

Scroll area

atomUsed in 6 files

A box that scrolls and can take keyboard focus, so keyboard users can Tab to it and scroll with the arrow keys.

@/design-system/components/scroll-area · exports ScrollArea

Use it when

  • Wide lists or tables that scroll sideways
  • Panels whose content scrolls up and down

Don’t use it when

  • Data tables → TableCard (already a ScrollArea)
  • Menus and listboxes that move focus between items → DropdownMenu or CommandMenu

Rules

  • Never write overflow-auto on a plain div in a screen; use ScrollArea
  • axis: x (default), y or both

Accessibility

  • tabIndex=0 with the brand focus ring while the content overflows (WCAG 2.1.1); when everything fits it leaves the Tab order
  • Give label when the content has no buttons or links: it becomes a named region

Example

<ScrollArea label="Payments" className="rounded-lg border border-black/5">
  <ul className="min-w-[820px]">…</ul>
</ScrollArea>

Blocks · how it connects

Built from
Tokens only
Used by components
Notification Center, Settings Modal, Table
Used on screens
Finance & Growth, Projects & Clients, Proposals & Scope
Show 6 files
  • app/(app)/finance/_components/overview-view.tsx
  • app/(app)/finance/_components/payments-view.tsx
  • app/(app)/finance/_components/payroll-view.tsx
  • app/(app)/finance/_components/subscriptions-view.tsx
  • app/(app)/projects/_components/projects-grouped-list.tsx
  • app/(app)/proposals/_components/proposals-view.tsx

Glyph

atomUsed in 4 files

Shared line icons and filled status marks that take the surrounding text colour.

@/design-system/components/glyph · exports glyphNames statusGlyphNames Glyph StatusGlyph

Use it when

  • A component or screen needs a close, chevron, tick, plus, bin, search, cloud, home or calendar icon
  • You need a status mark: success, error, info, warning, sparkle, or the loading burst

Don’t use it when

  • The icon is one of the Figma-exported product icons (pencil, bell, users…) → icon
  • The icon is the only content of a clickable control → button (iconOnly) wrapping the glyph

Rules

  • Never draw a new inline <svg> in a component or screen; add the path to glyph.tsx
  • Size with a size-* class; colour with a text-* class

Accessibility

  • Decorative (aria-hidden). The control or text around it must carry the meaning

Example

<Glyph name="close" className="size-4" />
<StatusGlyph name="success" className="text-green-600" />

Properties · StatusGlyph

PropTypeDefault
name *"success" | "error" | "info" | "warning" | "sparkle" | "burst"–
classNamestring–
markstring"stroke-white"
fadebooleanfalse

Blocks · how it connects

Built from
Tokens only
Used by components
Accordion, Agent limits card, Agent thinking, Alert, Area chart card, Bar list card, Breadcrumbs, Button, Checkbox, Choice chip, Colour picker, Bar chart card, Combo chart card, Command menu, Date picker, Dropdown menu, Field and inputs, File upload, Funnel chart card, Notification Center, Number field, Radar chart card, Radial chart card, Table, Toast
Used on screens
Projects & Clients, Onboarding
Show 4 files
  • app/(app)/projects/_components/create-project-dialog.tsx
  • app/(app)/projects/_components/projects-grouped-list.tsx
  • app/(app)/projects/[id]/_components/project-detail-view.tsx
  • app/(onboarding)/onboarding/_components/onboarding-steps.tsx

Icon

atomUsed in 11 files

Renders an icon exported from Figma (public/figma/icons).

@/design-system/components/icon · exports iconNames Icon

Use it when

  • Navigation and product icons that exist in the Figma file: dashboard, users, pencil, bell, search…

Don’t use it when

  • A generic UI glyph (close, chevron, check) → glyph

Rules

  • Default shows the colours baked into the file; pass color="current" inside buttons so it follows the text colour
  • Add new icons by exporting from Figma into public/figma/icons and adding the name to iconNames

Accessibility

  • Decorative (alt=""). Give icon-only buttons an aria-label

Example

<Icon name="pencil" size={20} />
<Icon name="plus" size={16} color="current" />

Properties · Icon

PropTypeDefault
name *(typeof iconNames)[number]–
size *number–
classNamestring–
color"baked" | "current""baked"

Blocks · how it connects

Built from
Tokens only
Used by components
Breadcrumbs, Dropdown menu, Empty state, Field and inputs, Notification Center, Pagination, Segmented control, Settings Modal
Used on screens
Dashboard, Projects & Clients, Design Inspiration, App shell
Show 11 files
  • app/(app)/_components/dashboard/dashboard-projects.tsx
  • app/(app)/_components/dashboard/overview-header.tsx
  • app/(app)/_components/projects/projects-table.tsx
  • app/(app)/library/_components/library-view.tsx
  • app/(app)/projects/_components/client-cards.tsx
  • app/(app)/projects/_components/create-project-dialog.tsx
  • app/(app)/projects/_components/projects-clients-view.tsx
  • app/(app)/projects/_components/projects-grouped-list.tsx
  • app/(app)/projects/[id]/_components/project-detail-view.tsx
  • components/layout/sidebar.tsx
  • components/layout/topbar.tsx

Auth card

organismNot used on a screen yet

Sign-in or sign-up screen: social buttons, email and password, submit.

@/design-system/components/auth-card · exports AuthCard

Use it when

  • The login and sign-up pages

Don’t use it when

  • Any other form → field + button in a dialog or page

Rules

  • The page handles real authentication in onSubmit; it is only called once the built-in checks pass (required, email format, 8+ characters on sign-up)
  • Pass server errors through errors; they replace the built-in messages

Accessibility

  • Errors are tied to their fields

Example

<AuthCard mode="sign-in" onSubmit={signIn} switchHref="/sign-up" />

Properties · AuthCard

PropTypeDefault
mode *"sign-in" | "sign-up"–
logoReactNode–
titlestring–
subtitleReactNode–
providersSocialProvider[]["google", "apple", "figma"]
onProvider(provider: SocialProvider) => void–
onSubmit(values: AuthValues) => void–
pendingbooleanfalse
errors{ email?: string; password?: string }–
forgotPasswordHrefstring"#"
switchHrefstring"#"
classNamestring–

Blocks · how it connects

Built from
Button, Checkbox, Field and inputs, Social button
Used by components
None yet
Used on screens
Not used on a screen yet