Foundations

Styling

A guide to the Constructive color system and CSS variables. Tokens ship with @constructive-io/ui and the shadcn registry theme — the same values power every primitive on this site.

Overview

The theme builds on shadcn/ui’s CSS variable approach: semantic names on :root and .dark, wired into Tailwind via @theme inline so utilities like bg-primary and text-muted-foreground always track the active mode.

What you get

hsl() neutral ramp + OKLCH accents
Pure-neutral hsl() surfaces and text (strong 16% · default 36% · subtle 50% · selected 96% · border 95%) with OKLCH brand, feedback, and chart tokens in light and dark.
Radius scale
A single --radius (0.5rem) with derived xs → 2xl steps for consistent corners.
Shadows & card elevation
Tailwind shadow steps plus package utilities shadow-card and shadow-card-lg.
Typography stacks
Sans, mono, and serif CSS variables mapped to font-sans / font-mono utilities.
Z-index layers
Named stacking levels for floating UI, modals, toasts, and the portal root.

Swatches below resolve against the live document theme — use the theme toggle in the top bar to compare light and dark. Source of truth is packages/ui/src/theme.ts; generated CSS is imported as @constructive-io/ui/globals.css.

Installation

Pull in the full token set with one import (npm) or by adding the registry theme (shadcn).

@constructive-io/ui

Install the package, then import the generated globals in your app stylesheet.

# install

pnpm add @constructive-io/ui

# app/globals.css

@import '@constructive-io/ui/globals.css';

New to the dual install paths? See Setup for the full install guide. Your npm/registry choice is remembered across pages.

Colors

Semantic tokens pair a surface with a foreground. Prefer names like bg-primary over raw hex so components stay mode-aware.

Contrast pairslive

Aa Bb Cc 123background / foreground
Aa Bb Cc 123primary / primary-foreground
Aa Bb Cc 123secondary / secondary-foreground
Aa Bb Cc 123muted / muted-foreground
Aa Bb Cc 123card / subtle-foreground
Aa Bb Cc 123accent / accent-foreground
Aa Bb Cc 123destructive / destructive-foreground
Aa Bb Cc 123card / card-foreground
Aa Bb Cc 123popover / popover-foreground

Token galleryCSS vars · Tailwind

Surfaces

Page canvas, raised panels, and floating layers.

--backgroundbg-background
App canvas / body background
…
--foregroundbg-foreground
Default body text
…
--cardbg-card
Card and panel surfaces
…
--card-foregroundbg-card-foreground
Text on card surfaces
…
--popoverbg-popover
Popover, menu, and select surfaces
…
--popover-foregroundbg-popover-foreground
Text on popover surfaces
…

Brand & interactive

Primary actions, secondary fills, and quiet emphasis.

--primarybg-primary
Brand accent and primary actions
…
--primary-foregroundbg-primary-foreground
Text/icons on primary
…
--secondarybg-secondary
Secondary buttons and fills
…
--secondary-foregroundbg-secondary-foreground
Text on secondary
…
--mutedbg-muted
Subtle backgrounds and wells
…
--muted-foregroundbg-muted-foreground
Secondary and helper text
…
--subtle-foregroundbg-subtle-foreground
Subtle — placeholders, shortcuts, tertiary hints
…
--accentbg-accent
Hover, selected, and soft highlight
…
--accent-foregroundbg-accent-foreground
Text on accent
…

Feedback

Semantic status colors for errors, success, and warnings.

--destructivebg-destructive
Destructive actions and error states
…
--destructive-foregroundbg-destructive-foreground
Text on destructive
…
--infobg-info
Informational status
…
--info-foregroundbg-info-foreground
Text for info emphasis
…
--successbg-success
Success and positive status
…
--success-foregroundbg-success-foreground
Text for success emphasis
…
--warningbg-warning
Warning and caution status
…
--warning-foregroundbg-warning-foreground
Text for warning emphasis
…

Borders, inputs & focus

Structural lines, field chrome, and focus rings.

--borderbg-border
Default borders (often used at 60% opacity)
…
--inputbg-input
Input borders and field edges
…
--ringbg-ring
Focus ring color
…

Charts

Series colors for data visualization.

--chart-1bg-chart-1
Chart series 1
…
--chart-2bg-chart-2
Chart series 2
…
--chart-3bg-chart-3
Chart series 3
…
--chart-4bg-chart-4
Chart series 4
…
--chart-5bg-chart-5
Chart series 5
…

Sidebar

Navigation shell tokens used by layout chrome.

--sidebarbg-sidebar
Sidebar background
…
--sidebar-foregroundbg-sidebar-foreground
Sidebar text
…
--sidebar-primarybg-sidebar-primary
Sidebar brand / active accent
…
--sidebar-primary-foregroundbg-sidebar-primary-foreground
Text on sidebar primary
…
--sidebar-accentbg-sidebar-accent
Sidebar hover / active fill
…
--sidebar-accent-foregroundbg-sidebar-accent-foreground
Text on sidebar accent
…
--sidebar-borderbg-sidebar-border
Sidebar borders
…
--sidebar-ringbg-sidebar-ring
Sidebar focus ring
…

Radius

One base radius drives the scale. Default --radius is 0.5rem; derived steps keep buttons, inputs, and cards optically aligned.

Scale--radius: 0.5rem

--radius-xsrounded-xs
calc(var(--radius) - 6px)
--radius-smrounded-sm
calc(var(--radius) - 4px)
--radius-mdrounded-md
var(--radius) · 0.5rem
--radius-lgrounded-lg
calc(var(--radius) + 2px)
--radius-xlrounded-xl
calc(var(--radius) + 6px)
--radius-2xlrounded-2xl
calc(var(--radius) + 10px)

Shadows

Standard shadow utilities plus card elevation helpers that use --shadow-border and --shadow-border-hover for a subtle edge + lift.

Elevation

shadow-2xs
shadow-xs
shadow-sm
shadow
shadow-md
shadow-lg
shadow-xl
shadow-2xl

Card elevation utilities (package-specific, not Tailwind defaults):

.shadow-card
Default elevated card edge (uses --shadow-border)
.shadow-card-lg
Hover / emphasized card edge (uses --shadow-border-hover)

Typography

Font stacks are CSS variables mapped into Tailwind. This docs site loads Geist; the package defaults fall back to Open Sans and system mono.

Font tokens

--font-sansfont-sans
The quick brown fox jumps over the lazy dog
Body UI font (Inter by default)
--font-monofont-mono
const token = "primary"
Code and tabular data
--font-seriffont-serif
Editorial serif for long-form accents
Optional serif stack (Georgia)

Z-index layers

Named layers keep portaled overlays (dialogs, menus, toasts) above page content without ad-hoc magic numbers.

Stacking

Token	Value	Use
`--z-layer-floating`	1000	Floating UI above page content
`--z-layer-modal-backdrop`	2000	Modal / dialog backdrops
`--z-layer-modal-content`	2001	Modal / dialog content
`--z-layer-floating-elevated`	3000	Elevated floating layers
`--z-layer-toast`	4000	Toasts and transient notices
`--z-layer-portal-root`	9999	Portal root stacking context

The package also sets isolation on the app root and position: relative on body so Base UI portals and backdrops stack predictably — including on iOS Safari after scroll.

Dark mode

Tokens redefine under .dark. Pair the class strategy with next-themes (or your own toggle) so documentElement carries class dark.

Variant

Tailwind v4 dark variant

/* from package globals */
@custom-variant dark (&:is(.dark *));

Light values live on :root; dark values on .dark. Primary brand blue stays consistent across modes; neutrals and surfaces shift for contrast.

Customization

Override semantic variables after the package import. Keep names intact so components continue to resolve the right tokens.

Override example

app/globals.css

/* Override after the package import */
@import '@constructive-io/ui/globals.css';

:root {
  --primary: oklch(0.55 0.18 250);
  --radius: 0.625rem;
}

.dark {
  --primary: oklch(0.72 0.14 250);
}

Prefer redefining --primary, --radius, and surface tokens over editing component source.
Always set matching *-foreground pairs when you change a surface or brand color.
For registry installs, overrides still belong in your app CSS after generated theme CSS.

Theme presets

Ten editor-classic palettes adapted to Constructive tokens — Ghostty built-ins and iTerm2-Color-Schemes, each AA-checked against its own surfaces. Install one over the base theme, or open Create to tune it further.

Catppuccin

Catppuccin Mocha mapped onto the Constructive token set, with Catppuccin Latte for light mode. Ported from the Ghostty built-in color schemes.

pnpm dlx shadcn@latest add @constructive/theme-catppuccin

Dracula

Dracula mapped onto the Constructive token set, with a derived light mode. Ported from the Ghostty built-in color schemes.

pnpm dlx shadcn@latest add @constructive/theme-dracula

Nord

Nord mapped onto the Constructive token set, with Nord Light for light mode. Ported from the Ghostty built-in color schemes.

pnpm dlx shadcn@latest add @constructive/theme-nord

Gruvbox

Gruvbox Dark mapped onto the Constructive token set, with Gruvbox Light for light mode. Ported from the Ghostty built-in color schemes.

pnpm dlx shadcn@latest add @constructive/theme-gruvbox

Tokyo Night

TokyoNight mapped onto the Constructive token set, with TokyoNight Day for light mode. Ported from the Ghostty built-in color schemes.

pnpm dlx shadcn@latest add @constructive/theme-tokyo-night

One Dark

Atom One Dark mapped onto the Constructive token set, with Atom One Light for light mode. Ported from the Ghostty built-in color schemes.

pnpm dlx shadcn@latest add @constructive/theme-one-dark

Solarized

iTerm2 Solarized Dark mapped onto the Constructive token set, with iTerm2 Solarized Light for light mode. Ported from the Ghostty built-in color schemes.

pnpm dlx shadcn@latest add @constructive/theme-solarized

Rosé Pine

Rose Pine mapped onto the Constructive token set, with Rose Pine Dawn for light mode. Ported from the Ghostty built-in color schemes.

pnpm dlx shadcn@latest add @constructive/theme-rose-pine

Everforest

Everforest Dark Med mapped onto the Constructive token set, with Everforest Light Med for light mode. Ported from the Ghostty built-in color schemes.

pnpm dlx shadcn@latest add @constructive/theme-everforest

Kanagawa

Kanagawa Wave mapped onto the Constructive token set, with Kanagawa Lotus for light mode. Ported from the Ghostty built-in color schemes.

pnpm dlx shadcn@latest add @constructive/theme-kanagawa

Presets require the Constructive base theme and merge only color tokens — radius, shadows, and motion stay yours. Try them live on Create, where moving a dial releases just that token family.