Theming Guide

Preview, configure, and validate RapidKit themes from one page.

Live Preview

Use the interactive playground below to switch themes at runtime and review component rendering.

Default

Preview Surface

Visual

UI

Theme

Preview

Inputs

Email

Search

Start DateApr 19, 2026

Country

Select country

Assignee

Actions

Terms

I agree to the terms

PrimarySecondaryTertiary

UI

Theme

Preview

Data

	Logo	Service↑	Owner↕	Status↕	Region	Created↕	Alerts	Compliant	Tags
		Component Registry	Platform	active	US East	Feb 12, 2026			stable+1
		Docs Preview Worker	Frontend	degraded	US West	Jan 25, 2026			preview+1

0 of 2 row(s) selected.

Showing 1 - 2 of 5 items

Rows per page1020304050

<<<

1 / 3

>>>

Surface

Release Summary

Sync

LatestTheme tokens are in sync across docs, package CSS, and preview.

OverviewActivity

Package Health98%

Active Themes8

Weekly Publish12

Preview richer surfaces like tab framing, separators, button actions, and scrollable content under each theme token set.

Layout

All teams

PublishExport

Active queryTheme

Ready to publish24 components

Token audit finished8 themes checked

Preview snapshots updatedBuild artifacts refreshed

Release notes draftedAwaiting approval

Tokens

BackgroundForegroundPrimarySecondaryMutedAccentDestructiveBorder

Goals

• Ship pre-built themes out of the box.
• Keep components token-driven and host-app agnostic.
• Enable deterministic AI workflows for switching and creating themes.

Token Surface

RapidKit components resolve color and radius from namespaced CSS variables.

Required tokens:

• --rk-background
• --rk-foreground
• --rk-card
• --rk-card-foreground
• --rk-popover
• --rk-popover-foreground
• --rk-primary
• --rk-primary-foreground
• --rk-secondary
• --rk-secondary-foreground
• --rk-muted
• --rk-muted-foreground
• --rk-accent
• --rk-accent-foreground
• --rk-destructive
• --rk-destructive-foreground
• --rk-border
• --rk-input
• --rk-ring
• --rk-radius

Optional style tokens used by core components (recommended):

• --rk-font-sans
• --rk-font-mono
• --rk-button-height
• --rk-button-padding-x
• --rk-button-padding-y
• --rk-button-font-size
• --rk-button-font-weight
• --rk-button-letter-spacing
• --rk-button-shadow
• --rk-button-shadow-hover
• --rk-control-height
• --rk-control-padding-x
• --rk-control-padding-y
• --rk-control-font-size
• --rk-control-shadow
• --rk-control-shadow-focus
• --rk-checkbox-size
• --rk-checkbox-radius

Using Built-In Themes

import '@rapidset/rapidkit/styles.css';
import '@rapidset/rapidkit/themes/default.css';

Swap to slate:

import '@rapidset/rapidkit/styles.css';
import '@rapidset/rapidkit/themes/slate.css';

Additional built-in options:

import '@rapidset/rapidkit/styles.css';
import '@rapidset/rapidkit/themes/carbon.css';

import '@rapidset/rapidkit/styles.css';
import '@rapidset/rapidkit/themes/corporate.css';

import '@rapidset/rapidkit/styles.css';
import '@rapidset/rapidkit/themes/ocean.css';

import '@rapidset/rapidkit/styles.css';
import '@rapidset/rapidkit/themes/polaris.css';

import '@rapidset/rapidkit/styles.css';
import '@rapidset/rapidkit/themes/midnight.css';

import '@rapidset/rapidkit/styles.css';
import '@rapidset/rapidkit/themes/sand.css';

import '@rapidset/rapidkit/styles.css';
import '@rapidset/rapidkit/themes/forest.css';

import '@rapidset/rapidkit/styles.css';
import '@rapidset/rapidkit/themes/sunset.css';

AI-Friendly Commands

List themes:

pnpm theme:list

Apply a built-in theme to the workspace default:

pnpm theme:apply --theme default
pnpm theme:apply --theme slate --mode dark

Create a custom theme scaffold:

pnpm theme:create --id brand-x --from default

This command creates:

• src/themes/brand-x.css
• ai/contracts/themes/brand-x-theme.contract.json
• a new themes entry in ai/contracts/index.json

Extending With shadcn Host Tokens

src/styles.css bridges shadcn tokens (--background, --primary, and others) to RapidKit tokens (--rk-*). If your host app already defines shadcn tokens, components can render correctly without rewriting component code.

For full control, set --rk-* tokens directly in your app theme CSS.

Theme Configuration Workflow

This section explains how theme selection, theme files, and runtime mode behavior are configured in this workspace.

Configuration Files

• ai/contracts/index.json: source of truth for available theme entries (id, contractPath, cssPath).
• ai/contracts/themes/*.contract.json: contract metadata for each theme.
• ai/theme.schema.json: JSON schema that validates theme contract structure.
• ai/theme.active.json: current workspace-selected theme and preferred mode metadata.
• src/themes/active.css: generated import file that points to the selected theme stylesheet.
• src/themes/*.css: built-in theme token files.

Theme Selection Flow

1. Run pnpm theme:list to inspect available themes from contracts.
2. Run pnpm theme:apply --theme <theme-id> [--mode light|dark|system].
3. The script updates:
   • src/themes/active.css to import the selected src/themes/<id>.css
   • ai/theme.active.json with themeId, mode, and updatedAt
4. Components pick up tokens via src/styles.css and Tailwind semantic utilities.

Runtime Mode Behavior

--mode is stored as workspace metadata in ai/theme.active.json.

It does not automatically apply .dark at runtime. Dark mode still depends on your runtime class strategy (Tailwind darkMode: ['class']), so the host app or preview shell must control the .dark class.

Typography And Component Style Tokens

Themes support styling beyond color. In addition to color and radius tokens, the library consumes optional typography and component-shape tokens, including:

• --rk-font-sans and --rk-font-mono for typeface control
• button sizing and rhythm tokens (--rk-button-height, --rk-button-padding-x, --rk-button-padding-y)
• button typography tokens (--rk-button-font-size, --rk-button-font-weight, --rk-button-letter-spacing)
• button elevation tokens (--rk-button-shadow, --rk-button-shadow-hover)
• control layout tokens (--rk-control-height, --rk-control-padding-x, --rk-control-padding-y, --rk-control-font-size)
• control elevation tokens (--rk-control-shadow, --rk-control-shadow-focus)
• checkbox shape tokens (--rk-checkbox-size, --rk-checkbox-radius)

When creating a custom theme with pnpm theme:create, copy and tune these tokens in the generated CSS so components remain visually polished out of the box.

Validation And Quality Gates

Run contract validation after theme changes:

pnpm validate:contracts

Theme-related CI checks in .github/workflows/ci.yml include:

• pnpm theme:list to ensure registry metadata remains readable
• pnpm test:scripts to verify theme script integration behavior
• pnpm validate:contracts to confirm theme contract/index consistency
• standard lint/type/test/build quality gates before release

Docs publishing CI in .github/workflows/docs-deploy.yml builds Nextra and deploys documentation to GitHub Pages on main.

AI Context And MCP Compatibility

Theme metadata is intentionally machine-readable for AI systems:

• ai/contracts/index.json provides the theme registry
• ai/contracts/themes/*.contract.json defines theme contract metadata
• ai/theme.active.json records workspace-selected theme state

RapidKit uses the standalone rapidmcp MCP server package.

For theme workflows, that server can expose active theme state, theme registry metadata, and theme contract details without requiring tools to inspect the repository manually.

Run it with:

pnpm --dir ../rapidmcp mcp:start -- --root "$PWD"

For a broader overview of the MCP surface, see docs/MCP-SERVER.md.

Recommended release checks:

pnpm lint
pnpm tsc --noEmit
pnpm test
pnpm build

Consumer Packaging Notes

Published consumers usually import a concrete theme directly:

import '@rapidset/rapidkit/styles.css';
import '@rapidset/rapidkit/themes/default.css';

src/themes/active.css is primarily a workspace/development convenience for switching themes locally.