Styling
Every element is styled with utilities: short classes, such as p-4 or bg-surface, that apply tokens from the theme. Styles are worked out when the app is built, so nothing is matched on the device, and every target draws the same thing.
<view class="row items-center gap-3 p-4 rounded-lg bg-surface shadow-sm">
<view class="w-10 h-10 rounded-full bg-primary"></view>
<text class="grow truncate text-label text-ink">Ada Lovelace</text>
<button class="px-3 py-2 rounded-md bg-raised hover:bg-border pressed:opacity-75">Follow</button>
</view>
Two runnable examples go with this page: examples/styling shows every group of utilities, one page each, and examples/theming shows one screen with a project theme in light and dark. Run either with duolith dev examples/styling.
Layout: every container is a stack
A view lays its children out top to bottom. Add row to lay them out side by side, gap-* for the space between them, and items-*, justify-* and self-* to align them. grow takes the remaining space and shrink-0 refuses to shrink. To place something on top of another element, give the parent relative and the child absolute with inset-0 or top-*, right-*, bottom-*, left-*, and z-* to order overlaps.
Prefixes
A prefix makes a utility conditional. Write it before the utility with a colon, and combine as many as you need, in any order:
<button class="bg-primary hover:bg-ink pressed:opacity-75 focus:shadow-md disabled:opacity-50">Save</button>
<view class="col md:row gap-4 dark:md:bg-raised"></view>
- States:
pressed:,hover:,focus:anddisabled:follow how the person is using the element. When several hold at once,disabled:wins overpressed:, which wins overfocus:, which wins overhover:. - **
hover:is web only.** It applies when a mouse or trackpad rests on the element, and only on devices whose pointer can hover, so a tap on a phone's browser never leaves it stuck on. On iOS and Android it never applies: usepressed:for feedback that every target shows. - Dark mode:
dark:applies when the app shows its dark values (see Light and dark). - Window sizes:
md:applies when the window is at least 768px wide andlg:from 1024px. Write the phone layout first, without a prefix, and widen it:col md:row,hidden lg:flex. On native these will follow the window's size class (decision 0017).
When two utilities set the same property, the class order never matters. The winner is decided in this order:
- The stronger state:
disabled:, thenpressed:, thenfocus:, thenhover:, then no state. Sopressed:bg-raisedshows on a pressed button even next tomd:hover:bg-surface. - Then the wider window:
lg:, thenmd:, then no window prefix. Solg:p-8 md:p-4pads by 8 in a large window. - Then more conditions over fewer:
md:p-6 p-4pads by 6 in a wide window, anddark:md:beatsmd:.
Theming
Every token can be changed by a theme.yaml at the root of the project. Change only what you need; every token you leave out keeps its default value, and you can add tokens of your own, which the utilities pick up straight away (brand below makes bg-brand, text-brand and border-brand).
# theme.yaml
dark: system # system, light or dark
color:
primary: { light: "#0f766e", dark: "#5eead4" }
brand: { light: "#be185d", dark: "#f9a8d4" }
radius:
md: 4px
lg: 6px
shadow:
md: { light: "0 2px 0 rgb(0 0 0 / 0.08)", dark: "0 2px 0 rgb(0 0 0 / 0.5)" }
text:
title: { size: 32px, line: 38px, weight: 800 }
font:
family: "Georgia, 'Times New Roman', serif"
The groups are space, radius, color, shadow, text, font, and, for the kit and motion, duration, easing, shape and control (see Looks, motion and parts). Colours and shadows need a light and a dark value. Numbers may be written with or without quotes. Token names use letters, digits, -, _ and . (so a space step 0.5 gives p-0.5). A value may not be empty, and may not contain ;, {, }, <, \, a comment, a line break, or an unclosed quote or bracket, so a theme can never break out of the style it is written into.
theme.yaml is checked against spec/schemas/theme.schema.json before the build starts, and every problem is reported at once, by where it is:
error: theme.yaml: 3 problems:
color.brand: dark is missing
colour: not allowed at the top level; did you mean color? Allowed: color, dark, font, radius, shadow, space, text.
dark: auto is not one of system, light, dark
Editors that understand JSON Schema can use the same file for completion: point the YAML language server at it with # yaml-language-server: $schema=../../spec/schemas/theme.schema.json (adjust the path to your project).
Looks, motion and parts
duration (instant, fast, normal, slow, screen) and easing (standard, enter, leave, emphasized) set how fast and how the kit and the motion presets move. shape sets the corners of kinds of things (control, field, container, chip, sheet, dialog, thumb) and control the measures of switches, checkboxes, sliders, progress bars and fields. A value may name another token: control: "{radius.md}". These groups take only the names listed, and each value must be its group's kind once the tokens it names are filled in: a duration such as 120ms, a curve such as ease-out or cubic-bezier(0.2, 0, 0, 1), a length such as 8px. A misspelt name or a value of another kind fails the build.
look: platform makes the kit look like iOS on an iPhone and like Material on Android: iOS's 51×31 green switch, Material's outlined one, each platform's field heights, radii, tab indicator and title alignment, and its motion. On the web, web-look decides: user-agent (the default) follows the browser's platform; ios, material or default picks one. A look changes shape, control, motion and part tokens only, never colours, and a token your theme sets wins over every look.
Each part has its own tokens, listed under look: in its spec (spec/kit/<part>.yaml), and its variants and slots have tokens too. Change them under parts::
look: platform
parts:
Button:
tokens: { press-scale: "0.96" }
variants:
primary: { background: "{color.brand}", ink: "{color.on-brand}" }
slots:
label: { weight: "700" }
An unknown part (E0507), token (E0508), slot (E0509) or variant (E0510), a reference to a token that does not exist (E0511), or a value of another kind than the token's default (E0520: a colour for a corner, banana for a duration), fails the build. The theming example sets all of these (decision 0103).
Light and dark
Colours and shadows have a light and a dark value. dark: in theme.yaml chooses which one the app shows:
dark: | The app shows |
|---|---|
system (the default) | Light or dark, following the device setting, and changing when it changes |
light | Always the light values; dark: utilities never apply |
dark | Always the dark values; dark: utilities always apply |
Most screens need no dark: utilities at all: bg-surface is already dark in dark mode. Use dark: only for a change that is not a colour swap, such as a border that only dark mode needs.
A light/dark switch
With dark: system, the app can also choose for itself, as a settings screen does, with colorScheme from @duolith/client (decision 0043):
---
import { colorScheme, effect, state } from "@duolith/client";
import { SegmentedControl } from "@duolith/kit";
let scheme = state(colorScheme.choice);
effect(() => colorScheme.choose(scheme));
const schemes = [
{ value: "system", label: "System" },
{ value: "light", label: "Light" },
{ value: "dark", label: "Dark" },
];
---
<SegmentedControl label="Appearance" options={schemes} bind:value={scheme} />
<text>{colorScheme.isDark ? "Showing dark" : "Showing light"}</text>
colorScheme.choice is "system", "light" or "dark"; colorScheme.isDark is what shows now; both are state. The choice is kept on the device, so the app opens as it was left, and choosing "system" follows the device again. A theme that is always light or always dark ignores the choice, and colorScheme.isDark then always says what the theme shows. examples/gallery has the switch on its Appearance tab.
The page's head has a small inline script that applies the kept choice before the first paint, so the app never flashes the other scheme while it loads. The build's own Content-Security-Policy allows it by its hash, 'sha256-sSKSwu1CdCfvRHw6f3shtEDfBuf0kZ+H4QB7fEY5ui8=' (see security.md), and merges it into a policy you write out yourself. The script is only there when the theme follows the system.
Page styles
When no utility fits, define a class in the page's own <style> block. It applies to that page only. Prefer a token to a raw value, through its custom property on the web: var(--color-primary), var(--space-4).
Fonts of your own
Put the font files in public/ and declare them with @font-face at the top of a style block. Then ask for the family in font-family, or make it the theme's font.family:
@font-face {
font-family: "Caladea";
font-weight: 700;
src: url("/fonts/Caladea-Bold.ttf") format("truetype");
}
The web serves the file from public/. A native build copies it into the iOS and Android apps, and the shells register it before the first screen draws.
A phone loads only TrueType and OpenType files. Give each face a .ttf or .otf source, beside a WOFF2 one if you like; a face with neither is E0450. format("truetype"), format("opentype") and their -variations forms count. The source must be a file of public/ named from the root, not another server's font (E0451), and the file must be there (E0452). A @font-face inside @media or @supports stays E0209 on native.
The native build reads every font file before it ships it, and stops rather than leave text in the system font:
- The file must be a TrueType or OpenType font, one face per file: not a WOFF2 file renamed
.ttf, not a.ttccollection, not cut short (E0457). - iOS finds a font only by the family name written inside the file. So the build reads the file's name table and
font-familymust be one of the names it gives (E0458, case does not matter). The build checks rather than renaming the font, so both platforms find it by the same name. - Android keeps one face per family for each of normal, bold, italic and bold italic, and a weight of 600 or more counts as bold. Two faces of one family that land on one of those, such as a 400 and a 500, are E0455. Give the extra weight its own family, the name its file gives it (often "Inter Medium").
font-weightmust benormal,bold, a number from 1 to 1000 or a range for a variable font.bolderandlightermean nothing in a@font-face(E0456).- Two files for one family, weight and style are E0454. Each file ships under its path in
public/, with_between the folders, so/fonts/a/Regular.ttfand/fonts/b/Regular.ttfboth ship.
examples/theming ships Caladea this way.
Reference
These tables are generated from spec/styling/utilities.yaml and spec/styling/default-theme.yaml by tools/generate-styling-reference.ts; do not edit them by hand. A pattern such as p-{space} stands for one utility per token or step listed under it: p-0, p-1, and so on.
Prefixes
| Prefix | Kind | Applies |
|---|---|---|
pressed: | state | While the element is being pressed. |
hover: | state | While a pointer rests on the element. Web only, and only on devices with a pointer that can hover; on iOS and Android it never applies. |
focus: | state | While the element has keyboard focus. |
disabled: | state | While the element is disabled. |
dark: | scheme | When the app is in dark mode (the system setting, or the theme's dark choice). |
md: | window | When the window is at least 768px wide (a medium window, such as a tablet in portrait). |
lg: | window | When the window is at least 1024px wide (a large window, such as a laptop or a tablet in landscape). |
Layout
| Utility | Does | Sets |
|---|---|---|
row | Lay children out in a row instead of a column. | flex-direction: row |
col | Lay children out in a column, the default; undoes row at a wider window, as in row md:col. | flex-direction: column |
wrap | Let a row wrap onto more lines. | flex-wrap: wrap |
grow | Take up the remaining space. | flex-grow: 1 |
shrink-0 | Never shrink below the element's own size. | flex-shrink: 0 |
items-start | Align children to the start across the stack. | align-items: flex-start |
items-center | Centre children across the stack. | align-items: center |
items-end | Align children to the end across the stack. | align-items: flex-end |
items-stretch | Stretch children across the stack. | align-items: stretch |
justify-start | Pack children at the start of the stack. | justify-content: flex-start |
justify-center | Centre children along the stack. | justify-content: center |
justify-end | Pack children at the end of the stack. | justify-content: flex-end |
justify-between | Spread children along the stack, with no space at the ends. | justify-content: space-between |
justify-around | Spread children along the stack, with half a gap at each end. | justify-content: space-around |
justify-evenly | Spread children along the stack, with equal space everywhere. | justify-content: space-evenly |
self-start | Align this element to the start, whatever its parent says. | align-self: flex-start |
self-center | Centre this element, whatever its parent says. | align-self: center |
self-end | Align this element to the end, whatever its parent says. | align-self: flex-end |
self-stretch | Stretch this element across its parent. | align-self: stretch |
overflow-hidden | Clip children to the element's bounds and corners. | overflow: hidden |
hidden | Remove the element from the layout. | display: none |
flex | Show an element again as a stack, as in hidden md:flex. | display: flex |
Spacing
| Utility | Does | Sets |
|---|---|---|
p-{space} | Padding on all sides.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | padding: {space} |
px-{space} | Padding at the start and end.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | padding-inline: {space} |
py-{space} | Padding at the top and bottom.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | padding-block: {space} |
pt-{space} | Padding at the top.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | padding-top: {space} |
pb-{space} | Padding at the bottom.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | padding-bottom: {space} |
gap-{space} | Space between children.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | gap: {space} |
Sizing
| Utility | Does | Sets |
|---|---|---|
w-full | Full width of the parent. | width: 100% |
w-screen | Full width of the window. | width: 100vw |
w-auto | Width from the content and the layout, the default. | width: auto |
w-{space} | A width from the space scale.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | width: {space} |
w-{fraction} | A fraction of the parent's width, such as w-1/2.<br>fraction steps: 1/2, 1/3, 2/3, 1/4, 3/4 | width: {fraction} |
h-full | Full height of the parent. | height: 100% |
h-screen | Full height of the window. | height: 100vh |
h-auto | Height from the content and the layout, the default. | height: auto |
h-{space} | A height from the space scale.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | height: {space} |
h-{fraction} | A fraction of the parent's height, when the parent has a height.<br>fraction steps: 1/2, 1/3, 2/3, 1/4, 3/4 | height: {fraction} |
min-w-full | At least the width of the parent. | min-width: 100% |
min-w-{space} | A minimum width from the space scale.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | min-width: {space} |
min-h-full | At least the height of the parent. | min-height: 100% |
min-h-screen | At least the height of the window. | min-height: 100vh |
min-h-{space} | A minimum height from the space scale.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | min-height: {space} |
max-w-full | At most the width of the parent. | max-width: 100% |
max-w-{space} | A maximum width from the space scale.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | max-width: {space} |
max-w-{fraction} | At most a fraction of the parent's width.<br>fraction steps: 1/2, 1/3, 2/3, 1/4, 3/4 | max-width: {fraction} |
max-h-full | At most the height of the parent. | max-height: 100% |
max-h-screen | At most the height of the window. | max-height: 100vh |
max-h-{space} | A maximum height from the space scale.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | max-height: {space} |
aspect-square | Keep a 1:1 shape; set one side and the other follows. | aspect-ratio: 1 / 1 |
aspect-video | Keep a 16:9 shape; set one side and the other follows. | aspect-ratio: 16 / 9 |
Position
| Utility | Does | Sets |
|---|---|---|
relative | Lay out normally, and be the frame absolute children are placed in. | position: relative |
absolute | Take the element out of the stack and place it in its nearest relative parent. | position: absolute |
inset-0 | Pin all four edges to the parent, so an absolute element covers it. | top: 0px<br>right: 0px<br>bottom: 0px<br>left: 0px |
top-{space} | Distance of an absolute element from the parent's top.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | top: {space} |
right-{space} | Distance of an absolute element from the parent's right edge.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | right: {space} |
bottom-{space} | Distance of an absolute element from the parent's bottom.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | bottom: {space} |
left-{space} | Distance of an absolute element from the parent's left edge.<br>space tokens: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 14, 16, 20, 24, 32, 40, 48, 64, 80, 96 | left: {space} |
z-{z} | Stacking order; higher draws on top.<br>z steps: 0, 10, 20, 30, 40, 50 | z-index: {z} |
Colour
| Utility | Does | Sets |
|---|---|---|
bg-{color} | Background colour.<br>color tokens: canvas, surface, raised, border, primary, on-primary, ink, muted, danger, success, scrim | background-color: {color} |
text-{color} | Text colour.<br>color tokens: canvas, surface, raised, border, primary, on-primary, ink, muted, danger, success, scrim | color: {color} |
border-{color} | Border colour; use with border or border-{border-width}.<br>color tokens: canvas, surface, raised, border, primary, on-primary, ink, muted, danger, success, scrim | border-color: {color} |
Type
| Utility | Does | Sets |
|---|---|---|
text-left | Align text to the left. | text-align: left |
text-center | Centre text. | text-align: center |
text-right | Align text to the right. | text-align: right |
text-{text} | A text style from the theme (size, line height and weight).<br>text tokens: title, heading, body, label, caption | font-size: {text.size}<br>line-height: {text.line}<br>font-weight: {text.weight} |
font-{weight} | Font weight, overriding the text style's.<br>weight steps: normal, medium, semibold, bold | font-weight: {weight} |
truncate | Keep text on one line and end it with an ellipsis when it does not fit. | overflow: hidden<br>text-overflow: ellipsis<br>white-space: nowrap |
line-clamp-{line-clamp} | Show at most this many lines, ending with an ellipsis.<br>line-clamp steps: 2, 3 | display: -webkit-box<br>-webkit-box-orient: vertical<br>-webkit-line-clamp: {line-clamp}<br>overflow: hidden |
Borders and radius
| Utility | Does | Sets |
|---|---|---|
border | A one-pixel border in the border colour. | border-width: 1px<br>border-style: solid<br>border-color: {color.border} |
border-{border-width} | A thicker border (or none, with border-0) in the border colour.<br>border-width steps: 0, 2, 4, 8 | border-width: {border-width}<br>border-style: solid<br>border-color: {color.border} |
border-t | A one-pixel border on the top edge only. | border-top: 1px solid {color.border} |
border-b | A one-pixel border on the bottom edge only. | border-bottom: 1px solid {color.border} |
rounded-{radius} | Corner radius; rounded-full makes a pill or a circle.<br>radius tokens: none, xs, sm, md, lg, xl, 2xl, full | border-radius: {radius} |
Shadows and opacity
| Utility | Does | Sets |
|---|---|---|
shadow-{shadow} | A shadow from the theme, with its own dark mode value.<br>shadow tokens: none, sm, md, lg | box-shadow: {shadow} |
opacity-{opacity} | How opaque the element and its children are, in percent.<br>opacity steps: 0, 25, 50, 75, 100 | opacity: {opacity} |
Default tokens
Colour scheme: dark: system. Font: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif.
| Space | Value |
|---|---|
0 | 0px |
1 | 4px |
2 | 8px |
3 | 12px |
4 | 16px |
5 | 20px |
6 | 24px |
8 | 32px |
10 | 40px |
12 | 48px |
14 | 56px |
16 | 64px |
20 | 80px |
24 | 96px |
32 | 128px |
40 | 160px |
48 | 192px |
64 | 256px |
80 | 320px |
96 | 384px |
| Radius | Value |
|---|---|
none | 0px |
xs | 3px |
sm | 6px |
md | 10px |
lg | 16px |
xl | 24px |
2xl | 32px |
full | 9999px |
| Colour | Light | Dark |
|---|---|---|
canvas | #f6f5f2 | #111214 |
surface | #ffffff | #1b1c1f |
raised | #eeece7 | #26272b |
border | #e2dfd8 | #2f3035 |
primary | #4b5bdc | #8b96ff |
on-primary | #ffffff | #0d0f24 |
ink | #1c1c1e | #ececee |
muted | #6b6a66 | #9a9aa0 |
danger | #c2362b | #ff7a6e |
success | #2f7d4f | #6fd49a |
scrim | #1c1c1e66 | #000000a6 |
| Shadow | Light | Dark |
|---|---|---|
none | none | none |
sm | 0 1px 2px rgb(0 0 0 / 0.06) | 0 1px 2px rgb(0 0 0 / 0.4) |
md | 0 4px 12px rgb(0 0 0 / 0.08), 0 1px 3px rgb(0 0 0 / 0.06) | 0 4px 12px rgb(0 0 0 / 0.5), 0 1px 3px rgb(0 0 0 / 0.4) |
lg | 0 12px 32px rgb(0 0 0 / 0.12), 0 2px 6px rgb(0 0 0 / 0.06) | 0 12px 32px rgb(0 0 0 / 0.6), 0 2px 6px rgb(0 0 0 / 0.4) |
| Text style | Size | Line height | Weight |
|---|---|---|---|
title | 28px | 34px | 700 |
heading | 20px | 26px | 600 |
body | 16px | 22px | 400 |
label | 15px | 20px | 600 |
caption | 13px | 18px | 400 |