// 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.
| 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. |
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:
Button, Callout, Checkbox, Combobox, Menu, Modal, MultiSelectCombobox, ProgressBar, Spinner, and TextInputelements/* building blocks such as Avatar, Card, CopyButton, PaginationControls, Sidebar, Snippet, and ToastContainercomponents/*, features/*, and lib/* stories used across the Convex dashboardWhen asked to build Convex style UI:
elements/* when the UI needs a shared layout or display pattern.components/* or features/* only when the request matches an existing dashboard pattern closely.Use these first for new UI:
ButtonCalloutCheckboxComboboxKeyboardShortcutMenuModalMultiSelectComboboxProgressBarSpinnerTextInputThese cover reusable display and layout patterns:
elements/Avatarelements/AvatarGridelements/Cardelements/CopyButtonelements/DetailPanelelements/PaginationControlselements/ReadonlyCodeelements/ReadonlyCodeDiffelements/Sidebarelements/Snippetelements/ToastContainerelements/UsagePeriodSelectorThese are useful as implementation references when the user asks for admin or dashboard UI:
components/header/NavBarcomponents/header/Breadcrumbscomponents/header/UsageBannercomponents/billing/*components/teamSettings/*components/projectSettings/*features/data/components/*features/functions/components/*features/health/components/*features/logs/components/*features/settings/components/*lib/ConvexStatusBadgelib/ConvexStatusWidgetThese details were confirmed from the live Storybook controls.
Use for primary actions, neutral actions, destructive actions, and unstyled inline actions.
primary, danger, neutral, unstyledxs, sm, md, lgicon, inline, focused, disabled, loading, tip<Button variant="primary" size="md">
Save changes
</Button>
<Button variant="danger" size="sm" disabled>
Delete project
</Button>
Use for inline page feedback and guidance blocks.
instructions, error, hint, localDevUpsell, successchildren<Callout variant="instructions">
Review the settings before continuing.
</Callout>
Use for standard form fields and search style inputs.
idlabel, labelHidden, description, errortext, search, email, time, password, numbersm, mdleftAddon, rightAddon, Icon, SearchIconisSearchLoading<TextInput
id="project-name"
label="Project name"
type="text"
size="md"
/>
Use for boolean settings and bulk selection states.
checked, onChangedisabled<Checkbox
id="email-notifications"
checked={enabled}
onChange={setEnabled}
/>
Use for searchable single selection inputs.
label, options, setSelectedOption{ label, value }selectedOption, placeholder, searchPlaceholderdisableSearch, allowCustomValue, disabledsm, md<Combobox
label="Team"
options={teams}
selectedOption={teamId}
setSelectedOption={setTeamId}
/>
Use for searchable multi select inputs with count based labels.
options, unit, unitPlural, label, selectedOptionslabelHidden and disableSearch<MultiSelectCombobox
label="Regions"
options={regions}
unit="region"
unitPlural="regions"
selectedOptions={selectedRegions}
setSelectedOptions={setSelectedRegions}
/>
Use for focused workflows, confirmations, and settings flows.
title, onClose, childrendescriptionsm, md, lg<Modal
title="Invite team member"
description="Send access to a new teammate."
onClose={closeModal}
size="md"
>
<InviteMemberForm />
</Modal>
Use for loading and background work feedback.
ProgressBar stories include indeterminate, empty, half, full, animated value, and solidSpinner has a default loading state storyBuild forms from:
TextInputCheckboxComboboxMultiSelectComboboxButtonCallout for validation or setup guidanceUse:
Callout for inline information, errors, and success statesProgressBar for long running progressSpinner for short blocking waitselements/ToastContainer for transient feedbackUse these as references for admin style product UI:
components/header/NavBarcomponents/header/Breadcrumbselements/Sidebarelements/Cardelements/DetailPanelelements/* next.components/* or features/* stories before building from scratch.https://storybook.previews.convex.dev/https://convex.dev/brandhttps://storybook.previews.convex.dev/index.jsonStatic analysis checklist for Convex backends covering 72 rules across security, performance, correctness, schema, architecture, configuration, and client-side patterns. Use when writing, reviewing, or auditing Convex code. Trigger on mentions of "convex-doctor", "health score", "static analysis", "anti-patterns", "audit convex", or before shipping backend changes.
Patterns for scaling read-heavy Convex apps to millions of users. Use when optimizing bandwidth, reducing query costs, fixing slow queries, creating digest tables, replacing reactive subscriptions with one-shot fetches, adding compound indexes, debouncing writes, rate-controlling backfills, or running npx convex insights. Trigger when users mention "scale", "bandwidth", "performance", "optimize", "slow queries", "expensive queries", "digest table", "denormalize", or "thundering herd" in the context of Convex.
Guide for when to use and when not to use return validators in Convex functions. Use this skill whenever the user is writing Convex queries, mutations, or actions and needs guidance on return value validation. Also trigger when the user asks about Convex type safety, runtime validation, AI-generated Convex code, Convex AI rules, Convex security best practices, or when they're debugging return type issues in Convex functions. Trigger this skill when users mention "validators", "returns", "return type", or "exact types" in the context of Convex development. Also trigger when writing or reviewing Convex AI rules or prompts that instruct LLMs how to write Convex code.
Set up and configure WorkOS AuthKit authentication with Convex backend. Use when integrating AuthKit, configuring JWT providers, setting up environment variables, or implementing sign in and sign out flows with React and Vite. Supports Netlify deployment.
Debug and troubleshoot WorkOS AuthKit authentication issues with Convex. Use when authentication fails, JWT validation errors occur, user identity returns null, email claims are missing, admin access checks fail, or sign in button does not work. Supports Netlify deployment.