Design System — uicraft

Architecture

Two-layer system: raw palette scales mapped to semantic tokens.

Palette (raw scales)

--grey-50 … --grey-950

--blue-50 … --blue-950

--green-50 … --green-950

--red-50 … --red-950

--orange-50 … --orange-950

Semantic Tokens

--mains-primary → grey-950

--surfaces-surface → generic-0

--info-primary → blue-500

--border-default → grey-100

--error-background → red-50

How It Works

Two independent axes: visual theme (fonts, radius, colors) and color mode (light/dark).

Visual Theme

data-theme="..."

Controls font family, border radius, color palette

Color Mode

class="dark"

Toggles light/dark semantic tokens

Color Tokens

Semantic color tokens organized by purpose. All switch automatically in dark mode.

Group	Token	UC Class	Description
Foreground	--mains-primary	text-mains-primary	Primary text & icons
Foreground	--mains-secondary	text-mains-secondary	Secondary text
Foreground	--mains-tertiary	text-mains-tertiary	Tertiary / subtle text
Foreground	--mains-quaternary	text-mains-quaternary	Disabled / placeholder
Foreground	--generic-white	text-generic-white	Text on accent / brand fills
Neutrals	--surfaces-background	bg-surfaces-background	Page background
Neutrals	--surfaces-surface	bg-surfaces-surface	Card / panel surface
Neutrals	--surfaces-subtle	bg-surfaces-subtle	Hover fills
Neutrals	--surfaces-moderate	bg-surfaces-moderate	Secondary fills
Neutrals	--surfaces-contrast	bg-surfaces-contrast	Stronger fills
Border	--border-default	border-border-default	Standard border
Border	--border-strong	border-border-strong	Prominent border
Accents	--accents-brand	bg-accents-brand / text-accents-brand	Brand / primary
Accents	--info-primary	bg-info-primary / text-info-primary	Info / Focus
Accents	--success-primary	bg-success-primary / text-success-primary	Success
Accents	--error-primary	bg-error-primary / text-error-primary	Error / Danger
Accents	--warning-primary	bg-warning-primary / text-warning-primary	Warning
Tints	--accents-brand / 0.1	bg-brand-tint	Brand tint background (alpha)
Tints	--info-background	bg-info-background	Info tint background
Tints	--success-background	bg-success-background	Success tint background
Tints	--error-background	bg-error-background	Danger tint background
Tints	--warning-background	bg-warning-background	Warning tint background
Interactive	--accents-brand	bg-accents-brand	Brand button — default
Interactive	--brand-hover	bg-brand-hover	Brand button — hover
Interactive	--brand-active	bg-brand-active	Brand button — active
Interactive	--brand-disabled	bg-brand-disabled	Brand button — disabled
Interactive	--error-primary	bg-error-primary	Danger button — default
Interactive	--red-600	bg-red-600	Danger button — hover
Interactive	--red-700	bg-red-700	Danger button — active
Interactive	--red-200	bg-red-200	Danger button — disabled
Interactive	--surfaces-subtle	bg-surfaces-subtle	Secondary button — default
Interactive	--surfaces-moderate	bg-surfaces-moderate	Secondary button — hover
Interactive	--surfaces-contrast	bg-surfaces-contrast	Secondary button — active
Interactive	--surfaces-subtle	bg-surfaces-subtle	Secondary button — disabled
Focus Ring	--border-focus	ring-focus-brand	Brand focus ring
Focus Ring	--border-focus	ring-focus-danger	Danger focus ring
Focus Ring	--border-focus	ring-focus-neutral	Neutral focus ring
Constant	--generic-white	text-generic-white / bg-generic-white	Always white
Constant	--generic-black	text-generic-black / bg-generic-black	Always black

Spacing

Consistent spacing scale used for padding, margin, and gap.

Key	Value	Example Classes
0	0	uc-p-0 uc-m-0 uc-gap-0
0.5	0.125rem (2px)	uc-p-0.5 uc-m-0.5 uc-gap-0.5
1	0.25rem (4px)	uc-p-1 uc-m-1 uc-gap-1
1.5	0.375rem (6px)	uc-p-1.5 uc-m-1.5 uc-gap-1.5
2	0.5rem (8px)	uc-p-2 uc-m-2 uc-gap-2
3	0.75rem (12px)	uc-p-3 uc-m-3 uc-gap-3
4	1rem (16px)	uc-p-4 uc-m-4 uc-gap-4
5	1.25rem (20px)	uc-p-5 uc-m-5 uc-gap-5
6	1.5rem (24px)	uc-p-6 uc-m-6 uc-gap-6
8	2rem (32px)	uc-p-8 uc-m-8 uc-gap-8
10	2.5rem (40px)	uc-p-10 uc-m-10 uc-gap-10
12	3rem (48px)	uc-p-12 uc-m-12 uc-gap-12
16	4rem (64px)	uc-p-16 uc-m-16 uc-gap-16

Typography

Font size scale with corresponding utility classes.

Name	Size	Class	Preview
xs	0.75rem (12px)	uc-text-xs	Aa
sm	0.875rem (14px)	uc-text-sm	Aa
base	1rem (16px)	uc-text-base	Aa
lg	1.125rem (18px)	uc-text-lg	Aa
xl	1.25rem (20px)	uc-text-xl	Aa
2xl	1.5rem (24px)	uc-text-2xl	Aa
3xl	1.875rem (30px)	uc-text-3xl	Aa
4xl	2.25rem (36px)	uc-text-4xl	Aa

Shadows

Elevation system for layered interfaces.

--shadow-sm

Subtle shadow for inputs

--shadow

Default component shadow

--shadow-md

Medium elevation

--shadow-lg

High elevation (dropdowns)

--shadow-xl

Maximum elevation (modals)

Z-Index

Layering system to keep overlapping elements in the right order.

Token	Value	Usage
--z-dropdown	1000	Dropdowns
--z-sticky	1020	Sticky headers
--z-fixed	1030	Fixed elements
--z-drawer	1040	Drawers / sheets
--z-modal	1050	Modals / dialogs
--z-popover	1060	Popovers
--z-tooltip	1070	Tooltips

Transitions

Timing tokens for consistent animation speed.

Token	Value	Usage
--transition-fast	150ms ease	Hover / micro-interactions
--transition-normal	200ms ease	Default transitions
--transition-slow	300ms ease	Page / layout transitions

Usage

Reuse ready uicraft classes and components — they already consume semantic tokens.

html

Utility Classes

UC

Primary text token

Disabled text token

Surface + border via semantic utility classes

Ready Components

UI

Semantic tokens in components

Colors/radius/typography come from active theme tokens.

<!-- Reuse ready uicraft classes/components -->
<div class="uc-card">
  <div class="uc-card-header">
    <span class="uc-badge uc-badge-secondary">Token-driven UI</span>
  </div>
  <div class="uc-card-body">
    <p class="uc-text-mains-primary">Primary text token</p>
    <p class="uc-text-mains-quaternary">Secondary text token</p>
    <button class="uc-btn uc-btn-primary">Primary Action</button>
  </div>
</div>

Built-in Presets

Three theme presets ship with uicraft. Each changes fonts, radius, and subtle color shifts.

Theme	Font Family	Radius (lg)	Character
default	Inter, system-ui, sans-serif	12px	Clean and modern
editorial	Source Serif 4, Georgia, serif	10px	Classic, editorial feel
rounded-sans	Manrope, Inter, sans-serif	14px	Soft, rounded corners

Aa

Default

data-theme="default"

Aa

Editorial

data-theme="editorial"

Aa

Rounded Sans

data-theme="rounded-sans"

Dark Mode

Add .dark to <html> to switch all semantic tokens to their dark variants.

Light mode

--mains-primary → grey-950

--surfaces-background → grey-50

--surfaces-surface → white

--border-default → grey-100

Dark mode

--mains-primary → grey-50

--surfaces-background → grey-950

--surfaces-surface → black

--border-default → grey-900

html

Dark mode toggle & persistence script

<!-- Toggle dark mode with JS -->
<script>
  function toggleDarkMode() {
    const html = document.documentElement;
    html.classList.toggle('dark');
    const mode = html.classList.contains('dark') ? 'dark' : 'light';
    localStorage.setItem('theme', mode);
  }
</script>

<!-- Restore on page load (put in <head>) -->
<script>
  const mode = localStorage.getItem('theme');
  if (mode === 'dark' ||
      (!mode && matchMedia('(prefers-color-scheme: dark)').matches)) {
    document.documentElement.classList.add('dark');
  }
</script>

Switching Themes

Set data-theme on <html> and persist with localStorage.

html

Live Theme Controls

Mode

Theme

Live Tokens

Preview

Foreground and accents react to current theme + mode.

Semantic tokens in sync

Sample Component

Button

Radius and colors update as you switch presets.

<!-- Switch theme preset -->
<script>
  function setTheme(name) {
    document.documentElement.setAttribute('data-theme', name);
    localStorage.setItem('uicraft-theme', name);
  }

  // Restore on page load
  const theme = localStorage.getItem('uicraft-theme') || 'default';
  document.documentElement.setAttribute('data-theme', theme);
</script>

Custom Theme

Create a JSON file in themes/ to add your own preset.

json

1

Create a JSON file: themes/my-theme.json

2

Run the build — theme CSS is auto-generated from JSON

3

Apply with data-theme="my-theme"

{
  "name": "my-theme",
  "label": "My Theme",
  "fontFamily": "Poppins, system-ui, sans-serif",
  "radius": {
    "sm": "8px",
    "lg": "12px",
    "xl": "16px",
    "2xl": "20px",
    "3xl": "24px"
  },
  "colors": {
    "genericWhite": "0 0% 100%",
    "genericBlack": "0 0% 0%",
    "mainsPrimary": "240 3% 6%",
    "mainsSecondary": "228 4% 25%",
    "surfacesBackground": "0 0% 98%",
    "surfacesSurface": "0 0% 100%",
    "borderDefault": "0 5% 92%",
    "infoPrimary": "219 88% 54%",
    ...
  },
  "dark": { "colors": { "mainsPrimary": "0 0% 98%", ... } }
}

Token Override Order

How CSS specificity works: theme preset > dark mode > component styles > utilities.

1

Theme preset — sets font, radius, base color tokens

2

Dark mode — overrides color tokens for dark palette

3

Component classes — uc-btn, uc-card use tokens

4

Utility classes — override anything inline

Surface Classes

Wrappers that provide consistent card-like appearance with borders, radius, and background.

html

Surface Card

.uc-surface-card — bordered container with surface background

Table Wrap

.uc-table-wrap — same as surface card, with overflow hidden

<!-- Surface card -->
<div class="uc-surface-card">
  <div class="uc-p-6">Content inside a surface card</div>
</div>

<!-- Table wrap -->
<div class="uc-table-wrap">
  <table class="uc-table">
    <thead>...</thead>
    <tbody>...</tbody>
  </table>
</div>

Tone Modifiers

Apply semantic coloring for info, success, warning, and danger states.

html

Informational tone .uc-tone-info

Success / positive tone .uc-tone-success

Warning / caution tone .uc-tone-warning

Error / danger tone .uc-tone-danger

<!-- Tone modifiers add bg, border, and text color -->
<div class="uc-alert uc-tone-info">Info message</div>
<div class="uc-alert uc-tone-success">Success message</div>
<div class="uc-alert uc-tone-warning">Warning message</div>
<div class="uc-alert uc-tone-danger">Error message</div>

Status Indicators

Small pills and dots for showing state in tables, lists, and cards.

html

Active

Offline

Pending

In Review

<div class="uc-status-pill uc-tone-success">
  <span class="uc-status-dot"></span>
  Active
</div>

<div class="uc-status-pill uc-tone-danger">
  <span class="uc-status-dot"></span>
  Offline
</div>

Component Class Reference

Quick reference of all pre-built component classes defined in the system.

Group	Classes
Button	`.uc-btn.uc-btn-primary.uc-btn-secondary.uc-btn-bordered.uc-btn-ghost.uc-btn-danger.uc-btn-link.uc-btn-sm.uc-btn-lg.uc-btn-icon`
Input	`.uc-input.uc-input-error.uc-textarea.uc-textarea-error.uc-label`
Card	`.uc-card.uc-card-header.uc-card-body.uc-card-footer`
Badge	`.uc-badge.uc-badge-secondary.uc-badge-danger.uc-badge-success.uc-badge-warning.uc-badge-bordered`
Alert	`.uc-alert.uc-alert-info.uc-alert-success.uc-alert-warning.uc-alert-danger`
Avatar	`.uc-avatar.uc-avatar-sm.uc-avatar-md.uc-avatar-lg.uc-avatar-xl`
Tabs	`.uc-tabs-list.uc-tabs-trigger.uc-tabs-list-underline.uc-tabs-trigger-underline`
Separator	`.uc-separator.uc-separator-h.uc-separator-v`
Progress	`.uc-progress.uc-progress-bar`
Dialog	`.uc-dialog-overlay.uc-dialog`
Toast	`.uc-toast`
Tooltip	`.uc-tooltip`
Scroll	`.uc-scroll.uc-scroll-hidden.uc-scroll-autohide.uc-scroll-indicator.uc-scroll-indicator-h`