| name | convex-design-system |
| description | Convex UI component patterns from the live Storybook preview. Use when building React components, forms, modals, navigation, feedback states, or app layouts that should match the current Convex design system. Applies to both shared primitives and dashboard style product UI. |
Convex Design System
Use the live Storybook as the source of truth: https://storybook.previews.convex.dev/
The current Storybook is broader than the older website only library. It now includes:
- primitives such as
Button, Callout, Checkbox, Combobox, Menu, Modal, MultiSelectCombobox, ProgressBar, Spinner, and TextInput
- shared
elements/* building blocks such as Avatar, Card, CopyButton, PaginationControls, Sidebar, Snippet, and ToastContainer
- product level
components/*, features/*, and lib/* stories used across the Convex dashboard
How to use this skill
When asked to build Convex style UI:
- Start with the smallest reusable primitive that matches the job.
- Reach for
elements/* when the UI needs a shared layout or display pattern.
- Reuse
components/* or features/* only when the request matches an existing dashboard pattern closely.
- Prefer composition over custom styling. Build from existing pieces before inventing a new wrapper.
- Do not rely on old website Storybook URLs or old token lists unless you verify them again.
Current Storybook map
Primitives
Use these first for new UI:
Button
Callout
Checkbox
Combobox
KeyboardShortcut
Menu
Modal
MultiSelectCombobox
ProgressBar
Spinner
TextInput
Shared elements
These cover reusable display and layout patterns:
elements/Avatar
elements/AvatarGrid
elements/Card
elements/CopyButton
elements/DetailPanel
elements/PaginationControls
elements/ReadonlyCode
elements/ReadonlyCodeDiff
elements/Sidebar
elements/Snippet
elements/ToastContainer
elements/UsagePeriodSelector
Product and dashboard references
These are useful as implementation references when the user asks for admin or dashboard UI:
components/header/NavBar
components/header/Breadcrumbs
components/header/UsageBanner
components/billing/*
components/teamSettings/*
components/projectSettings/*
features/data/components/*
features/functions/components/*
features/health/components/*
features/logs/components/*
features/settings/components/*
lib/ConvexStatusBadge
lib/ConvexStatusWidget
Verified primitive patterns
These details were confirmed from the live Storybook controls.
Button
Use for primary actions, neutral actions, destructive actions, and unstyled inline actions.
- variants:
primary, danger, neutral, unstyled
- sizes:
xs, sm, md, lg
- supports:
icon, inline, focused, disabled, loading, tip
<Button variant="primary" size="md">
Save changes
</Button>
<Button variant="danger" size="sm" disabled>
Delete project
</Button>
Callout
Use for inline page feedback and guidance blocks.
- variants seen in controls:
instructions, error, hint, localDevUpsell, success
- accepts
children
<Callout variant="instructions">
Review the settings before continuing.
</Callout>
TextInput
Use for standard form fields and search style inputs.
- required in stories:
id
- supports:
label, labelHidden, description, error
- input types seen in controls:
text, search, email, time, password, number
- sizes:
sm, md
- supports addons and icons:
leftAddon, rightAddon, Icon, SearchIcon
- supports
isSearchLoading
<TextInput
id="project-name"
label="Project name"
type="text"
size="md"
/>
Checkbox
Use for boolean settings and bulk selection states.
- required in stories:
checked, onChange
- supports
disabled
- includes checked, unchecked, and indeterminate states
<Checkbox
id="email-notifications"
checked={enabled}
onChange={setEnabled}
/>
Combobox
Use for searchable single selection inputs.
- required in stories:
label, options, setSelectedOption
- option shape:
{ label, value }
- supports
selectedOption, placeholder, searchPlaceholder
- supports
disableSearch, allowCustomValue, disabled
- sizes:
sm, md
<Combobox
label="Team"
options={teams}
selectedOption={teamId}
setSelectedOption={setTeamId}
/>
MultiSelectCombobox
Use for searchable multi select inputs with count based labels.
- required in stories:
options, unit, unitPlural, label, selectedOptions
- supports
labelHidden and disableSearch
<MultiSelectCombobox
label="Regions"
options={regions}
unit="region"
unitPlural="regions"
selectedOptions={selectedRegions}
setSelectedOptions={setSelectedRegions}
/>
Modal
Use for focused workflows, confirmations, and settings flows.
- required in stories:
title, onClose, children
- supports optional
description
- sizes:
sm, md, lg
<Modal
title="Invite team member"
description="Send access to a new teammate."
onClose={closeModal}
size="md"
>
<InviteMemberForm />
</Modal>
ProgressBar and Spinner
Use for loading and background work feedback.
ProgressBar stories include indeterminate, empty, half, full, animated value, and solid
Spinner has a default loading state story
Composition guidance
Forms
Build forms from:
TextInput
Checkbox
Combobox
MultiSelectCombobox
Button
Callout for validation or setup guidance
Feedback states
Use:
Callout for inline information, errors, and success states
ProgressBar for long running progress
Spinner for short blocking waits
elements/ToastContainer for transient feedback
App layout
Use these as references for admin style product UI:
components/header/NavBar
components/header/Breadcrumbs
elements/Sidebar
elements/Card
elements/DetailPanel
Decision rules
- If the request is a new button, input, modal, or filter control, use a primitive first.
- If the request is a dashboard panel, code display, snippet, toast, or navigation shell, inspect
elements/* next.
- If the request matches billing, team settings, logs, data browser, or deployment settings, inspect the related
components/* or features/* stories before building from scratch.
- If a prop or state is unclear, check the live Storybook controls instead of guessing.
Additional resources
- Live Storybook:
https://storybook.previews.convex.dev/
- Brand guide:
https://convex.dev/brand
- Storybook index:
https://storybook.previews.convex.dev/index.json