Overview · Docs · PyColors

UIComposable primitives

Build interfaces that scale with your productLink to section

PyColors UI components are small, composable primitives built for real SaaS interfaces.

They are designed to help you build:

dashboards
forms
settings pages
billing surfaces
admin tools
auth flows
data-heavy product views

This is not a UI kit for isolated demos.

It is a component foundation for products that need to evolve without becoming inconsistent.

Core idea

UI components are the lowest product layer. They should stay small, token-driven, and predictable.

Where UI fitsLink to section

PyColors is organized as a product system, not only a component library.

Design System

Tokens, colors, typography, radius, and shadows define the visual foundation.

Mental modelLink to section

Tokens define the system. Components stay small. Guides explain usage. Patterns handle complexity. Starters connect everything into a product.

This keeps the UI layer focused.

If a primitive starts carrying too much product logic, the abstraction is probably in the wrong place.

Interactive component examplesLink to section

Storybook is the canonical interactive component example system for @pycolors/ui. Use it to inspect isolated component states, exercise keyboard and pointer behavior, and compare the PyColors light and dark themes. These Fumadocs pages remain the public usage documentation and product-context examples; Storybook does not replace them.

Run Storybook from the repository root:

pnpm --filter @pycolors/ui storybook

Maintaining examplesLink to section

The maintained public-surface stories live in packages/ui/stories/public-surface.stories.tsx. When a public component or a meaningful documented state changes:

Add or update its representative story and import it through the package's public src/index.ts barrel, not a component's internal file.
Keep the story token-driven, accessible, and usable in both Storybook themes.
Update the matching Fumadocs page when public usage or behavior changes.
Run pnpm --filter @pycolors/ui verify; this includes a production Storybook build. For documentation changes, also run pnpm --filter pycolors-marketing types:check.

This one-to-one maintenance path keeps isolated examples aligned with the public exports while the documentation continues to explain product usage and composition.

Start with the essentialsLink to section

ButtonThe action primitive used for intent, hierarchy, submission, and navigation.CardThe primary surface primitive for grouping content, metrics, sections, and product panels.InputThe form primitive for labels, values, helper text, and validation states.BadgeCompact metadata and status labels used to clarify information without becoming actions.

Component categoriesLink to section

SurfacesUse surfaces to group content, create hierarchy, and communicate structure.CardAlertEmptyStateSkeleton ActionsUse action primitives to represent user intent and interaction hierarchy.ButtonDropdownMenuDialogSheet InputsUse inputs to collect values, communicate validation, and support form workflows.InputPasswordInput Data and navigationUse data primitives for tables, paging, tabs, and product navigation states.TablePaginationTabsToast

Composition rulesLink to section

Start with semantic tokensLink to section

Use token-driven utilities such as bg-card, text-muted-foreground, border-border, and shadow-sm.

Components should consume meaning, not raw visual values.

Compose before configuringLink to section

Prefer composition over large prop APIs.

If a component needs too many product-specific props, extract the product behavior into a pattern.

Keep interaction ownership clearLink to section

A primitive should usually own one interaction responsibility.

Complex flows like forms, tables, overlays, and async actions belong in Guides or Patterns.

Use UI for structure, not business logicLink to section

Components should render state clearly.

Product rules, billing checks, auth ownership, and backend decisions should stay outside the primitive layer.

When to use PatternsLink to section

Use a UI component when you need a primitive.

Use a Pattern when you need a product behavior.

Need	Use
Button action	UI component
Form input	UI component
Form validation flow	Guide
Data table with loading, empty, error, filters	Pattern
Dropdown vs Dialog vs Sheet decision	Pattern
Mutation feedback with toast, retry, undo	Pattern

Rule of thumb

Components render building blocks. Patterns explain how those blocks behave in a real product.

What to avoidLink to section

Prefer

small primitives
semantic tokens
composition-first APIs
clear accessibility defaults
patterns for complex flows

Avoid

hardcoded one-off styles
giant components with too many variants
business logic inside primitives
using badges as buttons
duplicating the same product flow repeatedly

Explore core componentsLink to section

ButtonAction hierarchy, intent, loading states, and interaction patterns.InputAccessible form primitives with validation and consistent UX behavior.CardSurface primitives used to structure dashboards and product interfaces.DialogFocused modal flows for confirmations, forms, and product actions.

Next stepsLink to section

Why PyColors UIUnderstand the product philosophy behind the component system.PatternsMove from primitives to reusable feature-level product blocks.

Build the primitive once. Compose the product many times.

PyColors UI is designed to keep your components simple while your SaaS grows in complexity.