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 assembles the following utilities:

• align-content
• align-items
• align-self
• background-color
• color
• container-type
• 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

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

container-type

• .-container-type:{value}

Currently supported values are:

• inline-size

Use this on an ancestor whose descendants use container queries. Supported layout primitives can use the equivalent containerType="inline-size" prop or data-unitone-layout token. Use the utility class for other HTML elements.

responsive-context

• .-responsive-context:container

This class is provided by the responsive-context behavior, which also handles the equivalent data-unitone-layout token. Load app.css or include the behavior through src/behaviors; loading src/utilities alone does not include it.

The default responsive context is the viewport. Setting -responsive-context:container together with -container-type:inline-size on the same element switches descendants to container-based fluid typography, spacing, padding, gutters, and responsive CSS. Only container is supported; there is no context setting that restores viewport behavior inside a container context.

Both markers must be on the same element for the context to become active. The first selects the responsive context for descendants; the second establishes the query container that supplies its width. Setting either marker alone does not change the responsive context. Classes and data-unitone-layout tokens can be combined on the same supported primitive.

<!-- No container context: switches when the viewport width is below 600px. -->
<div data-unitone-layout="frame -switch">...</div>
 
<div class="-container-type:inline-size -responsive-context:container">
	<!-- Switches when the container width is below 600px. -->
	<div data-unitone-layout="frame -switch">...</div>
</div>

The context applies only to descendants, not to the element carrying it. Use a wrapper when the target element itself also needs to switch contexts. Fluid tokens are recalculated for the direct children and inherited by their descendants. Static tokens keep their inherited values.

Use the equivalent data-unitone-layout tokens on a supported layout primitive:

<div data-unitone-layout="container -container-type:inline-size -responsive-context:container">
	<div data-unitone-layout="frame -switch">...</div>
</div>

In JSX, pair responsiveContext="container" with containerType="inline-size" on a supported layout primitive.

Nested containers

Container contexts can be nested. Set both markers on each context element. Descendants use the nearest eligible query container; the context element itself continues to use its ancestor’s context.

<div
	class="-container-type:inline-size -responsive-context:container"
	style="width: 800px"
>
	<!-- Uses the 800px-wide container and keeps its base aspect ratio. -->
	<div data-unitone-layout="frame -switch">...</div>
 
	<div
		class="-container-type:inline-size -responsive-context:container"
		style="width: 320px"
	>
		<!-- Uses the 320px-wide container and switches. -->
		<div data-unitone-layout="frame -switch">...</div>
	</div>
</div>

When the markers are not paired

If -container-type:inline-size is missing from the element carrying -responsive-context:container, that context marker is ignored. A container marker on a different element, or container-type set only through custom CSS, does not activate it.

The existing responsive context remains active. Without an active ancestor context, fluid values use the viewport and responsive changes use media queries. Inside an active ancestor context, its fluid values remain inherited and responsive changes continue to use container queries.

<!-- No active ancestor context; this unpaired marker has no effect. -->
<div class="-responsive-context:container">
	<!-- Fluid typography uses the viewport width. -->
	<p class="-font-size:6xl -fluid-typography">...</p>
	<!-- Switches when the viewport width is below 600px. -->
	<div data-unitone-layout="frame -switch">...</div>
</div>
 
<!-- Markers on separate elements do not activate a context either. -->
<div class="-container-type:inline-size" style="width: 320px">
	<div class="-responsive-context:container">
		<!-- Still switches based on the viewport width. -->
		<div data-unitone-layout="frame -switch">...</div>
	</div>
</div>

The selectors check marker presence, not the computed container-type property. If both markers are present but custom CSS disables the query container and no eligible ancestor container exists, 100cqw resolves to the small viewport width (100svw) and container size queries do not match. In that case, there is no automatic fallback to media queries.

The @container token (JSX: queryContext="container") selects container queries for the responsive behavior of the Frame, Layers, or VerticalWriting primitive carrying it. The only supported queryContext value is container. It requires an eligible ancestor query container and does not change fluid values or establish a context for descendants.

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 the font-size property to the matching font-size token. In plain HTML, write them in class. Example: class="-font-size:xl"

The same names can also be used with data-unitone-layout when you load the font-size behavior without the utility classes. Example: data-unitone-layout="-font-size:xl"

Named font-size utilities map to font-size tokens like this:

• 2xs -> --unitone--font-size-2xs
• xs -> --unitone--font-size-xs
• s -> --unitone--font-size-s
• m -> --unitone--font-size-m
• l -> --unitone--font-size-l
• xl -> --unitone--font-size-xl
• 2xl -> --unitone--font-size-2xl
• 3xl -> --unitone--font-size-3xl
• 4xl -> --unitone--font-size-4xl
• 5xl -> --unitone--font-size-5xl
• 6xl -> --unitone--font-size-6xl

Approximate font sizes with the default --unitone--root-font-size: 16px 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.

Add .-fluid-typography together with a .-font-size:* utility to switch to the matching fluid token, such as --unitone--font-size-xl-fluid. The .-fluid-typography class is a modifier for font-size utilities and has no standalone effect.

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 line-height system, so typography helpers are 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.