UI Components

PyColors UI components are primitives, not finished widgets. They are designed to be composed, extended, and owned by your project.

This section is the entry point to the UI library: buttons, surfaces, inputs, and feedback components — all aligned with the PyColors design system.

How to think about components

PyColors UI follows a simple model:

• Tokens define the language (colors, typography, radius, shadows).
• Components consume tokens via semantic Tailwind utilities.
• Patterns compose components into real features and flows.

If you feel a component needs “too many props” to cover a real product need, it likely belongs in Patterns, not in UI primitives.

Component categories

Surfaces

Surfaces group content and establish hierarchy.

• Card — foundational surface for panels, tiles, and list items
• Alert — feedback surface for system notices and validation results

Actions

Actions trigger user intent.

• Button — primary action primitive, with variants and sizes

Inputs

Inputs collect user data and support validation patterns.

• Input — label, helper text, error state, icons, and sizing

Status & metadata

Compact components for categorization and state.

• Badge — status, labels, counts, and metadata

Composition rules

A few rules keep the system consistent:

• Prefer composition over configuration.
• Use semantic tokens (bg-card, text-muted-foreground, border-border) instead of raw colors.
• Avoid one-off variants; if something repeats, extract a primitive or a pattern.
• If a component is interactive, ensure it remains semantic (render as button / a via asChild when needed).
• Don’t nest interactive targets (link-in-link). Keep one primary clickable element per component boundary.

What belongs in Patterns instead

Use Patterns when you need:

• multiple components + layout rules
• async states and loading skeletons
• validation flows (RHF + Zod)
• reusable “feature blocks” (Settings panel, Pricing card, Auth form)

Patterns document how primitives are used in real products.

Start here