CSS architecture and ownership

The ideal target of a UI architecture is simple: feature development should be pure composition, and writing CSS in a feature should be the exception rather than the rule.

In practice, large applications rarely eliminate local styling entirely. But treating feature CSS as an occasional exception rather than standard practice keeps stylesheets from sprawling across product boundaries.

An engineer building a view reaches first for shared components and spatial primitives—Stack, Grid, Card, and Button. The visual decisions and layout rules are already solved, tokenized, and tested by the system.

When feature code stays focused on composition, the application remains resilient. Themes swap cleanly, typography updates uniformly, and shared components can be upgraded without breaking mysterious local overrides.

Where styling decisions live

CSS stays maintainable when ownership follows the level of decision being made:

• The design system owns tokens: Canonical values for color roles (--color-text-secondary), spacing scales, and typography. It defines the visual vocabulary without knowing which features use it.
• The UI kit owns primitives and layout: Encapsulated components (buttons, dialogs, tables) and spatial primitives (stacks, clusters, grids). It consumes tokens and exposes layout props, keeping styling details internal.

When both layers do their job, feature code is pure composition. If an engineer feels forced to write CSS just to space cards or align elements, that is not a feature problem—it is a signal the kit is missing a layout primitive.

Local CSS is an exception boundary

Rare exceptions still happen. A feature may encounter a requirement that existing primitives and variants cannot yet satisfy.

When that happens, custom CSS is acceptable, but it should be treated as an exception boundary: keep the rule co-located beside the view, anchor every value to semantic tokens, and never override kit internals.

If that exception repeats across features and represents a durable pattern, we promote it into the shared kit. Until then, keeping it local avoids polluting shared infrastructure with one-off product styles.