Overview
The foundations of PyColors UI. Tokens, colors, typography, and the rules that keep the system consistent as products grow.
Design consistent products with PyColorsLink to section
PyColors UI is not a collection of isolated components. It is a system of visual decisions designed to keep product interfaces consistent as they grow.
The design system defines the rules behind:
- reusable components
- product dashboards
- documentation pages
- settings and billing surfaces
- marketing sections
- future SaaS templates and starters
The goal is simple: components should stay small because the foundation carries the complexity.
Why this matters
Most product inconsistency does not come from one bad component. It comes from many small local decisions that slowly drift away from each other. PyColors prevents that by moving visual decisions into shared roles, tokens, and rules.
What you’ll understandLink to section
System layers
Understand how tokens, colors, typography, and components work together instead of competing locally.
Semantic roles
Use meaning-driven utilities such as bg-card, text-muted-foreground, and border-border.
Product consistency
Keep PyColors readable, premium, and trustworthy across docs, dashboards, and commercial pages.
StepsLink to section
Start with roles, not raw valuesLink to section
Components should consume semantic roles instead of hardcoded visual values.
export function ProductCard() {
return (
<article className="rounded-2xl border border-border bg-card p-6 text-card-foreground">
<p className="text-sm text-muted-foreground">
Production-shaped SaaS foundation
</p>
<h2 className="mt-2 text-xl font-semibold tracking-tight">
Starter Pro
</h2>
</article>
);
}This keeps the component stable when the theme evolves. The component does not need to know the exact color, radius, or contrast value. It only needs to know the role it should express.
| Use | Avoid |
|---|---|
bg-card | hardcoded hex values |
text-muted-foreground | one-off opacity values |
border-border | local border colors |
| shared radius tokens | arbitrary corner values |
Keep one source of truthLink to section
Global visual decisions should be made once, then reused everywhere.
That includes:
- radius
- shadows
- color roles
- typography hierarchy
- focus states
- product surface density
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-card: var(--card);
--color-card-foreground: var(--card-foreground);
--color-primary: var(--primary);
--color-border: var(--border);
}Implementation note
A design system becomes valuable when changing one token updates many surfaces coherently. That is the difference between a theme and a collection of local styles.
Build small primitives on strong foundationsLink to section
PyColors primitives stay intentionally small because the system underneath already defines the visual behavior.
Define geometry, elevation, spacing direction, and future visual scales.
Define meaning for surfaces, text, borders, states, and actions.
Compose roles into reusable UI primitives and product patterns.
export function SettingsPanel() {
return (
<section className="rounded-2xl border border-border bg-card p-6">
<h2 className="text-lg font-semibold tracking-tight">
Workspace settings
</h2>
<p className="mt-2 text-sm leading-6 text-muted-foreground">
Manage product configuration from a consistent surface.
</p>
</section>
);
}System layersLink to section
PyColors is organized as a layered system. Each layer has a clear responsibility and should not replace the layer below it.
| Layer | Responsibility | Example |
|---|---|---|
| Tokens | Atomic visual decisions | radius, shadows, future scales |
| Colors | Semantic color roles | background, card, primary, muted |
| Typography | Readable hierarchy | headings, body text, labels, metadata |
| UI components | Reusable primitives | buttons, cards, inputs, dialogs |
| Product patterns | Composed flows | dashboards, settings, billing, onboarding |
Why this matters
When every layer has a clear responsibility, components become easier to reason about. You know where to change the system instead of patching the symptom locally.
Decision guideLink to section
Use the design system when:
- a visual decision appears in more than one place
- a component needs to support light and dark mode
- a page must feel coherent with the rest of the product
- a pattern will be reused in docs, starters, or commercial pages
- the decision affects trust, readability, or product polish
Avoid local overrides when:
- the value is purely decorative
- the same exception already exists elsewhere
- the change weakens semantic meaning
- the override makes theming harder
- the code becomes harder to maintain than the system rule
Prefer
- semantic roles over raw values
- tokens for repeated visual decisions
- small primitives with predictable behavior
- centralized color and typography rules
- documentation that explains system intent
Avoid
- hardcoded colors inside reusable components
- one-off radius and shadow values
- local typography scales per page
- using chart colors as interface states
- duplicating visual decisions in product areas
Reading pathLink to section
Follow this order to understand the system from the foundation to implementation.
Start with the atomic decisions that power the visual system.
Learn how corner geometry keeps surfaces and controls consistent.
Understand elevation rules for calm, predictable depth.
Use semantic roles for surfaces, text, states, and theming.
Define hierarchy, rhythm, labels, and readable product structure.
Where this fitsLink to section
PyColors is structured in product layers:
| Product layer | Purpose |
|---|---|
| Design System | Rules, tokens, roles, and visual foundations |
| UI Components | Reusable primitives built on top of the system |
| Patterns | Composition guidance for real product surfaces |
| Starter Free | Product-shaped UX for validation |
| Starter Pro | Production-shaped SaaS foundation with auth, billing, backend, and delivery |
The design system is the deepest layer in that stack. It protects consistency before product complexity increases.
Ready to turn the system into a launch foundation?
Continue from visual foundations to product implementation with Starter Pro. → /docs/starter-pro