Utilities

Small utility classes for typography, spacing, color, alignment, positioning, overflow, and simple decoration.

Utilities are available when you load app.css, and they can also be loaded explicitly from src/utilities in Sass-based setups.

src/utilities/_index.scss currently assembles the following files:

• align-content
• align-items
• align-self
• background-color
• color
• display
• flex-direction
• flex-wrap
• font-size
• font-weight
• gap
• global
• justify-content
• justify-items
• justify-self
• mix-blend-mode
• overflow
• padding
• position
• text-align
• typography

When to use

Use utilities only after checking whether a requirement can be solved more clearly by primitive props or primitive composition.

Recommended priority:

1. Primitive props
2. Primitive composition
3. Utilities on non-primitive elements
4. Custom CSS
5. Primitive overrides only when unavoidable

Utilities are especially useful for:

• Small typographic adjustments on plain text elements
• Minor spacing on non-primitive wrappers
• Alignment and positioning on simple wrappers
• Overflow and blend-mode control for decorative elements
• Color and background-color assignment
• Simple presentational helpers such as border radius or box shadow

How to apply utilities

In plain HTML, utilities in this page are utility classes. Apply them with class, not data-unitone-layout. The leading . shown in CSS selector notation is not part of the class attribute value.

<p class="-font-size:xl -color:dark-teal -fluid-typography">
	...
</p>

Use data-unitone-layout for layout primitives and their documented attribute-based modifiers.

<div data-unitone-layout="stack -gap:1">
	<p class="-font-size:xl -color:dark-teal">...</p>
</div>

If a helper is documented on a primitive page as part of that primitive API, follow that primitive page. Otherwise, if it appears in utilities.mdx, treat it as a utility class.

Available utilities

global

• .-box-shadow
• .-border-radius
• .-gutters
• .-max-width:content-size
• .-max-width:wide-size

These are simple presentation and wrapper helpers.

align-content

• .-align-content:start
• .-align-content:center
• .-align-content:end
• .-align-content:space-between
• .-align-content:space-around
• .-align-content:space-evenly
• .-align-content:stretch

Use these mainly on multi-row flex or grid wrappers when a full primitive is unnecessary.

align-items

• .-align-items:start
• .-align-items:center
• .-align-items:end
• .-align-items:baseline
• .-align-items:stretch

align-self

• .-align-self:start
• .-align-self:center
• .-align-self:end
• .-align-self:stretch
• .-align-self:auto

typography

• .-fluid-typography

This applies the shared fluid typography mixin. In plain HTML, write it in class. Example: class="-fluid-typography"

font-size

• .-font-size:2xs
• .-font-size:xs
• .-font-size:s
• .-font-size:m
• .-font-size:l
• .-font-size:xl
• .-font-size:2xl
• .-font-size:3xl
• .-font-size:4xl
• .-font-size:5xl
• .-font-size:6xl

These utilities set --unitone--font-size, so they work with the typography system already provided by app.css. In plain HTML, write them in class. Example: class="-font-size:xl"

Named font-size utilities map to the internal numeric scale like this:

• 2xs -> -3
• xs -> -2
• s -> -1
• m -> 0
• l -> 1
• xl -> 2
• 2xl -> 3
• 3xl -> 4
• 4xl -> 5
• 5xl -> 6
• 6xl -> 7

Approximate font sizes with the default --unitone--base-font-size: 16 are:

For screenshot matching or visual approximation, it is usually better to pick the nearest row from this table first and only then fine-tune if needed. These values are approximate static sizes; .-fluid-typography changes the rendered size with the viewport.

font-weight

• .-font-weight:bold

Use this when a simple bold treatment is sufficient and introducing element-level styles would be excessive. In plain HTML, write it in class. Example: class="-font-weight:bold"

gap

• .-gap:{variation}
• .-column-gap:{variation}
• .-row-gap:{variation}

Supported variations follow the spacing scale already used in primitives:

• -3 to 7
• 1s to 7s
• 2m to 7m

padding

• .-padding:{variation}
• .-padding-inline:{variation}
• .-padding-inline-start:{variation}
• .-padding-inline-end:{variation}
• .-padding-block:{variation}
• .-padding-block-start:{variation}
• .-padding-block-end:{variation}
• .-padding-top:{variation}
• .-padding-right:{variation}
• .-padding-bottom:{variation}
• .-padding-left:{variation}

Supported variations are the same as the gap utilities.

display

• .-display:none
• .-display:inline
• .-display:inline-block
• .-display:block
• .-display:flex
• .-display:grid
• .-display:inline-flex
• .-display:inline-grid

Use these on plain wrappers or interactive elements when a full primitive is unnecessary.

flex-direction

• .-flex-direction:row
• .-flex-direction:row-reverse
• .-flex-direction:column
• .-flex-direction:column-reverse

Use these on flex wrappers when you only need to change the main axis direction.

flex-wrap

• .-flex-wrap:wrap
• .-flex-wrap:nowrap

Use these on flex wrappers when you only need to control wrapping behavior.

justify-content

• .-justify-content:start
• .-justify-content:center
• .-justify-content:end
• .-justify-content:space-between
• .-justify-content:space-around
• .-justify-content:space-evenly

justify-items

• .-justify-items:start
• .-justify-items:center
• .-justify-items:end
• .-justify-items:stretch

justify-self

• .-justify-self:start
• .-justify-self:center
• .-justify-self:end
• .-justify-self:stretch
• .-justify-self:auto

mix-blend-mode

• .-mix-blend-mode:{value}

Supported values are:

• normal
• multiply
• screen
• overlay
• darken
• lighten
• color-dodge
• color-burn
• hard-light
• soft-light
• difference
• exclusion
• hue
• saturation
• color
• luminosity

overflow

• .-overflow:visible
• .-overflow:hidden
• .-overflow:scroll
• .-overflow:auto
• .-overflow:clip

position

• .-position:static
• .-position:relative
• .-position:absolute
• .-position:fixed
• .-position:sticky

text-align

• .-text-align:start
• .-text-align:end
• .-text-align:left
• .-text-align:right
• .-text-align:center
• .-text-align:justify

Use these on text containers when a simple alignment utility is clearer than custom CSS.

color

• .-color:{token}

background-color

• .-background-color:{token}

Available tokens include semantic colors and palette colors such as:

• background
• background-alt
• text
• text-alt
• text-immutable
• white
• pale-gray to heavy-pink

Usage notes

• Prefer utilities on non-primitive elements.
• Do not use utilities as a substitute for a missing primitive structure.
• If app.css is loaded, normal text already participates in the unitone typography system, so data-unitone-layout="-typography" is not required for every text node.
• For borders, backgrounds, padding, and layout-affecting grouping, Decorator is often clearer than stacking multiple utility classes.
• For alignment keywords, use start and end rather than flex-start and flex-end, matching the rest of unitone CSS.