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

OKLCH semantic colors
Surfaces, brand, feedback, charts, and sidebar 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 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
…
--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 (Open Sans / Geist Sans when loaded)
--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.