llms.txt
Compare with other sites' llms.txt files →# Alloy CSS
> One stylesheet for HTML a server renders: utilities, plus dialogs, menus,
> drawers, tabs, tooltips and toasts that work with no JavaScript. MIT.
> Version 1.0.8. Docs with live examples: https://alloyhtml.com/docs
Link it in the <head>:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@alloyhtml/css@1/dist/alloy.min.css">
The examples use Google's Material Icons, which are not part of the kit:
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
Dark mode, following the visitor's device (optional):
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@alloyhtml/css@1/dist/themes/dark.min.css" media="(prefers-color-scheme: dark)">
A whole page built this way, to copy from: https://alloyhtml.com/example.html
Alloy CSS is one stylesheet of utilities and parts (buttons, fields, dialogs,
menus, tabs) for HTML a server renders. Every page you write with it must
look like it belongs with the others, so you write with the kit's classes
and values and nothing else.
The reference below lists every class with examples. Read the
topic you need before you write a part you haven't written in this project
yet: a modal, a menu, tabs, a form field.
## Rules
1. **Only classes the kit defines.** Never invent one, and never bring
Tailwind or Bootstrap names (`mt-4`, `btn`, `p-4`, `text-sm`). If no
class does what you need, see rule 6.
2. **Only the kit's values.** Spacing is 0, 2, 4, 8, 12, 16, 20, 24, 32, 40,
48, 60, 80, 100, 120, 140 (px). Gaps and gutters are 0, 4, 8, 12, 16, 20,
24, 32, 40. Radius is 0, 4, 8, 12, 16, 20. Widths are percentages
(`width-50`) or fractions (`width-1-3`). There is no `padding-15`.
3. **Semantic colours for the page, palette colours for meaning.** Surfaces
are `bg-base` (the page), `bg-surface`, `bg-raised` (cards, dialogs),
`bg-sunken`, `bg-inverse`. Text is `text-primary`, `text-secondary`,
`text-muted`, `text-inverse`. Borders are `border-subtle`, `border-strong`.
These follow the theme. The brand is `primary-1`; red, green, orange and
the rest are for status. A tint is `-light-1`, text on a tint `-dark-1`.
4. **No JavaScript for interactions.** A modal is a `<dialog>` opened with
`commandfor` and `command="show-modal"`. A menu or drawer is a `popover`.
An accordion is a `<details>`. Tabs are radio buttons. Look each one up in
`reference.md` and copy its markup.
5. **Breakpoints go down.** A suffix applies at that width and below: `-lg`
1200px, `-md` 992px, `-sm` 768px, `-xs` 576px. Write the desktop class
first, then the smaller ones: `width-50 width-100-sm`. Not every family
has them; the reference says which.
6. **One-offs go inline.** A size or position the kit doesn't have (a 420px
panel, a 3/4 image ratio) goes in a `style` attribute. A colour, radius,
shadow or spacing never does: pick the nearest kit value. CSS of your own
is only for what inline can't do (a media query, `:hover` on a child,
`::before`), in the page's `<style>` block.
7. **No state classes.** There is no `.active`. A current link swaps
utilities in the markup (`text-primary-1` instead of `text-secondary`)
and carries `aria-current="page"`.
8. **Two page widths.** `container-1320` for headers and pages you browse,
`container-960` for pages you read or fill in.
## Names
A class says what it does, and its prefix says where it goes. Anything on
the flex container starts with `flex-` (`flex-wrap`, `flex-gap-16`,
`flex-items-center`). Anything on a child has its own prefix (`grow-1`,
`shrink-0`, `align-center`, `order-1`). States are prefixes: `hover-`,
`active-` (`hover-bg-primary-2`).
## Quick map
| You'd write | Alloy |
|---|---|
| `p-4`, `px-4`, `mt-2` | `padding-16`, `padding-x-16`, `margin-top-8` |
| `gap-4` | `flex-gap-16` |
| `items-center`, `justify-between` | `flex-items-center`, `flex-justify-between` |
| `flex-1` | `grow-1` (or `equal` for equal columns) |
| `w-full`, `w-1/2` | `width-100`, `width-50` |
| `text-sm`, `text-xs` | `text-body-2`, `text-body-3` |
| `text-2xl font-bold` | `h4 font-weight-700` (`h1` to `h6` work on any element) |
| `text-gray-500` | `text-secondary` or `text-muted` |
| `bg-white`, `bg-gray-50` | `bg-raised`, `bg-base` |
| `rounded-lg`, `rounded-full` | `rounded-8`, `circle` |
| `shadow`, `shadow-lg` | `shadow-1`, `shadow-3` |
| `hidden md:block`, `md:hidden` | `hidden-sm` (hidden at 768px and below), `hidden-sm-greater` (hidden above it) |
| `sr-only` | `visually-hidden` |
| `btn btn-primary` | `button bg-primary-1 border-primary-1 text-white hover-bg-primary-2 hover-border-primary-2` |
| a grid of cards | `flex flex-wrap flex-gutter-12` with `width-1-3 width-100-sm` wrappers |
## Check your work
Run the checker on what you wrote. It lists every class the kit doesn't
define, with its file and line:
```
npx @alloyhtml/css check templates/
```
Pass `--css` for the project's own stylesheet and `--allow` for an icon
font's class. Fix everything it lists before you finish.
# Reference
Every class, value and pattern, as the docs at alloyhtml.com/docs list them.
Generated from the docs; do not edit by hand.
## Make It Yours
### Themes & Brands
Two kinds of small stylesheet, linked after the kit's. A theme sets the page's colours: the kit is light, and Dark (a soft graphite) and Midnight (a soft navy) ship with it. A brand sets a product's colour and the shape of its fields and buttons. The theme builder (/themes) writes both files for you.
#### Stylesheets
```html
<!-- Fonts. Required, or the text falls back to system fonts. Add your own typeface here. -->
<link rel="stylesheet" href="/fonts/fonts.css">
<!-- Icons: Google's Material Icons (Apache 2.0), not part of the kit. Swap this one file for another icon set. -->
<link rel="stylesheet" href="/fonts/icons.css"> <!-- or your own icon set -->
<!-- The kit. Required. -->
<link rel="stylesheet" href="/assets/css/index.css">
<!-- The brand. Optional: edit it to rebrand. -->
<link rel="stylesheet" href="/assets/css/brands/cedar-health.css"> <!-- or my-brand.css -->
<!-- The theme. Optional: one of these two, or none for light only. -->
<!-- Follows the visitor's device: -->
<link rel="stylesheet" href="/assets/css/themes/dark.css" media="(prefers-color-scheme: dark)"> <!-- or midnight.css, or my-theme.css -->
<!-- Always dark: -->
<link rel="stylesheet" href="/assets/css/themes/dark.css"> <!-- or midnight.css, or my-theme.css -->
```
A light-only page downloads none of the dark styles. The brand and the theme can go in either order.
#### Theme
Surfaces, text and borders. Solid palette colours such as red stay the same in every theme. A dark theme of your own goes after themes/dark.css, so it keeps the dark extras (soft tints, lifted coloured text, dark form fields).
```html
/* my-theme.css: link it after the kit's stylesheet and themes/dark.css. */
:root {
--color-bg-base: #242427; /* the page */
--color-bg-surface: #080808; /* buttons, icon tiles, table heads */
--color-bg-raised: #404045; /* cards */
--color-border-subtle: #4e4e54; /* dividers */
--color-border-strong: #8a8a8f; /* field edges: keep 3:1 */
--color-text-primary: #f4f4f5;
--color-text-secondary: #cdcdd4;
--color-text-muted: #ababb1; /* keep 4.5:1 on cards */
}
```
#### Brand
Each product page links its brand file, assets/css/brands/<name>.css (cedar-health.css, stagepass.css …). Edit that one file to rebrand a product, or link your own in its place: every page and every theme follows.
```html
/* my-brand.css: link it after the kit's stylesheet. */
:root {
--brand-primary-1: hsl(158, 80%, 29%); /* buttons, fills, brand text */
--brand-primary-2: hsl(158, 82%, 25%); /* hover */
--brand-primary-3: hsl(158, 85%, 21%); /* pressed */
--brand-primary-light-1: hsl(150, 70%, 97%); /* tints behind badges */
--brand-primary-light-2: hsl(150, 70%, 94%);
--brand-primary-light-3: hsl(150, 70%, 90%);
--brand-primary-dark-1: hsl(158, 85%, 22%); /* brand text on a tint */
--brand-primary-dark-2: hsl(158, 90%, 16%);
--brand-primary-dark-3: hsl(158, 95%, 12%);
/* The dark themes: lighter, so brand text reads on dark cards. */
--brand-dark-primary-1: hsl(158, 55%, 50%);
--brand-dark-primary-2: hsl(158, 60%, 58%);
--brand-dark-primary-3: hsl(158, 65%, 66%);
--brand-dark-on-primary: hsl(160, 30%, 10%); /* text on a brand fill */
/* Links and the focus outline don't follow the brand on their own. */
--color-link: hsl(158, 80%, 26%);
--color-focus-ring: hsl(158, 80%, 26%);
/* Type: the headings' font, and the one for everything else. */
--font-family-heading: 'Merriweather', Georgia, serif;
--font-family-base: 'Plus Jakarta Sans', system-ui, sans-serif;
/* Fields and buttons: their corner radius (999px makes pills). */
--control-radius: 12px;
}
```
Keep white button text readable: at least 4.5:1 against primary-1, about 40% lightness for most hues and darker for green and yellow. Fonts: Plus Jakarta Sans and Merriweather ship in fonts/fonts.css; for another font, add its @font-face there and name it here. --font-family-heading styles the h1 to h6 elements (the .h1 to .h6 classes keep the base font), and --font-family-serif the .font-family-serif class.
#### Theme switch
Optional, and the only part that needs a script. Give the theme link an id, point it at the chosen file, and remember the choice. Run the restore part in the <head>, so the page never flashes the wrong theme.
```html
<link id="theme" rel="stylesheet" href="/assets/css/themes/dark.css" media="(prefers-color-scheme: dark)">
<script>
function setTheme(name) {
var link = document.getElementById('theme');
if (name === 'light') link.media = 'not all';
else { link.href = '/assets/css/themes/' + name + '.css'; link.media = 'all'; }
try { localStorage.setItem('theme', name); } catch (e) {}
}
try { var saved = localStorage.getItem('theme'); if (saved) setTheme(saved); } catch (e) {}
</script>
```
## Quick Reference
### Cheatsheet
Every value the utilities are built from, on one page.
No breakpoint versions: the same at every width.
#### Browsers
| Browser | From version (desktop and phone) |
|---|---|
| Chrome | 123 |
| Edge | 123 |
| Firefox | 125 |
| Safari | 17.5 |
Menus, dialogs, tabs and filters are built on popover, :has(), color-mix() and light-dark(), which older browsers do not have. Dialogs need newer still: their buttons use command and commandfor, from Chrome and Edge 135, Firefox 144 and Safari 26.2. On an older browser the button that opens a dialog does nothing. A click outside closes a dialog from Safari 27.3; Esc and its close button work everywhere.
#### Breakpoints
A suffixed class applies at that width and below: .padding-16-xs is 16px of padding on a phone. Put the plain class first and the smaller screens after it.
| Suffix | Max-width |
|---|---|
| -lg | 1200px |
| -md | 992px |
| -sm | 768px |
| -xs | 576px |
| Classes | Breakpoint versions |
|---|---|
| Spacing, width and height, display, flex and gap, order, position, overflow, text size, alignment and wrapping, font weight, rounded-0 | Yes |
| Colour, border, rounded, shadow, opacity, z-index, icon and square sizes, animation | No: the same at every width |
#### Scales
Each family offers the steps the kit designs with. Spacing, gap and square sizes share their common numbers, so 16 is 16 everywhere.
| Scale | Values |
|---|---|
| Margin / padding (px) | 0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 60, 80, 100, 120, 140 |
| Square size (px) | 8, 12, 16, 20, 24, 28, 32, 36, 40, 48, 56, 64, 80 |
| Icon size (px) | 12, 16, 20, 24, 32, 48 |
| Width (%) | 0, 10, 20, 25, 30, 40, 50, 60, 70, 75, 80, 90, 100 (height: 100) |
| Flex gap and gutter | 0, 4, 8, 12, 16, 20, 24, 32, 40 |
| Border radius | 0, 4, 8, 12, 16, 20 |
| z-index | 0 to 5, plus z-max |
| Opacity | 0, 0.05, 0.2, 0.4, 0.6, 0.8, 1 |
#### Palette
Each colour works after .bg-, .text- and .border-.
Brand: primary-1, primary-2, primary-3, primary-light-1, primary-light-2, primary-light-3, primary-dark-1, primary-dark-2, primary-dark-3, violet-1, violet-2, violet-3, violet-light-1, violet-light-2, violet-light-3, violet-dark-1, violet-dark-2, violet-dark-3, amber-1, amber-2, amber-3, amber-light-1, amber-light-2, amber-light-3, amber-dark-1, amber-dark-2, amber-dark-3
Neutral: light-1, light-2, light-3, gray-1, gray-2, gray-3, dark-1, dark-2, dark-3
Utility: red-1, red-2, red-3, red-light-1, red-light-2, red-light-3, red-dark-1, red-dark-2, red-dark-3, magenta-1, magenta-2, magenta-3, magenta-light-1, magenta-light-2, magenta-light-3, magenta-dark-1, magenta-dark-2, magenta-dark-3, blue-1, blue-2, blue-3, blue-light-1, blue-light-2, blue-light-3, blue-dark-1, blue-dark-2, blue-dark-3, cyan-1, cyan-2, cyan-3, cyan-light-1, cyan-light-2, cyan-light-3, cyan-dark-1, cyan-dark-2, cyan-dark-3, green-1, green-2, green-3, green-light-1, green-light-2, green-light-3, green-dark-1, green-dark-2, green-dark-3, orange-1, orange-2, orange-3, orange-light-1, orange-light-2, orange-light-3, orange-dark-1, orange-dark-2, orange-dark-3
Grayscale: white, white-5, white-20, white-40, white-60, white-80, black, black-5, black-20, black-40, black-60, black-80, transparent
## Layout & Structure
### Container
Centres content up to a max-width, with 24px of side padding. Both containers are fluid.
Has breakpoint versions (-lg, -md, -sm, -xs).
No breakpoint suffix needed. A container fills the screen up to its max-width, so the wide one is never narrower than the narrow one and a page lines up with the header above it at every width.
| Class | Description |
|---|---|
| .container-1320 | Max-width 1320px. Headers, footers and pages you browse. |
| .container-960 | Max-width 960px. Pages you read or fill in: profiles, settings, checkout. |
```html
<div class="container-1320 bg-surface border border-subtle rounded-8 padding-y-12">
Default container content
</div>
<div class="container-960 bg-surface border border-subtle rounded-8 padding-y-12 margin-top-8">
Narrower container content
</div>
```
### Flex
Arrange, align and space items in a row or column.
Has breakpoint versions (-lg, -md, -sm, -xs).
#### Container & direction
| Class | Description |
|---|---|
| .flex | Flex container. |
| .inline-flex | Inline flex container. |
| .flex-row | Items flow horizontally (default). |
| .flex-column | Items flow vertically. |
| .flex-nowrap / .flex-wrap | Keep items on one line / let them wrap to new lines. |
| .flex-row-reverse | Reversed horizontal flow. |
| .flex-column-reverse | Reversed vertical flow. |
```html
<div class="flex flex-column flex-row-sm flex-gap-12">
<div class="bg-surface border border-subtle rounded-8 padding-12">Item 1</div>
<div class="bg-surface border border-subtle rounded-8 padding-12">Item 2</div>
<div class="bg-surface border border-subtle rounded-8 padding-12">Item 3</div>
</div>
```
#### Justify & align
| Class | Description |
|---|---|
| .flex-justify-start / .flex-justify-end | Pack items at the start / end of the main axis. |
| .flex-justify-between / .flex-justify-around | Space between items / around each item. |
| .flex-justify-center | Center items on the main axis. |
| .flex-items-start / .flex-items-end | Align items to the start / end of the cross axis. |
| .flex-items-center | Center items on the cross axis. |
| .flex-items-baseline / .flex-items-stretch | Align items to their text baseline / stretch them to fill the cross axis. |
| .flex-content-start / .flex-content-end / .flex-content-center | Place wrapped rows at the start / end / middle of the cross axis. |
| .flex-content-between / .flex-content-around / .flex-content-stretch | Space wrapped rows apart / around / stretch them. |
```html
<div class="flex flex-justify-between flex-items-center bg-surface border border-subtle rounded-8 padding-12">
<div>Item 1</div>
<div>Item 2</div>
<div>Item 3</div>
</div>
```
#### Gap
Space between items. Use it for rows of buttons, chips, badges and cards.
| Class | Description |
|---|---|
| .flex-gap-{size} | Both axes. Sizes: 0, 4, 8, 12, 16, 20, 24, 32, 40. |
| .flex-gap-x-{size} | Between columns only. |
| .flex-gap-y-{size} | Between wrapped rows only. |
```html
<div class="flex flex-gap-16 flex-gap-4-sm">
<div class="bg-surface border border-subtle rounded-8 padding-12">Item 1</div>
<div class="bg-surface border border-subtle rounded-8 padding-12">Item 2</div>
<div class="bg-surface border border-subtle rounded-8 padding-12">Item 3</div>
</div>
```
#### Gutter, for percentage columns
Gutter is padding on each child, so a .width-50 column plus its gutter still adds up to 100%. Put the width on a plain wrapper and the card inside it: a child that paints its own background, or sets its own padding, loses the space.
| Class | Description |
|---|---|
| .flex-gutter-{size} | Both axes. Same sizes as gap. |
| .flex-gutter-x-{size} | Horizontal only. |
| .flex-gutter-y-{size} | Vertical only. |
```html
<div class="flex flex-wrap flex-gutter-16">
<div class="width-50">
<div class="bg-surface border border-subtle rounded-8 padding-12">Half</div>
</div>
<div class="width-50">
<div class="bg-surface border border-subtle rounded-8 padding-12">Half</div>
</div>
</div>
```
#### Grow, shrink, fill & equal
| Class | Description |
|---|---|
| .grow-1 / .grow-0 | Item can / cannot grow to fill space. |
| .shrink-1 / .shrink-0 | Item can / cannot shrink. |
| .fill | flex: 1 1 auto. |
| .equal | flex: 1 0 0%, for equal-width siblings. |
```html
<div class="flex flex-gap-12">
<div class="grow-1 bg-surface border border-subtle rounded-8 padding-12">grow-1 (fills space)</div>
<div class="shrink-0 bg-surface border border-subtle rounded-8 padding-12">shrink-0</div>
</div>
```
#### Align self & order
| Class | Description |
|---|---|
| .align-start / .align-center / .align-end | Aligns one item on the cross axis. |
| .align-auto / .align-baseline / .align-stretch | Follow the container / align to the text baseline / stretch. |
| .order-min-1 … .order-5 | Visual order, independent of markup order. |
```html
<div class="flex flex-gap-12" style="height: 60px;">
<div class="align-start bg-surface border border-subtle rounded-8 padding-8">align-start</div>
<div class="align-center bg-surface border border-subtle rounded-8 padding-8">align-center</div>
<div class="align-end bg-surface border border-subtle rounded-8 padding-8">align-end</div>
</div>
```
### Positioning
Display, position, edge offsets, centering and z-index.
Has breakpoint versions (-lg, -md, -sm, -xs).
#### Display & position
| Class | Description |
|---|---|
| .block / .inline-block / .inline | display: block / inline-block / inline. |
| .static | Normal flow. |
| .relative | Offset from its own position. Anchors absolute children. |
| .absolute | Positioned against the nearest positioned ancestor. |
| .fixed | Positioned against the viewport. |
| .sticky | Sticks once scrolled to its offset. |
```html
<div class="relative bg-surface border border-subtle rounded-8 padding-24" style="height: 80px;">
Relative parent
<div class="absolute top-0 right-0 bg-raised border border-subtle rounded-4 padding-8">absolute top-0 right-0</div>
</div>
```
#### Edge offsets & centering
Offsets need a position class. Centering needs a .relative parent.
| Class | Description |
|---|---|
| .top-0 / .right-0 / .bottom-0 / .left-0 | Offset to 0. |
| .top-auto / .right-auto / .bottom-auto / .left-auto | Remove an offset set at another breakpoint. |
| .top-100 / .right-100 / .bottom-100 / .left-100 | Offset to 100%. |
| .center-x / .center-y / .center | Center horizontally / vertically / both. |
```html
<div class="relative bg-surface border border-subtle rounded-8" style="height: 80px;">
<div class="absolute center bg-primary-1 text-white rounded-4 padding-x-12 padding-y-4">Fully Centered</div>
</div>
`