Overview · Docs · PyColors

Design SystemTokens

The foundation of every interfaceLink to section

Design tokens are the single source of truth for the visual language of PyColors UI.

They encode small decisions that every component can consume:

radius
elevation
color roles
typography roles
future motion, spacing, and layering rules

Tokens are not components. They are not random CSS values. They are design decisions expressed as reusable variables.

Why this matters

Without tokens, every component slowly starts making its own visual decisions. That creates drift, makes refactors risky, and weakens the premium feeling of the product over time.

What tokens controlLink to section

Geometry

Radius tokens keep buttons, cards, inputs, and overlays visually related.

Elevation

Shadow tokens define calm, predictable depth across cards, menus, and modals.

System intent

Tokens make design intent explicit so the product can scale without visual drift.

StepsLink to section

Start from design decisionsLink to section

A token exists when a visual decision should be shared by the system.

Instead of asking every component to decide its own radius, shadow, or surface treatment, PyColors defines those decisions once.

system-flow.txt

Design decisions
  ↓
Tokens
  ↓
Tailwind utilities
  ↓
UI components
  ↓
Product surfaces

This flow keeps components small while the system stays expressive.

Define tokens centrallyLink to section

Tokens are defined as CSS variables and mapped into utilities.

tokens.css

:root {
  --radius: 0.625rem;
}

@theme inline {
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
}

The raw value stays in the token layer. Components consume the utility.

components/product-card.tsx

export function ProductCard() {
  return (
    <article className="rounded-lg border bg-card p-6 shadow-sm">
      <h2 className="text-lg font-semibold tracking-tight">
        Product surface
      </h2>
      <p className="mt-2 text-sm leading-6 text-muted-foreground">
        This surface consumes tokens indirectly through utilities.
      </p>
    </article>
  );
}

Extend only when the system needs itLink to section

Not every visual value needs to become a token on day one.

A new token should exist when it:

appears in multiple places
expresses a reusable product decision
improves theming or consistency
reduces duplicated local styling
makes future changes safer

System rule

Tokenize repeated design decisions, not one-off visual preferences.

Token categoriesLink to section

PyColors intentionally starts with a small token surface. That keeps the system understandable and avoids token sprawl too early.

Category	Purpose	Current status
Radius	Corner geometry for controls, cards, and overlays	Active
Shadows	Elevation for surfaces and floating layers	Active
Colors	Semantic surface, text, state, and chart roles	Active
Typography	Font roles, hierarchy, labels, and density	Active
Spacing	Product layout rhythm and density	Future
Motion	Transitions, easing, and interaction feel	Future
Z-index	Layering rules for overlays and navigation	Future

Why the surface is intentionally small

A smaller token system is easier to understand, document, and maintain. PyColors adds tokens when they clarify the system, not when they create extra vocabulary.

Decision guideLink to section

Use a token when:

the value appears across multiple components
changing it globally would be useful
the value carries product meaning
it improves consistency across light and dark mode
it prevents teams from inventing local alternatives

Avoid creating a token when:

the value is purely decorative
it only appears once
the name would be vague
the token duplicates an existing role
it makes the system harder to understand

Prefer

tokens for repeated visual decisions
semantic names that describe intent
centralized values exposed through utilities
small scales that are easy to remember
documentation that explains when to use each token

Avoid

tokenizing every one-off value
names that describe appearance only
duplicating existing semantic roles
hardcoding token values inside components
adding scales before the product needs them

Token flowLink to section

Decision

The system needs a consistent corner feel.

Token

--radius-lg defines the shared geometry.

Utility

rounded-lg exposes the token to components.

Surface

Cards, dialogs, and panels feel related.

components/settings-card.tsx

export function SettingsCard() {
  return (
    <section className="rounded-lg border border-border bg-card p-6 shadow-sm">
      <div className="flex items-center gap-2">
        <CircleDot className="h-4 w-4 text-primary" />
        <h2 className="text-sm font-medium text-foreground">
          Workspace settings
        </h2>
      </div>
      <p className="mt-2 text-sm leading-6 text-muted-foreground">
        The component consumes tokens through semantic utilities.
      </p>
    </section>
  );
}