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… | Use | On screens |
|---|---|---|
| Any action with a label: save, create, cancel, open | Button | 19 |
| A whole card, tile or row is clickable | Pressable | 7 |
| Sign-in and sign-up screens that offer a third-party account | Social button | – |
| Forms · I need to… | Use | On screens |
|---|---|---|
| Agreeing to terms | Checkbox | 1 |
| Short answers in onboarding or forms: team size, services | Choice chip | 1 |
| Editing a palette colour or a brand colour | Colour picker | – |
| A deadline, start date or due date (DatePicker) | Date picker | – |
| Every single-line text, number, email, URL or search input | Field and inputs | 7 |
| Attaching files to a project or brief (FileUpload + FileCard) | File upload | – |
| An exact number matters: seats, quantity, hours, a price, a percentage | Number field | – |
| 2–5 mutually exclusive options that should all be visible | Radio | – |
| Collecting or showing a 1–5 score | Rating | – |
| Switching between 2–5 short, mutually exclusive periods or views: Weekly / Monthly / Yearly, List / Board | Segmented control | – |
| An approximate value in a known range: opacity, volume, budget share, hours | Slider | – |
| Turning a setting on or off with immediate effect (notifications, visibility) | Switch | – |
| Data display · I need to… | Use | On screens |
|---|---|---|
| Status of a row or card: Active, Draft, Paid | Badge | 6 |
| Showing who owns or is assigned to something | Person avatar | 5 |
| Team lists and member panels | Profile card | – |
| Summary numbers at the top of a dashboard or report | Stat card | 1 |
| Comparing rows of the same kind across columns: projects, invoices, people | Table | 1 |
| Feedback · I need to… | Use | On screens |
|---|---|---|
| The assistant is drafting a reply, proposal, invoice or brief and the wait is open-ended | Agent thinking | – |
| Something the person should know while they stay on the page: an overdue invoice, a failed save, a tip | Alert | – |
| A short list of things someone must act on, like Home's "Needs your attention" | Callout card | 1 |
| A screen or section has no data yet (required on every screen) | Empty state | 2 |
| The loading state of every screen | Skeleton | 17 |
| 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… | Use | On screens |
|---|---|---|
| Global search across people, files and actions | Command menu | – |
| A short form: create, rename, add | Dialog | 3 |
| Three or more actions on a row or page that don't all deserve a button | Dropdown menu | – |
| Filtering a list without leaving it | Drawer | 2 |
| Navigation · I need to… | Use | On screens |
|---|---|---|
| Detail pages two or more levels deep: Projects & Clients › Project | Breadcrumbs | 1 |
| Under a table or list with more rows than one page | Pagination | 1 |
| Narrowing a list by status inside a page or tab: All / Due / Paid | Filter pills | 2 |
| Switching between views of the same data (All / Active / Completed) with counts | Tabs | 5 |
| Layout · I need to… | Use | On screens |
|---|---|---|
| FAQs and long settings that would crowd a page | Accordion | – |
| Wide lists or tables that scroll sideways | Scroll area | 6 |
| Patterns · I need to… | Use | On screens |
|---|---|---|
| The login and sign-up pages | Auth card | – |
Component documentation
40 of 40 components
Pressable
atomUsed in 7 filesUnstyled 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.tsxapp/(app)/projects/_components/client-cards.tsxapp/(app)/projects/_components/create-project-dialog.tsxapp/(app)/projects/_components/projects-grouped-list.tsxapp/(app)/proposals/_components/proposals-view.tsxapp/(onboarding)/onboarding/_components/onboarding-steps.tsxcomponents/layout/sidebar.tsx
Checkbox
atomUsed in 1 fileTick 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>Choice chip
atomUsed in 1 filePill-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
| Prop | Type | Default |
|---|---|---|
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 yetPanel 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
| Prop | Type | Default |
|---|---|---|
value * | ColorValue | – |
onChange * | (value: ColorValue) => void | – |
modes | ColorPickerMode[] | ["image", "solid", "gradient"] |
onRemove | () => void | – |
onAdd | () => void | – |
disabled | boolean | – |
id | string | "color-picker" |
surface | "popover" | "inline" | "popover" |
className | string | – |
Date picker
moleculeNot used on a screen yetDatePicker 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
| Prop | Type | Default |
|---|---|---|
id * | string | – |
value * | string | null | – |
onChange * | (value: string | null) => void | – |
placeholder | string | "Select date" |
disabled | boolean | false |
min | string | – |
max | string | – |
name | string | – |
aria-invalid | boolean | – |
aria-describedby | string | – |
className | string | – |
Properties · DateRangePicker
| Prop | Type | Default |
|---|---|---|
value * | DateRange | – |
onChange * | (range: DateRange) => void | – |
presets | DateRangePreset[] | defaultRangePresets |
min | string | – |
max | string | – |
className | string | – |
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 filesField 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
| Prop | Type | Default |
|---|---|---|
id * | string | – |
label * | string | – |
required | boolean | – |
hint | string | – |
error | string | – |
children * | ReactNode | – |
Properties · Input
| Prop | Type | Default |
|---|---|---|
leadingIcon | IconName | – |
leadingGraphic | ReactNode | – |
leadingText | string | – |
leadingSelect | ReactNode | – |
prefix | string | – |
trailingSelect | ReactNode | – |
trailingButton | ReactNode | – |
help | string | – |
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.tsxapp/(app)/library/_components/add-site-dialog.tsxapp/(app)/projects/_components/add-client-dialog.tsxapp/(app)/projects/_components/create-project-dialog.tsxapp/(app)/projects/[id]/_components/project-detail-view.tsxapp/(onboarding)/onboarding/_components/onboarding-view.tsxcomponents/layout/topbar.tsx
File upload
moleculeNot used on a screen yetFileUpload (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
| Prop | Type | Default |
|---|---|---|
label | string | "PDF" |
color | "red" | "orange" | "yellow" | "green" | "sky" | "blue" | "purple" | "pink" | "gray" | "red" |
size | "sm" | "md" | "md" |
className | string | – |
Properties · FileUpload
| Prop | Type | Default |
|---|---|---|
id | string | – |
accept | string | "image/png,image/jpeg" |
maxSize | number | – |
multiple | boolean | false |
disabled | boolean | false |
title | ReactNode | "Choose a file or drag & drop it here." |
hint | ReactNode | "Min 400×400px, PNG or JPEG" |
icon | ReactNode | – |
buttonLabel | string | null | "Browse File" |
shape | "box" | "circle" | "box" |
children | ReactNode | – |
onFiles * | (files: File[]) => void | – |
onReject | (files: RejectedFile[]) => void | – |
aria-describedby | string | – |
className | string | – |
Properties · FileCard
| Prop | Type | Default |
|---|---|---|
name * | string | – |
size * | number | – |
progress | number | 0 |
status * | "uploading" | "complete" | "error" | – |
error | string | – |
onRemove | () => void | – |
onRetry | () => void | – |
className | string | – |
Properties · ImageUpload
| Prop | Type | Default |
|---|---|---|
src | string | null | – |
kind | "person" | "company" | "person" |
title | string | "Upload image" |
hint | string | "Min 400×400px, PNG or JPEG" |
compact | boolean | false |
accept | string | "image/png,image/jpeg" |
disabled | boolean | false |
onUpload * | (file: File) => void | – |
onRemove | () => void | – |
className | string | – |
Number field
moleculeNot used on a screen yetType 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
| Prop | Type | Default |
|---|---|---|
label | string | – |
hint | string | – |
error | string | – |
required | boolean | – |
value | number | null | – |
defaultValue | number | null | null |
onValueChange | (value: number | null) => void | – |
minValue | number | – |
maxValue | number | – |
step | number | – |
formatOptions | Intl.NumberFormatOptions | – |
locale | string | "en-US" |
disabled | boolean | – |
size | "sm" | "md" | "md" |
wheelDisabled | boolean | – |
placeholder | string | – |
name | string | – |
id | string | – |
className | string | – |
aria-label | string | – |
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 yetOne 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
| Prop | Type | Default |
|---|---|---|
size | "sm" | "md" | "sm" |
label | ReactNode | – |
hint | ReactNode | – |
Properties · RadioGroup
| Prop | Type | Default |
|---|---|---|
legend * | ReactNode | – |
hideLegend | boolean | – |
orientation | "vertical" | "horizontal" | "vertical" |
hint | ReactNode | – |
error | ReactNode | – |
children * | ReactNode | – |
Properties · RadioCard
| Prop | Type | Default |
|---|---|---|
title * | ReactNode | – |
description | ReactNode | – |
icon | ReactNode | – |
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 yetStar 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
| Prop | Type | Default |
|---|---|---|
label * | string | – |
value | number | – |
defaultValue | number | 0 |
onValueChange | (value: number) => void | – |
max | number | 5 |
size | "sm" | "md" | "md" |
readOnly | boolean | – |
disabled | boolean | – |
name | string | – |
className | string | – |
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 yetPick 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
| Prop | Type | Default |
|---|---|---|
aria-label * | string | – |
options * | SegmentedControlOption<T>[] | – |
value | T | – |
defaultValue | T | – |
onValueChange | (id: T) => void | – |
size | "sm" | "md" | "md" |
fullWidth | boolean | false |
className | string | – |
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 yetPick 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
| Prop | Type | Default |
|---|---|---|
value | number | – |
defaultValue | number | – |
min | number | 0 |
max | number | 100 |
step | number | – |
onValueChange | (value: number) => void | – |
onValueCommit | (value: number) => void | – |
onChange | ComponentProps<"input">["onChange"] | – |
label | ReactNode | – |
showValue | boolean | – |
showMinMax | boolean | – |
showTooltip | boolean | false |
formatValue | (value: number) => string | String |
Properties · RangeSlider
| Prop | Type | Default |
|---|---|---|
value | [number, number] | – |
defaultValue | [number, number] | [min, max] |
min | number | 0 |
max | number | 100 |
step | number | 1 |
onValueChange | (value: [number, number]) => void | – |
onValueCommit | (value: [number, number]) => void | – |
label | ReactNode | – |
aria-label | string | – |
showTooltip | boolean | true |
formatValue | (value: number) => string | String |
disabled | boolean | – |
id | string | – |
name | string | – |
className | string | – |
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 yetOn/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
| Prop | Type | Default |
|---|---|---|
checked | boolean | – |
defaultChecked | boolean | false |
onCheckedChange | (checked: boolean) => void | – |
size | "sm" | "md" | "sm" |
Properties · SwitchField
| Prop | Type | Default |
|---|---|---|
label * | ReactNode | – |
hint | ReactNode | – |
checked | boolean | – |
defaultChecked | boolean | – |
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 filesSmall 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
| Prop | Type | Default |
|---|---|---|
tone | "slate" | "neutral" | "blue" | "violet" | "amber" | "emerald" | "red" | "slate" |
dot | boolean | false |
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.tsxapp/(app)/finance/_components/payments-view.tsxapp/(app)/finance/_components/payroll-view.tsxapp/(app)/projects/_components/member-sheet.tsxapp/(app)/projects/_components/projects-grouped-list.tsxapp/(app)/proposals/_components/proposals-view.tsx
Person avatar
atomUsed in 5 filesPhoto 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
| Prop | Type | Default |
|---|---|---|
member * | Person | – |
size | keyof typeof sizes | "sm" |
src | string | – |
className | string | – |
Properties · AvatarStack
| Prop | Type | Default |
|---|---|---|
members * | Person[] | – |
onSelect * | (id: string) => void | – |
max | number | 3 |
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.tsxapp/(app)/finance/_components/payroll-view.tsxapp/(app)/projects/_components/member-sheet.tsxapp/(app)/projects/_components/projects-grouped-list.tsxapp/(app)/projects/[id]/_components/project-detail-view.tsx
Profile card
moleculeNot used on a screen yetA 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
| Prop | Type | Default |
|---|---|---|
name * | string | – |
role | string | – |
email | string | – |
id | string | – |
avatar | ReactNode | – |
stats | ProfileStat[] | – |
actions | ReactNode | – |
variant | "full" | "compact" | "full" |
className | string | – |
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 fileA 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
| Prop | Type | Default |
|---|---|---|
stats | Stat[] | – |
loading | boolean | false |
count | number | 4 |
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 fileData 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
| Prop | Type | Default |
|---|---|---|
toolbar | ReactNode | – |
footer | ReactNode | – |
className | string | – |
Properties · TableToolbar
| Prop | Type | Default |
|---|---|---|
caption | ReactNode | – |
title | ReactNode | – |
children | ReactNode | – |
className | string | – |
Properties · Table
| Prop | Type | Default |
|---|---|---|
aria-label * | string | – |
minWidth | number | 720 |
size | "sm" | "md" | "md" |
selectionMode | "none" | "single" | "multiple" | "none" |
selectedKeys | Selection | – |
onSelectionChange | (keys: Selection) => void | – |
sortDescriptor | SortDescriptor | – |
onSortChange | (descriptor: SortDescriptor) => void | – |
onRowAction | (key: Key) => void | – |
className | string | – |
Properties · TableColumn
| Prop | Type | Default |
|---|---|---|
id * | Key | – |
isRowHeader | boolean | – |
allowsSorting | boolean | – |
width | number | string | – |
index | boolean | false |
align | "start" | "end" | "start" |
className | string | – |
Properties · TableBody
| Prop | Type | Default |
|---|---|---|
renderEmptyState | () => ReactNode | – |
items | Iterable<T> | – |
Properties · TableRow
| Prop | Type | Default |
|---|---|---|
id * | Key | – |
highlight | boolean | false |
textValue | string | – |
onAction | () => void | – |
isDisabled | boolean | – |
className | string | – |
Properties · TableCell
| Prop | Type | Default |
|---|---|---|
index | boolean | false |
align | "start" | "end" | "start" |
className | string | – |
Properties · TableSkeletonRows
| Prop | Type | Default |
|---|---|---|
rows | number | 5 |
columns * | number | – |
Properties · TableEmptyState
| Prop | Type | Default |
|---|---|---|
children * | ReactNode | – |
Properties · CellText
| Prop | Type | Default |
|---|---|---|
primary * | ReactNode | – |
secondary | ReactNode | – |
leading | ReactNode | – |
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 yetThe 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
| Prop | Type | Default |
|---|---|---|
variant | "wave" | "spin" | "stars" | "infinity" | "burst" | "wave" |
label | string | "Thinking" |
showTimer | boolean | true |
shimmer | boolean | true |
tone | "default" | "subtle" | "accent" | – |
startedAt | number | – |
className | string | – |
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 yetA 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
| Prop | Type | Default |
|---|---|---|
title * | ReactNode | – |
description | ReactNode | – |
tone | "error" | "warning" | "success" | "info" | "neutral" | "info" |
variant | "filled" | "light" | "lighter" | "stroke" | "lighter" |
size | "xs" | "sm" | "lg" | "sm" |
action | AlertAction | – |
secondaryAction | AlertAction | – |
onClose | () => void | – |
role | "alert" | "status" | "group" | – |
className | string | – |
Callout card
moleculeUsed in 1 fileTinted 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
| Prop | Type | Default |
|---|---|---|
tone | "red" | "yellow" | "purple" | "blue" | "emerald" | "neutral" | "neutral" |
label * | string | – |
children * | ReactNode | – |
action | ReactNode | – |
className | string | – |
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 filesSays 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
| Prop | Type | Default |
|---|---|---|
icon | IconName | "text-select" |
title * | string | – |
body | ReactNode | – |
actions | ReactNode | – |
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.tsxapp/(app)/_components/projects/projects-empty.tsx
Skeleton
atomUsed in 17 filesLoading 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.tsxapp/(app)/_components/dashboard/overview-header.tsxapp/(app)/_components/projects/projects-section.tsxapp/(app)/_components/projects/projects-table.tsxapp/(app)/finance/_components/finance-ui.tsxapp/(app)/finance/_components/overview-view.tsxapp/(app)/finance/_components/payments-view.tsxapp/(app)/finance/_components/payroll-view.tsxapp/(app)/finance/_components/subscriptions-view.tsxapp/(app)/library/_components/library-view.tsxapp/(app)/projects/_components/client-cards.tsxapp/(app)/projects/_components/projects-clients-view.tsxapp/(app)/projects/_components/projects-grouped-list.tsxapp/(app)/projects/[id]/_components/project-detail-view.tsxapp/(app)/proposals/_components/proposals-view.tsxapp/(onboarding)/onboarding/_components/onboarding-steps.tsxapp/(onboarding)/onboarding/_components/onboarding-view.tsx
Toast
moleculeNot used on a screen yetA 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
| Prop | Type | Default |
|---|---|---|
title * | string | – |
description | ReactNode | – |
tone | "error" | "warning" | "success" | "info" | "neutral" | "neutral" |
icon | ReactNode | – |
avatar | ReactNode | – |
timestamp | string | – |
action | { label: string; onClick: () => void } | – |
secondaryAction | { label: string; onClick: () => void } | – |
onClose | () => void | – |
countdown | number | – |
paused | boolean | false |
role | "status" | "alert" | "group" | – |
className | string | – |
Properties · ToastProvider
| Prop | Type | Default |
|---|---|---|
children * | ReactNode | – |
position | "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" | "bottom-right" |
Properties · toast() options
| Prop | Type | Default |
|---|---|---|
title * | string | – |
description | ReactNode | – |
tone | "error" | "warning" | "success" | "info" | "neutral" | "neutral" |
icon | ReactNode | – |
avatar | ReactNode | – |
timestamp | string | – |
action | { label: string; onClick: () => void } | – |
secondaryAction | { label: string; onClick: () => void } | – |
duration | number | 5000 |
Tooltip
atomNot used on a screen yetShort 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
| Prop | Type | Default |
|---|---|---|
children * | ReactElement<{ "aria-describedby"?: string }> | – |
content * | ReactNode | – |
title | ReactNode | – |
placement | "top" | "bottom" | "top" |
variant | "dark" | "light" | "dark" |
open | boolean | – |
className | string | – |
Blocks · how it connects
- Built from
- Tokens only
- Used by components
- Accordion, Agent limits card
- Used on screens
- Not used on a screen yet
Dialog
moleculeUsed in 3 filesCentred 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
| Prop | Type | Default |
|---|---|---|
open * | boolean | – |
onOpenChange * | (open: boolean) => void | – |
title * | string | – |
description | ReactNode | – |
children * | ReactNode | – |
size | "md" | "lg" | "xl" | "md" |
hideTitle | boolean | false |
className | string | – |
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.tsxapp/(app)/projects/_components/add-client-dialog.tsxapp/(app)/projects/_components/create-project-dialog.tsx
Drawer
moleculeUsed in 2 filesPanel 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
| Prop | Type | Default |
|---|---|---|
open * | boolean | – |
onOpenChange * | (open: boolean) => void | – |
placement | "start" | "end" | "top" | "bottom" | "end" |
size | "sm" | "md" | "lg" | "md" |
aria-label | string | – |
className | string | – |
children * | ReactNode | – |
Properties · DrawerHeader
| Prop | Type | Default |
|---|---|---|
title * | ReactNode | – |
description | ReactNode | – |
closeLabel | string | "Close" |
className | string | – |
Properties · DrawerBody
| Prop | Type | Default |
|---|---|---|
children * | ReactNode | – |
className | string | – |
Properties · DrawerFooter
| Prop | Type | Default |
|---|---|---|
children * | ReactNode | – |
className | string | – |
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.tsxapp/(app)/proposals/_components/proposals-view.tsx
Pagination
organismUsed in 1 filePrevious / 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
| Prop | Type | Default |
|---|---|---|
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 filesPill 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
| Prop | Type | Default |
|---|---|---|
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.tsxapp/(app)/finance/_components/subscriptions-view.tsx
Tabs
moleculeUsed in 5 filesTabs: 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
| Prop | Type | Default |
|---|---|---|
items * | TabItem[] | – |
value * | string | – |
onChange * | (id: string) => void | – |
label * | string | – |
variant | "underline" | "pill" | "pill-neutral" | "underline" |
loading | boolean | false |
action | ReactNode | – |
idBase | string | – |
Properties · LinkTabs
| Prop | Type | Default |
|---|---|---|
items * | LinkTabItem[] | – |
current * | string | – |
label * | string | – |
variant | "underline" | "pill" | "pill-neutral" | "underline" |
hrefSuffix | string | "" |
action | ReactNode | – |
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.tsxapp/(app)/finance/_components/finance-tabs.tsxapp/(app)/library/_components/library-view.tsxapp/(app)/projects/[id]/_components/project-detail-view.tsxapp/(app)/proposals/_components/proposals-view.tsx
Accordion
moleculeNot used on a screen yetExpandable 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
| Prop | Type | Default |
|---|---|---|
variant | "bordered" | "card" | "bordered" |
size | "md" | "lg" | "md" |
className | string | – |
children * | ReactNode | – |
Properties · AccordionGroup
| Prop | Type | Default |
|---|---|---|
title * | ReactNode | – |
info | ReactNode | – |
className | string | – |
children * | ReactNode | – |
Properties · AccordionItem
| Prop | Type | Default |
|---|---|---|
title * | ReactNode | – |
description | ReactNode | – |
status | "complete" | "current" | "pending" | – |
badge | ReactNode | – |
name | string | – |
defaultOpen | boolean | – |
className | string | – |
children * | ReactNode | – |
Scroll area
atomUsed in 6 filesA 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.tsxapp/(app)/finance/_components/payments-view.tsxapp/(app)/finance/_components/payroll-view.tsxapp/(app)/finance/_components/subscriptions-view.tsxapp/(app)/projects/_components/projects-grouped-list.tsxapp/(app)/proposals/_components/proposals-view.tsx
Glyph
atomUsed in 4 filesShared 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
| Prop | Type | Default |
|---|---|---|
name * | "success" | "error" | "info" | "warning" | "sparkle" | "burst" | – |
className | string | – |
mark | string | "stroke-white" |
fade | boolean | false |
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.tsxapp/(app)/projects/_components/projects-grouped-list.tsxapp/(app)/projects/[id]/_components/project-detail-view.tsxapp/(onboarding)/onboarding/_components/onboarding-steps.tsx
Icon
atomUsed in 11 filesRenders 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
| Prop | Type | Default |
|---|---|---|
name * | (typeof iconNames)[number] | – |
size * | number | – |
className | string | – |
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.tsxapp/(app)/_components/dashboard/overview-header.tsxapp/(app)/_components/projects/projects-table.tsxapp/(app)/library/_components/library-view.tsxapp/(app)/projects/_components/client-cards.tsxapp/(app)/projects/_components/create-project-dialog.tsxapp/(app)/projects/_components/projects-clients-view.tsxapp/(app)/projects/_components/projects-grouped-list.tsxapp/(app)/projects/[id]/_components/project-detail-view.tsxcomponents/layout/sidebar.tsxcomponents/layout/topbar.tsx
Auth card
organismNot used on a screen yetSign-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
| Prop | Type | Default |
|---|---|---|
mode * | "sign-in" | "sign-up" | – |
logo | ReactNode | – |
title | string | – |
subtitle | ReactNode | – |
providers | SocialProvider[] | ["google", "apple", "figma"] |
onProvider | (provider: SocialProvider) => void | – |
onSubmit | (values: AuthValues) => void | – |
pending | boolean | false |
errors | { email?: string; password?: string } | – |
forgotPasswordHref | string | "#" |
switchHref | string | "#" |
className | string | – |
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
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· exportsSocialButtonSocialButtonGroup· Figma 108:11967, 108:12238Use it when
Don’t use it when
Rules
Accessibility
Example
Properties · SocialButton
provider *"google" | "facebook" | "apple" | "x" | "figma" | "dribbble"–theme"brand" | "color-with-brand" | "color""brand"iconOnlybooleanfalselabelstring–Properties · SocialButtonGroup
layout"buttons" | "icons""buttons"classNamestring–children *ReactNode–Blocks · how it connects