v2.3 · Last updated: 03/09/26 · Etch 1.6.7 · ACSS 4.0.1
Heading levels, text sizes, and font families — all driven by Automatic.css variables. Sizes are fluid and responsive out of the box.
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.
Each card prints the family its token resolves to, read from the rendered specimen. ACSS declares --heading-font-family and --text-font-family only when a font is entered in its dashboard. On a site that sets its fonts elsewhere the token does not exist, the card says so, and reports the family the headings actually render in.
This is a standard body text paragraph rendered at the default text size with your configured line-height and max-width.
A second paragraph demonstrates content spacing. ACSS Smart Content Spacing handles the vertical rhythm between paragraphs, headings, lists, and other elements automatically.
The six ACSS color families with auto-generated shades (OKLCH in v4). Each swatch uses the corresponding CSS variable — change your ACSS dashboard and this guide updates instantly. Use color-mix() for transparencies.
Your action color — buttons, links, CTAs.
Your secondary brand color.
Your third brand color.
Your least-used brand color — sparingly for emphasis.
Your preferred neutral color — backgrounds, text, borders.
Black, white, and shades of grey.
Success, warning, info and danger, with the same eight-shade scale as the brand colours. All four slots ship switched off: until they are enabled in the dashboard's Semantic Colors panel, ACSS emits nothing for them, and a hatched swatch below means exactly that.
ACSS emits light-dark() for every palette variable. Shades invert, so --primary-ultra-light shows the ultra-dark value and --white and --black swap. Main colours and hover variants do not invert: they hold the same value in both schemes, which is why --primary and --secondary are identical above. That is the documented behaviour, not a broken demo, and Main Color Override in the dashboard is where you change it. Force a scheme on any element with .scheme--light or .scheme--dark.
Standard linkPrimary ButtonBoth cards paint this button with the same fill on purpose: --primary is a main colour and does not invert. Its label does, because a label colour is a shade. Measured here: fill oklch(0.664 0.107 202) in both cards, label lightness 0.95 in light against 0.10 in dark. That asymmetry is what makes some solid buttons unreadable under a dark scheme, see Buttons on Assigned Backgrounds.
ACSS emits light-dark() for every palette variable. Shades invert, so --primary-ultra-light shows the ultra-dark value and --white and --black swap. Main colours and hover variants do not invert: they hold the same value in both schemes, which is why --primary and --secondary are identical above. That is the documented behaviour, not a broken demo, and Main Color Override in the dashboard is where you change it. Force a scheme on any element with .scheme--light or .scheme--dark.
Standard linkPrimary ButtonBoth cards paint this button with the same fill on purpose: --primary is a main colour and does not invert. Its label does, because a label colour is a shade. Measured here: fill oklch(0.664 0.107 202) in both cards, label lightness 0.95 in light against 0.10 in dark. That asymmetry is what makes some solid buttons unreadable under a dark scheme, see Buttons on Assigned Backgrounds.
Content spacing and contextual gaps. All values are fluid and responsive via ACSS clamp() functions. Nested containers show how each spacing level relates to the others — padding is applied to all sides so you can see both block and inline simultaneously.
Every downward pairing of the scale exists as one fluid token, --space--to-, 15 for content spacing and the same 15 again for section spacing. A bridge spans a wider range than either end alone: desktop of the large size down to mobile of the small one. At desktop width a bridge and its plain counterpart print almost the same value below; narrow the window and the bridge falls faster.
The section scale has the identical matrix, --section-space-xl-to-m and friends, for section padding that has to collapse harder on mobile than the fluid calculation alone would.
Vertical rhythm between sections. Each ring shows its actual padding-block value — the visible vertical space is the real section padding applied by ACSS.
ACSS's utility grids and the Content Grid. The zones are additive offsets on one shared width: feature is content plus 2 × --feature-width, feature-max adds --feature-max-width on top, full spans everything. So a content width that already fills the container leaves the zones nowhere to go, and every child renders the same width with no error.
ACSS 4 is variable-first: the .grid--* utility classes were removed with most class modules, and grids are built from variables on your own class or, as here, inline. Each demo below is one declaration, grid-template-columns: var(--grid-N), with gap riding the contextual --grid-gap. The auto variants pack columns by available space.
One grid with named zones. Children land in the centred content zone by default and opt out sideways with a class. The bands below are live children of a real .content-grid, their widths measured off the rendered page. Here full is the section's inner width; on a real page it is the viewport.
Two traps worth naming. The zone rules select direct children, so wrapping a grid's content in a container silently disables every zone class below it. And because --content-width does double duty, a wide container setting collapses all zones onto the content width with no error. Opt a single box out of a defaulted grid with .content-grid--off.
The tokens this guide borrows for its own chrome, finally shown as specimens. --radius is one dial, not a scale: --radius-m resolves straight to --radius here, and the remaining radius tokens are fixed geometry, 0, 50% and 50vw. The composites assemble the pieces: --border is --border-size --border-style --border-color-dark.
--border paints with --border-color-dark, a translucent mix of --black, so it rides any light surface. --border-light is the same composite built on --white, for dark surfaces, shown here on a bg--dark strip.
Deliberately a single dial. Each square carries its token as border-radius and prints the value it resolves to. Squares, not bars: --radius-50 and --radius-circle only read correctly on one.
A divider is a border on its own line. --divider assembles --divider-size and --divider-style with whichever colour the dashboard's Default Divider Scheme picks; --divider-dark and --divider-light are the same composite pinned to one colour, shown here on a light and a dark surface. Below that, each dashboard setting on its own. --divider-gap rides --content-gap so the spacing follows the site's rhythm and sits on both sides of the rule, margin above and padding below, as the ?divider-all recipe lays it out, and --divider-inline-size is for dividers drawn as pseudo-elements rather than borders. Every value is measured.
on a light surface
on bg--dark
First item
Second item
Third item
Three steps per scale, 1 to 3, each black mixed at increasing opacity and blur; shipped 4.0.1 has no six-step ladder and no -subtle step. The specimens sit on a fixed light panel because a shadow on a dark page is invisible, which is a property of shadows, not of the tokens.
--text-shadow-1
--text-shadow-2
--text-shadow-3
filter: drop-shadow() follows the rendered contour instead of the box, which only shows on a non-rectangular shape. The filter sits on a parent and the clip-path on a child; on one element the clip would cut the shadow away with it.
Default link styles, link color variations on light and dark surfaces, and the ACSS button system. All buttons inherit global variables from the ACSS dashboard.
Light surface (default)
Here is a paragraph with a standard inline link embedded in the middle of the text to show how it reads in context. Links should be clearly distinguishable from surrounding body text.
Under a dark colour scheme these two panels invert. Measured on this install, .bg--dark computes oklch(0.25) in light and oklch(0.85) in dark, so a section that reads as dark in one scheme reads as light in the other. Background assignments are scheme-aware. Main colours are not, and that pairing is why some labels below drop out: the button text colour is a shade, so it inverts to the dark end, while the fill is a main colour and stays put. .btn--neutral measured 1.02:1 here. The fix is per colour, under Main Color Override in the ACSS dashboard.
bg--dark
Buttons
All six variants paint the same colour here, and that is ACSS working as designed. Automatic Color Relationships assign one Button Style per background context, and the rule matches on the btn-- prefix, so the variant class is never read. Add .unrelate to a button to opt it out, as in the row below.
Buttons with .unrelate
Links
Links are the one element Color Assignments leaves alone by default: the Link Color input for this background is blank on this install, and blank means a link keeps its global --link-color on any surface. The variants here set a light shade per link instead, which is the manual route until that input is filled.
bg--ultra-dark
Buttons
All six variants paint the same colour here, and that is ACSS working as designed. Automatic Color Relationships assign one Button Style per background context, and the rule matches on the btn-- prefix, so the variant class is never read. Add .unrelate to a button to opt it out, as in the row below.
Buttons with .unrelate
Links
Links are the one element Color Assignments leaves alone by default: the Link Color input for this background is blank on this install, and blank means a link keeps its global --link-color on any surface. The variants here set a light shade per link instead, which is the manual route until that input is filled.
The background utility classes and the assignment tokens behind them. A .bg--* class does more than paint: Automatic Color Relationships assign text, heading, link and button treatment for that context, which is why this guide's own panels carry these classes instead of colours.
Text on this surface is assigned by Automatic Color Relationships, not set by the guide.
Text on this surface is assigned by Automatic Color Relationships, not set by the guide.
Text on this surface is assigned by Automatic Color Relationships, not set by the guide.
Text on this surface is assigned by Automatic Color Relationships, not set by the guide.
The tokens the classes resolve to. --text-color, the body default, is --text-dark-muted, a translucent mix, not --text-dark; opaque body text is an explicit override.
There is no .bg--primary in ACSS 4: the contextual classes are exactly the four assigned ones above, and everything else went variable-first when the utility class modules were removed. A brand surface is painted with the token directly, and because no class is involved, Automatic Color Relationships do not fire: foreground and background are picked by hand, as in the strip below.
No class, no relationship: this pairing is a manual choice. Both tokens are shades from one family on purpose, shades invert together under a colour scheme, so the pairing holds in light and dark. Pairing a shade with the main colour does not: the shade flips, the main colour stays, and the two meet.
The focus system is context-aware: --focus-color is reassigned by every background relationship, so the ring on a dark panel is not the ring on the page. Every link and button in this guide is a real target, so the whole document is keyboard-testable.
Tab through the row below. The ring is ACSS's own focus styling, a specimen; the guide adds nothing to it.
ACSS wraps its motion output in prefers-reduced-motion guards, and this guide follows the same signal: smooth scrolling and the scheme switch transition turn off when the OS asks for less motion. There is nothing to see here unless your system requests it, which is the point.
Agency kit add-ons beyond stock ACSS specimens: custom surfaces 1–5, overlays 1–5, cards, icons (data-icon), and bpn Scheme Switch for Light/Dark handoff. Radius sizes band omitted while option-radius-sizes is off.
Kit custom surface slots. ACR sample text follows each surface’s color-relationship (light vs dark).
surface-1 · Paper texture · light
Accessible contrast sample. Headings and body should stay readable on this surface.
surface-2 · Radial wash · light
Accessible contrast sample. Headings and body should stay readable on this surface.
surface-3 · Brand gradient · dark
Accessible contrast sample. Headings and body should stay readable on this surface.
surface-4 · Dark grain · dark
Accessible contrast sample. Headings and body should stay readable on this surface.
surface-5 · Photo placeholder · dark
Accessible contrast sample. Headings and body should stay readable on this surface.
ACSS overlay presets on a photo stage. Copy sits above the ::before wash — confirm contrast per slot.
ACSS card framework (padding, radius, shadow-2). Specimens use .card + heading/body hooks.
Body copy on the card surface. Kit drives background, padding, and shadow.
Second specimen for padding/gap rhythm beside the first.
Framework icons: plain vs boxed. data-icon on the SVG enables shared icon-* tokens.
bpn Scheme Switch (BpnSchemeSwitch) — light / system / dark. Prefer this over the vendor Light Dark toggle for Normal + Color Scheme Support kits.
Toggle light and dark here, then scroll specimens above to confirm token flip.