21st Design Sync — publish your project's design as a theme
Take the design a project already ships (its light + dark CSS variables) and
publish it to the public 21st.dev theme library so anyone can preview,
bookmark, and apply it. Under the hood this is one CLI call:
21st publish-theme <file.css> --name "…".
Pre-flight (always)
- Auth needs a real API key.
publish-themeis a management endpoint: it accepts a21st_sk_…key only, not a21st loginsession token. Get one at https://21st.dev/mcp (or https://21st.dev/settings/api-keys) and pass it via--api-key 21st_sk_…or theTWENTYFIRST_TOKEN/API_KEY_21STenv var. If the user has no key, point them there — don't try to mint one. - The CLI is the unified
@21st-dev/cli(bin21st). Usenpx @21st-dev/cliif it isn't installed. - Publishing is public and outward-facing. A published theme is immediately
is_publicin the community library (there is no unlisted/private option for themes). Confirm with the user before publishing.
Step 1 — Find the project's design tokens
Locate the file that defines the shadcn/Tailwind theme variables. Check, in order:
app/globals.css,src/app/globals.csssrc/index.css,styles/globals.css,app/styles/globals.css
You're looking for a :root { … } block of CSS custom properties
(--background, --foreground, --card, --primary, --secondary,
--muted, --accent, --destructive, --border, --input, --ring, the
--chart-* / --sidebar-* tokens, --radius) and a matching .dark { … }
block. Values may be hsl(...), oklch(...), hex, or raw channels — keep them
exactly as the project wrote them.
Tailwind v4 projects usually keep the same :root / .dark blocks plus an
@theme inline mapping; you only need the :root and .dark token values,
not the @theme mapping.
Step 2 — Assemble a valid theme CSS file
The publish endpoint parses --name: value; pairs out of a :root { … } block
and a .dark { … } block, and requires both to be non-empty. So the file
you publish must contain both.
- Copy the project's
:rootand.darkblocks into a standalone file (e.g.project-theme.css). Nothing else is required. - If the project has only a light
:rootand no.dark(or an empty one), generate a dark variant before publishing — don't ship a theme with an empty dark mode. Reuse theadd-dark-mode/oklch-skillapproach: invert lightness while preserving hue/chroma so the dark set stays on-brand. Keep the same token names. - Keep the token names shadcn-standard so the theme previews correctly on the card and applies cleanly for others.
Minimal shape:
Step 3 — Name & tag it
- Name (required, ≤ 50 chars): infer from the project — the product/brand
name from
package.json, the repo, or the site title. Ask the user if it's ambiguous. - Tags (optional): a few descriptors that match how people browse themes,
e.g.
dark,minimal,neutral,vibrant,saas. Pass comma-separated.
Step 4 — Publish
The command prints the live theme URL (https://21st.dev/community/themes/<slug>).
Share it with the user.
Updating vs re-publishing
- Each
publish-themecreates a NEW theme (there's no upsert-by-slug like components have). Running it twice = two themes in the library. - To change name/tags/visibility on an existing theme, edit it in place:
21st edit <theme-id> --type theme [--name "…"] [--tags a,b]. - To change the colors, publish a fresh file and remove the old one:
21st delete <theme-id> --type theme --yes(soft-unpublish, reversible).
When NOT to use this
- Syncing a component library to a Claude Design project → that's the
built-in
/design-syncskill, a different destination. - Publishing a component (not a color theme) → use
21st-registry.
