convex-design-system
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.
Best use case
convex-design-system is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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.
Teams using convex-design-system should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/convex-design-system/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How convex-design-system Compares
| Feature / Agent | convex-design-system | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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:
1. Start with the smallest reusable primitive that matches the job.
2. Reach for `elements/*` when the UI needs a shared layout or display pattern.
3. Reuse `components/*` or `features/*` only when the request matches an existing dashboard pattern closely.
4. Prefer composition over custom styling. Build from existing pieces before inventing a new wrapper.
5. 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`
```tsx
<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`
```tsx
<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`
```tsx
<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
```tsx
<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`
```tsx
<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`
```tsx
<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`
```tsx
<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`Related Skills
workos-convex-debug
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.
workos-convex-auth
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.
convex-scale-optimization
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.
frontend-design
Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context.
convex-self-hosting
Integrate Convex static self hosting into existing apps using the latest upstream instructions from get-convex/self-hosting every time. Use when setting up upload APIs, HTTP routes, deployment scripts, migration from external hosting, or troubleshooting static deploy issues across React, Vite, Next.js, and other frontends.
convex-return-validators
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.
convex-doctor
Static 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.
convex
Routes general Convex requests to the right project skill. Use when the user asks which Convex skill to use or gives an underspecified Convex app task.
convex-setup-auth
Sets up Convex auth, identity mapping, and access control. Use for login, auth providers, users tables, protected functions, or roles in a Convex app.
convex-quickstart
Creates or adds Convex to an app. Use for new Convex projects, npm create convex@latest, frontend setup, env vars, or the first npx convex dev run.
convex-performance-audit
Audits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.
convex-migration-helper
Plans Convex schema and data migrations with widen-migrate-narrow and @convex-dev/migrations. Use for breaking schema changes, backfills, table reshaping, or zero-downtime rollouts.