05-styling/04-component-styling.md

Component styling

Components should follow the Vroq visual system instead of inventing a new style per component.

A component's styling should support reuse, clarity, and consistency.

Preferred styling order

When styling a component, prefer this order:

1. built-in component defaults 2. theme tokens 3. small local inline style adjustments 4. component CSS via ensureCSS(...) when the styling is structural or reused

When component-specific CSS is appropriate

Use component-specific CSS when:

the component has a repeated structural style
hover/focus/variant styles are part of the component contract
the style would be noisy if repeated inline

In these cases, co-located component CSS is usually better than large inline style objects.

When to avoid component-specific CSS

Avoid adding component CSS when:

the styling is only a tiny one-off layout tweak
the effect can be expressed clearly with existing props or tokens
the component would become harder to understand because of unnecessary styling layers

Rules

keep component styling aligned with Vroq theme variables
avoid hard-coded visual values unless justified
avoid one-off visual experiments that do not match the app
keep the component visually boring unless the UI clearly needs something stronger

Final rule

Component styling should make the component easier to reuse and easier to keep visually consistent across the app.