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
Variant Class Generator
Variant Class Generator
Declare a component's variants once instead of scattering conditionals through its markup.
What it does
A declarative variant definition per component mapping size, tone, and state to the classes each combination produces.
How it works
- 1 Find the components whose markup is threaded with conditional class logic and replace that logic with a single declaration listing each variant, its options, and its default.
- 2 Support combinations that are more than the sum of their parts, so a specific pairing of size and tone can produce classes that neither produces alone, without reintroducing a conditional in the markup.
- 3 Make invalid combinations impossible to express rather than merely undesirable, and give the component a defined appearance when it receives a combination it does not recognise.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/variant-class-generator
Tokenized Inline Styles
Tokenized Inline Styles
Allow styles computed at runtime without letting arbitrary values escape the design system.
What it does
A constrained path for dynamically computed styles, where every value is either a design token or a number clamped to an approved range.
How it works
- 1 Find every place the app already sets a style value at runtime — progress widths, chart bar heights, avatar colours, drag positions, user-chosen accent colours — and sort them into two groups: values that must come from the token set, and values that are genuinely continuous numbers.
- 2 For the first group, accept only token names and resolve them to values at the boundary. A caller passing a raw colour or a raw pixel value should be rejected loudly in development rather than quietly rendered.
- 3 For the second group, clamp to a documented minimum and maximum and round to a sensible precision, so a percentage of 4000 or a width of 0.3847291 pixels never reaches the DOM.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/tokenized-inline-styles
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
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.