Utility Class Conventions
Agree how utility classes are written so the markup stays readable as the app grows.
What it adds
A written convention for the order, grouping, merging, and extraction of utility classes across the app.
What your agent is told to do
5
What your agent is told to do
5-
1
Fix a canonical order for utility classes — layout, then box model, then typography, then colour, then state and responsive variants — and apply it mechanically so that reviewers never argue about it.
-
2
Write down the extraction threshold in plain terms: how many repetitions, in how many places, before a run of utilities becomes a named component. State the number rather than leaving it to taste.
-
3
Define which variants and states are permitted inline and which must be expressed as a component variant, so a screen does not accumulate a dozen conditional branches in its markup.
-
4
Record where handwritten CSS is the correct answer — complex selectors, keyframes, print rules, anything that reads worse as a chain of utilities — so people do not contort the utility vocabulary to avoid a stylesheet.
-
5
Leave the mechanics of combining conditional classes to Class Merge Helper and the mapping of component variants to classes to Variant Class Generator. This feature sets the rules; those two implement them.
Edge cases it handles
6
Edge cases it handles
6- Extracting a component the first time a pattern repeats is premature and produces a primitive with one caller and five props. Hold the repetition threshold, and prefer a second literal copy over an abstraction invented too early.
- Two utilities setting the same property in one class list produce a result decided by stylesheet order rather than by the order they were written, which is why contradictory pairs must be prevented at authoring time rather than reasoned about later.
- Conditional classes must be combined through one agreed mechanism everywhere. Hand-rolled string concatenation in some components and a helper in others guarantees that caller overrides work in one place and not the next.
- The convention needs to say when custom CSS is clearer than utilities, or every rule ends up expressed as utilities regardless of whether that reads well.
- Long utility chains on a single element are a signal, not a style crime. Say what length triggers a look at extraction, and what to do when the element is genuinely one of a kind.
- Arbitrary one-off values written inline defeat the token system entirely. Require a token, or a deliberate documented exception, rather than a raw measurement in the markup.
Definition of done
9
Definition of done
9- The convention is written down in the repository, not held as folklore.
- Utility class order is canonical and applied consistently across the app.
- The extraction threshold is stated as a number and observed in the codebase.
- Contradictory utilities on the same element are prevented rather than tolerated.
- All conditional class composition goes through a single agreed mechanism.
- Cases where handwritten CSS is preferred are documented with examples.
- Arbitrary inline values are absent, or carry a documented exception.
- The feature matches the existing design system.
- No existing functionality is broken.
Related features
CSS Module Boundaries
CSS Module Boundaries
Keep each component's styles its own, and make the shared parts deliberate.
What it does
A boundary around each component's styles, exposing only a named set of hooks that callers are permitted to style through.
How it works
- 1 Identify the primitives the rest of the app builds on — button, field, card, menu, table — and treat everything inside them as private unless it is deliberately published.
- 2 For each primitive, publish an explicit surface: the variants it accepts, the slots a caller may target, and the custom properties it reads. Anything not on that list is internal and may change without notice.
- 3 Find the places where product screens currently reach into a primitive's internals and rewrite them to use the published surface, adding a variant or a slot where the need is legitimate.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/css-module-boundaries
Class Merge Helper
Class Merge Helper
Combine conditional classes in one place so the last one written actually wins.
What it does
A single helper every component uses to resolve base, conditional, and caller-supplied classes into one final list.
How it works
- 1 Find every component that currently builds a class string by hand and route all of them through one helper, so the resolution rules are identical everywhere.
- 2 Define the precedence plainly: the component's own base classes lose to its variant classes, and both lose to whatever the caller passed in. A caller that supplies a class expects it to take effect.
- 3 Accept the shapes calling code actually produces rather than forcing every call site to normalise first, and make the behaviour for absent and empty values explicit rather than incidental.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/class-merge-helper
CSS Layer Strategy
CSS Layer Strategy
Give the stylesheet an explicit order of precedence instead of one decided by accident.
What it does
An ordered set of cascade layers — reset, tokens, base, components, utilities, overrides — that every stylesheet is assigned to.
How it works
- 1 Define the layer order once, in one file, and have every other stylesheet declare which layer it belongs to rather than relying on the order the bundler happens to emit.
- 2 Assign the existing stylesheets to layers before changing any of them. The map from current file to intended layer is the whole design decision, and it should be reviewable on its own.
- 3 Migrate in stages: place everything currently unlayered into a defined position relative to the new layers, then move files into their proper layer one at a time, checking the rendered result after each move.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/css-layer-strategy
How it works
-
1
Copy the link
Grab the Markdown instruction URL for this feature.
-
2
Give it to your AI
Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
-
3
It inspects, then implements
Your agent reads your existing app first, then adds the feature to fit it.
Works with your stack
These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.
Need it tighter than that? Customize the feature and tell it exactly what you're running.