Design System

PyColors UI is not a collection of random components — it’s a system.

The design system defines the rules and foundations that make every component feel consistent: colors, typography, radius, shadows, and the token architecture that ties everything together.

If you want PyColors UI to remain clean as your product grows, start here.

What the design system solves

Most UI inconsistency comes from the same root causes:

styles are decided at the component level
raw values (hex, px, arbitrary radii) creep into the codebase
small “exceptions” accumulate until nothing matches
design decisions live in people’s heads, not in the system

PyColors UI prevents that by encoding design decisions into tokens and exposing them through semantic utilities.

Core principles

1) Roles over raw values

Components should use roles (meaning) instead of raw values (appearance).

✅ bg-card, text-muted-foreground, border-border
❌ #0f172a, rgba(...), rounded-[11px]

Roles keep components stable across themes and brands.

2) One source of truth

Global decisions (radius, elevation, colors) are defined once and consumed everywhere. Change the system — the UI updates coherently.

3) Predictable composition

Tokens define the language
Components consume tokens
Patterns document real flows

This separation keeps primitives small and reusable, while patterns stay realistic.

System layers

Tokens (atomic decisions)

Tokens encode the base decisions of the system:

radius scale
shadow scale (elevation)
(future) spacing, motion, z-index

Tokens live in global.css and are mapped to Tailwind utilities.

Tokens

Atomic decisions powering the system (radius, shadows, and more).

Radius

Corner geometry tokens (rounded-*).

Shadows

Elevation scale for surfaces and floating layers.

Colors (semantic theming)

Colors are role-based and themeable:

OKLCH-based values for predictable contrast
light mode on :root, dark mode on .dark
semantic roles mapped to Tailwind tokens

Colors

Semantic color roles, OKLCH architecture, and theming.

Typography (hierarchy and rhythm)

Typography defines readability, hierarchy, and content rhythm:

headings and type scale
text roles (foreground vs muted)
consistent metadata styles

Typography

Text scale, roles, and hierarchy for UI and content.

How it all connects

A component like Card is simple because the design system does the heavy lifting:

colors define surface roles (bg-card, text-card-foreground)
tokens define geometry (rounded-lg) and elevation (shadow-sm)
typography defines hierarchy (title vs description vs content)

This is why PyColors UI scales: components remain small while the system stays expressive.