The systemLumos 0.0.1
Utility or prop?
When to reach for a class, when to use a prop, and when the answer is a new component.
Lumos gives you two ways to change how something looks: a prop on the component, or a utility class on it. They are not interchangeable, and picking the right one is most of what keeps a project tidy over time.
The rule
- A prop, if one exists. Props are the decisions the component has already thought about: variants, spacing steps, alignment. They are named for intent, they are checked as you type, and they keep every instance consistent.
- A utility, for a one-off. When this particular instance needs something the component has no opinion about (no top margin here, full width there), a utility says exactly that and nothing more.
- A component of your own, when it repeats. The third time you write the same four utilities together, that combination has become a thing. Give it a name.
Worked examples
| You want | Do this | Not this |
|---|---|---|
| A dark section | <Section theme="dark"> | class="theme-dark": the prop is the documented way in |
| Less space above a section | <Section paddingTop="small"> | class="padding-top-4": breaks the section rhythm |
| No margin on one heading | class="margin-top-0" | A new variant nobody else will use |
| A card that stretches to fill its row | class="flex-grow" | A wrapper div |
| The same three-card panel on six pages | Your own <FeaturePanel> component | Copying the markup six times |
Why not just use utilities for everything
Because utilities describe appearance and props describe intent. paddingTop="large" still means the right thing after the spacing scale is redesigned; padding-top-8 means whatever 8 happens to be. Utilities have no memory of why they were added, which is fine for one instance and expensive across a site.
Why not put everything in props
Because a component with forty props is a stylesheet with extra steps. If a prop would only ever be used once, it should not exist: a utility on that one instance is cheaper for everyone reading the code later.