DEV Community: richi.codes

CSS style queries: one variable, every style

richi.codes — Thu, 29 Oct 2026 08:30:43 +0000

This note has an interactive demo. Try it in the original

You can now write @container style(--status: warn) and have CSS react to the value of a custom property, in every major browser. Container style queries became Baseline on May 19, 2026, when Firefox 151 shipped them, joining Chrome and Edge 111 and Safari 18.

Size container queries got all the attention. Style queries are the quieter half of the same feature, and I think they're the more surprising one: instead of asking "how wide is my container?", a rule asks "what value does my container have for this variable?". That turns a custom property into a switch that CSS can read.

What problem it solves

Think of a status card with three states: operational, degraded, down. Each state changes the border, the glow, the icon, the badge text and the colour of a chart. The usual answer is a modifier class or a data-status attribute, plus one selector per state for every piece of the card.

With a style query, the state lives in one custom property, and every descendant can ask about it:

<div class="card" style="--status: warn">
  <span class="badge">Degraded</span>
</div>

.badge { background: rgb(0, 212, 170); }

@container style(--status: warn) {
  .badge { background: rgb(251, 191, 36); }
}

That's the whole trick in the demo above. Each card carries style="--status: ok" and the only thing the JavaScript does on click is card.style.setProperty('--status', next). The colour, the ▲/✕ icon, the badge text (via content: var(--badge)), the latency figure, the progress bar and the pulsing ring are all CSS reacting to that value. The board view uses a second variable, --view: list, on the board element, and even the highlighted line in the code panel is a style query reading --last.

What makes this different from an attribute selector is that custom properties inherit and cascade. The value can come from a parent, a theme class higher up, a media query or an inline style, and every element below it can query it without knowing where it was set.

How it works

A few rules that I checked against MDN and the spec, and then in the browser:

No container-type needed. Every element is a style container. You only need container-type for size queries.
An element queries its ancestors, not itself. The query is evaluated against an ancestor container, so in the example above .badge can react to --status, but a rule that tries to style .card itself from its own --status won't match. That's why every card in the demo has an inner .body that carries the visual styles.
Stick to custom properties. The spec also allows normal properties, as in style(color: red), but MDN's guide says custom properties are the only style feature currently supported, and that query didn't match in the Chromium I tested with.
A query without a value checks "is it set?". style(--flag) is true when the computed value differs from the initial value. For an unregistered custom property, that means any value at all.

The gotcha: plain matching compares tokens

style(--status: warn) compares the computed value of the property with the value you wrote. For an unregistered custom property, that computed value is basically the text you wrote, so --accent: #00f does not match style(--accent: blue), and --n: calc(6/2) does not match style(--n: 3). I tested both in Chromium and neither matches.

If you need equivalent values to match, register the property with a type:

@property --accent {
  syntax: "<color>";
  inherits: true;
  initial-value: black;
}

/* Now --accent: #00f matches too */
@container style(--accent: blue) {
  .icon { color: var(--accent); }
}

For keyword-like states such as ok, warn and down, plain matching is exactly what you want, and you don't need @property at all.

Browser support and other gotchas

Support: Chrome and Edge 111, Safari 18, Firefox 151. Baseline "newly available" since May 19, 2026, so check your audience before you drop a fallback.
Safari and :root: MDN's compatibility data notes that in Safari the document element can't be a container. If you set a variable on :root and query it, the children of <body> are fine, because <body> inherits the value and acts as the container. A rule that styles <body> itself from it won't match.
Feature detection: @supports can't test an at-rule like this. In the demo I use a tiny probe: a hidden element sets --sq: yes, a style query gives its child a 7 px width, and JavaScript checks the computed width. If it doesn't match, the page adds a class and falls back to data-status attribute selectors that set the same variables.
Range syntax isn't Baseline. MDN documents a newer form with comparison operators, such as style(--columns >= 3), which compares values numerically. MDN's compatibility data lists Chrome 142 and no Safari support yet, so I left it out of the demo.

What to keep an eye on

Range syntax across engines. Numeric comparisons like style(0 < --n < 10) are where style queries get really expressive. Once Safari ships them, a lot of "set a class from JavaScript when the number crosses a threshold" code can go.
Querying normal properties. style(display: flex) or style(font-weight: bold) are in the spec, but you can't count on them in every browser yet. When they arrive, components will be able to adapt to how their parent is styled, not only to variables you set on purpose.
Design systems. A single --variant or --tone variable on a component, with style queries inside it, is a clean alternative to stacks of modifier classes. I expect to see that pattern a lot more now that it works everywhere.

Sources

Originally published at richi.codes.

CSS light-dark() now swaps images, not just colors

richi.codes — Wed, 28 Oct 2026 08:30:39 +0000

This note has an interactive demo. Try it in the original

light-dark() has been swapping colors for a while. Now it swaps images too: give it two gradients, two url()s, or an image and none, and the browser picks one based on the element's color scheme. As of September 14, 2026 that works in Chrome, Edge, Firefox and Safari, which makes it Baseline newly available.

The landscape in the demo above has no image files and no theming JavaScript. The sky, the sun that turns into a moon, the stars, the clouds, the hills and the lit windows are all background-image: light-dark(day, night). The JavaScript in the demo only does two things: it changes the scene's color-scheme when you click Day or Night, and it writes the code panel.

Why this matters

Dark mode always had a gap. Colors were easy with light-dark() or custom properties, but any time an image had to change (a logo, a hero gradient, a list bullet, a decorative background) you went back to @media (prefers-color-scheme: dark) and duplicated the rule.

A media query only knows what the user picked in their system or browser. It doesn't know that one section of your page is forced to color-scheme: dark. light-dark() resolves against the color scheme of the element it's applied to, so the same rule does the right thing in a dark sidebar sitting inside a light page. The three logo tiles at the bottom of the demo share one CSS rule: one tile is color-scheme: light, one is dark, and one is light dark, which follows your system.

How it works

The spec now defines two forms. The color form you already know, and an image form where each argument is an <image> or none:

:root {
  color-scheme: light dark;
}

.hero {
  background-image: light-dark(
    linear-gradient(#38bdf8, #fde68a), /* light */
    linear-gradient(#050816, #4c1d95)  /* dark */
  );
}

The first argument is used when the element's color scheme is light. The second is used when it's dark. As MDN notes, you have to opt in with color-scheme: light dark (usually on :root). Without it, the page stays light and you always get the first image.

To force one area to a scheme, set color-scheme on that element. That's exactly what the demo's switch does:

.scene[data-scheme="light"] { color-scheme: light; }
.scene[data-scheme="dark"]  { color-scheme: dark; }

none is valid on either side. The spec defines it as a fully transparent image with no natural size, and in Chrome the computed value reads image(rgba(0, 0, 0, 0)). It's handy for layers that should only appear in one scheme, like the stars:

.stars {
  background-image: light-dark(none, radial-gradient(1px 1px at 20px 30px, #fff 50%, transparent 51%));
}

It works anywhere an image goes, not only on backgrounds. The spec's own example uses it for list bullets:

ul.fancy {
  list-style-image: light-dark(url("light.svg"), url("dark.svg"));
}

I checked all of these snippets in Chromium by reading getComputedStyle() under a light and a dark scheme. Each time the browser returned the image I expected.

The gotcha that cost me a layer

My first version of the demo had no stars. I had written this:

/* Does NOT work: three images on the dark side */
.stars {
  background-image: light-dark(none, radial-gradient(…), radial-gradient(…), radial-gradient(…));
}

Each side of light-dark() takes a single image. A comma-separated list makes the whole value invalid, and the property falls back to none. The fix is one light-dark() per layer:

.stars {
  background-image:
    light-dark(none, var(--star1)),
    light-dark(none, var(--star2)),
    light-dark(none, var(--star3));
}

With var() it's harder to spot. The browser can't reject the declaration while parsing because it doesn't know what the variables contain yet, but in my test the result was still none.

Browser support

According to MDN's browser compatibility data, the image form shipped in Chrome and Edge 150, Firefox 150 and Safari 27. The color form has been around much longer: Chrome 123, Firefox 120 and Safari 17.5. If you test only with colors in an older browser, you may wrongly assume images work as well.

The demo checks support with:

CSS.supports('background-image', 'light-dark(none, linear-gradient(red, blue))');

If that returns false, the demo shows a notice and switches to a plan B: the same gradients chosen with a data-resolved attribute. In plain CSS, the fallback can be an @supports block:

.hero { background-image: url(light.png); }

@supports (background-image: light-dark(none, none)) {
  .hero { background-image: light-dark(url(light.png), url(dark.png)); }
}

The fade you see when you switch between day and night isn't part of light-dark(). It comes from a View Transition (document.startViewTransition), and the demo skips it when prefers-reduced-motion is on.

What to keep an eye on

Older browsers in your traffic. This is newly available, not widely available. Keep a fallback for anything important, like a logo that disappears on a dark background.
Image loading. Before you swap two heavy raster images this way, check in your own DevTools Network panel what each browser downloads and when.
Where you use it. Logos, illustrations and decorative gradients are the obvious first targets. Anything that used to need a duplicated rule inside a prefers-color-scheme query is worth reviewing.

Sources

Originally published at richi.codes.

View Transitions: animate any DOM change with one call

richi.codes — Tue, 27 Oct 2026 08:30:37 +0000

This note has an interactive demo. Try it in the original

You change the DOM however you like, wrap that change in document.startViewTransition(), and the browser animates from the old state to the new one. No FLIP math, no animation library, no keeping two copies of the UI alive. Same-document view transitions have been Baseline since October 14, 2025, and the parts that make them scale (view-transition-class and transition types) joined them by January 2026.

The demo above is a bento grid where nothing is animated by hand. The grid simply gets reordered, filtered or switched to a list, and a card turns into a full panel. Turn on Slow motion to watch it, or untick View Transitions to see the same DOM changes without it.

What it is and why it matters

Animating a layout change used to mean measuring every element before and after, then faking the motion with transforms. The View Transition API flips that around. When you call startViewTransition(update), the browser takes a snapshot of the current page, runs your update callback, captures the new state, and animates between the two with a tree of pseudo-elements that sits on top of the page.

By default the whole page is one snapshot called root, and you get a cross-fade. The spec's user agent stylesheet sets it to a quarter of a second. Give an element its own view-transition-name and it gets its own group, which the browser animates from its old position and size to its new ones. That's where the "wow" comes from.

How the demo works

Everything goes through one function. This is a trimmed version of the one in the demo:

function transition(type, update) {
  if (!document.startViewTransition) {
    update(); // Plan B: same change, no animation
    return;
  }
  const vt = document.startViewTransition({ update, types: [type] });
  // If another transition replaces this one before it starts animating,
  // ready rejects with an AbortError. Handle it or the console will complain.
  vt.ready.catch(() => {});
  return vt;
}

// Shuffling is just reordering DOM nodes
const shuffled = (arr) => arr.map((el) => [Math.random(), el]).sort((a, b) => a[0] - b[0]).map(([, el]) => el);
transition('shuffle', () => grid.append(...shuffled([...grid.children])));

Each card gets a unique name and a shared class:

tile.style.viewTransitionName = `tile-${i}`;

.tile { view-transition-class: tile; }

/* Don't capture the rest of the page: the toolbar updates instantly */
:root { view-transition-name: none; }

/* One rule for all twelve cards, thanks to the class */
::view-transition-group(.tile) {
  animation-duration: .55s;
  animation-timing-function: cubic-bezier(.2, .9, .25, 1.15);
}

Without view-transition-class you'd write a rule for tile-0, another for tile-1, and so on. A class doesn't need to be unique and doesn't create a group; it's only a styling hook for elements that already have a name.

The types array is what lets one API do several choreographies. In CSS, :active-view-transition-type() matches the root element while a transition of that type is running:

:root:active-view-transition-type(filter) {
  &::view-transition-new(.tile):only-child { animation: pop-in .45s both; }
  &::view-transition-old(.tile):only-child { animation: pop-out .3s both; }
}
/* pop-in and pop-out are ordinary @keyframes (scale + opacity) */

The :only-child trick comes from the spec. When a card is filtered out it only exists in the old state, so its group has an old image and no new one. Cards that come back only have a new image. That's how the demo pops cards in and out while the rest slide into place.

The card-to-panel morph doesn't need anything new. The name moves from one element to another inside the update:

transition('open', () => {
  tile.style.viewTransitionName = 'none';
  panel.style.viewTransitionName = name; // same name, different element
  panel.hidden = false;
});

Same name in the old and new state means same group, so the browser animates the card's box into the panel's box and cross-fades the content. I also give that pair a hero class with ::view-transition-group(.hero) { z-index: 1; }. Without it, in my first version the growing panel was painted underneath the cards that come after it.

Gotchas I hit or checked

Names must be unique among rendered elements. If two rendered elements share a view-transition-name, ready rejects and the transition is skipped. In Chromium I got an InvalidStateError. Hidden elements (display: none) don't count, which is why filtering works.
Interrupting a transition. Calling startViewTransition() while another is active skips the old one with an AbortError. If that happens before it starts animating, its ready promise rejects, and with no handler Chromium logs an uncaught "Transition was skipped" error. If it happens mid-animation, ready has already resolved and finished simply resolves early. Press Shuffle twice quickly in the demo and the log shows both cases.
Clicks during the animation. The ::view-transition overlay covers the page. In Chromium, a click during the animation hit <html>, not the button underneath, until I added ::view-transition { pointer-events: none; }.
The old state is a picture. The old snapshot is a static image and the new one is live, so stretched text during a size change is normal. MDN's trick of setting height: 100% on ::view-transition-old() and ::view-transition-new() smooths over the different aspect ratios, and the demo uses it.
Reduced motion is on you. With reduced motion emulated in Chromium, the transitions still ran. The demo sets animation: none on the view transition pseudo-elements inside @media (prefers-reduced-motion: reduce), so changes apply instantly.

Browser support

According to MDN's compat data, document.startViewTransition() works in Chrome 111, Firefox 144 and Safari 18. The options object with types, and :active-view-transition-type(), arrived in Chrome 125, Firefox 147 and Safari 18.2. view-transition-class is in Chrome 125, Firefox 144 and Safari 18.2. I ran the demo in Chromium 153 and WebKitGTK 2.52 with no console errors; I couldn't run Firefox in my environment. When the method doesn't exist, the demo shows a notice and applies the same changes instantly, which is exactly how the API was designed to degrade.

What to keep an eye on

Element-scoped transitions. MDN already documents Element.startViewTransition() for running transitions inside a subtree, but ViewTransition.transitionRoot is still marked experimental and Chromium-only.
match-element. It gives every selected element an automatic unique name, so you can skip the tile-${i} step for same-document transitions. Its support is in Chrome 137, Firefox 144 and Safari 18.4.
Cross-document transitions. The @view-transition rule for multi-page sites isn't Baseline yet; web-features still lists it without Firefox support.

Sources

Originally published at richi.codes.

CSS field-sizing: inputs that grow as you type

richi.codes — Mon, 26 Oct 2026 08:30:39 +0000

This note has an interactive demo. Try it in the original

A textarea that grows as you type used to need a script that measured scrollHeight on every keystroke. Now it takes one line of CSS: field-sizing: content. With Firefox 152 shipping it on June 16, 2026, the property is Baseline, so it works in Chrome, Edge, Firefox and Safari.

Type in the demo above, or press "Type it for me": the blanks in the sentence widen with every letter, the dropdown shrinks to the option you picked, and the chat box gains a line at a time until it hits its limit. Flip the switch to fixed and you get the old behaviour back on the same markup.

What it is and why it matters

Form controls have always had a size that ignores what's inside them. An <input> is just as wide whether it holds "Al" or a full street address, a <textarea> is however many rows and cols it gets, and a <select> is as wide as its longest option. The spec calls these "elements with default preferred size".

field-sizing takes two values:

fixed: the default. The control keeps that default preferred size.
content: the browser works out the control's size from its content and ignores the default.

That's the whole API. What makes it worth knowing is how many small annoyances it removes: chat composers, comment boxes, inline "fill in the blank" forms, tag inputs, compact filters with a <select> that shouldn't reserve space for its longest option. All of that used to mean JavaScript that measured text, ran on every input event and fought with fonts that hadn't loaded yet.

How it works

This is the CSS behind the demo, trimmed to the parts that matter:

/* The technique: fields take the size of their content */
input, textarea, select {
  field-sizing: content;
}

/* Inline blanks: never narrower than 3 characters,
   never wider than their container */
.sentence input,
.sentence select {
  min-width: 3ch;
  max-width: 100%;
}

/* Chat: fixed width, the height grows up to a limit and then scrolls */
.composer textarea {
  width: 100%;
  min-height: 2.75em;
  max-height: 7.5em;
  resize: none;
}

Three behaviours are going on there:

Text inputs shrink-wrap their text. The text, email, search, tel, url, number and password types grow and shrink with the value. If there's a placeholder, the field is wide enough to show it.
A textarea grows sideways first, then down. With nothing stopping it, a textarea with field-sizing: content behaves like a single-line field. Once it can't get any wider, because it has a fixed width or hits a max-width, it starts adding lines. When it reaches max-height, a scrollbar shows up. That's why the chat in the demo has width: 100%: the width stays put and only the height changes. The spec uses exactly this case as its example.
A dropdown fits the selected option. A regular <select> changes width as you pick different options. A list box (multiple, or size above 1) shows every option instead of scrolling.

In the demo the only JavaScript that touches sizes is the ResizeObserver that prints the pixel readouts, plus the fallback I'll get to below. The growing itself is all CSS.

The gotchas

I checked each of these in Chromium with a small test page before writing them down. They match what MDN describes:

Always set a min-width. An empty input with field-sizing: content and no minimum is as wide as the text cursor. In my test it measured 9 pixels. That's why the demo uses min-width: 3ch.
size, rows and cols stop doing anything. They set the default preferred size, and content ignores that. An <input size="40"> with field-sizing: content was exactly as narrow as one without the attribute.
A fixed width and height cancel the effect. If you set both, the control has a fixed size again. Use min-* and max-* to keep it within bounds, or fix only the width, as in the chat.
maxlength also caps the size, because the field stops growing when no more characters fit.
Mind the container. In a CSS grid, an item's automatic minimum size can let a growing field push the whole card wider than the screen. That's exactly what my first version of this demo did at 375 px. grid-template-columns: minmax(0, 1fr) on the parent fixes it, and so does min-width: 0 on the item.

Browser support

According to MDN's compatibility data, Chrome and Edge 123 (March 2024) were first, followed by Safari 26.2 (December 2025) and Firefox 152 (June 2026). That makes it Baseline newly available from June 16, 2026. For the next few months, some people will still be on browsers without it.

The good news is that the fallback is free: a browser that doesn't understand field-sizing ignores the declaration and draws the form exactly as it always has. If the old size is acceptable, you don't need anything else. If it isn't, check for support and only load the old trick when the property is missing:

if (!CSS.supports('field-sizing', 'content')) {
  // Old trick: measure and set the size by hand
  textarea.addEventListener('input', () => {
    textarea.style.height = 'auto';
    textarea.style.height = textarea.scrollHeight + 'px';
  });
}

The demo does exactly that, and shows a notice when it's running on the fallback. In CSS you can use @supports (field-sizing: content) for the same check.

What to keep an eye on

The spec home has changed. field-sizing now lives in CSS Form Control Styling Level 1 (it moved there from CSS UI 4). That draft also covers appearance: base and fully styleable form controls, so expect more news in this area.
Long fields in real layouts. A field that grows changes the layout around it. In flex and grid that's fine, but a max-width is always worth having.
Removing old code. If you have a dependency or a hook whose only job is to auto-size textareas, it's a good candidate to delete once your audience is on browsers from the last few months.

Sources

Originally published at richi.codes.

CSS contrast-color(): text that picks its own color

richi.codes — Sun, 25 Oct 2026 08:30:39 +0000

This note has an interactive demo. Try it in the original

You give CSS a background color and it hands back white or black, whichever reads better on it. That's contrast-color(), and since April 2026 it works in Chrome, Firefox and Safari.

Play with the demo above for a minute. The big card has no text color set anywhere: drag the lightness slider, or hit Sweep, and watch the text flip from white to black at the point where black starts winning. The strip of twelve tiles below is the same idea at a glance: same lightness and chroma, twelve hues, and each tile flips at a different spot because yellow and blue don't have the same luminance at the "same" lightness.

What it is and why it matters

Any time a color comes from data (a tag color from a CMS, a user-picked theme, a chart series, a team's brand color) you need a text color that stays legible on top of it. Until now that meant a JavaScript helper, a Sass function at build time, or a lookup table of hand-checked pairs. contrast-color() moves that decision into the browser, at computed-value time, so it also follows custom properties, :hover states and theme switches.

There's a real example in this very repo. The active tag chip in the notes explorer on this site uses bg-richi-orange text-white, which is white on #FF5200. By the WCAG 2.1 formula that pair gives 3.25:1; black on the same orange gives 6.46:1. contrast-color(#FF5200) returns black. The demo starts on that exact orange so you can see it.

How it works

The minimal version is three lines, and it's what the demo card uses:

.badge {
  --bg: #FF5200;
  background: var(--bg);
  color: contrast-color(var(--bg));
}

The CSS Color Level 5 spec is short on purpose. The function takes one <color> and resolves to either white or black, whichever produces maximum contrast with the input used as a solid background. If both tie, it returns white. That's it: no target ratio, no list of candidates, no custom colors. The spec's changelog records that the function was simplified by a working group resolution, and a note says future versions are expected to add more control over the algorithm and the returned color.

Two details from the spec are worth knowing:

The algorithm is up to the browser. The spec says the exact contrast algorithm is UA-defined and advises browsers not to simply use the WCAG 2.1 contrast ratio, because of its known issues. It does require that the result still meets WCAG 2.1 AA for large text (3:1).
It decides; it doesn't guarantee. It picks the better of two options. It can't make a bad background good.

Out of curiosity I checked whether today's engines follow WCAG anyway. In Chromium 153 and in WebKitGTK 2.52, I compared contrast-color() against the WCAG 2.1 "pick the higher ratio" rule on 2,000 random sRGB colors, and the picks matched every time in both. That's a test, not a promise: the spec allows it to change.

The mid-tone trap

Here's the catch MDN warns about: on mid-tones, neither white nor black is great. MDN's own example is #2277d3, a royal blue that gets black text. By the WCAG formula that's 4.65:1 for black and 4.52:1 for white: both technically pass AA for normal text, both are uncomfortable for small type.

There's a hard floor here too. Doing the math with the WCAG luminance formula, the best of black or white can never drop below √21 ≈ 4.58:1. So contrast-color() will never fail AA outright, but on mid-tones it will hover right on that line. The demo shows both ratios live and tells you when you're above 7:1 (AAA) or only just in AA territory. The fix is still a design one: push the background lighter or darker.

Support, fallbacks and one gotcha

Support according to MDN's browser compat data: Chrome 147, Firefox 146 and Safari 26. web-features marks it Baseline newly available since April 10, 2026. I ran the demo in Chromium 153 and WebKitGTK 2.52; I couldn't run Firefox in my environment.

For older browsers, the classic "declare a fallback first" trick has a trap when you use a custom property. This doesn't work the way you'd expect:

.badge {
  color: black;
  color: contrast-color(var(--bg)); /* parses fine because of var() */
}

Because the value contains var(), the browser accepts the second declaration at parse time without checking the function. If it then can't resolve contrast-color(), the property becomes invalid at computed-value time and falls back to the inherited color, not to your black. I tested this in Chromium with a made-up function name and that's exactly what happens. Use @supports instead:

.badge { color: black; }

@supports (color: contrast-color(red)) {
  .badge { color: contrast-color(var(--bg)); }
}

And if you need the same decision in JavaScript (the demo does this as plan B when CSS.supports('color', 'contrast-color(red)') is false), the WCAG 2.1 version is short:

const lin = (v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);

function luminance(hex) {
  const [r, g, b] = [1, 3, 5].map((i) => lin(parseInt(hex.slice(i, i + 2), 16) / 255));
  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}

function contrastRatio(a, b) {
  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
  return (hi + 0.05) / (lo + 0.05);
}

// Same rule as contrast-color(): the one with more contrast wins, ties go to white
function pickTextColor(bg) {
  return contrastRatio(bg, '#000000') > contrastRatio(bg, '#ffffff') ? 'black' : 'white';
}

pickTextColor('#FF5200'); // "black"

What to keep an eye on

The next level of the function. The spec already says more control over the algorithm and the returned colors is expected. If you need brand colors instead of pure black and white, that's where it would show up.
The algorithm itself. Since it's UA-defined and the spec discourages plain WCAG 2.1, a browser could switch to a perceptual model. Mid-tone backgrounds are where you'd notice.
Your own audits. Automated checkers compute WCAG 2.1 ratios. If a browser ever picks differently from WCAG on a mid-tone, the checker and the screen could disagree.

Sources

Originally published at richi.codes.

llms.txt v2: what an agent actually reads

richi.codes — Sat, 24 Oct 2026 07:30:39 +0000

This note has an interactive demo. Try it in the original

The llms.txt proposal got its first big revision in August 2026, and the changes answer the obvious question nobody could answer before: given a page, how does an agent find the llms.txt that describes it? I read the new text, ran this site's own /llms.txt through the small reference parser that lives in the proposal's repository, and it crashed. The demo above shows both things: what a parser really gets out of the file, and how an agent walks from a page to its llms.txt and its Markdown version.

What llms.txt is, in one paragraph

It's a Markdown file that gives agents a curated entry point into a site: a name, a short summary, some context and lists of links to LLM-friendly content. Jeremy Howard published the original in September 2024. It's still a proposal "open for community input", not a W3C or IETF standard. The text is clear about what it's for: robots.txt says what automated access is acceptable, while llms.txt "is instead used on demand, when an agent needs information about a topic while assisting a user". It's meant for inference, not training.

What changed in v2

The Changes page lists four things:

Any path, most specific wins. A file at /docs/llms.txt covers everything under /docs/, and "where more than one file applies, agents should use the most specific one". This is what lets a GitHub Pages project site, which can't touch the host root, take part.
Two Markdown URL forms. v1 only had .md appended (page.html.md). v2 also allows replacing the extension (page.md). URLs without a file name use index.html.md or index.md.
Discovery through link relations. rel="alternate" type="text/markdown" points to a page's Markdown version and rel="describedby" points to the llms.txt that covers it, either as <link> elements or as an HTTP header.
## Optional lost its special meaning. The context-expansion tool from v1 is no longer part of the proposal, so Optional is now just a convention for secondary links.

The header form is the interesting one, because you can add it in your server or CDN config without touching a single page, and it also works on non-HTML files. This is the proposal's own example:

Link: </docs/page.html.md>; rel="alternate"; type="text/markdown", </docs/llms.txt>; rel="describedby"

And the equivalent in the page's <head>:

<link rel="alternate" type="text/markdown" href="/docs/page.html.md">
<link rel="describedby" href="/docs/llms.txt">

The "How it gets found" tab in the demo builds that header for each page of a small example site. These are the two functions behind it, which I ran in Node with the outputs shown:

// The llms.txt files that cover a path, most specific first.
function coveringLlms(path, files) {
  return files
    .filter(f => path.startsWith(f.slice(0, f.lastIndexOf('/') + 1)))
    .sort((a, b) => b.length - a.length);
}

// page.html -> page.html.md ('append') or page.md ('replace').
function markdownUrl(path, mode) {
  if (path.endsWith('/')) return path + (mode === 'append' ? 'index.html.md' : 'index.md');
  return mode === 'append' ? path + '.md' : path.replace(/\.[^./]+$/, '') + '.md';
}

const files = ['/llms.txt', '/docs/llms.txt'];
coveringLlms('/docs/api/fetch.html', files); // ['/docs/llms.txt', '/llms.txt']
markdownUrl('/docs/api/fetch.html', 'replace'); // '/docs/api/fetch.md'
markdownUrl('/docs/', 'append');                // '/docs/index.html.md'

Untick "/docs/llms.txt exists" and the docs pages fall back to the root file.

The format is stricter than it looks

The proposal says the file is "in a precise format allowing fixed processing methods (i.e. classical programming techniques such as parsers and regex)". In order: an H1 with the name (the only required part), a blockquote with a short summary, zero or more paragraphs or lists with no headings, then H2 sections whose lists hold [name](url) links, optionally followed by : and notes.

The repository still ships a parser of about twenty lines, llms_txt/miniparse.py, and the demo's first tab is a line-for-line JavaScript port of it. I ran both on the same seven files, this site's llms.txt and the proposal's own included, and they return the same result in every case. Here is what I found by feeding it real input:

from miniparse import parse_llms_txt

parse_llms_txt("# My site\n\n> What it is.\n\nOne line of details.\n\n## Docs\n\n- [Guide](https://example.com/guide.md): start here\n")
# {'title': 'My site', 'summary': 'What it is.', 'info': 'One line of details.',
#  'sections': {'Docs': [{'title': 'Guide', 'url': 'https://example.com/guide.md', 'desc': 'start here'}]}}

Every non-empty line in a section must contain a [name](url) link. A line like - GitHub: https://github.com/me raises AttributeError. So does a long list item wrapped onto a second, indented line, because the parser splits sections line by line. This site's /llms.txt does both, which is why the "richi.codes today" example opens in red.
Only the first line of the summary counts. A blockquote spread over several > lines keeps its first line as the summary and dumps the rest into the details.
The summary needs details after it. With nothing between the blockquote and the first ##, the summary comes back as None and the blockquote ends up in info. With only an H1 before the first ##, the parser raises AttributeError. Even the llms.txt in the proposal's own repository comes back with summary: None for this reason.
### also splits. The pattern is ^##, so ### Getting started becomes a section called # Getting started. The spec doesn't allow headings before the first H2 anyway.

An agent reading the file as plain Markdown won't care about any of this. But if a tool parses llms.txt the way the proposal invites it to, these details decide whether your links survive. The "richi.codes fixed" example shows the cheap fix: one line per link, real Markdown links, and a short paragraph after the summary.

What to keep an eye on

Who actually consumes it. The proposal lists documentation platforms that generate the file and says the AI labs publish llms.txt files for their own developer docs. Publishing a file isn't the same as reading one, so check what the agents you care about document before treating llms.txt as a ranking factor.
The Link header. It's the cheapest v2 change to adopt: one line of server config, and agents can go from any page to its Markdown version and its llms.txt.
This site's file. The demo makes it obvious that /llms.txt here has plain-URL list items and wrapped lines. That's worth fixing.

Sources

Originally published at richi.codes.

CSS shape(): responsive shapes without SVG

richi.codes — Fri, 23 Oct 2026 07:30:40 +0000

This note has an interactive demo. Try it in the original

You can now draw a star, a blob or a speech bubble in clip-path with percentages, px, calc() and custom properties, and morph between shapes with a single transition: the CSS shape() function has been Baseline since February 2026.

For years, any clip-path more interesting than circle() or polygon() meant path(), and path() takes an SVG path string where every number is a pixel. That's fine for a fixed-size icon, but it breaks the moment the element resizes: the shape doesn't scale, and you end up recalculating the string in JavaScript. shape() uses the same drawing model as SVG paths, but written in CSS syntax, so each coordinate can be whatever CSS value makes sense.

What shape() is

shape() is a <basic-shape> function, and MDN lists it for clip-path, offset-path and the newer border-shape. It takes a starting point and a comma-separated list of commands:

.triangle {
  clip-path: shape(from 0% 0%, line to 100% 0%, line to 50% 100%, close);
}

The commands mirror SVG path commands, with words instead of letters:

move, line, hline and vline for jumps and straight lines.
curve ... with ... for Bézier curves: one control point gives a quadratic curve, two (separated by /) a cubic one.
smooth for a curve that continues the previous one, arc for elliptical arcs, and close to go back to the start.
to means coordinates measured from the top-left corner of the reference box; by means relative to where the previous command ended.

Percentages are relative to the width and height of the reference box. And according to MDN, this is the real difference from path(): path() is a single string limited to px, while shape() accepts percentages, rem, em and math functions such as calc(), max() or abs().

Mixing units: the responsive bubble

The second tab in the demo above is a speech bubble. The trick is deciding what scales and what doesn't: the corners and the tail are fixed in px, while the box and the tail's position are percentages. Because shape() is just CSS, the values come straight from custom properties:

.bubble {
  --r: 18px; --arrow: 30%; --tail: 16px;
  clip-path: shape(from var(--r) 0,
    hline to calc(100% - var(--r)),
    curve to 100% var(--r) with 100% 0,
    vline to calc(100% - var(--tail) - var(--r)),
    curve to calc(100% - var(--r)) calc(100% - var(--tail)) with 100% calc(100% - var(--tail)),
    hline to calc(var(--arrow) + var(--tail)),
    line to var(--arrow) 100%,
    line to calc(var(--arrow) - var(--tail)) calc(100% - var(--tail)),
    hline to var(--r),
    curve to 0 calc(100% - var(--tail) - var(--r)) with 0 calc(100% - var(--tail)),
    vline to var(--r),
    curve to var(--r) 0 with 0 0,
    close);
}

Read it as a walk around the edge: top edge, a quadratic curve for the top-right corner (the control point is the corner itself), down the right side, the bottom-right corner, along the bottom to the tail, down to the tip at 100% and back up, and the same on the left. Drag the width slider in the demo and the corners stay round instead of turning into ellipses, because their radius is in px. The spec itself uses a speech bubble like this one to explain why mixing units matters.

The sliders don't rebuild the string: they only change --r, --arrow and --tail with style.setProperty(). The browser redraws the shape.

Morphing for free

The first tab is the part that catches the eye. The specification says that two shape() values (or a shape() and a path()) can be interpolated if their command lists are the same length and have the same commands in order. A command counts as "the same" if it uses the same keyword and the same by/to, and for curve and smooth the same number of control points.

So if you design every shape with the same skeleton, a transition does the morph:

.badge {
  clip-path: shape(from 0% 0%, line to 100% 0%, line to 100% 100%, line to 0% 100%, close);
  transition: clip-path .6s ease;
}
.badge:hover {
  clip-path: shape(from 50% 0%, line to 100% 50%, line to 50% 100%, line to 0% 50%, close);
}

In the demo, the circle, the star, the flower and the random blob are all twelve curve to X Y with CX CY commands generated from polar coordinates. The star simply puts each control point halfway along the segment, so the curve looks straight. Since the skeleton never changes, any shape morphs into any other.

I checked the flip side in Chromium too: if I replace one of the line commands in the hover state with a curve, the transition stops interpolating and the shape jumps straight to the final value.

Support and gotchas

According to MDN's compatibility data, shape() is supported in Chrome and Edge 135, Firefox 148 and Safari 18.4. It became Baseline newly available on 24 February 2026, so it's not yet "widely available". For older browsers, feature detection is straightforward:

@supports not (clip-path: shape(from 0 0, line to 100% 0, line to 0 100%, close)) {
  .badge { clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%); }
}

The demo uses the same check in JavaScript with CSS.supports(). If it fails, it falls back to path() with pixel values computed from the element's size and recalculated with a ResizeObserver. That's exactly the work shape() saves you. You can see the fallback by adding ?fallback to the demo's URL.

Things to keep in mind:

clip-path only clips. Shadows and borders are clipped too, so the glow in the demo is a filter: drop-shadow() on the parent, which follows the clipped shape.
Computed values keep the units you wrote: getComputedStyle() returns something like shape(from 0px 0px, hline to calc(100% - 20px), ...), which helps when you're debugging.

What to keep an eye on

border-shape: it accepts shape() too, but in MDN's compatibility data it only appears in Chrome 147. It's the piece that would let you shape the border as well, not just clip the element.
Relative control points: the spec defines from start, from end and from origin for control points. MDN's examples use them behind their own @supports check, so test them in every browser before relying on them.
Converting existing paths: if you already have an SVG d string, the translation to shape() is mechanical (M → from/move, L → line, Q/C → curve, Z → close), and that's when you can swap pixels for percentages.

Sources

Originally published at richi.codes.

CSS Custom Highlight API: style text without spans

richi.codes — Thu, 22 Oct 2026 07:30:40 +0000

This note has an interactive demo. Try it in the original

You can paint any piece of text on a page without wrapping it in a <span> or a <mark>: the CSS Custom Highlight API has been Baseline since March 2026, when Firefox 149 shipped the last missing piece, the ::highlight() pseudo-element.

Type something in the demo above. Every match turns orange, but keep an eye on the middle counter: the number of DOM nodes inside the text doesn't move. Start the read-along or flag the typos and it still doesn't move. In a browser without the API, the demo falls back to real <mark> elements and you can watch that counter grow and turn orange.

Why this matters

The classic way to highlight search results is to rewrite the HTML: split text nodes, wrap the matches in elements, and undo it all on the next keystroke. It means extra elements in the DOM on every keystroke, and it gets messy fast when two highlights need to overlap.

MDN describes the API as a way to style arbitrary text ranges by "using JavaScript to create the ranges, and CSS to style them". It extends the idea behind the highlight pseudo-elements the browser already had (::selection, ::spelling-error, ::grammar-error, ::target-text) to ranges you define yourself. Typical uses: search in page, spell and grammar checkers, code editors, collaborative editors with one colour per user.

How it works

Four steps: create Range objects, group them in a Highlight, register it by name in CSS.highlights, and style that name with ::highlight().

const p = document.querySelector('p');
const text = p.firstChild; // a text node

// 1. A Range for every match
const ranges = [];
let i = text.textContent.indexOf('ranges');
while (i !== -1) {
  const range = new Range();
  range.setStart(text, i);
  range.setEnd(text, i + 'ranges'.length);
  ranges.push(range);
  i = text.textContent.indexOf('ranges', i + 1);
}

// 2 and 3. One Highlight holds them all; the registry gives it a name
CSS.highlights.set('search', new Highlight(...ranges));

/* 4. Only the name is shared between JS and CSS */
::highlight(search) {
  background-color: #FF5200;
  color: white;
}

That's the whole trick in the demo's search box: on each input event it walks the text nodes with a TreeWalker, builds the ranges and calls CSS.highlights.set() again. CSS.highlights is a Map-like registry, so delete(name) and clear() remove highlights, and a Highlight is Set-like, with add(), delete() and size.

The read-along button uses the same idea with a single range that moves to the next word every 280 ms. The typos button registers a third highlight and sets its type:

const typos = new Highlight(...typoRanges);
typos.type = 'spelling-error'; // default is 'highlight'; 'grammar-error' also exists
CSS.highlights.set('typo', typos);

According to MDN, type lets assistive technologies include that meaning when they expose the highlight, although support "may vary across platforms".

When highlights overlap

In the demo the search can overlap the read-along word. Which colour wins is not decided by CSS order or !important: it's decided by Highlight.priority. With equal priorities, the most recently registered highlight wins for the conflicting properties. The demo gives the search priority = 1, so orange stays on top. Properties that don't conflict are all applied.

What you can style

::highlight() only accepts a short list of properties: color, background-color, text-decoration and its longhands, text-shadow, and -webkit-text-stroke-color, -webkit-text-fill-color and -webkit-text-stroke-width. background-image is ignored, so no gradients. The wavy red underline in the demo is plain text-decoration: underline wavy.

Browser support and gotchas

Support: Chrome and Edge 105, Safari 17.2, Firefox 149 for the full feature. Firefox had the JavaScript side (Highlight, CSS.highlights) from 140, but ::highlight() couldn't use text-decoration before 146 or text-shadow before 149.
Detect it: 'highlights' in CSS is the basic check. The demo checks that and typeof Highlight === 'function', shows a warning and falls back to <mark> elements.
Safari and user-select: none: browser-compat-data notes that in Safari the highlight style is ignored when combined with user-select: none (WebKit bug 278455). Don't put highlights on text you've made unselectable.
No semantics by default: MDN is clear that custom highlights don't add semantic meaning to the document; type only covers spelling and grammar errors, and support for it varies. If the highlight carries meaning a screen reader user needs, MDN suggests semantic HTML such as <mark> or another accessible cue.
Ranges point at text nodes. If your framework re-renders and replaces those nodes, recompute the ranges. The demo's fallback does exactly that after each reset.

What to keep an eye on

Older Firefox: until your audience is on 149+, test text-shadow and text-decoration there, or stick to color and background-color.
Accessibility: use type where it fits, and don't rely on colour alone for meaning.
Editors and search: in-page search, spell checking and collaborative cursors are the obvious places where this replaces a lot of DOM juggling.

Sources

Originally published at richi.codes.

CSS progress(): one number drives the whole layout

richi.codes — Wed, 21 Oct 2026 07:30:39 +0000

This note has an interactive demo. Try it in the original

CSS can now tell you how far along a value is between two others, as a plain number from 0 to 1. That's the progress() function, and since 1 September 2026 it's Baseline newly available: Chrome and Edge 138, Safari 26 and Firefox 155 all ship it.

It sounds modest. In practice it's the missing piece for fluid components: you compute one ratio from, say, the width of a container, and then every property that should "grow with the space" reads from that same number. Drag the card in the demo above and watch the cover, the corners, the gradient, the shadow, the equaliser bars and the extra text all move together. The only JavaScript in it changes the width of the box and prints the value; the morphing is pure CSS.

What progress() returns

The definition in CSS Values and Units Level 5 is short. progress() takes three calculations — the progress value, a start and an end — and returns:

(progress value - start) / (end - start)

clamped to the [0, 1] range. So progress(5, 0, 10) is 0.5, progress(15, 0, 10) is 1 and progress(-5, 0, 10) is 0.

The three arguments can be numbers, dimensions or percentages, and they can even mix units, as long as they're the same type. progress(3em, 0px, 100px) is fine (all lengths, with 3em resolved to its computed size); progress(3s, 0px, 100px) is invalid. Whatever goes in, what comes out is a unitless <number>, which is exactly what you want to multiply other values by.

If you've written fluid sizes with clamp() and a slope you worked out on paper, this is the same idea with the maths moved into the browser. The spec itself notes that progress() is essentially syntactic sugar for a particular calc() pattern — but it's sugar that makes the intent readable.

The pattern from the demo

Here's the core of the demo's CSS, trimmed down:

@property --p {
  syntax: "<number>";
  inherits: true;
  initial-value: 0;
}

.stage { container-type: inline-size; }

.player {
  /* 0 when the container is 220px wide, 1 at 640px */
  --p: progress(100cqi, 220px, 640px);

  gap: calc(10px + 18px * var(--p));
  padding: calc(10px + 18px * var(--p));
  border-radius: calc(36px - 14px * var(--p));
}

.cover { width: calc(52px + 110px * var(--p)); }

/* progress() of progress(): only shows up in the last stretch */
.extra {
  --reveal: progress(var(--p), .55, .9);
  opacity: var(--reveal);
}

/* each bar fills over its own slice of --p */
.eq i {
  --start: calc(var(--i) * .06);
  height: calc(12% + 88% * progress(var(--p), var(--start), calc(var(--start) + .35)));
}

A few things are going on:

100cqi is the input. .stage is a size container, so 100cqi inside .player is the stage's full inline size. progress(100cqi, 220px, 640px) turns that width into a ratio. Swap 100cqi for 100vw and the same component follows the viewport instead.
Everything else is start + range * var(--p). Padding, gap, radius and cover size are all linear interpolations off one number. In the full demo the background also uses color-mix(in oklch, var(--teal) calc(100% - var(--p) * 100%), var(--orange)), so the colour shifts from teal to orange as the card grows.
progress() can take --p as its own input. progress(var(--p), .55, .9) remaps the 0.55–0.9 stretch of --p to a fresh 0–1, so the extra line fades in late instead of all at once. Giving each bar a slightly later --start turns the same trick into a staggered reveal.

I checked these numbers in Chromium 141: with the stage at 430px, --p computes to 0.5, the cover to 107px and the radius to 29px, which is what the formula predicts.

Why the @property matters

You could write --p: progress(...) without registering it, and in a flat component it would mostly work. But an unregistered custom property is just a stream of tokens: var(--p) pastes progress(100cqi, 220px, 640px) into every place that uses it, and 100cqi is then resolved against that element's nearest container.

I tested it with a nested container 100px wide: the unregistered version gave 0 there (100px is below the 220px start), while the version registered as <number> kept the 0.5 computed on .player. Registering --p with @property makes the browser compute the number once, on the element that declares it, and pass that number down. It's also what lets the demo read --p with getComputedStyle() and show it.

Support and gotchas

Baseline newly available, not widely available. It works in current versions of all major engines, but older browsers don't understand it: a regular property that uses progress() is thrown away at parse time, and a registered --p ends up with its initial-value (or whatever an ancestor sets). The demo checks CSS.supports('width', 'calc(progress(1, 0, 2) * 1px)') and, if that fails, computes the same ratio in JavaScript and writes it to --p. If you'd rather avoid JS, choose an initial-value that looks fine on its own and treat the fluid behaviour as an enhancement.
no-clamp isn't there yet. The spec allows progress(no-clamp 15, 0, 10) to return 1.5, but according to MDN's compatibility data only Firefox 155 supports the keyword (Safari has it in Technology Preview). Chromium 141, which I tested with, rejects it in CSS.supports(). For now, assume the result is always clamped.
Types have to match. Mixing a time and a length, or a length and a plain number (progress(3em, 0, 100)), makes the function invalid.
Start equal to end. The spec defines the clamped result as 0 in that case, so a container query where both bounds collapse won't blow up, but it won't animate either.
Discrete changes are still a job for queries. progress() interpolates; it doesn't switch layouts. Changing from a column to a row is still a container query. The two combine well: queries for the jumps, progress() for everything in between.

What to keep an eye on

no-clamp reaching Chromium and stable Safari, which would make it practical to extrapolate past the bounds.
The spec still has open questions on progress(), including whether it should clamp to 0–100% (issue 11825). Earlier drafts had media-progress() and container-progress(); they were dropped in favour of using units like vw or cqi directly inside progress(), which is the approach the demo uses.
The rest of CSS Values 5: the spec describes progress() as an input for other calculations, including the *-mix() notations defined in the same draft.

Sources

Originally published at richi.codes.

Say no to AI training, not to AI search: robots.txt per bot

richi.codes — Tue, 20 Oct 2026 07:30:40 +0000

This note has an interactive demo. Try it in the original

"Block the AI bots" sounds like one switch, but it isn't. Anthropic uses three different crawlers, one for training, one for search and one for requests a person makes in Claude, and robots.txt can treat each one differently. That means you can keep your content out of training without disappearing from the answers. There's one rule in how robots.txt groups work that can quietly undo the whole setup, and the demo above opens right on it.

Three bots, three jobs

Anthropic's help article on crawling lists them with what happens when you disable each one:

ClaudeBot collects web content that could contribute to training. Restricting it "signals that the site's future materials should be excluded from our AI model training datasets".
Claude-SearchBot analyses content to improve search results. Blocking it "prevents our system from indexing your content for search optimization", which may reduce your visibility in user search results.
Claude-User fetches pages when someone asks Claude something. Blocking it prevents Claude from retrieving your content in response to a user query.

So if what you want is "don't train on my site, but do cite it", the file is short:

# Training: no. Search and user requests: yes.
User-agent: ClaudeBot
Disallow: /

User-agent: *
Disallow: /private/

That's the "No training, yes search" example in the demo. ClaudeBot has its own group and gets nothing. Claude-SearchBot and Claude-User aren't named, so they fall back to the * group and can read everything except /private/.

The same article has a few practical notes. The file has to go in the top-level directory of every subdomain you want to opt out. Blocking Anthropic's IP addresses instead "may not work correctly or persistently guarantee an opt-out", because it stops them from reading your robots.txt. They also support the non-standard Crawl-delay directive.

The trap: naming a bot makes it forget `*`

Now suppose you want Claude-SearchBot to focus on your blog and you add a small group for it. That's the "The * trap" example:

User-agent: *
Disallow: /private/

User-agent: ClaudeBot
Disallow: /

# Looks harmless...
User-agent: Claude-SearchBot
Allow: /blog/

Look at the /private/x column in the demo. Claude-SearchBot is now allowed there, and the cell gets an orange * badge. The reason is that a crawler follows one group only: the one that names it. If such a group exists, the * group is ignored completely, not merged in. Its only rule says Allow: /blog/, nothing in it matches /private/x, and a path that no rule matches is allowed.

This isn't a quirk of my demo. Google's open-source robots.txt parser, which its README describes as the production code Googlebot uses, has a test for exactly this: with Disallow: /x/ under * and Disallow: /y/ under FooBot, FooBot is allowed into /x/page. In the code, once a group for the agent has been seen, the matcher never looks at the global rules again.

The fix is boring: repeat in each named group the * rules that should still apply ("Trap fixed" in the demo).

User-agent: Claude-SearchBot
Allow: /blog/
Disallow: /private/

How a rule wins

Inside a group, order doesn't matter. Every Allow and Disallow whose pattern matches the path is a candidate, and the longest pattern wins. If an Allow and a Disallow are the same length, Allow wins. Patterns are anchored at the start of the path, * matches any sequence of characters, and $ only means "end of the URL" when it's the last character.

This is the matching function the demo uses, ported line by line from Google's robots.cc. It keeps a list of positions in the path that can still match the pattern read so far:

function rtMatches(path, pattern) {
  const n = path.length; let pos = [0];
  for (let k = 0; k < pattern.length; k++) {
    const c = pattern[k];
    if (c === '$' && k === pattern.length - 1) return pos[pos.length - 1] === n;
    if (c === '*') { const from = pos[0]; pos = []; for (let i = from; i <= n; i++) pos.push(i); }
    else { pos = pos.filter(p => p < n && path[p] === c).map(p => p + 1); if (!pos.length) return false; }
  }
  return true;
}

rtMatches('/fish.html', '/fish');  // true: rules are prefixes
rtMatches('/catfish', '/fish');    // false: anchored at the start
rtMatches('/x/y.html', '/*.html'); // true
rtMatches('/foo/bar/', '/foo/bar$'); // false: $ ends the URL

A rule's priority is simply the length of its pattern. To check that the port behaves like the original, I translated the assertions from the upstream test file (robots_test.cc, which says it tests against RFC 9309) to JavaScript: 151 checks on groups, case, longest match, encoding and special characters, plus the URL and escaping helpers. They all pass against the code shipped in the demo.

Gotchas

The user-agent token is case-insensitive, the path isn't. User-agent: claudebot applies to ClaudeBot, but Disallow: /Private/ doesn't block /private/.
Only letters, - and _ count in the token. Google's parser stops at anything else, so User-agent: Foo Bar is read as Foo. The demo's last row lets you type a token and flags invalid ones like Googlebot/2.1.
Several User-agent lines in a row share one group. That's the tidy way to give Claude-SearchBot and Claude-User the same rules.
An empty Disallow: allows everything for that group, and it still counts as a named group, so the * rules are still ignored.
robots.txt is a request, not a lock. It works when the crawler honours it, which Anthropic says its bots do. It doesn't protect private content.

What to keep an eye on

Your own named groups. Every time someone adds a User-agent: block for a specific bot, check which * rules it just dropped. The demo is a quick way to see it.
New tokens. Vendors split and rename crawlers. Read their own documentation for the exact names rather than copying a list from someone else's robots.txt.
This site. richi.codes currently has a single User-agent: * group with Allow: / (the "richi.codes today" example), so every bot that respects the file can read everything.

Sources

Originally published at richi.codes.

CSS can count now: sibling-index() and sibling-count()

richi.codes — Mon, 19 Oct 2026 07:30:40 +0000

This note has an interactive demo. Try it in the original

CSS can now tell an element where it sits among its siblings and how many siblings there are, as plain numbers you can use in calc(). sibling-index() and sibling-count() became Baseline Newly available on 18 August 2026, when Firefox 154 shipped them.

That sounds small until you remember the workarounds. A staggered entrance meant one :nth-child() rule per item, or JavaScript that wrote style="--i: 3" on every element and rewrote it whenever the list changed. A circular menu meant calculating angles in a script. Now the stylesheet can do it, and it stays correct when items are added or removed.

What they return

From the CSS Values and Units Level 5 spec:

sibling-index() is the element's position among its siblings, as an <integer>. Like :nth-child(), it starts at 1.
sibling-count() is the total number of child elements of the parent, including the element itself.

Neither takes arguments. They count elements only, so text nodes and comments between items don't change the numbers. MDN also points out the difference from counter(): a counter gives you a string you can only print with content, while these return integers you can do maths with.

The minimal version

This is the classic stagger. Each item waits a little longer than the one before it:

li {
  animation: fade-in 0.4s backwards;
  animation-delay: calc(sibling-index() * 60ms);
}

@keyframes fade-in {
  from { opacity: 0; translate: 0 8px; }
}

There's no class per item and no script. If you insert an element in the middle, everything after it moves up one position on its own.

sibling-count() comes in when the layout depends on the total. To spread items around a circle, each one takes its share of 360 degrees:

li {
  --a: calc(360deg / sibling-count() * (sibling-index() - 1));
  transform: rotate(var(--a)) translateY(-128px) rotate(calc(-1 * var(--a)));
}

The first rotate() turns the element towards its slot, translateY() pushes it out to the radius, and the second rotate() turns it back so the label stays upright. That's the "Ring" layout in the demo above. Remove a ball and the remaining ones get a new index and a new angle, and the transition on transform animates them into place.

The other two layouts use the same idea. "Fan" centres the indices around zero with var(--i) - (var(--n) + 1) / 2 and multiplies by a small angle. "Sunflower" rotates every item by the golden angle (137.5°) times its index and pushes it out by sqrt(index / count), which gives that seed-head spiral. The panel under the demo shows the CSS for whichever layout is active.

The gotcha: custom properties and children

Writing --i: sibling-index() is handy, but an ordinary custom property doesn't store the number. It stores the tokens sibling-index(), and those get evaluated wherever you use var(--i). If a child of the <li> reads var(--i), it gets the child's own index, not the <li>'s. I checked this in Chromium: a <span> that was the second child inside the first <li> got 2, not 1.

The fix is to register the property as an integer. It then resolves on the element where you declare it, and children inherit the number:

@property --i { syntax: "<integer>"; inherits: true; initial-value: 1; }
@property --n { syntax: "<integer>"; inherits: true; initial-value: 1; }

li { --i: sibling-index(); --n: sibling-count(); }
li > button { counter-reset: idx var(--i); }
li > button::before { content: counter(idx); }

That's how the demo prints each ball's number: the integer becomes a counter, and the counter becomes text. Pseudo-elements are less of a worry: according to the spec, on ::before and friends these functions resolve against the originating element anyway.

Browser support and fallback

According to MDN's compatibility data, support starts at Chrome and Edge 138, Safari 26.2 and Firefox 154. That's recent, so a fallback still makes sense for a while.

Feature detection is one line, and the old approach of writing the numbers from JavaScript works as the plan B:

if (!CSS.supports('width', 'calc(1px * sibling-index())')) {
  const items = list.children;
  for (let k = 0; k < items.length; k++) {
    items[k].style.setProperty('--i', k + 1);
    items[k].style.setProperty('--n', items.length);
  }
}

The demo does exactly that and shows a notice when it does. Because the rest of the CSS only reads var(--i) and var(--n), nothing else has to change. Inline styles beat the sibling-index() declaration in the stylesheet, so the JavaScript numbers win when they're present.

Two more things from the spec worth knowing:

These functions work on the DOM tree, not the flattened tree, just like :nth-child(). Slotted content is counted by its position in the light DOM.
If a rule tries to count elements inside a shadow tree from outside, for example through ::part(), the function returns 0. That's deliberate, so shadow DOM structure doesn't leak out.

What to keep an eye on

Wider support. Baseline Newly available means current versions of every major browser support them. Users on older versions still need the fallback until the feature becomes Widely available, which is 30 months after the newly available date.
Fewer :nth-child() ladders. Long lists of :nth-child(1), :nth-child(2)… rules in design systems are the obvious thing to replace.
Pairing with @property. If you plan to reuse the index in child elements, register the custom property from the start. It avoids the most confusing bug these functions can cause.

Sources

Originally published at richi.codes.

Invoker Commands API: Declarative UI Control

richi.codes — Sun, 18 Oct 2026 07:30:39 +0000

This note has an interactive demo. Try it in the original

Opening a modal or a popover from a button no longer needs a single line of JavaScript: the Invoker Commands API has been Baseline since December 2025. This API provides a declarative way to control interactive elements with buttons, reducing JavaScript boilerplate for common UI patterns like dialogs and popovers.

Historically, if you wanted a button to open a modal dialog or toggle a popover, you'd reach for JavaScript. You'd grab the button, add an event listener, find the target element, and then call its showModal() or togglePopover() method. It worked, but it meant waiting for your JavaScript to download and execute, and it added to your bundle size. The web platform is now giving us a more declarative way to handle this, moving that responsibility back to the browser.

What are Invoker Commands?

The Invoker Commands API introduces two new HTML attributes, commandfor and command, that you apply directly to a <button> element. These attributes allow a button to control other interactive elements on the page without needing any JavaScript. This means improved initial page interactivity, as the user does not have to wait for JavaScript to download and execute to make these buttons interactive.

Think of it like this:

commandfor: This attribute turns your <button> into a "command invoker" and tells the browser which element it should control. Its value is the id of the target element.
command: This attribute specifies what action the button should perform on the commandfor element.

This declarative approach can complement and in many cases, replace older methods like popovertargetaction and popovertarget, offering a unified and more powerful way to manage button interactions.

Practical Mini Build: Open Dialogs and Popovers

Let's build a simple HTML file that demonstrates how to open both a popover and a modal dialog using only these new attributes.

Step-by-Step Implementation

Create your HTML structure: We'll need buttons, a <dialog> element, and a <div> element with the popover attribute.
Link buttons to targets: Use commandfor to point to the id of your target element.
Specify actions: Use command with the appropriate built-in values for popovers and dialogs.

Here's the complete working code for a single index.html file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Invoker Commands: Dialogs & Popovers</title>
    <style>
        body {
            font-family: sans-serif;
            margin: 2rem;
            display: flex;
            flex-direction: column;
            gap: 1rem;
            align-items: flex-start;
        }

        dialog {
            border: 1px solid #ccc;
            padding: 2rem;
            border-radius: 8px;
            box-shadow: 0 4px 8px rgba(0,0,0,0.1);
            background-color: white;
        }

        dialog::backdrop {
            background: rgba(0, 0, 0, 0.5);
            backdrop-filter: blur(5px);
        }

        [popover] {
            border: 1px solid #ddd;
            padding: 1rem;
            border-radius: 4px;
            box-shadow: 0 2px 4px rgba(0,0,0,0.05);
            background-color: #f9f9f9;
        }

    </style>
</head>
<body>

    <h1>Invoker Commands: Declarative UI</h1>

    <h2>Popover Example</h2>
    <button commandfor="myPopover" command="toggle-popover">
        Toggle Popover
    </button>
    <div id="myPopover" popover>
        <p>This is a popover controlled declaratively!</p>
        <button commandfor="myPopover" command="hide-popover">
            Close Popover
        </button>
    </div>

    <h2>Modal Dialog Example</h2>
    <button commandfor="myDialog" command="show-modal">
        Show Modal Dialog
    </button>
    <dialog id="myDialog">
        <h3>This is a Modal Dialog</h3>
        <p>It blocks interaction with the rest of the page until dismissed.</p>
        <p>Press ESC or click the button to close it.</p>
        <button commandfor="myDialog" command="close">
            Close Dialog
        </button>
    </dialog>

    <h2>Custom Command Example</h2>
    <button commandfor="my-img" command="--rotate-left">Rotate left</button>
    <button commandfor="my-img" command="--rotate-right">Rotate right</button>
    <img id="my-img" src="photo.jpg" alt="A sample image" style="transition: rotate 0.3s ease;"/>

    <script>
        // Custom Command JavaScript
        const myImg = document.getElementById("my-img");
        myImg.addEventListener("command", (event) => {
            if (event.command === "--rotate-left") {
                myImg.style.rotate = "-90deg";
                console.log("Custom command: --rotate-left received!");
            } else if (event.command === "--rotate-right") {
                myImg.style.rotate = "90deg";
                console.log("Custom command: --rotate-right received!");
            }
        });

        // Support check: the JavaScript properties are `command` and `commandForElement`.
        if (!('command' in HTMLButtonElement.prototype)) {
            // Minimal plan B: call the classic methods on click.
            document.querySelectorAll('button[commandfor]').forEach((button) => {
                button.addEventListener('click', () => {
                    const target = document.getElementById(button.getAttribute('commandfor'));
                    const command = button.getAttribute('command');
                    if (command === 'show-modal') target.showModal();
                    else if (command === 'close') target.close();
                    else if (command === 'toggle-popover') target.togglePopover();
                    else if (command === 'hide-popover') target.hidePopover();
                });
            });
        }
    </script>
</body>
</html>

Explanation:

Popover:
- The <div> with id="myPopover" also has the popover global attribute. This attribute designates it as a popover element, handling its visibility and top-layer behavior.
- The "Toggle Popover" button uses commandfor="myPopover" and command="toggle-popover". This tells the browser to toggle the visibility of the element with id="myPopover".
- Inside the popover, a "Close Popover" button uses commandfor="myPopover" and command="hide-popover" to explicitly close it.
- The popover attribute on its own (without a value) defaults to popover="auto", which means it can be "light dismissed" (closed by clicking outside or pressing Escape), and usually only one auto popover is shown at a time.
Modal Dialog:
- The <dialog> element with id="myDialog" is inherently designed for modal behavior.
- The "Show Modal Dialog" button uses commandfor="myDialog" and command="show-modal". This opens the dialog as a modal, preventing interaction with the rest of the page until it's closed.
- Inside the dialog, a "Close Dialog" button uses commandfor="myDialog" and command="close" to dismiss it. The browser also handles closing the dialog when the Escape key is pressed.
Custom Commands:
- The command attribute isn't limited to built-in actions. You can define custom commands by prefixing their names with --, similar to CSS custom properties.
- The my-img element listens for a command event. This event fires on the element referenced by commandfor.
- The JavaScript code checks event.command to determine which custom action (--rotate-left or --rotate-right) was triggered and applies the corresponding style. This allows you to create declarative APIs for your custom components, reducing the need for explicit event listeners on the buttons themselves.

Gotchas and Considerations

Browser Support

The Invoker Commands API, along with the commandfor and command attributes, achieved "Baseline" status in December 2025. This means it is supported across all major browsers, including Chrome (135+), Edge (135+), Firefox (144+), and Safari (26.2+).

However, if your audience includes users on older browser versions, you will need a fallback.

Fallback for Older Browsers

For browsers that don't support the Invoker Commands API, you'd typically fall back to traditional JavaScript event listeners. The example checks support with 'command' in HTMLButtonElement.prototype (the JavaScript properties are command and commandForElement) and, when it's missing, wires the same buttons to showModal(), close(), togglePopover() and hidePopover(). A more robust solution would involve a polyfill if you need consistent behavior across all older browsers, or a more comprehensive progressive enhancement strategy. Be aware that polyfills for this API might not fully replicate native behavior, especially concerning ARIA states and focus management.

Permissions and HTTPS

The Invoker Commands API itself doesn't introduce new permission prompts or strict HTTPS requirements beyond what's standard for web platform features. Dialogs and popovers are generally considered safe UI elements. However, for any website in production today, HTTPS is a fundamental security and performance requirement, so you should always be serving your content over HTTPS regardless of whether you're using this API.

Accessibility (A11y)

One of the significant advantages of the Invoker Commands API is that the browser handles much of the accessibility automatically. When you use commandfor and command with built-in actions like show-modal or toggle-popover, the browser manages focus trapping, focus restoration on close, Escape key handling, and the necessary ARIA attributes (like aria-expanded). This vastly simplifies building accessible interactive components compared to writing all that logic manually in JavaScript.

Custom Commands and JavaScript

While the core benefit is reducing JavaScript, the ability to define custom commands using the command event handler means you can still leverage this declarative pattern for more complex interactions where pure HTML isn't enough. This provides a clean separation: HTML declares what command to send, and JavaScript listens for how to execute it on the target element.

What to keep an eye on

Full ecosystem adoption: While major browsers support it, tooling and frameworks might take time to fully integrate and promote this API.
New built-in commands: The specification might expand to include more built-in commands for other interactive elements like <details> or media controls.
Polyfills: If you need to support a very broad range of older browsers, keep an eye on the maturity and completeness of polyfills for this API.

Sources

Originally published at richi.codes.

DEV Community: richi.codes

CSS style queries: one variable, every style

What problem it solves

How it works

The gotcha: plain matching compares tokens

Browser support and other gotchas

What to keep an eye on

Sources

CSS light-dark() now swaps images, not just colors

Why this matters

How it works

The gotcha that cost me a layer

Browser support

What to keep an eye on

Sources

View Transitions: animate any DOM change with one call

What it is and why it matters

How the demo works

Gotchas I hit or checked

Browser support

What to keep an eye on

Sources

CSS field-sizing: inputs that grow as you type

What it is and why it matters

How it works

The gotchas

Browser support

What to keep an eye on

Sources

CSS contrast-color(): text that picks its own color

What it is and why it matters

How it works

The mid-tone trap

Support, fallbacks and one gotcha

What to keep an eye on

Sources

llms.txt v2: what an agent actually reads

What llms.txt is, in one paragraph

What changed in v2

The format is stricter than it looks

What to keep an eye on

Sources

CSS shape(): responsive shapes without SVG

What shape() is

Mixing units: the responsive bubble

Morphing for free

Support and gotchas

What to keep an eye on

Sources

CSS Custom Highlight API: style text without spans

Why this matters

How it works

When highlights overlap

What you can style

Browser support and gotchas

What to keep an eye on

Sources

CSS progress(): one number drives the whole layout

What progress() returns

The pattern from the demo

Why the @property matters

Support and gotchas

What to keep an eye on

Sources

Say no to AI training, not to AI search: robots.txt per bot

Three bots, three jobs

The trap: naming a bot makes it forget *

How a rule wins

Gotchas

What to keep an eye on

Sources

CSS can count now: sibling-index() and sibling-count()

What they return

The minimal version

The gotcha: custom properties and children

Browser support and fallback

What to keep an eye on

Sources

Invoker Commands API: Declarative UI Control

What are Invoker Commands?

The trap: naming a bot makes it forget `*`