Variants
A variant is a prefix that makes a class apply only in a certain situation, like when the pointer is over it, the field is disabled, the page is printed, or the screen is wide. You write it before the class, followed by a colon.
How to write them
bg-gray-100 always paints the background. hover:bg-gray-200 paints it
only while the pointer is over it. The variant doesn’t change the class name. It reads the same and goes next to the ts scope class like any other. Hover over the card, then reach it with the
keyboard.
Pointer and focus
A card whose background changes on hover and when focus arrives from the keyboard.
The vocabulary
The list is closed. These prefixes and no others. They work before any system utility, and also before the custom utilities you declare in your config.
| Prefix | When it applies | Example |
|---|---|---|
| hover: | The pointer is over it. Only on devices that can hover, so it doesn’t get “stuck” on a touch screen. | hover:bg-gray-200 |
| focus: | The element has focus, whether it got it from the mouse or the keyboard. | focus:bg-gray-200 |
| focus-visible: | Focus came from the keyboard (or the browser decides to show it). | focus-visible:underline |
| active: | While it’s being pressed. | active:opacity-70 |
| disabled: | The element is disabled, with the disabled attribute or with aria-disabled="true". | disabled:opacity-50 |
| checked: | A checked checkbox or radio. | checked:opacity-100 |
| invalid: | A field whose value fails its validation. | invalid:bg-danger-100 |
| aria-<state>: | The aria-<state>="true" attribute. Valid states are busy, checked, disabled, expanded, hidden, invalid, pressed, readonly, required, and selected. | aria-expanded:bg-gray-200 |
| data-<name>: | The element has the data-<name> attribute (presence only, no value). The name is lowercase and can’t start with ts-. | data-active:bg-gray-200 |
| group-<state>: | An ancestor marked with group is in that state. Any of the states above works. | group-hover:underline |
| peer-<state>: | A preceding sibling marked with peer is in that state. | peer-checked:opacity-100 |
| print: | When printing. | print:hidden |
| sm: md: lg: xl: | The screen is at least that wide. The breakpoints are your screens. | md:flex |
| max-sm: max-md: max-lg: max-xl: | The screen is narrower than that breakpoint. It’s the opposite of sm: md: lg: xl: and uses the same breakpoints, so md: applies from 48rem and max-md: below it. If they overlap, the smaller breakpoint wins (max-sm: over max-md:). | max-md:hidden |
| @sm: … @7xl: | The container marked with cq is at least that wide: @sm 24rem, @md 28, @lg 32, @xl 36, @2xl 42, @3xl 48, @4xl 56, @5xl 64, @6xl 72, and @7xl 80rem. | @2xl:flex |
Screen and container conditions are explained in Responsive. The rest are covered here.
Disabled, aria, and data
disabled: applies with either the disabled attribute or aria-disabled="true", so it also works for a link or a div that behaves
like a button. aria-expanded: and its siblings follow an attribute you already need to set
for accessibility, and data-active: follows an attribute of your own. You don’t need to
write JavaScript for the style, only change the attribute.
Disabled button
On hover the background gets darker, except on the disabled button, which keeps its own.
State attributes
The background follows aria-expanded and data-active. Change the attribute in the HTML and the style changes.
group and peer
Sometimes an element has to react to another one’s state. Mark the element in charge with group or peer, next to the ts class
(class="ts group"), and the one that reacts uses group-hover:, peer-checked:, and the like. The markers don’t style anything on their own.
groupgoes on an ancestor, and all of its descendants react.peergoes on a sibling, and it has to come before the one that reacts in the HTML. That’s what lets you, for example, show something based on a checked checkbox without writing JavaScript.
group
The link on the right gets underlined and highlighted when the pointer enters any part of the row.
peer
The checkbox comes first, and the text after it changes when it’s checked.
Named groups
When there are groups inside groups, name the one you want to follow, with group/menu on
the ancestor and group-hover/menu: on the one that reacts. The same goes for peer/field and peer-invalid/field:. The name is lowercase,
with letters, numbers, and hyphens.
<div class="ts group/proyecto p-base radius-lg bg-gray-100">
<p>Data pipeline</p>
<ul>
<li class="ts group/miembro hover:bg-gray-200">
<span>Carla Ruiz</span>
<span class="ts color-subtle group-hover/proyecto:underline">Project lead</span>
<span class="ts color-subtle group-hover/miembro:underline">Remove</span>
</li>
</ul>
</div>Variant chains
You can combine up to three, always in this order: screen or container, then print:, then group- or peer-, and
last the element’s own state. Only one of each kind. That way every rule has a single name.
Screen and state
The card only reacts to the pointer from medium screens up.
If you put them out of order (the state before the screen, for example), the class isn’t emitted and taisho generate warns you with the correct form, as in “is out of order and isn’t emitted.
Did you mean …?” The same happens if the chain has more than three, repeats a kind, or includes a prefix that doesn’t exist.
print: applies only on the printed page or in the PDF. Use it to hide what doesn’t
make sense on paper.
<button type="button" class="ts px-base py-half radius-md bg-gray-200 print:hidden">
Download report
</button>Variants inside your custom utilities
A custom utility in your config (utilities) can carry variants inside it. Each
entry is variant:class, with the same chain rules as above. That way the whole
button, with its resting, hover, focus, and disabled styles, fits in a single name.
// taisho.config.ts
utilities: {
'my-button': [
'p-base', 'radius-lg', 'bg-gray-100',
'hover:bg-gray-200',
'focus-visible:bg-gray-200',
'disabled:opacity-50',
'md:p-double',
],
},<button type="button" class="ts my-button">Save</button>
<button type="button" class="ts my-button hover:bg-gray-300">Save and close</button>- They’re validated when you generate. A prefix that doesn’t exist, an
out-of-order chain, a
data-ts-*, or a variant on a component (hover:button) stopstaisho generatewith an error that says which one it is and, if there’s a correct form, what it is. - The prefix where you use it adds to the chain inside.
md:my-buttonwith ahover:inside reacts to the pointer only frommdup. If the combination isn’t a valid chain (anlg:inside and anmd:outside, two contexts), the class isn’t emitted, andtaisho generateandtaisho checkwarn you. - A class of yours at the same level fine-tunes it. Your utility’s rules
come before the system’s at the same level, so
hover:bg-gray-300on the element wins over thehover:bg-gray-200inside. - Between two custom utilities, the one the other composes comes first, then the one you declared earlier.
- It costs nothing if you don’t use it. With
content, only the rules for the utilities your code names are emitted.
Modifiers for your custom utilities
A custom utility can have versions, like a destructive button, an outlined one, or one that’s both. You declare them as dotted keys
(component.modifier) and use them by adding the modifier to the class in the markup.
// taisho.config.ts
utilities: {
'my-button': ['p-half', 'radius-full', 'bg-brand-700', 'color-brand-100', 'hover:bg-brand-800'],
'my-button.destructive': ['bg-danger-700', 'hover:bg-danger-800'],
'my-button.outlined': ['bg-transparent', 'color-brand-700', 'hover:bg-brand-100'],
'my-button.destructive.outlined': ['bg-transparent', 'color-danger-700', 'hover:bg-danger-100'],
},<button class="ts my-button">Save</button>
<button class="ts my-button destructive">Delete</button>
<button class="ts my-button outlined">Cancel</button>
<button class="ts my-button destructive outlined">Delete</button>
<button class="ts md:my-button destructive">Delete from md</button>How to read them
- The key is the selector.
'my-button.destructive.outlined'is emitted as.my-button:where(.destructive.outlined), which applies when the element has all three classes. The order you write them in the markup doesn’t matter. - Declare the utility first.
my-buttonhas to exist without a dot; the modifiers hang off it. - The entries are the same as a utility’s. Short class
names, variants (
hover:,md:…), and other plain custom utilities. What you can’t compose is another modifier ('x': ['my-button.destructive']is an error). Composemy-buttonand putdestructivein the markup. - It costs nothing if you don’t use it. A modifier’s rule is only emitted if your code uses both the utility and the modifier.
Combinations and the cascade
Declare only the combinations that look different. The ones you don’t declare aren’t made up. The element gets
the base and whichever simple modifiers it has. If you declare destructive.outlined, you don’t need to declare destructive or outlined separately.
- The order is base, simple, compound. All three weigh the same
(
:where()adds no specificity), so the later one wins. Inmy-button destructive outlined, the background and color ofdestructive.outlinedoverride those ofdestructiveandoutlined, and those overridemy-button’s. - An atomic class in the markup fine-tunes it.
class="ts my-button destructive bg-danger-900"paints the background withbg-danger-900and leaves the rest of the button as is. - States follow the same rule. The
hover:ofdestructive.outlinedoverrides the one ondestructive.
With a screen variant
The prefix goes on the utility, not on the modifier, as in md:my-button destructive. An md:destructive doesn’t exist, because every modifier would have to be multiplied by every
context. taisho generate and taisho check warn you:
"md:destructive" isn't emitted. "destructive" is a modifier of "my-button", and a modifier can't take a variant. Put the variant on the utility itself (e.g., "md:my-button").How to choose the name
A modifier is a standalone class on an element that already has ts. That’s why it can’t
share a name with something the system applies on its own.
- It can’t be a system name, whether a component
(
link,card), a utility (flex,color-danger), orcompact. It also can’t bets, start withts-, or be the name of another utility of yours. - It can be a component modifier. If
linkconflicts, usevariant-link. Outside a system component it does nothing, and it reads like the rest of the system’s classes. destructive,outlined,primary,ghost,soft… all work, because they don’t exist as standalone system classes.
Common errors
They’re validated together when you generate, and they stop taisho generate.
- “uses the component "my-button", which isn’t in utilities.” You declared
'my-button.destructive'without'my-button'. Declare the base first, without a dot. - “has a modifier ("link") that conflicts with a short DS name.” Change the name.
'my-button.variant-link'is enough. - “that’s the name of another of your utilities.”
'my-button.card-hero'would triggercard-hero. Pick another name. - “has an invalid modifier.” Use lowercase letters and digits separated by
hyphens, starting with a letter.
Destructiveis writtendestructive. - “repeats the combination” / “repeats a modifier.”
a.bandb.aare the same, anda.asays nothing. Keep just one. - “a modifier isn’t a utility.” You composed it inside another utility. Compose the base and put the modifier in the markup.
- “does nothing without that utility on the same element.” It’s a warning, not an
error. You used
destructiveon an element that doesn’t havemy-button.taisho checkflags it too.
What doesn’t exist
The vocabulary is closed on purpose, so every class has a single, predictable meaning.
| Doesn’t exist | What to do |
|---|---|
| dark: | The theme handles dark mode. The tokens switch on their own, without a variant on every class. See Theming. |
| Arbitrary values, like hover:p-[13px], data-[open=true]:, or aria-[sort=up]: | The vocabulary is closed. For a value that isn’t there, add a token to your config; for an attribute with a value, use a presence-only data-<name>. |
| data-ts-<something>: | data-ts-* is the components’ hook, not a variant. Your own attributes (data-active:) do work. |
| Other states and conditions: first:, last:, odd:, even:, focus-within:, ranges that combine two breakpoints in one class (md:max-xl:), and anything starting with has-, not-, motion-, or supports- | Your own class in your CSS, or the attribute that already changes in your HTML, with aria-<state>: or data-<name>:. |
| A variant on a component | A component owns its states: its modifiers (is-*), its aria attributes, and its inner parts. Variants only apply to utilities, the system’s and yours. |
What the static CSS includes and what you generate
The CSS you load from the CDN (or from taisho.full.css) has no build step, so
the variants it includes are a short list, the ones used most in handwritten HTML:
- hover: on the scale colors (bg-, color-, border-, and ring-, in every family and shade).
- hover: on the semantic colors (color-heading, color-copy, color-subtle, color-label, color-success, color-warning, color-info, and color-danger).
- hover: on underline, no-underline, and opacity-*.
- print:hidden and print:block.
- Screen variants (sm: … xl:; max-* only if your code uses it) for a curated set, and container variants (@sm: … @xl:) for grids and spacing, as Responsive explains.
Everything else (focus:, active:, disabled:, aria-…:, data-…:, group-…:, peer-…:, chains, and containers from @2xl: up) is written by taisho generate when you use it. You declare in content where to look, and any utility with any variant that appears written out in
full in your code ends up in the CSS; what you don’t use weighs nothing. A variant built at runtime
can’t be read from the code. Request it in the safelist, with the full name or as a family
ending in an asterisk.
// taisho.config.ts (excerpt)
content: ['**/*.{html,svelte,vue,astro,jsx,tsx,js,ts,css}'],
safelist: ['md:hover:bg-gray-200', 'hover:bg-gray-*'],How to install and run taisho generate is in the Installation guide.
Specificity, in plain words
The system’s CSS is ordered in six layers, from lowest to highest priority: base, components, utilities, states, utility-states, and print. Between layers specificity doesn’t
count, the layer does; within a layer, the one written later wins. That gives an order that’s easy to remember:
- A utility beats a component’s resting value.
ts button radius-fullrounds andts button bg-danger-700paints red, even though the button brings its own radius and its own background. - A utility doesn’t override the component’s states. That red button still
changes under the pointer (it moves to the next shade of its color), keeps its focus ring, and stays gray when
disabled. To change a state, use its variant:
hover:bg-success-500. - The text follows the background, unless a color is asked for.
hover:bg-success-500also sets that background’s contrast color, and so dofocus-visible:,group-hover:, and the other state variants ofbg-*. Acolor-*written on the element wins, in hover and active too, and ahover:color-*wins over the contrast ofhover:bg-*. Indisabled,checked,selected,invalidandopen, the component’s state rules. - A state beats the plain class. If an element has
bg-gray-100andhover:bg-gray-200, the second one wins on hover, no matter the order you wrote the classes in. - A state beats a screen. If
md:p-doubleandhover:p-baseboth apply, the hover one wins. - Screen plus state beats the state alone.
md:hover:bg-gray-300overrideshover:bg-gray-200frommdup. - Among states without a screen,
disabled:wins. A disabled button under the pointer keeps whatdisabled:says. group-…:andpeer-…:weigh the same as the element’s own states, and if they both apply, its own state wins.print:goes last of all, so on paper it wins over the plain class, over screens, and over states. A button withhover:bg-gray-200andprint:hiddenis hidden when printing even with the pointer over it.
Your CSS
utilities layer, doesn’t beat a state. If you
write your CSS unlayered, it always wins.Tips
- Don’t hide information behind a hover. A touch screen has
no pointer, and keyboard users don’t use one either. Keep what matters visible and use the variant to
reinforce it, as in the
groupexample. - For keyboard focus, use
focus-visible:.focus:also triggers when you click with the mouse. - If the state already exists as an attribute, follow it.
aria-expanded:keeps style and accessibility in sync from a single source.