makeover_webview/

lib.rs

//! The webview renderer for [`makeover_layout`].
//!
//! <!-- wiki: makeover-webview -->
//!
//! # The renderer that needs no palette
//!
//! `makeover-immediate` and `makeover-tui` both take a `Palette`, because egui
//! and a terminal need an actual colour before they can put anything on
//! screen. A webview does not: `var(--surface-raised)` *is* the late binding,
//! and the browser resolves it against whatever `themes.js` last wrote onto
//! `:root`.
//!
//! So this crate emits text naming intents, and never learns a colour. It is
//! the deferral rule with no adapter in the way, and it is why the webview was
//! always the wrong renderer to derive a vocabulary from: it can express
//! anything, so it never pushes back.
//!
//! # Phase A: the stylesheet
//!
//! This module emits component CSS and no markup, deliberately. GoingsOn has
//! 145 `innerHTML` sites and Balanced Breakfast 175 `createElement` sites, so
//! moving markup is a migration where adopting a generated stylesheet is not.
//! The apps keep every line of their markup and gain the classes.
//!
//! It is not a deletion either, which this header claimed until the measurement
//! came in. Adoption across goingson removed 49 declarations net and *added* 25
//! lines: a rule loses its depth declarations and gains a variant selector next
//! to it, so the file stays the same size. What phase A moves is where depth is
//! defined, not how much CSS exists. Numbers and method in the wiki note under
//! "The deletion test, run".
//!
//! The bevel properties are byte-identical to what both apps already
//! hand-write, which is asserted below.
//!
//! # Phase B: the markup, one description at a time
//!
//! [`form`] renders [`makeover_layout::Field`], which is the half of phase B
//! whose description is settled. It emits strings, because both apps
//! interpolate their fields into larger string-built forms and returning nodes
//! would rewrite those too. It owns its own escaping, on the reasoning in that
//! module: a Rust encoder can cover element text and attribute values with one
//! function, where the apps need four and have to choose correctly at every
//! call site.
//!
//! [`facet`] renders `makeover_layout::Facet`: a dimension a set is narrowed by,
//! and the one phase-B emitter whose markup an app is not keeping, because the
//! markup it replaces was two mechanisms rather than one. A tag's selection and
//! a tag's browse position were separate state on MNW's discover page, which is
//! why every filter row there carries a tick box *and* a chevron; one gesture
//! doing both is what lets the second one go.
//!
//! [`list`] is the other half: column tracks, the narrowing rules, and the cell
//! containers a row is made of. It stops at the cell boundary and does not
//! render what goes inside one, on the reasoning in that module. So phase B is
//! now the frame around content in both directions, and what an app still owns
//! is the content itself.
//!
//! # What phase A settled, and what it costs
//!
//! Decided 2026-07-29 against goingson's `styles.css` rather than against a
//! component list. The useful finding there was that `.btn` (line 644),
//! `.card` (768) and `.tag, .badge` (882) each hand-write the same
//! composition, so three quarters of phase A is one rule with several names.
//!
//! Two of the four decisions change how goingson looks, and adoption should
//! not be described as a pure deletion:
//!
//! - **Pressed carries its fill.** [`interactive_rules`] emits
//!   [`Depth::pressed`] whole. goingson presses to `--surface-sunken` today and
//!   will press to `--surface-well`, and hovers to `--surface-overlay` today
//!   and will hover to `--hover-surface`. Since `surface-well` inverts by theme
//!   where `surface-sunken` does not, a dark theme presses *lighter* than it
//!   hovers. That falls out of `makeover`'s own derivation, which says outright
//!   that `surface-sunken` cannot serve as a well, so if it reads wrong the
//!   answer is there and not here.
//! - **Badges go flat.** See [`token_rules`].
//!
//! The other two: the progress trough is renderer-local and the scrollbar
//! track was dropped ([`component_rules`]), and no class prefix ships by
//! default, so adoption means deleting the app's hand-written rule in the same
//! commit that adds the generated one. `.card`, `.badge` and the tab classes
//! all already exist in goingson, and while both rules exist the cascade order
//! decides which wins. That is the one real risk in adopting this, and it is
//! why the migration lands per component rather than in one commit.
//!
//! # 0.10.0: the states this crate used to leave to its consumers
//!
//! [`interactive_rules`] emitted hover and pressed and stopped, because
//! `makeover-layout` modelled no interaction state. Focus and disabled were
//! therefore unsayable, and every app completed the primitive from outside the
//! only way that works: by out-specifying a rule it does not own. goingson
//! carries 19 such rules and the MNW server 21, and the three focus rings do
//! not match each other.
//!
//! That also blocked the cascade-layer work outright. An app that declares
//! `@layer` puts its own rules in a named layer, and unlayered declarations
//! outrank every named layer regardless of specificity, so all of those
//! overrides lose in the commit that adopts layers. They cannot simply be
//! deleted, because they are the only thing supplying the missing states.
//! Emitting the states here is what turns that adoption into a deletion.
//!
//! Four states now, in emission order, and the order is load-bearing: they are
//! all specificity (0,2,0), so disabled beats hover by coming last and by
//! nothing else. Nothing here reaches for `:not(:disabled)`, which would raise
//! a selector this crate will shortly be wrapping in its own layer.
//!
//! Hover additionally sits inside a capability query now. `makeover-touch`
//! answers whether a fingertip has hover and `makeover-geometry` spells the
//! condition; this crate asks and does not decide. goingson's section 60 exists
//! solely to take the hover state back on touch, which is a fight it should
//! never have been handed.
//!
//! # 0.11.0: the layer contract
//!
//! [`stylesheet`] emits into the `makeover` cascade layer ([`CSS_LAYER`], which
//! lives in `makeover-geometry` because that is the one crate every CSS emitter
//! in the family already depends on). `makeover-geometry` 0.6.0 does the same
//! for `geometry.css`.
//!
//! The cascade resolves origin and importance, then layer, then specificity,
//! then source order, and **unlayered normal declarations outrank every named
//! layer**. So before this, an app that declared `@layer base, components,
//! responsive` put every rule it owns into a named layer and lost all of them to
//! this unlayered file, regardless of specificity and regardless of loading
//! last. Nothing errors when that happens: the CSS is valid, the minifier is
//! happy, and buttons and badges look subtly wrong.
//!
//! That is why the layer belongs here rather than in each app. An app cannot fix
//! it from its own stylesheet, because the fix is to layer the file it does not
//! own.
//!
//! **What it flips**, and the reason each app wants a look when it bumps the
//! pin: a generated rule that currently beats an app rule by being more specific
//! stops beating it. The direction is always "the app wins", which is what the
//! apps already assume, but a hand-written rule an app thought was dead can come
//! back to life.
//!
//! An app should declare the order once, or the layer's position is decided by
//! whichever generated file the browser happens to see first:
//!
//! ```css
//! @layer makeover, base, components, responsive;
//! ```
//!
//! [`in_css_layer`] is re-exported for an app that assembles its own stylesheet
//! from this crate's pieces. goingson builds `tables.css` in its own `build.rs`
//! out of [`list::narrowing_css`] and [`list::grid_template_columns`], and those
//! rules are as generated as the ones here, so they belong in the same layer and
//! this crate cannot put them there on the app's behalf.
//!
//! # 0.12.0: the ring gets its own width
//!
//! [`focus_rule`] reused [`Emit::border_width`] and emitted a 1px ring. That was
//! an implementation convenience dressed as consistency with the invalid-field
//! ring: a bevel and a focus indicator answer different questions, and only one
//! of them has to be noticed from across a desk.
//!
//! Caught while adopting 0.11.0 into goingson, by the check the adoption tasks
//! ask for. Every consumer had already written its own ring and all three chose
//! at least 2px: the MNW server 2px across 10 rules, Balanced Breakfast 2px,
//! goingson 2px on three rules and 3px on the one covering twelve selectors. The
//! design system was the only thing in the tree saying 1px, so deleting the app
//! rules in favour of it would have thinned the focus indicator everywhere.
//!
//! [`Emit::focus_width`] now carries it, defaulting to `2px`, and the offset is
//! the same magnitude with its sign off the depth. Both values are the measured
//! consensus rather than a new opinion.
//!
//! # 0.57.0: a suggestion's second line, in place of a reason it cannot be picked
//!
//! `1fcf2e9b`, ruled by Max 2026-08-21. `Outcome::Suggestions` now carries
//! `Candidate` rather than `Choice`, and a candidate has no `unavailable`: a
//! suggestion that cannot be picked is a row a route should not have offered.
//! What it has instead is a `detail`, the line that tells it from a row reading
//! the same -- "Format" under audio, software, writing and video.
//!
//! So `.form-suggestion-why` is gone and `.form-suggestion-detail` is here, and
//! the difference is not only the name. `why` was drawn in the disabled token,
//! which said the row was refusing. A detail orients rather than refuses, so it
//! is `--content-muted`, which is what every other secondary line in this crate
//! reads as.
//!
//! No consumer is affected: the only emitter is `quasi-webview`, which moves in
//! the same cascade.
//!
//! # 0.56.0: an interval, as the group MNW already wrote by hand
//!
//! [`makeover_layout::FieldKind::Interval`] emits a `role="group"` named by the
//! field's label, holding one `<input type="number">` per end. That is not a
//! shape invented here: MNW's discover sidebar has a `role="group"` with
//! `aria-labelledby` over `min_price` and `max_price` today, written by hand
//! because nothing in the description could say the two boxes were one
//! question. The markup is what the measurement found, and this emits it.
//!
//! - **The group carries the error and the descriptions**, on the split
//!   [`makeover_layout::FieldKind::Radio`] already uses here: what is wrong is
//!   the answer, and a crossed interval is not the fault of either end.
//! - **Both boxes take the whole extent.** `min`, `max` and `step` describe the
//!   axis, so they are written twice. The crossing rule is not emitted, because
//!   HTML has no attribute for it and the description does not carry it: it
//!   comes back as an error on the group, like every other refusal.
//! - **Which end is which is `aria-label` and nothing more.** The description
//!   states direction structurally, by which member holds which name, and never
//!   in words. Visible Min and Max captions are a page's own and reach the
//!   group through [`form::Filling::trailing`].
//!
//! [`form::Value::Between`] is the second value. A separator inside one string
//! would have made this crate the owner of a delimiter that either end could
//! contain.
//!
//! # 0.55.0: a number's unit, as adjacent text
//!
//! `makeover-layout` 0.33.0's `Field::unit`. HTML has no unit attribute and
//! inventing one would be markup nothing reads, so it is a `<span>` after the
//! control -- and it is named in `aria-describedby` rather than left as
//! decoration, because a number and what it is measured in are one fact and
//! reading the first without the second is reading it wrong.
//!
//! This is the renderer the member costs something. egui already had somewhere
//! better than the label to put a unit; here the two placements are equally
//! adjacent, and what is bought is that the unit is a value a consumer can read
//! back rather than a suffix on a label it would have to parse.
//!
//! # 0.54.0: a curve this renderer can carry, and one it cannot
//!
//! `makeover-layout` 0.32.0's `Curve`. A range takes its granularity from the
//! curve now (`Field::curve.step()`), every other kind keeps `Field::step`, and
//! `Curve::Linear` emits exactly what it emitted before.
//!
//! **A constant-ratio curve still emits a linear track, and that is a
//! shortfall rather than a decision.** HTML has no logarithmic range input, so
//! honouring one here means either shipping JS that maps the thumb position to
//! a value -- renderer-side app code, which is the thing this stack exists to
//! delete -- or changing what the control submits from a value to a fraction,
//! and then something has to map it on the way back in. That something is not
//! this crate: the MNW server reads these forms with its own handlers, so a
//! fraction arriving where a value is expected would be silent. Filed rather
//! than guessed at.
//!
//! What is not lost: the extent, the granularity, and the value's own units.
//! What is lost is resolution at the small end, which is exactly the reason an
//! app asked for a ratio in the first place. No consumer is affected today --
//! every described range on this path is linear.
//!
//! # 0.52.0: a markdown field gets the preview it was permitted
//!
//! 0.50.0 marked a [`makeover_layout::FieldKind::Rich`] field with
//! `data-format="markdown"` and stopped there, and nothing read the mark: no
//! rule, no markup, no selector anywhere in the tree. So a described editor was
//! a plain textarea carrying an attribute, and MNW converting its four
//! hand-written section editors onto the member would have *lost* the
//! Write/Preview pair one of them already has. A permission taken and not spent
//! turns every conversion into a regression.
//!
//! [`form::editor_rules`] and the chrome beside it are the spending. The pair is
//! a segmented control, so it takes the depth, the focus ring and the chosen
//! state from rules that already existed; the preview pane is a well, because it
//! stands where the control stood. Both are gated on the attribute rather than
//! on a class, which is what the attribute was for.
//!
//! **This crate still renders no markdown.** The pane arrives empty and is
//! filled by whatever binds the editor, which is where the host's sanitiser
//! already is. A converter here would have moved that guarantee into a crate
//! with no view of the host's content-security posture.
//!
//! # 0.47.0: a range, a chooser's ghost text, and an option that cannot be
//! picked yet
//!
//! `makeover-layout` 0.28.0's three form findings, all of them cheap here and
//! none of them cheap in the app that found them.
//!
//! - `FieldKind::Range` emits `<input type="range">`, and `Field::step` emits
//!   `step`. The step is emitted only when the description carries one: the
//!   browser's own default is `step="1"`, which is what a description means by
//!   saying nothing, and is also what turns a 0-to-1 threshold into a
//!   two-position control.
//! - A select with nothing chosen emits a disabled, selected, valueless first
//!   option carrying `Field::placeholder`. HTML has no placeholder attribute on
//!   `<select>`; this is the idiom, and `required` keeps working through it
//!   because the option's value is empty.
//! - `Choice::unavailable` emits `disabled` plus the reason. Where it goes
//!   differs by control and the difference is forced: a radio group gets a
//!   `.form-option-reason` span beside the label, and a `<select>` option has
//!   room for no element at all, so the reason runs into its text.
//!
//! # 0.25.0: a cell says what it holds
//!
//! 0.23.0 gave a table its layout and left every cell the same. One `.cell`
//! carried the whole thing, so a cell holding text and a cell holding a button
//! were one class and one content colour, and a control in a cell was painted
//! as text. That is the drift [`RowPart::intent`](makeover_layout::RowPart)
//! has prevented for list rows since 0.2.0 and prevented for nothing here.
//!
//! makeover-layout 0.14.0's [`CellPart`](makeover_layout::CellPart) names the
//! four things a cell holds, and [`table_rules`] turns them into
//! `.cell-value`, `.cell-tokens`, `.cell-actions` and `.cell-link`. Only the
//! first takes a colour: a token carries its own tone, an action is a control
//! rather than text, and a link takes the action colour from the anchor it is.
//!
//! The colour going on `.cell-value` rather than on `.cell` is the fix rather
//! than an implementation detail. On the container it cascades into the parts
//! that are not text, which is the bug said in one rule.
//!
//! [`list::Cell::part`] is `Option<CellPart>` here, where it was
//! `Option<RowPart>`. A table cell borrowing the list row's vocabulary was the
//! drift with a type on it: the two answer different questions, and only one of
//! them was ever about a cell.
//!
//! # 0.23.0: a table lays itself out, and a row shows its controls
//!
//! Three things a description could say and this renderer had no rule for,
//! found together by rendering the MNW server's SSH-keys settings tab through
//! `quasi` and preferring the hand-written Askama original.
//!
//! **A table had no layout at all.** [`list::narrowing_css`] emits the track
//! list, and it has to be called with the columns, so it works where the
//! columns are known at build time: goingson builds `tables.css` in its own
//! `build.rs` and is untouched. A table a description produced knows its
//! columns at render time, and the rules would have had to travel with the
//! markup: a `<style>` element per table, which needs `style-src
//! 'unsafe-inline'` that the MNW server is working to drop, or the head, which
//! an htmx fragment swap does not carry. [`table_rules`] lays a table out with
//! `display: table` instead, which aligns columns across rows knowing nothing
//! about how many there are. [`Priority`](makeover_layout::Priority) hiding
//! moves from a generated rule per dropped column to one rule per drop class,
//! and [`list::column_classes`] is what puts those classes on a cell. A header
//! row emitted by a renderer's own code should call it too, or the header and
//! the body disagree about which column just dropped.
//!
//! **A destructive button had nowhere for its tone to land.** `.button` carried
//! no tone, on the reading that a control's colour is its surface. Every
//! consumer had written the danger rule itself. It joins the badge in taking
//! the four tones as colour, off `data-tone`.
//!
//! **A list rendered as a bulleted list**, because nothing here reset the `ul`
//! a renderer emits for one.
//!
//! `RowPart::revealed_on_hover` also stops being honoured, which its own doc
//! sanctioned: a renderer decides. It was retired outright in makeover-layout
//! 0.13.0, once this had been its only consumer for a release. The rule hid a
//! row's actions until hover,
//! and every escape it grew was a report that hiding was wrong for somebody:
//! `focus-within` for the keyboard, the capability gate for a fingertip with no
//! way to unhide. What survived hid the controls from pointer users alone, who
//! are the ones scanning a list to learn what can be done to a row.
//!
//! # 0.17.0: the depth classes stop being controls
//!
//! [`depth_rules`] gave `.raised` the whole interactive set. A depth is a
//! statement about shape, so that left the vocabulary with no raised surface
//! that is merely an object, and an app wanting one had two moves: write its
//! own class from tokens, or take a control class and cancel the control half.
//! goingson took the second, in three variants over sixteen elements
//! (`.card--static` at 14 call sites, `.card--muted` at 2, `.card--shell` at 1),
//! each re-asserting the resting fill and bevel on `:hover` and `:active`.
//!
//! Measured before changing it: `.raised` is emitted into goingson, Balanced
//! Breakfast and the MNW server, and none of the three has a single call site.
//! The states were unasked-for everywhere at once, and dropping them costs no
//! migration anywhere.
//!
//! `.card` and `.button` are unchanged. They are the same depth *and* controls,
//! and they take their states from [`surface_rules`], which is where a state
//! belongs: on the thing that claims to answer a pointer.
//!
//! # Substitution, three ways
//!
//! `Fill::Well` has no colour on makeover before 2.3.0, and each renderer
//! answers that differently, which is the evidence that dropping
//! `Fill::fallback` from the description was right:
//!
//! - `makeover-immediate` substitutes the page in Rust.
//! - `makeover-tui` refuses to substitute and draws an edge instead, because a
//!   terminal would quantise the two together.
//! - here, CSS already has the mechanism: `var(--surface-well,
//!   var(--surface-page))` falls back in the browser, and nothing in Rust
//!   decides anything.

#![forbid(unsafe_code)]

pub mod facet;
pub mod figure;
pub mod form;
pub mod list;
pub mod meter;
pub mod placeholder;
pub mod vocabulary;

/// A render of every emitter, scraped for the classes it wrote.
///
/// Test-only, and the guard behind [`vocabulary::names`]. See the module's own
/// header for why the check renders rather than reads the source.
#[cfg(test)]
mod corpus;

use crate::list::{cell_part_class, part_class};
use makeover_geometry::{Density, SizeClass};
// Re-exported rather than redefined. An app assembling its own stylesheet out
// of this crate's pieces needs the same layer name, and most such apps depend
// on this crate and not on `makeover-geometry` directly: goingson builds
// `tables.css` in its own build.rs from [`list::narrowing_css`], and those
// rules are as generated as the ones here.
pub use makeover_geometry::{CSS_LAYER, in_css_layer};
use makeover_layout::{
    Bevel, CellPart, Depth, Fallback, Fill, Flow, Intent, RowPart, Selector, Sort, State, Token,
    Tone,
};
use makeover_touch::Affordance;
use std::fmt::Write as _;

/// How the emitted CSS is shaped.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Emit {
    /// Bevel thickness, as a CSS length.
    ///
    /// A value, so it arrives from the caller: border widths belong to
    /// `makeover-geometry` and will come from there once it carries them.
    pub border_width: &'static str,
    /// Focus ring thickness, as a CSS length.
    ///
    /// Separate from [`border_width`](Self::border_width), which it reused
    /// until 0.12.0. That reuse was an implementation convenience dressed as
    /// consistency, and it emitted a 1px ring: a bevel and a focus indicator
    /// are answering different questions, and only one of them has to be
    /// noticed from across a desk.
    ///
    /// The default is the measured consensus rather than a new opinion. Every
    /// consumer had already written its own ring and all three chose at least
    /// 2px: the MNW server 2px across 10 rules, Balanced Breakfast 2px,
    /// goingson 2px on three rules and 3px on the one covering twelve
    /// selectors. The design system was the only thing in the tree saying 1px.
    pub focus_width: &'static str,
    /// Prefix for emitted class names, without the leading dot.
    pub class_prefix: &'static str,
}

impl Default for Emit {
    fn default() -> Self {
        Self {
            border_width: "1px",
            focus_width: "2px",
            class_prefix: "",
        }
    }
}

/// A string as CSS escapes, for a `content` value.
///
/// `\u{25B2}` becomes `\25B2`. Emitted escaped rather than literally so the
/// stylesheet is ASCII whatever the description spells: a `content` string is
/// read by whatever encoding the consumer serves the file as, and a caret that
/// depends on that is a caret that works on one machine.
///
/// Terminated by the closing quote at every site here. A CSS hex escape takes
/// up to six digits and ends at the first character that cannot be one, so an
/// escape followed by more text would need a space that these do not.
fn css_escape(text: &str) -> String {
    text.chars().fold(String::new(), |mut out, c| {
        let _ = write!(out, "\\{:X}", c as u32);
        out
    })
}

/// The CSS custom property holding a bevel's composition.
#[must_use]
pub fn bevel_var(bevel: Bevel) -> &'static str {
    match bevel {
        Bevel::Raised => "--bevel-raised",
        Bevel::Inset => "--bevel-inset",
    }
}

/// A `var()` reference to a fill intent, with the browser's own fallback where
/// the intent may be absent.
///
/// The fallback is CSS syntax, not a decision made here. That is the whole
/// difference between this renderer and the other two.
#[must_use]
pub fn fill_var(fill: Fill) -> String {
    match fill {
        Fill::Well => format!("var(--{}, var(--{}))", fill.token(), Fill::Page.token()),
        other => format!("var(--{})", other.token()),
    }
}

/// The two-tone edge as a `box-shadow` value.
///
/// Two inset shadows, one per corner pair: the light one offset down and
/// right so it lands on the top and left edges, the dark one the other way.
/// The same assignment `makeover-immediate` draws with polylines and
/// `makeover-tui` draws with box-drawing characters.
#[must_use]
pub fn bevel_shadow(bevel: Bevel, opts: &Emit) -> String {
    let (top_left, bottom_right) = bevel.edges();
    let w = opts.border_width;
    format!(
        "inset {w} {w} 0 var(--{}), inset -{w} -{w} 0 var(--{})",
        top_left.token(),
        bottom_right.token()
    )
}

/// The custom properties both bevels resolve through.
///
/// Emitted as properties rather than inlined into every rule because that is
/// what the apps already do, and because a consumer that wants the edge
/// without the fill reads the property directly.
#[must_use]
pub fn bevel_properties(opts: &Emit) -> String {
    let mut css = String::new();
    for bevel in [Bevel::Raised, Bevel::Inset] {
        let _ = writeln!(
            css,
            "    {}: {};",
            bevel_var(bevel),
            bevel_shadow(bevel, opts)
        );
    }
    css.push_str(ELEVATION_PROPERTY);
    css
}

/// The cast shadow of a surface that floats over the page.
///
/// Composed here for the reason the bevel pair is: `makeover` derives the tone,
/// this crate owns the geometry, and neither has to know the other's numbers.
///
/// **Only for a surface that overlays the page.** A menu, a toast, a popover, a
/// dropdown. A surface *in* the page takes `.raised` and its bevel, and a rule
/// that reaches for this on a card or a plate has renamed a literal rather than
/// replaced it.
///
/// Two lengths rather than one, because a single blur reads as a smudge at
/// plate size and as a halo at menu size. The offset is small and downward: a
/// Platinum-era menu sits just off the page rather than hovering above it.
const ELEVATION_PROPERTY: &str =
    "    --elevation-overlay: 0 2px 4px var(--elevation), 0 8px 24px var(--elevation);\n";

/// The class name for a depth.
#[must_use]
pub fn depth_class(depth: Depth, opts: &Emit) -> Option<String> {
    let name = match depth {
        Depth::Flat => return None,
        Depth::Raised => "raised",
        Depth::Well => "well",
        Depth::Sunken => "sunken",
        // A depth added to the description since this renderer was last
        // built. No class, on the same footing as Flat: emitting a name
        // whose rule body we cannot write would put a class in the markup
        // that the stylesheet never defines.
        _ => return None,
    };
    Some(format!("{}{name}", opts.class_prefix))
}

/// A prefixed class name.
///
/// Public since 0.27.0, for the renderers that emit markup this crate does not.
/// A screen renderer writing `class="row"` has to prefix it the way the
/// stylesheet half does or a prefixed app gets rules matching everything except
/// the elements that renderer wrote, and the failure is invisible: the CSS
/// stays valid and one element is unstyled. quasi-webview carried a byte
/// identical copy of this function until it could call this one.
#[must_use]
pub fn class(name: &str, opts: &Emit) -> String {
    let mut out = String::with_capacity(opts.class_prefix.len() + name.len());
    push_class(&mut out, name, opts);
    out
}

/// A prefixed class name, written into a buffer the caller already has.
///
/// The form the emitters use, and the reason it exists is [`escape_into`]'s:
/// every class on every element went through a `format!` before 0.40.0,
/// including the default case where the prefix is empty and the answer is the
/// argument. A described table row carried roughly eighty transient
/// allocations, and this and the escaper were most of them.
///
/// [`class`] stays for callers holding a name rather than a buffer.
///
/// [`escape_into`]: crate::form::escape_into
pub fn push_class(out: &mut String, name: &str, opts: &Emit) {
    out.push_str(opts.class_prefix);
    out.push_str(name);
}

/// The class an option of a selector carries, which is what the rules key off.
///
/// Named for the option and not for the group: [`selector_rules`] styles the
/// thing that gets picked, so `Selector::Tabs` is `tab` and not `tabs`. The
/// distinction is not pedantry. quasi-webview spelled these `tabs`, `segmented`
/// and `option`, put `toggle` on the wrapping element rather than on the
/// buttons inside it, and every described selector in that renderer came out
/// with no depth, no focus ring and no chosen state, while the toggle group got
/// a bevel meant for its buttons.
///
/// The chosen option additionally carries `chosen`, the same way a latched chip
/// carries `latched`. That name is this crate's too; there is no reason for a
/// caller to spell it, and [`selector_rules`] is where it is written down.
#[must_use]
pub fn option_class(selector: Selector) -> &'static str {
    match selector {
        Selector::Tabs => "tab",
        Selector::Segmented => "segment",
        Selector::Toggle => "toggle",
    }
}

/// The fill and edge declarations for a depth, as a rule body.
///
/// Empty for [`Depth::Flat`], which has neither and inherits what it sits on.
/// Callers lean on the emptiness to skip the rule rather than emit a class that
/// sets nothing: a class that sets no properties is a class that means "I
/// thought about this", which is what comments are for.
///
/// The two halves are emitted independently because [`Depth::Sunken`] has a
/// fill and no bevel. Requiring both, which this did before makeover-layout
/// 0.3.0, silently dropped the fill for exactly that case. Independent does not
/// mean unpaired: both halves still come off one `Depth`, so they cannot
/// disagree about what the region is.
#[must_use]
pub fn depth_declarations(depth: Depth) -> String {
    let mut css = String::new();
    if let Some(fill) = depth.fill() {
        let _ = writeln!(css, "    background: {};", fill_var(fill));
    }
    if let Some(bevel) = depth.bevel() {
        let _ = writeln!(css, "    box-shadow: var({});", bevel_var(bevel));
    }
    css
}

/// One rule giving a selector a depth, or nothing when the depth declares
/// nothing.
#[must_use]
pub fn depth_rule(selector: &str, depth: Depth) -> String {
    let body = depth_declarations(depth);
    if body.is_empty() {
        return String::new();
    }
    format!(".{selector} {{\n{body}}}\n")
}

/// The media condition a hover rule has to sit inside, or `None` if hover is
/// unconditional.
///
/// Two crates answer this and neither answer is made here. `makeover-touch`
/// owns *whether* hover exists at a density, and `makeover-geometry` owns how
/// that capability is spelled as a media condition. Asking both is what stops
/// this renderer minting a third opinion, which is what all three apps did:
/// goingson sniffed the user agent, Balanced Breakfast used `(hover: none)`
/// alone, and the MNW server had no gate at all.
///
/// [`SizeClass`] is required by [`Affordance::available`] and ignored by this
/// member, which reports as much through `reads_size`. Passing Compact is not
/// a claim about width; the test below pins that every class agrees.
fn hover_condition() -> Option<&'static str> {
    if Affordance::Hover.available(Density::Touch, SizeClass::Compact) {
        // A fingertip grew a hover state. Nothing to gate, and this renderer
        // should not invent a reason to gate anyway.
        None
    } else {
        Some(Density::Pointer.media_condition())
    }
}

/// Put a rule inside a media query, or leave it alone.
fn gated(condition: Option<&str>, rule: &str) -> String {
    let Some(condition) = condition else {
        return rule.to_string();
    };
    let mut css = format!("@media {condition} {{\n");
    for line in rule.lines() {
        // Blank lines stay blank. Indenting one leaves trailing whitespace,
        // which is the sort of thing a formatter later reverts and calls a diff.
        if line.is_empty() {
            css.push('\n');
        } else {
            let _ = writeln!(css, "    {line}");
        }
    }
    css.push_str("}\n");
    css
}

/// The keyboard focus ring, placed by the depth it lands on.
///
/// This is the webview's **focus ring** and nothing more. **Reach** and
/// **focus** are both the browser's — the document decides what is reachable
/// and `:focus-visible` decides which reached thing wears the ring — and no
/// description states either. The three terms are defined once in
/// `makeover_layout`'s crate header, "Reach, focus and the focus ring".
///
/// One ring for the whole system, because a focus ring's job is to be
/// recognised and three apps having three of them is the failure. What varies
/// is where it sits, and that comes off [`Depth`] rather than off a per-
/// component choice: a well takes the ring inside its own edge, and anything
/// standing proud of the page takes it outside.
///
/// `outline` rather than the composed `box-shadow` the invalid-field ring at
/// [`field_rules`] uses, and deliberately the one place the two rings are built
/// differently. A `box-shadow` ring has to restate the bevel beside it, because
/// `box-shadow` is not additive and a lone ring silently drops the well out
/// from under the element. That restatement is a second copy of the depth,
/// living in a different function from the first, and it is exactly the
/// duplication `Depth` exists to prevent. `outline` occupies its own property,
/// so the bevel survives untouched and there is nothing to keep in agreement.
/// They render the same: both are a flush ring one border-width wide.
#[must_use]
pub fn focus_rule(selector: &str, depth: Depth, opts: &Emit) -> String {
    let w = opts.focus_width;
    // Same magnitude either way, and only the sign comes off the depth. Both
    // values are what the consumers had already converged on independently:
    // 2px out is what all three wrote, and 2px in is the MNW server's own
    // answer for the one inset ring it had.
    let offset = match depth.bevel() {
        // Inside the well, clear of its edge rather than painted over it.
        Some(Bevel::Inset) => format!("calc(-1 * {w})"),
        // Raised, or no edge at all. Outside, standing off by its own width.
        _ => w.to_string(),
    };
    // The token by name. It is `makeover`'s, derived from the action colour,
    // and reaching it through a description member was a second path to the
    // same variable for as long as one existed.
    format!(
        ".{selector}:focus-visible {{\n    outline: {w} solid var(--focus-ring);\n    outline-offset: {offset};\n}}\n"
    )
}

/// Present, visible, and not answering.
///
/// Matches the ARIA attribute as well as the pseudo-class, because `:disabled`
/// only matches form elements and half the things this crate emits are not
/// one: a `div` carrying `.chip` or `.tab` can never be `:disabled`. Keying on
/// the accessible state is the pattern [`field_rules`] already establishes for
/// `aria-invalid`, on the reasoning that one fact read by both the styling and
/// the accessibility tree cannot drift from itself.
///
/// The rest depth is re-asserted rather than assumed, because this rule has to
/// beat the hover and pressed rules above it. It does that on source order at
/// equal specificity, not by out-specifying them: every rule this function's
/// caller emits is (0,2,0), and adding a `:not(:disabled)` anywhere would raise
/// one of them and have to be unpicked when this output moves inside its own
/// cascade layer.
#[must_use]
pub fn disabled_rule(selector: &str, depth: Depth) -> String {
    format!(
        ".{selector}:disabled,\n.{selector}[aria-disabled=\"true\"] {{\n{}    color: var(--{});\n    cursor: not-allowed;\n}}\n",
        depth_declarations(depth),
        State::Disabled.token()
    )
}

/// Every state a selector that answers a click implies: hover, pressed, focus
/// and disabled, in that order.
///
/// Order is the whole cascade mechanism here. All four selectors are
/// specificity (0,2,0), so disabled wins over hover and pressed by coming last
/// and by nothing else.
///
/// Pressed emits [`Depth::pressed`] in full, fill and edge together. Emitting
/// only the edge is what left goingson hand-writing `background:
/// var(--surface-sunken)` on three separate rules, and a fill that does not
/// travel with its edge is precisely the disagreement `Depth` exists to make
/// unrepresentable. So the pressed fill comes from the description
/// (`--surface-well`) rather than from whatever each app reached for.
///
/// Hover has no member in the description and is renderer policy: a terminal
/// and an immediate-mode painter have no hover to express. It resolves against
/// `--hover-surface`, which `makeover` already derives and which nothing
/// consumed until now. What it *is* gated on is capability, via
/// [`hover_condition`]. Before that gate existed the apps each wrote their own:
/// goingson's section 60 exists solely to take back the hover state this
/// function had just handed it, by out-specifying a rule it does not own.
///
/// `depth` is the selector's **rest** depth, used to place the focus ring and
/// to restore the surface under a disabled control. The pressed rule keeps
/// inverting from [`Depth::Raised`] regardless, which is what every caller got
/// before this parameter existed: a tab's unchosen depth is
/// [`Depth::Sunken`], and `Sunken.pressed()` is `Sunken`, so deriving the press
/// from the rest depth would leave a tab with no press at all.
#[must_use]
pub fn interactive_rules(selector: &str, depth: Depth, opts: &Emit) -> String {
    let mut css = gated(
        hover_condition(),
        &format!(".{selector}:hover {{\n    background: var(--hover-surface);\n}}\n"),
    );
    css.push_str(&depth_rule(
        &format!("{selector}:active"),
        Depth::Raised.pressed(),
    ));
    css.push_str(&focus_rule(selector, depth, opts));
    css.push_str(&disabled_rule(selector, depth));
    css
}

/// One rule per depth: its fill and its edge, together.
///
/// A depth and nothing else. `.raised` says a surface sits on what is behind
/// it, which is a statement about the shape and not about what happens when a
/// pointer arrives, so it emits no hover, press, focus or disabled rule. The
/// named surfaces are where interaction lives: `.card` and `.button` are the
/// same depth *and* controls, and they get their states from
/// [`surface_rules`].
///
/// This class carried the interactive set until 0.17.0, which left the
/// vocabulary with no raised surface that is merely an object. Consumers that
/// needed one took a control class and cancelled half of it instead: sixteen
/// elements in goingson across three `.card--*` variants, each re-asserting the
/// resting fill and bevel on `:hover` and `:active`. Nothing anywhere used
/// `.raised` itself, so the states were unasked-for in every consumer at once.
#[must_use]
pub fn depth_rules(opts: &Emit) -> String {
    let mut css = String::new();
    for depth in [Depth::Raised, Depth::Well] {
        let Some(class) = depth_class(depth, opts) else {
            continue;
        };
        css.push_str(&depth_rule(&class, depth));
    }
    css
}

/// The three surfaces that are a depth with a name.
///
/// `button` and `card` are both [`Depth::Raised`], and `field` is a
/// [`Depth::Well`] because that is the reading `Depth`'s own documentation
/// gives a text field. Their bodies come out identical by construction rather
/// than by hand: three hand-written copies in goingson's stylesheet is what
/// phase A deletes, and generating them from one call is what stops them
/// drifting apart again.
fn surface_rules(opts: &Emit) -> String {
    let mut css = String::new();
    for name in ["button", "card"] {
        let c = class(name, opts);
        css.push_str(&depth_rule(&c, Depth::Raised));
        css.push_str(&interactive_rules(&c, Depth::Raised, opts));
    }

    let field = class("field", opts);
    css.push_str(&depth_rule(&field, Depth::Well));

    // A field takes focus and refuses input like everything else here, and got
    // neither until now, which is why all three apps hand-write a focus ring
    // for it and no two of them match. No hover or pressed: a text field does
    // not light up under the pointer and does not invert when clicked, so the
    // two states `interactive_rules` would add are the two it does not have.
    css.push_str(&focus_rule(&field, Depth::Well, opts));
    css.push_str(&disabled_rule(&field, Depth::Well));

    // Keyed on the ARIA attribute rather than on a class, so the visual state
    // and the accessible state cannot drift apart: there is one fact and both
    // read it. goingson already drove its invalid styling this way and was
    // right to; the `.invalid` class this emitted before 0.5.0 was a second
    // place to forget.
    //
    // The ring composes *after* the bevel rather than replacing it. box-shadow
    // is not additive, so a lone ring silently dropped the well out from under
    // an invalid field. Flat and unlit: this edge is saying "wrong", and
    // lighting one side would have it say "raised" at the same time.
    let _ = writeln!(
        css,
        ".{field}[aria-invalid=\"true\"] {{\n    box-shadow: var({}), 0 0 0 {} var(--danger);\n}}",
        bevel_var(Bevel::Inset),
        opts.border_width
    );
    css
}

/// Badges and chips.
///
/// The one place phase A changes how goingson looks rather than only where its
/// rules live. [`Token::Badge`] is [`Depth::Flat`], so a badge emits no fill
/// and no edge at all, where goingson ships `.tag, .badge` as a single rule
/// carrying the raised bevel. Splitting that means reading every call site to
/// decide which of the two it always was.
///
/// What a badge does carry is a [`Tone`], the intent family it shares with
/// notices and nothing else. Neutral is the bare class rather than a variant,
/// because it is the absence of a status and not a status called "none".
/// Text that goes somewhere.
///
/// The one inline control, and the vocabulary had no word for it until a
/// description layer needed one. A table cell has carried `cell-link` since
/// 0.14.0's part list, deliberately unruled because the cell's own rule covers
/// it; what was missing is the same thing outside a table, which is what a
/// described run holds when a sentence contains a link.
///
/// Colour and underline only. Whether a link is inline in a sentence or sitting
/// on its own line is the app's layout, and how much room it takes is
/// `makeover-geometry`'s. What is here is the pair of signals that say "this
/// goes somewhere" and nothing that says where it sits.
///
/// The visited arm is deliberately absent. A link inside an app points at the
/// app's own screens, which the user is expected to have been to, so painting
/// them differently marks almost everything and distinguishes nothing.
fn link_rules(opts: &Emit) -> String {
    let mut css = String::new();
    let link = class("link", opts);

    let _ = writeln!(
        css,
        ".{link} {{\n    color: var(--action);\n    \
         text-decoration: underline;\n}}"
    );
    // The hover step is the same one every other control takes, and it is a
    // colour rather than a surface: a link has no box to raise.
    let _ = writeln!(
        css,
        "@media (hover: hover) and (pointer: fine) {{\n    .{link}:hover \
         {{\n        color: var(--action-hover);\n    }}\n}}"
    );
    let _ = writeln!(
        css,
        ".{link}:focus-visible {{\n    outline: {} solid var(--focus-ring);\n    \
         outline-offset: 2px;\n}}",
        opts.focus_width
    );
    // A link is often a `<button>` rather than an `<a>`: a renderer picks the
    // element from the method, so a link that writes is a button that has to
    // stop looking like one.
    let _ = writeln!(
        css,
        "button.{link} {{\n    background: none;\n    border: none;\n    \
         padding: 0;\n    font: inherit;\n    cursor: pointer;\n}}"
    );
    css
}

fn token_rules(opts: &Emit) -> String {
    let mut css = String::new();

    // No `depth_rule` call here, deliberately: `Token::Badge.depth(_)` is Flat,
    // and a label with an edge says it can be pressed.
    let badge = class("badge", opts);
    let _ = writeln!(
        css,
        ".{badge} {{\n    color: var(--{});\n}}",
        Tone::Neutral.token()
    );
    for tone in [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger] {
        let _ = writeln!(
            css,
            ".{badge}[data-tone=\"{0}\"] {{\n    color: var(--{0});\n}}",
            tone.token()
        );
    }

    // A button carries the four tones a badge does. It had none, on the reading
    // that a control's colour is its surface rather than its text, and that
    // reading has one hole big enough to matter: the button that destroys
    // something. Every consumer had written that rule itself, and a description
    // that says `Tone::Danger` on an act had nowhere for it to land.
    //
    // Colour and not a fill, matching the badge. A red surface is a decision
    // about emphasis that belongs to an app's own layer, and two of them
    // fighting is worse than neither.
    let button = class("button", opts);
    for tone in [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger] {
        let _ = writeln!(
            css,
            ".{button}[data-tone=\"{0}\"] {{\n    color: var(--{0});\n}}",
            tone.token()
        );
    }

    // A chip holds itself down, which is `Depth::pressed` arrived at
    // independently by two apps. `removable` is a remove affordance, so it is
    // markup and waits for phase B.
    let chip = class("chip", opts);
    let unlatched = Token::Chip { removable: false };
    css.push_str(&depth_rule(&chip, unlatched.depth(false)));
    css.push_str(&interactive_rules(&chip, unlatched.depth(false), opts));
    css.push_str(&depth_rule(
        &format!("{chip}.latched"),
        unlatched.depth(true),
    ));
    css
}

/// The three selectors, each named by what it picks.
///
/// A tab comes *forward* to join the pane it opens, which is why
/// [`Selector::Tabs`] chooses [`Depth::Raised`] where a segment and a toggle
/// are held in. That is the folder semantic, and it is the whole reason the
/// three are not one member with a flag.
///
/// [`Selector::abutting`] is not emitted: whether the options touch is
/// spacing, and spacing is `makeover-geometry`'s question to answer.
///
/// Both states emit as of makeover-layout 0.3.0. Before it the description
/// named only the chosen option, so an unchosen one fell through to
/// [`Depth::Flat`] and nothing was drawn for it, which left goingson's tab
/// strip hand-writing the recess that makes its chosen tab read as forward.
fn selector_rules(opts: &Emit) -> String {
    let mut css = String::new();
    for selector in [Selector::Tabs, Selector::Segmented, Selector::Toggle] {
        let c = class(option_class(selector), opts);
        css.push_str(&depth_rule(&c, selector.unchosen()));
        css.push_str(&interactive_rules(&c, selector.unchosen(), opts));
        css.push_str(&depth_rule(&format!("{c}.chosen"), selector.chosen()));
    }
    css
}

/// The parts of a list row.
///
/// The list is written out rather than derived because `RowPart` is
/// `#[non_exhaustive]` as of makeover-layout 0.9.0, so there is nothing to
/// iterate. A member added upstream emits no rule until it is named here, which
/// is the trade `non_exhaustive` makes: a silent gap instead of a build break.
/// [`part_class`] carries the same list and the same obligation.
fn row_rules(opts: &Emit) -> String {
    let mut css = String::new();

    // The container the rows sit in. Three zeroes and a keyword, all of them
    // undoing a browser default the description never asked for: a described
    // list of SSH keys is not a bulleted list, and it rendered as one because
    // nothing here said otherwise. Not a size: there is no magnitude in it,
    // which is the line this crate holds.
    let _ = writeln!(
        css,
        ".{} {{\n    list-style: none;\n    margin: 0;\n    padding: 0;\n}}",
        class("list", opts)
    );

    for part in [
        RowPart::Primary,
        RowPart::Secondary,
        RowPart::Meta,
        RowPart::Actions,
        RowPart::Tokens,
        RowPart::Proportion,
    ] {
        let c = class(part_class(part), opts);

        // Actions carry controls rather than text, and `RowPart::intent` says
        // so by returning the same intent inheriting already gives. Pinning it
        // would be louder than saying nothing. Tokens answer alike, for their
        // own reason: each token carries its own tone, and a colour on the
        // strip would fight the things sitting in it. A proportion is the same
        // case again: the meter inside carries the tone.
        if !matches!(
            part,
            RowPart::Actions | RowPart::Tokens | RowPart::Proportion
        ) {
            let _ = writeln!(css, ".{c} {{\n    color: var(--{});\n}}", part.intent());
        }

        // A row's actions are shown at rest. `RowPart::revealed_on_hover` said
        // otherwise and was not honoured here from 0.23.0; makeover-layout
        // 0.13.0 retired the method, so there is no longer a description saying
        // one thing and a renderer doing another.
        //
        // The rule was `opacity: 0` gated to pointer devices, revealed on
        // `:hover` and on `:focus-within`. Each escape it needed was a report
        // that hiding was wrong for somebody: `focus-within` because tabbing
        // could never reach an action; the gate because a fingertip had no way
        // to unhide, which both webview apps had already hand-written
        // `opacity: 1` to undo. What was left was a control hidden from
        // exactly one group: people using a pointer, who are also the group
        // scanning a list to find out what can be done to a row.
        //
        // A settings screen is where that reads worst: the whole reason to be
        // on it is to remove a key, and the button doing so was invisible
        // until pointed at. A table cell's actions were never hidden, so the
        // two arrangements now agree.
    }

    // A part that may take two lines. `Flow::Tight` gets no rule: one line is
    // what a run already does, and restating it here would put a declaration on
    // every part in every row to say nothing.
    //
    // This is the shape both webview apps had already written by hand and
    // commented -- Balanced Breakfast on a feed row's title, goingson on a
    // problem's body -- which is the whole argument for the description
    // carrying it. `-webkit-` prefixed and unprefixed together: the prefixed
    // trio is what every engine actually implements, and `line-clamp` is the
    // standard property landing behind it.
    let _ = writeln!(
        css,
        ".{} {{\n    display: -webkit-box;\n    -webkit-box-orient: vertical;\n    -webkit-line-clamp: {lines};\n    line-clamp: {lines};\n    overflow: hidden;\n}}",
        class("row-relaxed", opts),
        lines = Flow::Relaxed.lines()
    );

    css
}

/// A row of things that share their space, and what each fallback gets here.
///
/// Ruling: wiki `layout-room-and-fallback`, Max 2026-08-18. The bug it answers
/// is goingson's `styles.css:702`, which pinned every `.page-header` over the
/// pill strip with `position: absolute` and so took the toolbar out of flow:
/// zero width contributed to the row it shared, nothing able to collide with
/// it, and therefore nothing preventing the collision. Rule 1 of the ruling is
/// that every described member is in flow, and these rules are how that is kept
/// rather than asked for.
///
/// # The floor, which is most of the fix
///
/// `.run > *` gets `min-width: min-content`. That is the derived minimum the
/// ruling asks for, in this renderer's own unit and stated by the browser
/// rather than by anybody: a member cannot be squeezed narrower than what is
/// in it, so members in one flow push each other instead of overlapping. It
/// costs no query and no number, and it is what fixes all four measured widths
/// whichever fallback the group declared.
///
/// # What each fallback gets, exactly
///
/// [`Fallback::Wrap`] is `flex-wrap: wrap`, which is exact. The browser wraps
/// the run when the members no longer fit, deciding that from their own
/// intrinsic widths, which is the derived minimum doing the whole job.
///
/// [`Fallback::Stack`] is wrap plus `flex: 1 1 max-content` on the members, so
/// a member that cannot sit beside its sibling takes a line of its own and
/// fills it. For the two-member run this was ruled on -- a tab strip and a
/// band -- that is precisely "a row becomes a column".
///
/// [`Fallback::Shed`] and [`Fallback::Menu`] get wrap, and this renderer is
/// honouring less than the description says. **CSS cannot express either one
/// without breaking the ruling's own first constraint.** Both need to know that
/// the run is out of room in order to take a member out of it, a container
/// query is the only construct that can ask, and `@container` compares against
/// a `<length>` -- there is no `@container (inline-size < min-content)`. So
/// every honest spelling of Shed here needs an authored breakpoint, which is
/// the thing the ruling exists to forbid, and the dishonest ones are worse: a
/// clamped height clips by document order rather than by [`Priority`], and
/// `display: none` under a viewport `@media` is the `nth-child(n+5)` bug the
/// vocabulary replaced.
///
/// Wrapping is the right thing to do instead. It keeps every member reachable,
/// which is the property that was actually broken -- goingson's new-contact
/// button left the viewport entirely at 560 -- and it keeps rule 1. A renderer
/// answering with less than was described is precedented and deliberate here:
/// [`makeover_layout::Region::Columns`] says a terminal stacking a board's
/// columns is honouring the description rather than degrading it.
///
/// The real mechanism needs the shed members to have somewhere to go, which is
/// markup and belongs to quasi-webview: an overflow control is a member of the
/// run, and the description does not yet say that a member *is* one. Filed
/// rather than guessed at.
fn run_rules(opts: &Emit) -> String {
    let run = class("run", opts);
    let mut css = String::new();

    // `flex-wrap: nowrap` is stated rather than left to the default, because
    // the fallbacks below are read as overrides of this line and a reader
    // should not have to know which way flexbox leans to see that.
    //
    // No gap. Spacing between members is the app's, the same way this crate
    // states no margins anywhere else; a gap here would be a size, and the one
    // hardcoded size in the mechanism is makeover-geometry's contact patch.
    let _ = writeln!(
        css,
        ".{run} {{\n    display: flex;\n    flex-wrap: nowrap;\n    align-items: center;\n}}"
    );

    // The derived minimum, and the whole reason a member can no longer be
    // overlapped. `min-width: auto` is flexbox's default for a flex item and is
    // *not* the same thing: auto lets an item be compressed below its content
    // in a nowrap run, which is how a toolbar ends up drawn over a tab strip
    // even without anything leaving the flow.
    let _ = writeln!(css, ".{run} > * {{\n    min-width: min-content;\n}}");

    for fallback in [
        Fallback::Wrap,
        Fallback::Stack,
        Fallback::Shed,
        Fallback::Menu,
    ] {
        let name = fallback_class(fallback);
        let c = class(name, opts);
        let _ = writeln!(css, ".{c} {{\n    flex-wrap: wrap;\n}}");
        if matches!(fallback, Fallback::Stack) {
            let _ = writeln!(css, ".{c} > * {{\n    flex: 1 1 max-content;\n}}");
        }
    }

    css
}

/// Every class [`fallback_class`] can return, plus the run itself.
///
/// [`ROW_PART_CLASSES`](crate::list::ROW_PART_CLASSES)'s reasoning and the same
/// obligation: a `match` over a `#[non_exhaustive]` enum cannot be enumerated
/// from outside, so the list sits beside it and a test holds the two together.
/// `run` is in it because it is emitted in its own right rather than only as a
/// fallback's fallback.
pub const RUN_CLASSES: &[&str] = &["run", "run-wrap", "run-stack", "run-shed", "run-menu"];

/// The class a run carries for what it does when it is tight.
///
/// A run always carries `.run` as well, so an unrecognised fallback -- the enum
/// is `#[non_exhaustive]` -- lands as a plain nowrap row with the min-content
/// floor still under it. That is the safe failure: every member in flow and
/// none overlapped, which is the property, with only the rearrangement missing.
#[must_use]
pub fn fallback_class(fallback: Fallback) -> &'static str {
    match fallback {
        Fallback::Wrap => "run-wrap",
        Fallback::Stack => "run-stack",
        Fallback::Shed => "run-shed",
        Fallback::Menu => "run-menu",
        _ => "run",
    }
}

/// The progress trough these rules fill.
///
/// This was renderer-local chrome with nothing behind it until makeover-layout
/// 0.10.0, which is the unusual order: the tones below were emitted for every
/// bar in the tree while the only way to describe one was to concatenate the
/// numbers into a heading. `Meter` is the word that arrived late, and
/// [`meter::meter_html`](crate::meter::meter_html) is what now fills these.
///
/// The rules stay a superset of what a description can ask for. An app drawing
/// its own bar keeps these classes, which is what the four goingson grew
/// independently were adopted onto.
///
/// The trough is a [`Depth::Well`], the same reading a text field gets:
/// something with its content down inside it.
fn progress_rules(opts: &Emit) -> String {
    let progress = class("progress", opts);
    // `progress-fill` rather than a bare `fill`: an unprefixed build claims
    // these names in the app's own stylesheet, and `.fill` is grabby enough to
    // catch things that have nothing to do with progress. goingson already
    // calls it `.progress-fill`, so this is also the name that deletes.
    let fill = class("progress-fill", opts);
    let mut css = depth_rule(&progress, Depth::Well);

    // The untoned bar is `--action`, not [`Tone::Neutral`]. That is the one
    // place this differs from the badge rules, and deliberately: a badge with
    // no status is a muted label, while a bar with no status is still
    // reporting progress, and `content-muted` would read as disabled.
    let _ = writeln!(
        css,
        ".{progress} > .{fill} {{\n    background: var(--action);\n}}"
    );

    // A bar can be saying something, same as a badge: goingson colours subtask
    // progress as success and an over-estimate as danger, which is real
    // information rather than decoration. Emitting the tones is what lets that
    // survive adoption instead of staying hand-written.
    for tone in [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger] {
        let _ = writeln!(
            css,
            ".{progress} > .{fill}[data-tone=\"{0}\"] {{\n    background: var(--{0});\n}}",
            tone.token()
        );
    }
    css
}

/// A strip of figures, and the two spans inside each one.
///
/// Colour only, which is the deferral rule applied to a component that badly
/// wants to break it. A figure reads as a figure because the value is set large
/// over a small caption, and that is a size: `makeover-geometry` answers how
/// much space and this crate answers what the thing is. Emitting `font-size`
/// here would be this crate naming a value, which is the one thing it is defined
/// by not doing, and `progress_rules` is the precedent — it emits the tones and
/// never the width, because the width is not its to know.
///
/// So the arrangement and the type scale are the app's, and what is generated is
/// the part an app cannot get right by itself: which of the two spans carries
/// the tone.
fn figure_rules(opts: &Emit) -> String {
    let figure = class("figure", opts);
    let value = class("figure-value", opts);
    let caption = class("figure-caption", opts);
    let change = class("figure-change", opts);
    let mut css = String::new();

    let _ = writeln!(
        css,
        ".{figure} > .{value} {{\n    color: var(--{});\n}}",
        Tone::Neutral.token()
    );
    let _ = writeln!(
        css,
        ".{figure} > .{caption} {{\n    color: var(--content-muted);\n}}"
    );
    let _ = writeln!(
        css,
        ".{figure} > .{change} {{\n    color: var(--content-muted);\n}}"
    );

    // A toned figure tones one part and never the caption. The caption is the
    // noun and stays muted.
    //
    // Which part depends on whether there is a change, and that is the whole of
    // what 0.13.0 changed here. A figure with a delta is an ordinary number that
    // has moved in a direction worth reading, so the delta takes the colour and
    // the number stays plain; a figure without one has nowhere else to put it.
    // `:has` is what lets one attribute mean both, and the alternative was the
    // emitter deciding by writing the attribute onto a different element, which
    // leaves two elements able to disagree about a figure's one meaning.
    for tone in [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger] {
        let _ = writeln!(
            css,
            ".{figure}[data-tone=\"{0}\"] > .{change} {{\n    color: var(--{0});\n}}",
            tone.token()
        );
        let _ = writeln!(
            css,
            ".{figure}[data-tone=\"{0}\"]:not(:has(> .{change})) > .{value} \
             {{\n    color: var(--{0});\n}}",
            tone.token()
        );
    }
    css
}

/// A picture, its frame and its caption.
///
/// `makeover_layout::Image` arrived at 0.21.0, found by trying to describe MNW's
/// carousel and discovering nothing named a picture.
///
/// # The frame is a border, and this is the one place a bevel is wrong
///
/// 0.36.0 emitted [`Depth::Raised`] here through [`depth_rule`], the same call
/// `button` and `card` make. It was wrong, and MNW's landing page is where it
/// showed: **the frames had no visible edge at all.**
///
/// `Depth::Raised`'s edge is `--bevel-raised`, which is an *inset* shadow — a
/// 1px light run at the top-left and a dark one at the bottom-right, drawn
/// **inside** the element's box. On a button or a card that box is a surface
/// this crate owns, so an inset edge reads as the surface catching the light.
/// On a picture it is drawn on top of the picture, over whatever pixels the
/// image happens to have at its border. MNW's screenshots are light-on-light
/// parchment, so the light half landed on a light image and the frame
/// disappeared.
///
/// **You cannot bevel a surface you do not own.** A picture's content is the
/// app's, arrives at request time, and can be any colour, so its edge has to
/// sit *outside* the content rather than on it. That is a border.
///
/// The fill stays, and it is not decoration: it is what shows through a
/// transparent PNG and what stands in the frame's place while the image is
/// still loading.
///
/// This is a real limit on [`Depth`] rather than a special case. Every other
/// consumer of a depth draws its own surface; a picture is the first member
/// whose surface belongs to someone else.
///
/// # No size
///
/// `width: 100%` and nothing else. How large a picture is depends on the box it
/// was put in, which is the app's arrangement and `makeover-geometry`'s scales,
/// and a renderer that picked one would be answering for every consumer at
/// once. This is where `figure_rules` landed for the same reason.
fn picture_rules(opts: &Emit) -> String {
    let picture = class("picture", opts);
    let img = class("picture-img", opts);
    let caption = class("picture-caption", opts);
    let mut css = String::new();

    // Block, or an inline image sits on the text baseline and carries a
    // descender's worth of space under it that no app ever wants and every app
    // deletes by hand. The border is the frame; see the type docs for why it is
    // not the bevel every other surface here gets.
    let _ = writeln!(
        css,
        ".{img} {{\n    display: block;\n    width: 100%;\n    height: auto;\n    \
         background: var(--{});\n    border: {} solid var(--border);\n}}",
        Fill::Raised.token(),
        opts.border_width
    );

    // The two fits that need a rule. `Fit::Natural` emits no attribute at all,
    // so it is the bare rule above and needs nothing here.
    let _ = writeln!(
        css,
        ".{img}[data-fit=\"cover\"] {{\n    height: 100%;\n    object-fit: cover;\n}}"
    );
    let _ = writeln!(
        css,
        ".{img}[data-fit=\"contain\"] {{\n    height: 100%;\n    object-fit: contain;\n}}"
    );

    // A caption reads back one step, which is `figure-caption`'s answer and the
    // same claim: it says what the thing above it is, and it is not the thing.
    let _ = writeln!(
        css,
        ".{picture} > .{caption} {{\n    color: var(--content-muted);\n}}"
    );

    css
}

/// A region showing one child at a time, and the chrome that moves between them.
///
/// [`makeover_layout::Showing`] lets a description say that a region holds
/// several children and shows some of them. A renderer derives its own chrome
/// from that, which is what stops every renderer growing a `match` on a widget
/// name; these are the rules the derived chrome needs.
///
/// # Why the default is every child, and the enhancement takes them away
///
/// The controls are a lie until something binds them. A prev button rendered
/// into a document with no script is a control that looks live and answers
/// nothing, and the reader it lies to is exactly the one who cannot see the
/// other children either — the collapsing and the moving are the same half.
///
/// So the rules run in the direction the enhancement does. Nothing here hides a
/// child and nothing here shows a control. Whatever binds the region sets
/// `data-ready` on it, and that is what collapses the stack to one and reveals
/// the row that moves it. A reader with no script gets every child in order and
/// no controls, which is more content rather than less, and a reader with
/// script gets a settled page rather than a stack that jumps to one frame after
/// load.
///
/// MNW proved this shape by hand — a `<noscript>` stylesheet opening its
/// carousel back out — and it is here rather than there because the property is
/// the description's, not one app's.
///
/// # Not spacing
///
/// The row's gaps are `makeover-geometry`'s question and are absent for
/// [`row_rules`]'s reason. What is here is `display`, which carries no
/// magnitude, and the muted readout, which is the same claim `picture-caption`
/// makes: it says where you are among the children and it is not one of them.
fn showing_rules(opts: &Emit) -> String {
    let controls = class("showing", opts);
    let position = class("showing-position", opts);
    let frame = class("showing-frame", opts);
    let mut css = String::new();

    // Hidden until something binds it, which is the whole argument above.
    let _ = writeln!(css, ".{controls} {{\n    display: none;\n}}");
    // Block, and nothing about how the three sit in it. A button and a span are
    // inline already, so they make a row without this crate saying so, and
    // saying so is where `align-items` and a gap would follow -- both spacing,
    // both `makeover-geometry`'s, and `row_rules` refuses them for the same
    // reason.
    let _ = writeln!(
        css,
        "[data-ready] > .{controls} {{\n    display: block;\n}}"
    );

    // A child is in flow until the region is bound, and then only the current
    // one is. `.current` is a modifier for the reason `.chosen` and `.latched`
    // are: one name for the state, set by whoever knows it.
    let _ = writeln!(
        css,
        "[data-ready] > .{frame}:not(.current) {{\n    display: none;\n}}"
    );

    // Reads back one step. `picture-caption`'s rule and its reason.
    let _ = writeln!(css, ".{position} {{\n    color: var(--content-muted);\n}}");

    css
}

/// A time axis: the container, its gridlines and ruler, and the placed things.
///
/// `makeover-layout` 0.24.0's [`Track`](makeover_layout::Track), and the first
/// member here whose whole point is *position*. That makes the magnitude line
/// this crate keeps worth restating rather than assuming.
///
/// # Where the numbers come from
///
/// Every value that varies per item is a custom property the caller sets
/// inline, and every rule here reads one. `--track-at` and `--track-for` are
/// percentages of the span, which
/// [`Track::fraction`](makeover_layout::Track::fraction) computes once so three
/// renderers cannot disagree about it. Nothing here knows a pixel.
///
/// That is what lets the stylesheet stay static while the items move: an entry
/// carries `style="--track-at: 37.5%; --track-for: 4.166%"` and the rule below
/// turns it into a box. The alternative was emitting a rule per item, which is
/// a stylesheet that grows with the data.
///
/// **The height of the track is the app's**, not this crate's. 96 quarter-hour
/// slots at some slot height is a size, and a size is `makeover-geometry`'s
/// question -- the same refusal `figure_rules` and `placeholder_rules` make.
/// Percentages need a resolved height above them, so `.track` gets
/// `position: relative` and nothing else; the app says how tall a day is.
///
/// # Overlap
///
/// Two things at the same time is intrinsic to an axis and has no analogue in a
/// list. The description does not declare it -- `Placement::overlaps` derives it
/// from the times -- so what arrives here is a lane index and a lane count, and
/// the rule divides the width. A renderer that would rather stack them ignores
/// both properties and the defaults give it one full-width lane.
fn track_rules(opts: &Emit) -> String {
    let track = class("track", opts);
    let slot = class("track-slot", opts);
    let tick = class("track-tick", opts);
    let entry = class("track-entry", opts);
    let mut css = String::new();

    // The positioning context every entry resolves against, and the whole of
    // what this crate says about the container. No height: see the doc above.
    let _ = writeln!(css, ".{track} {{\n    position: relative;\n}}");

    // Gridlines and the ruler are the axis reading itself back, which is
    // `picture-caption` and `showing-position`'s claim: about the thing rather
    // than one of the things.
    //
    // `border_width` rather than a literal, the way `depth_rule` writes its
    // edge. A gridline is the one place a timeline would most naturally reach
    // for a hardcoded 1px, and a hardcoded 1px is this crate naming a size.
    let _ = writeln!(
        css,
        ".{slot} {{\n    border-top: {} solid var(--border);\n}}",
        opts.border_width
    );
    let _ = writeln!(css, ".{tick} {{\n    color: var(--content-muted);\n}}");

    // The one rule that does real work. Top and height are the placement;
    // left and width are the lane. Both lane properties default so an entry
    // that names neither is full width, which is the common case and the one a
    // renderer gets for free.
    let _ = writeln!(
        css,
        ".{entry} {{\n    \
         position: absolute;\n    \
         top: var(--track-at, 0%);\n    \
         height: var(--track-for, 100%);\n    \
         left: calc(var(--track-lane, 0) / var(--track-lanes, 1) * 100%);\n    \
         width: calc(100% / var(--track-lanes, 1));\n\
         }}"
    );

    css
}

/// A region's stand-in, and the header of a table that can be reordered.
///
/// Both are 0.12.0 members and both are colour and affordance only, which is
/// where `figure_rules` landed after trying to emit a type scale. How much room
/// a stand-in gets is a size — goingson has the same one at three, as
/// `--compact`, `--dashboard` and `--padded` — and a size is
/// `makeover-geometry`'s question.
///
/// The caret is the one thing here that is neither colour nor affordance, and it
/// is a renderer's own expression rather than a value the description named:
/// `aria-sort` is what the table actually says, and this turns it into something
/// visible for everyone not using a screen reader. A terminal draws its own; an
/// immediate-mode painter draws its own.
fn state_rules(opts: &Emit) -> String {
    let placeholder = class("placeholder", opts);
    let text = class("placeholder-text", opts);
    let heading = class("table-heading", opts);
    let mut css = String::new();

    let _ = writeln!(
        css,
        ".{placeholder} > .{text} {{\n    color: var(--content-muted);\n}}"
    );
    // Only the failure is toned. An empty list is the normal state of a new
    // install, and `Readiness::tone` is what says so.
    let _ = writeln!(
        css,
        ".{placeholder}[data-tone=\"{0}\"] > .{text} {{\n    color: var(--{0});\n}}",
        Tone::Danger.token()
    );

    // A header that reorders the table is a control, and the pointer is the
    // only part of saying so that is not the app's own type and spacing.
    let _ = writeln!(
        css,
        ".{heading}[data-sortable] {{\n    cursor: pointer;\n}}"
    );
    // The caret carries its own leading space, the way `makeover-tui` and
    // `makeover-immediate` both write `" \u{25B2}"`. It used to be emitted bare,
    // and both apps that adopted the vocabulary had to put the gap back in their
    // own stylesheets on the same afternoon -- each having to work out first that
    // app CSS outranks this crate's cascade layer, so adding the space the
    // obvious way, as `content`, silently wins over the glyph and leaves the
    // heading with no caret at all. A consumer should not have to know that, and
    // with the space emitted here there is nothing left for one to add.
    //
    // Three states, three tones, on the convention in wiki
    // `three-tone-convention`. A column in force is `content`; a column offering
    // to reorder and not doing it now is `content-secondary`, because it still
    // answers a press; a column that is not sortable emits no caret at all and
    // takes nothing. The idle arm used to hide its glyph and reserve the box,
    // which cost a reflow-free press and said nothing. It draws now, and the
    // reservation stops being a thing to get right.
    //
    // The glyph is `Sort::glyph`, escaped rather than written: a CSS `content`
    // string cannot carry the character literally through this file's own
    // escaping, and spelling it here as well would put the third copy back that
    // `makeover-layout` 0.27.5 exists to remove.
    let _ = writeln!(
        css,
        ".{heading}[data-sortable]::after \
         {{\n    content: \" {}\";\n    color: var(--content-secondary);\n}}",
        css_escape(Sort::Ascending.glyph())
    );
    for direction in [Sort::Ascending, Sort::Descending] {
        let _ = writeln!(
            css,
            ".{heading}[aria-sort=\"{}\"]::after \
             {{\n    content: \" {}\";\n    color: var(--content);\n}}",
            direction.as_str(),
            css_escape(direction.glyph())
        );
    }
    css
}

/// The frame a table sits in.
///
/// # Why this is a CSS table and not the grid the rest of the module assumes
///
/// A grid row needs `grid-template-columns`, which has to name every column in
/// order, so it cannot be written without knowing the columns. That is what
/// [`list::narrowing_css`] is for, and it works: goingson builds `tables.css` in
/// its own `build.rs` out of it, and nothing here changes that.
///
/// It does not work for a table a *description* produced. Those columns are
/// known at render time rather than at build time, and the rules would have to
/// travel with the markup: a `<style>` element per table, which needs
/// `style-src 'unsafe-inline'` and so blocks the MNW server's standing plan to
/// drop it. The head is not an escape: a table swapped in by htmx after a
/// delete arrives as a fragment with no head at all.
///
/// A CSS table aligns its columns across rows knowing nothing about how many
/// there are, so there is no track list to emit and nothing per-table to carry.
/// The cost is that a described table cannot take a per-column fixed length,
/// which costs nothing today: [`Sizing`](list::Sizing) is looked up by column
/// name and a description carries no lengths to put in it, so every track a
/// described table could ask for is already content, fill or auto.
///
/// [`Priority`] hiding is unchanged in kind. It moves from a generated
/// `display: none` per dropped column to one rule per drop class, which is the
/// same fact addressed by class rather than by cutoff, and still never by
/// position.
fn table_rules(opts: &Emit) -> String {
    let table = class("table", opts);
    let head = class("table-head", opts);
    let row = class("table-row", opts);
    let heading = class("table-heading", opts);
    let cell = class("cell", opts);
    let mut css = String::new();

    let _ = writeln!(
        css,
        ".{table} {{\n    display: table;\n    width: 100%;\n}}"
    );
    let _ = writeln!(css, ".{head},\n.{row} {{\n    display: table-row;\n}}");
    let _ = writeln!(css, ".{heading},\n.{cell} {{\n    display: table-cell;\n}}");

    // A content column shrinks to what is in it. `width: 1%` is how a CSS table
    // is told that: auto layout hands the slack to the columns that asked for
    // room, and a column asking for almost none gets what it needs and no more.
    // The `nowrap` is what stops it being given less by wrapping.
    let _ = writeln!(
        css,
        ".{} {{\n    white-space: nowrap;\n    width: 1%;\n}}",
        class("cell-content", opts)
    );

    // A fixed column has no length to be fixed to. The description carries none
    // and `Sizing` is not reachable from here, so it behaves as content: the
    // honest answer to a width nobody supplied, and the same one `Sizing::track`
    // gives it.
    let _ = writeln!(
        css,
        ".{} {{\n    white-space: nowrap;\n}}",
        class("cell-fixed", opts)
    );

    // Optional columns go at the narrowest class, secondary ones go with them,
    // which is the cutoff walk `kept_at` describes said as two media queries.
    // Essential columns have no rule at all, because never dropping is what not
    // being mentioned already means.
    for (size, drops) in [
        (
            SizeClass::Compact,
            &["cell-drops-first", "cell-drops-next"][..],
        ),
        (SizeClass::Medium, &["cell-drops-first"][..]),
    ] {
        let selectors: Vec<String> = drops
            .iter()
            .map(|drop| format!(".{}", class(drop, opts)))
            .collect();
        css.push_str(&gated(
            Some(&size.media_condition()),
            &format!("{} {{\n    display: none;\n}}\n", selectors.join(",\n")),
        ));
    }

    // What is inside a cell, which the table side could not say until
    // makeover-layout 0.14.0. Every cell was one `.cell` and one content
    // colour, so a button in a cell was painted as text -- the drift
    // `RowPart::intent` has prevented for list rows since 0.2.0 and prevented
    // for nothing here.
    //
    // The colour goes on `.cell-value` rather than on `.cell`, and that
    // placement is the whole fix. On the container it would cascade into the
    // tokens and the controls sitting beside the text, which is the bug said
    // in one rule; on the part that is text, it reaches text and stops.
    for part in [
        CellPart::Value,
        CellPart::Tokens,
        CellPart::Actions,
        CellPart::Link,
    ] {
        // Three of the four inherit, each for its own reason: a token carries
        // its own tone, an action is a control rather than text, and a link
        // takes the action colour from the anchor it is. `CellPart::intent`
        // says so by answering with the intent inheriting already gives, and
        // pinning that would be louder than saying nothing.
        //
        // Written as a skip-list rather than as a match on Value, so a member
        // added upstream gets its intent emitted rather than being silently
        // dropped. That is the same trade `part_class`'s fallback makes: land
        // plainly, never land as nothing.
        if !matches!(part, CellPart::Tokens | CellPart::Actions | CellPart::Link) {
            let _ = writeln!(
                css,
                ".{} {{\n    color: var(--{});\n}}",
                class(cell_part_class(part), opts),
                part.intent()
            );
        }
    }

    css
}

/// The component layer: every named thing phase A emits.
///
/// No scrollbar track. It was on the phase A list and came off: eight lines of
/// `::-webkit-scrollbar` with no shape a terminal or an immediate-mode painter
/// would want handed to it, so it stays with the apps.
#[must_use]
pub fn component_rules(opts: &Emit) -> String {
    let mut css = String::new();
    css.push_str(&surface_rules(opts));
    css.push_str(&link_rules(opts));
    css.push_str(&token_rules(opts));
    css.push_str(&selector_rules(opts));
    css.push_str(&row_rules(opts));
    css.push_str(&run_rules(opts));
    css.push_str(&progress_rules(opts));
    css.push_str(&figure_rules(opts));
    css.push_str(&picture_rules(opts));
    css.push_str(&showing_rules(opts));
    css.push_str(&track_rules(opts));
    css.push_str(&state_rules(opts));
    css.push_str(&table_rules(opts));
    css.push_str(&facet::facet_rules(opts));
    css.push_str(&form::editor_rules(opts));
    css.push_str(&form::suggestion_rules(opts));
    css.push_str(&form::unit_rules(opts));
    css
}

/// The whole phase-A stylesheet: properties, depth rules and components, in
/// [`CSS_LAYER`], under a generated-file banner.
///
/// The banner sits outside the layer, because a comment participates in no
/// cascade and a reader opening the file should see what it is before seeing
/// an at-rule.
#[must_use]
pub fn stylesheet(opts: &Emit) -> String {
    format!(
        "/* Generated by makeover-webview from makeover-layout. Do not edit.\n   \
         Depth is a fill and an edge together; naming them apart is what let\n   \
         them disagree. See the crate's README and wiki note makeover-layout.\n\n   \
         Everything below is in the `{CSS_LAYER}` cascade layer. Declare the\n   \
         order once in your own stylesheet, or this layer's position is decided\n   \
         by whichever generated file the browser happens to see first:\n\n   \
         @layer {CSS_LAYER}, base, components, responsive; */\n{}",
        in_css_layer(&format!(
            ":root {{\n{}}}\n\n{}\n{}",
            bevel_properties(opts),
            depth_rules(opts),
            component_rules(opts)
        ))
    )
}

#[cfg(test)]
mod tests {
    use super::*;
    use makeover_layout::Edge;

    #[test]
    fn every_fallback_class_is_one_a_checker_knows_about() {
        // The obligation ROW_PART_CLASSES carries, for the same reason: a class
        // this crate can write and the vocabulary list does not carry is
        // invisible to the dead-vocabulary seal and to the overlap check both.
        for fallback in [
            Fallback::Wrap,
            Fallback::Stack,
            Fallback::Shed,
            Fallback::Menu,
        ] {
            assert!(
                RUN_CLASSES.contains(&fallback_class(fallback)),
                "{fallback:?} is missing from RUN_CLASSES"
            );
        }
        let names = crate::vocabulary::names(&Emit::default());
        for name in RUN_CLASSES {
            assert!(names.contains(*name), "{name} is not in the vocabulary");
        }
    }

    #[test]
    fn a_run_gives_every_member_a_floor_it_cannot_be_squeezed_below() {
        // The whole of what stops the overlap, and it is not a fallback: it
        // applies to every run whatever the group declared. flexbox's default
        // min-width is auto, which lets an item be compressed below its own
        // content in a nowrap row, and that is how a toolbar is drawn over a
        // tab strip even with nothing out of flow.
        let css = run_rules(&Emit::default());
        assert!(css.contains(".run > * {\n    min-width: min-content;\n}"));
        // No number anywhere in it. The minimum is derived by the browser from
        // what the members contain, which is the ruling's own requirement.
        assert!(!css.contains("px"));
        assert!(!css.contains("rem"));
        assert!(!css.contains("@media"));
    }

    #[test]
    fn room_is_never_asked_of_the_viewport() {
        // The 913 case: a window in SizeClass::Expanded holding a group out of
        // room. A viewport query answers about the window and would be wrong
        // about the group, which is why the table's @media walk is not the
        // precedent this follows.
        let css = run_rules(&Emit::default());
        for size in [SizeClass::Compact, SizeClass::Medium] {
            assert!(!css.contains(&size.media_condition()));
        }
    }

    #[test]
    fn every_fallback_lands_as_a_class_and_an_unknown_one_lands_plainly() {
        let css = run_rules(&Emit::default());
        for fallback in [
            Fallback::Wrap,
            Fallback::Stack,
            Fallback::Shed,
            Fallback::Menu,
        ] {
            let class = fallback_class(fallback);
            assert!(css.contains(&format!(".{class} {{")), "{class} unemitted");
        }
        // Stack is the one that also says what a member does with the line it
        // took, which is what separates it from wrapping.
        assert!(css.contains(".run-stack > * {\n    flex: 1 1 max-content;\n}"));
    }

    #[test]
    fn the_emitted_bevel_matches_what_the_apps_already_hand_write() {
        // Balanced Breakfast's styles.css, verbatim. Adoption has to be a
        // deletion, not a redesign, or nobody will take it.
        let opts = Emit::default();
        assert_eq!(
            bevel_shadow(Bevel::Raised, &opts),
            "inset 1px 1px 0 var(--bevel-light), inset -1px -1px 0 var(--bevel-dark)"
        );
        assert_eq!(
            bevel_shadow(Bevel::Inset, &opts),
            "inset 1px 1px 0 var(--bevel-dark), inset -1px -1px 0 var(--bevel-light)"
        );
    }

    #[test]
    fn no_colour_ever_reaches_the_output() {
        let css = stylesheet(&Emit::default());
        assert!(!css.contains('#'), "a hex literal escaped into the CSS");
        assert!(
            !css.contains("rgb"),
            "a colour function escaped into the CSS"
        );
        // Every colour is named, never resolved.
        assert!(css.contains("var(--surface-raised)"));
        assert!(css.contains("var(--bevel-light)"));
    }

    #[test]
    fn a_well_falls_back_through_css_rather_than_through_rust() {
        assert_eq!(
            fill_var(Fill::Well),
            "var(--surface-well, var(--surface-page))"
        );
        // Nothing else needs one.
        assert_eq!(fill_var(Fill::Raised), "var(--surface-raised)");
        assert_eq!(fill_var(Fill::Page), "var(--surface-page)");
    }

    #[test]
    fn raised_and_well_do_not_collapse_onto_each_other() {
        let css = depth_rules(&Emit::default());
        assert!(css.contains(".raised {"));
        assert!(css.contains(".well {"));
        assert!(css.contains("var(--bevel-raised)"));
        assert!(css.contains("var(--bevel-inset)"));
    }

    /// The cast shadow is composed here from the tone `makeover` derives, so
    /// neither crate has to hold the other's numbers.
    ///
    /// It is a `:root` property and deliberately not a depth class. There is no
    /// `Depth::Overlay` in the description layer, and adding one would be a
    /// claim about what a screen means rather than about how it is painted;
    /// until something asks for it, a consumer names the property on the rule
    /// for the menu or the toast it already has.
    #[test]
    fn the_cast_shadow_is_a_root_property_not_a_depth() {
        let css = bevel_properties(&Emit::default());
        assert!(css.contains("--elevation-overlay:"));
        assert!(css.contains("var(--elevation)"));
        assert!(
            !depth_rules(&Emit::default()).contains("elevation"),
            "elevation is not a depth class"
        );
    }

    #[test]
    fn the_cascade_carries_the_pressed_state() {
        let css = surface_rules(&Emit::default());
        // The one thing this renderer gets free that the other two resolve by
        // hand, eighteen call sites deep in audiofiles' case. Asserted on a
        // named surface: pressing belongs to the control, not to the depth.
        assert!(css.contains(".card:active {"));
        assert!(css.contains(".button:active {"));
    }

    #[test]
    fn the_depth_class_is_a_surface_and_not_a_control() {
        let css = depth_rules(&Emit::default());
        // The static surface the vocabulary was missing. Sixteen goingson
        // elements wore .card and cancelled its hover and press to get this,
        // because a raised object that is not pressable had no other spelling.
        for state in [":hover", ":active", ":focus-visible", ":disabled"] {
            assert!(
                !css.contains(&format!(".raised{state}")),
                "the depth class claimed {state}: {css}"
            );
        }
        assert!(css.contains("var(--bevel-raised)"), "still raised: {css}");
    }

    #[test]
    fn pressing_moves_the_fill_and_not_only_the_edge() {
        // The decision-1 guard, and the regression that mattered: emitting the
        // bevel flip alone is what left goingson hand-writing `background:
        // var(--surface-sunken)` on .btn, .card and .tag/.badge alike, so none
        // of the three could be deleted.
        let pressed = interactive_rules("button", Depth::Raised, &Emit::default());
        assert!(pressed.contains(".button:active {"));
        assert!(
            pressed.contains("background: var(--surface-well, var(--surface-page))"),
            "pressed dropped its fill: {pressed}"
        );
        assert!(pressed.contains("box-shadow: var(--bevel-inset)"));
    }

    #[test]
    fn pressed_takes_its_fill_from_the_description_not_from_the_app() {
        // goingson presses to --surface-sunken. The description says a pressed
        // raised region reads as a well, and makeover says outright that
        // surface-sunken cannot serve as one, so the app is the thing that
        // moves.
        //
        // Scoped to the pressed rules rather than to the whole sheet: since
        // makeover-layout 0.3.0 an unchosen tab is legitimately
        // --surface-sunken, so the token appearing somewhere in the output no
        // longer means the app's choice leaked in.
        let css = stylesheet(&Emit::default());
        let mut checked = 0;
        for rule in css.split("}\n") {
            if !rule.contains(":active") {
                continue;
            }
            checked += 1;
            assert!(
                !rule.contains("surface-sunken"),
                "a pressed rule took the app's fill: {rule}"
            );
        }
        assert!(checked > 0, "no pressed rules found to check");
        assert_eq!(
            Depth::Raised.pressed().fill(),
            Some(Fill::Well),
            "the description changed under us"
        );
    }

    #[test]
    fn the_whole_stylesheet_is_emitted_in_the_family_layer() {
        // The point of 0.11.0. Unlayered normal declarations outrank every
        // named layer, so an app declaring `@layer base, components` loses
        // every rule it owns to this file until this file is layered too.
        let css = stylesheet(&Emit::default());
        assert!(css.contains(&format!("@layer {CSS_LAYER} {{")));

        // Exactly one layer block, and nothing outside it but the banner.
        assert_eq!(css.matches("@layer").count(), 2, "banner names it once");
        let opened = css.find("@layer makeover {").expect("layer opens");
        for (i, line) in css.lines().enumerate() {
            let before_layer = css.lines().take(i).map(str::len).sum::<usize>() < opened;
            if before_layer || line.is_empty() {
                continue;
            }
            assert!(
                line.starts_with("    ") || line == "}" || line.starts_with("   "),
                "line outside the layer: {line:?}"
            );
        }
    }

    #[test]
    fn the_generated_sheet_carries_no_trailing_whitespace() {
        // A checked-in generated file that a formatter wants to rewrite is a
        // diff every time somebody saves it.
        let css = stylesheet(&Emit::default());
        for (i, line) in css.lines().enumerate() {
            assert_eq!(line, line.trim_end(), "trailing whitespace on line {i}");
        }
    }

    #[test]
    fn the_banner_tells_an_app_how_to_order_the_layer() {
        // Without a declared order the layer's position depends on which
        // generated file the browser sees first, which is not a contract.
        let css = stylesheet(&Emit::default());
        assert!(css.contains("@layer makeover, base, components, responsive;"));
        // And the banner is outside the layer, not a rule inside it.
        assert!(css.starts_with("/* Generated by makeover-webview"));
    }

    #[test]
    fn a_primitive_owns_every_state_it_implies() {
        // The whole point of 0.10.0. Anything emitting a hover rule owes the
        // other three, or the consuming app supplies them by out-specifying a
        // rule it does not own: 19 such rules in goingson, 21 in the MNW
        // server, and three focus rings that do not match.
        let css = stylesheet(&Emit::default());
        for selector in ["button", "card", "chip", "tab", "segment", "toggle"] {
            assert!(css.contains(&format!(".{selector}:hover {{")), "{selector}");
            assert!(
                css.contains(&format!(".{selector}:active {{")),
                "{selector}"
            );
            assert!(
                css.contains(&format!(".{selector}:focus-visible {{")),
                "{selector} has no focus ring"
            );
            assert!(
                css.contains(&format!(".{selector}:disabled,")),
                "{selector} has no disabled state"
            );
        }
    }

    #[test]
    fn a_field_takes_focus_and_refuses_input_without_taking_a_hover() {
        // A text field does not light up under the pointer, so it gets the two
        // states it has and not the two it does not.
        let css = stylesheet(&Emit::default());
        assert!(css.contains(".field:focus-visible {"));
        assert!(css.contains(".field:disabled,"));
        assert!(!css.contains(".field:hover {"));
        assert!(!css.contains(".field:active {"));
    }

    #[test]
    fn disabled_is_emitted_after_hover_so_source_order_settles_it() {
        // Every one of these selectors is specificity (0,2,0), so nothing but
        // order decides which wins. A disabled button taking the hover fill is
        // the exact bug goingson's `.button:disabled:hover` was written to fix,
        // and the reason it had to reach (0,3,0) to do it.
        let css = interactive_rules("button", Depth::Raised, &Emit::default());
        let hover = css.find(":hover").expect("hover");
        let active = css.find(":active").expect("active");
        let focus = css.find(":focus-visible").expect("focus");
        let disabled = css.find(":disabled").expect("disabled");
        assert!(hover < active && active < focus && focus < disabled);

        // And it restores the surface, or the hover fill survives underneath.
        let tail = &css[disabled..];
        assert!(tail.contains("background: var(--surface-raised)"));
    }

    #[test]
    fn a_disabled_state_reaches_things_that_cannot_be_disabled() {
        // `:disabled` matches form elements only, and a chip is a div. Keying
        // on the ARIA attribute too is the pattern the invalid field already
        // set: one fact, read by the styling and the accessibility tree alike.
        let css = disabled_rule("chip", Depth::Raised);
        assert!(css.contains(".chip:disabled,"));
        assert!(css.contains(".chip[aria-disabled=\"true\"]"));
        assert!(css.contains("cursor: not-allowed"));
    }

    #[test]
    fn the_focus_ring_does_not_disturb_the_bevel_it_lands_on() {
        // `outline` has its own property, so unlike the invalid ring there is
        // no bevel to restate beside it and nothing to keep in agreement.
        let opts = Emit::default();
        let css = focus_rule("button", Depth::Raised, &opts);
        assert!(css.contains("outline: 2px solid var(--focus-ring)"));
        assert!(!css.contains("box-shadow"), "the ring restated the bevel");
    }

    #[test]
    fn a_well_takes_the_ring_inside_and_a_raised_surface_outside() {
        // One ring, placed by depth. The offset comes off `Depth::bevel` and
        // not off a per-component choice, which is what gave three apps three
        // different rings.
        let opts = Emit::default();
        assert!(focus_rule("field", Depth::Well, &opts).contains("outline-offset: calc(-1 * 2px)"));
        assert!(focus_rule("button", Depth::Raised, &opts).contains("outline-offset: 2px"));
        // Nothing to sit inside of, so it sits outside.
        assert!(focus_rule("badge", Depth::Sunken, &opts).contains("outline-offset: 2px"));

        // And the ring is not the bevel. Reusing border_width emitted a 1px
        // ring that every consumer had already overridden.
        assert_ne!(opts.focus_width, opts.border_width);
    }

    #[test]
    fn hover_is_gated_on_capability_and_the_keyboard_path_is_not() {
        // goingson's section 60 exists only to take back the hover state this
        // crate handed it. Gating at the source is what deletes that section
        // in all three apps rather than having each fight for it.
        let css = stylesheet(&Emit::default());
        let condition = format!("@media {}", Density::Pointer.media_condition());
        assert!(css.contains(&condition));

        // What is gated is every hover state the surfaces carry. The row's
        // actions used to be the other half of this test and are not gated any
        // more, because they are not hidden any more: a rule that reveals
        // nothing needs no capability answer.
        let gated: Vec<&str> = css.lines().filter(|line| line.contains(":hover")).collect();
        assert!(!gated.is_empty(), "{css}");
        for line in gated {
            let indent = line.len() - line.trim_start().len();
            assert!(indent > 4, "an ungated hover rule: {line}");
        }
        assert!(!css.contains(".row:hover"), "{css}");
    }

    #[test]
    fn the_capability_answer_is_asked_for_and_not_assumed() {
        // Both halves come from the crates that own them. If `makeover-touch`
        // ever says a fingertip has hover, this stops gating on its own.
        assert!(!Affordance::Hover.available(Density::Touch, SizeClass::Compact));
        assert!(Affordance::Hover.available(Density::Pointer, SizeClass::Compact));
        assert_eq!(hover_condition(), Some(Density::Pointer.media_condition()));

        // And the size class passed to that call is not a claim about width.
        assert!(Affordance::Hover.reads_density());
        for size in [SizeClass::Compact, SizeClass::Medium, SizeClass::Expanded] {
            assert!(!Affordance::Hover.available(Density::Touch, size));
        }
    }

    #[test]
    fn hover_resolves_against_the_token_makeover_already_derives() {
        let css = interactive_rules("card", Depth::Raised, &Emit::default());
        assert!(css.contains(".card:hover {"));
        assert!(css.contains("background: var(--hover-surface)"));
        // Not the app's choice, which was --surface-overlay.
        assert!(!css.contains("surface-overlay"));
    }

    #[test]
    fn a_badge_gets_no_edge_and_no_fill() {
        // Decision 2, and the one visible redesign in phase A. Token::Badge is
        // Flat: an edge on a label says it can be pressed.
        let css = token_rules(&Emit::default());
        let badge = css
            .lines()
            .skip_while(|l| !l.starts_with(".badge {"))
            .take_while(|l| !l.starts_with('}'))
            .collect::<Vec<_>>()
            .join("\n");
        assert!(!badge.contains("box-shadow"), "badge kept an edge: {badge}");
        assert!(!badge.contains("background"), "badge kept a fill: {badge}");
        assert_eq!(Token::Badge.depth(false), Depth::Flat);
        assert_eq!(Token::Badge.depth(true), Depth::Flat);
    }

    #[test]
    fn a_badge_carries_a_tone_and_neutral_is_the_bare_class() {
        let css = token_rules(&Emit::default());
        // Neutral is the absence of a status, not a status named "none".
        assert!(css.contains(".badge {\n    color: var(--content-muted);"));
        assert!(!css.contains("data-tone=\"content-muted\""));
        for tone in ["info", "success", "warning", "danger"] {
            assert!(
                css.contains(&format!(".badge[data-tone=\"{tone}\"]")),
                "missing tone {tone}"
            );
            assert!(css.contains(&format!("color: var(--{tone})")));
        }
    }

    #[test]
    fn a_chip_is_raised_and_latches_into_a_well() {
        let css = token_rules(&Emit::default());
        assert!(css.contains(".chip {"));
        assert!(css.contains(".chip.latched {"));
        assert!(css.contains(".chip:active {"));
        // The whole difference from a badge: it answers a click.
        assert!(Token::Chip { removable: false }.interactive());
        assert!(!Token::Badge.interactive());
    }

    #[test]
    fn only_a_tab_comes_forward_when_chosen() {
        // The folder semantic. Collapsing the three selectors would lose it.
        let css = selector_rules(&Emit::default());
        assert!(css.contains(".tab.chosen {"));
        assert!(css.contains(".segment.chosen {"));
        assert!(css.contains(".toggle.chosen {"));
        assert_eq!(Selector::Tabs.chosen(), Depth::Raised);
        assert_eq!(Selector::Segmented.chosen(), Depth::Well);
        assert_eq!(Selector::Toggle.chosen(), Depth::Well);

        let tab = css
            .lines()
            .skip_while(|l| !l.starts_with(".tab.chosen {"))
            .take_while(|l| !l.starts_with('}'))
            .collect::<Vec<_>>()
            .join("\n");
        assert!(
            tab.contains("var(--bevel-raised)"),
            "tab was held in: {tab}"
        );
    }

    #[test]
    fn an_unchosen_tab_recedes_without_looking_picked() {
        let css = selector_rules(&Emit::default());
        // Recessed by colour and given no edge. An edge would make every option
        // look picked; flat would leave the chosen one nothing to come forward
        // from, which is the gap makeover-layout 0.3.0 closed.
        assert!(
            css.contains(".tab {\n    background: var(--surface-sunken);\n}"),
            "unchosen tab is not recessed: {css}"
        );
        assert_eq!(Selector::Tabs.unchosen(), Depth::Sunken);
        assert!(css.contains(".tab:hover {"));
    }

    #[test]
    fn a_segment_stands_up_so_the_chosen_one_can_be_held_in() {
        // The inverse of the tab, and why the three selectors are not one
        // member with a flag.
        let css = selector_rules(&Emit::default());
        assert!(css.contains(".segment {\n    background: var(--surface-raised);"));
        assert_eq!(Selector::Segmented.unchosen(), Depth::Raised);
        assert_eq!(Selector::Segmented.chosen(), Depth::Well);
    }

    #[test]
    fn a_rows_actions_are_shown_at_rest() {
        let css = row_rules(&Emit::default());

        // The hover reveal is gone, and with it every escape it needed. What
        // it hid was hidden from pointer users alone, who are the ones
        // scanning a list to learn what can be done to a row.
        assert!(!css.contains("opacity"), "{css}");
        assert!(!css.contains("pointer-events"), "{css}");
        assert!(!css.contains(":hover"), "{css}");
        assert!(!css.contains(":focus-within"), "{css}");

        // Nor is it hidden any other way. `display: none` would reflow the row
        // and `visibility: hidden` would take the actions out of the focus
        // order; the point is that neither is reached for.
        assert!(!css.contains("display: none"), "{css}");
        assert!(!css.contains("visibility:"), "{css}");
    }

    #[test]
    fn a_figures_tone_lands_on_the_delta_when_there_is_one() {
        // 0.13.0. The delta is the part that reads as good or bad; the number
        // itself is an ordinary fact. A figure with no delta has nowhere else to
        // put the colour, so the value takes it, and `:has` is what lets one
        // attribute mean both without the emitter choosing an element.
        let css = stylesheet(&Emit::default());

        assert!(
            css.contains(".figure[data-tone=\"success\"] > .figure-change"),
            "{css}"
        );
        assert!(
            css.contains(
                ".figure[data-tone=\"success\"]:not(:has(> .figure-change)) > .figure-value"
            ),
            "{css}"
        );
        // The caption is the noun and never takes the tone.
        assert!(
            !css.contains("[data-tone=\"success\"] > .figure-caption"),
            "{css}"
        );
    }

    #[test]
    fn the_three_text_parts_take_their_intents_and_actions_inherits() {
        let css = row_rules(&Emit::default());
        assert!(css.contains(".row-primary {\n    color: var(--content);"));
        assert!(css.contains(".row-secondary {\n    color: var(--content-secondary);"));
        assert!(css.contains(".row-meta {\n    color: var(--content-muted);"));
        // Actions carry controls, not text. Pinning the colour it would inherit
        // anyway is louder than saying nothing.
        assert!(!css.contains(".row-actions {\n    color:"));
    }

    #[test]
    fn the_token_strip_takes_no_colour_of_its_own() {
        // makeover-layout 0.9.0. A token carries its own tone, so a colour on
        // the strip would be a rule fighting the things sitting in it -- the
        // same reasoning as actions, reached for a different reason.
        let css = row_rules(&Emit::default());
        assert!(!css.contains(".row-tokens {\n    color:"));
    }

    #[test]
    fn an_unknown_row_part_renders_plainly_rather_than_failing_to_build() {
        // What `#[non_exhaustive]` bought and what it cost. `part_class` can no
        // longer be exhaustive, so a member added upstream lands as a bare
        // class with no rule instead of stopping the build. Asserting the
        // fallback exists is what keeps it from being written as `unreachable!`
        // by someone who reads the match as closed.
        assert_eq!(part_class(RowPart::Tokens), "row-tokens");
        assert_eq!(part_class(RowPart::Meta), "row-meta");
    }

    #[test]
    fn a_link_takes_the_action_colour_the_theme_actually_defines() {
        // `--action-primary` shipped here for months and no theme has ever
        // defined it, so every `.link` dropped its colour declaration outright
        // and fell back to inherited text. Nothing caught it because the sheet
        // is valid CSS either way; MNW's no-undefined-token lint is what found
        // it, 2026-08-14. The hover arm two lines below was always `--action-hover`,
        // which is what makes the typo legible in hindsight.
        let css = link_rules(&Emit::default());
        assert!(css.contains("color: var(--action);"));
        assert!(!css.contains("--action-primary"));
        assert!(css.contains("color: var(--action-hover);"));
    }

    #[test]
    fn the_progress_trough_is_a_well() {
        let css = progress_rules(&Emit::default());
        assert!(css.contains(".progress {"));
        assert!(css.contains("box-shadow: var(--bevel-inset)"));
        assert!(css.contains(".progress > .progress-fill {"));
        assert!(css.contains("background: var(--action)"));
        // A bare `.fill` would catch things that have nothing to do with
        // progress once the sheet lands unprefixed.
        assert!(!css.contains("> .fill "));
    }

    #[test]
    fn a_progress_bar_can_carry_a_tone_and_defaults_to_action() {
        let css = progress_rules(&Emit::default());
        // Untoned is --action, not Tone::Neutral's content-muted: a bar with no
        // status is still reporting progress, and muted would read as disabled.
        assert!(css.contains(".progress > .progress-fill {\n    background: var(--action);"));
        assert!(!css.contains("progress-fill {\n    color: var(--content-muted)"));
        for tone in ["info", "success", "warning", "danger"] {
            assert!(
                css.contains(&format!(".progress > .progress-fill[data-tone=\"{tone}\"]")),
                "missing progress tone {tone}"
            );
        }
        // goingson's two live cases, which is why the tones are emitted at all.
        assert!(css.contains("[data-tone=\"success\"] {\n    background: var(--success);"));
        assert!(css.contains("[data-tone=\"danger\"] {\n    background: var(--danger);"));
    }

    #[test]
    fn no_scrollbar_track_is_emitted() {
        // Decision 3's negative half. It was on the phase A list and came off;
        // this is what stops it drifting back in.
        let css = stylesheet(&Emit::default());
        assert!(!css.contains("scrollbar"));
        assert!(!css.contains("::-webkit"));
    }

    #[test]
    fn an_invalid_field_is_ringed_without_being_lit() {
        let css = surface_rules(&Emit::default());
        assert!(css.contains(".field {"));
        // The ARIA attribute, not a class: one fact, read by both the visual
        // and the accessible state, so they cannot drift.
        assert!(css.contains(".field[aria-invalid=\"true\"] {"));
        assert!(!css.contains(".field.invalid"));
        // A flat ring: this edge says "wrong", and a two-tone bevel would have
        // it say "raised" at the same time.
        assert!(css.contains("0 0 0 1px var(--danger)"));
    }

    #[test]
    fn an_invalid_field_keeps_the_well_underneath_it() {
        // box-shadow is not additive. A lone ring replaces the bevel and drops
        // the well out from under the field, which is what this emitted before
        // 0.5.0 and is the whole reason the rule composes.
        let css = surface_rules(&Emit::default());
        let invalid = css
            .lines()
            .skip_while(|l| !l.starts_with(".field[aria-invalid"))
            .take_while(|l| !l.starts_with('}'))
            .collect::<Vec<_>>()
            .join("\n");
        assert!(
            invalid.contains("var(--bevel-inset)"),
            "the well was dropped: {invalid}"
        );
        assert!(invalid.contains("var(--danger)"));
    }

    #[test]
    fn button_and_card_come_out_identical_by_construction() {
        // The duplication phase A deletes. They are the same composition, so
        // the only honest way to emit both is from one call.
        let opts = Emit::default();
        let css = surface_rules(&opts);
        assert_eq!(
            depth_declarations(Depth::Raised),
            depth_declarations(Depth::Raised)
        );
        assert!(css.contains(".button {"));
        assert!(css.contains(".card {"));
        assert_eq!(
            interactive_rules("button", Depth::Raised, &Emit::default()).replace("button", "card"),
            interactive_rules("card", Depth::Raised, &Emit::default())
        );
    }

    #[test]
    fn a_prefix_reaches_the_component_classes_too() {
        let opts = Emit {
            class_prefix: "mo-",
            ..Emit::default()
        };
        let css = stylesheet(&opts);
        for name in [
            "mo-button",
            "mo-card",
            "mo-field",
            "mo-badge",
            "mo-chip",
            "mo-tab",
            "mo-row-primary",
            "mo-progress",
            "mo-progress-fill",
        ] {
            assert!(css.contains(&format!(".{name}")), "unprefixed: {name}");
        }
        // The bare names must be gone entirely, or a prefixed build still
        // collides with the app's own stylesheet.
        assert!(!css.contains(".button {"));
        assert!(!css.contains(".card {"));
        assert!(!css.contains(".badge {"));
    }

    #[test]
    fn the_class_a_renderer_puts_on_an_option_is_the_one_the_rules_key_off() {
        // `option_class` is the contract a screen renderer writes markup
        // against, and the rules below are the other half of it. They come off
        // one mapping now, so this asserts the mapping is the one that reaches
        // the stylesheet rather than that two lists still agree.
        let css = stylesheet(&Emit::default());
        for selector in [Selector::Tabs, Selector::Segmented, Selector::Toggle] {
            let name = option_class(selector);
            assert!(css.contains(&format!(".{name} {{")), "{name}: {css}");
            assert!(css.contains(&format!(".{name}.chosen {{")), "{name}: {css}");
        }
        assert_eq!(option_class(Selector::Tabs), "tab");
    }

    #[test]
    fn the_caret_brings_its_own_gap_and_is_the_glyph_the_description_names() {
        let css = stylesheet(&Emit::default());

        // The space is inside the glyph, which is what the other two renderers
        // write. Emitted bare, every consumer has to add it back, and the
        // obvious way to add it -- `content` in an app stylesheet, which is
        // unlayered and so outranks this sheet -- deletes the caret instead.
        assert!(css.contains("content: \" \\25B2\";"), "{css}");
        assert!(css.contains("content: \" \\25BC\";"), "{css}");
        assert!(!css.contains("content: \"\\2"), "{css}");

        // The arrows this renderer used to draw alone are gone. Composition
        // rather than agreement: the glyph comes from `Sort::glyph`, so a
        // fourth spelling cannot appear here without appearing everywhere.
        assert!(!css.contains("2191") && !css.contains("2193"), "{css}");
        assert!(css.contains(&css_escape(Sort::Ascending.glyph())), "{css}");

        // Three states, three tones. An idle sortable heading draws its caret
        // now rather than reserving a hidden box for it, so there is no
        // visibility to order and no reflow left to guard against; what
        // separates the states is the colour, and the sorted arms come after
        // the idle one because the specificity is the same.
        let idle = css
            .find(".table-heading[data-sortable]::after")
            .expect("the idle caret is emitted");
        let sorted = css
            .find(".table-heading[aria-sort=\"ascending\"]::after")
            .expect("the ascending caret is emitted");
        assert!(idle < sorted, "{css}");
        assert!(
            css[idle..sorted].contains("color: var(--content-secondary);"),
            "{css}"
        );
        assert!(css[sorted..].contains("color: var(--content);"), "{css}");
        assert!(!css.contains("visibility: hidden;"), "{css}");
    }

    #[test]
    fn a_destructive_button_has_somewhere_for_its_tone_to_land() {
        let css = component_rules(&Emit::default());

        for tone in [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger] {
            assert!(
                css.contains(&format!(".button[data-tone=\"{}\"]", tone.token())),
                "{css}"
            );
        }
        // Colour, not a fill. A red surface is an app's decision about emphasis.
        assert!(!css.contains(".button[data-tone=\"danger\"] {\n    background"));
    }

    #[test]
    fn a_described_list_is_not_a_bulleted_list() {
        let css = component_rules(&Emit::default());
        assert!(css.contains(".list {\n    list-style: none;"), "{css}");
    }

    #[test]
    fn a_table_lays_itself_out_without_being_told_its_columns() {
        // The whole point of the CSS table. A described table's columns are
        // known at render time, so anything the stylesheet has to be told about
        // them would have to travel with the markup.
        let css = component_rules(&Emit::default());

        assert!(css.contains(".table {\n    display: table;"), "{css}");
        assert!(css.contains("display: table-row;"), "{css}");
        assert!(css.contains("display: table-cell;"), "{css}");
        assert!(!css.contains("grid-template-columns"), "{css}");
    }

    #[test]
    fn a_control_in_a_cell_is_not_painted_as_text() {
        // The point of makeover-layout 0.14.0's CellPart, and the table-side
        // twin of `the_three_text_parts_take_their_intents_and_actions_inherits`
        // above. One `.cell` and one content colour meant a button in a cell
        // inherited it.
        let css = table_rules(&Emit::default());

        assert!(
            css.contains(".cell-value {\n    color: var(--content);"),
            "{css}"
        );
        assert!(!css.contains(".cell-actions {\n    color:"), "{css}");
        assert!(!css.contains(".cell-tokens {\n    color:"), "{css}");
        assert!(!css.contains(".cell-link {\n    color:"), "{css}");

        // The colour is on the part that is text, never on the container. On
        // `.cell` it would cascade into the three parts that are not text,
        // which is the bug written as one rule.
        assert!(!css.contains(".cell {\n    color:"), "{css}");
    }

    #[test]
    fn an_unknown_cell_part_renders_plainly_rather_than_failing_to_build() {
        // `part_class`'s obligation, taken on for the table side too. CellPart
        // is `#[non_exhaustive]`, so a member added upstream must land as a
        // bare class rather than as a build that stops.
        assert_eq!(cell_part_class(CellPart::Value), "cell-value");
        assert_eq!(cell_part_class(CellPart::Actions), "cell-actions");
    }

    #[test]
    fn a_column_drops_by_its_priority_and_never_by_its_position() {
        let css = component_rules(&Emit::default());

        // Optional goes at the narrowest class and secondary goes with it,
        // which is `kept_at`'s cutoff walk said as two queries.
        let compact = css
            .find(&format!("@media {}", SizeClass::Compact.media_condition()))
            .expect("a compact query");
        let medium = css
            .find(&format!("@media {}", SizeClass::Medium.media_condition()))
            .expect("a medium query");
        assert!(css[compact..].contains(".cell-drops-next"), "{css}");
        assert!(!css[medium..].contains(".cell-drops-next"), "{css}");

        // Essential columns are never mentioned, because not being mentioned is
        // already what never dropping means.
        assert!(!css.contains(".cell-keeps"), "{css}");

        // And nothing counts. `nth-child` is the bug the priority vocabulary
        // exists to end.
        assert!(!css.contains("nth-child"), "{css}");
    }

    #[test]
    fn a_track_places_by_custom_property_and_never_by_a_size() {
        let css = track_rules(&Emit::default());

        // Placement arrives from the caller, computed once by Track::fraction.
        // If either of these becomes a literal, three renderers have started
        // disagreeing about where 09:30 is.
        assert!(css.contains("top: var(--track-at"), "{css}");
        assert!(css.contains("height: var(--track-for"), "{css}");

        // Overlap lanes default so an entry naming neither is full width.
        assert!(css.contains("--track-lane, 0"), "{css}");
        assert!(css.contains("--track-lanes, 1"), "{css}");

        // The refusal that matters. A slot height here would be this crate
        // deciding how tall a quarter of an hour is, which is the thing
        // makeover-geometry owns and the reason `.track` gets no height at all.
        assert!(!css.contains("height: var(--track-slot"), "{css}");
        for size in ["px", "rem", "em", "vh"] {
            let bare = css
                .lines()
                .filter(|l| !l.contains("var(--"))
                .any(|l| l.contains(size));
            assert!(!bare, "track_rules named a {size} outside a var(): {css}");
        }
    }

    #[test]
    fn a_relaxed_part_clamps_and_a_tight_one_says_nothing() {
        let css = stylesheet(&Emit::default());
        assert!(css.contains(".row-relaxed {"));
        assert!(css.contains("-webkit-line-clamp: 2;"));
        // The count is `Flow`'s, not this crate's. If the tier ever means three
        // lines, this fails here rather than in an app.
        assert!(css.contains(&format!("line-clamp: {};", Flow::Relaxed.lines())));
        // Tight gets no rule at all: one line is what a run already does, and a
        // class per part saying so is a declaration that changes nothing.
        assert!(!css.contains("row-tight"));
        assert_eq!(crate::list::flow_class(Flow::Relaxed), Some("row-relaxed"));
        assert_eq!(crate::list::flow_class(Flow::Tight), None);
        // Emitted, therefore checkable: an app's dead-vocabulary seal and the
        // overlap check both read `vocabulary::names`, so a class the renderer
        // can write and that list does not carry is invisible to both.
        assert!(crate::vocabulary::names(&Emit::default()).contains("row-relaxed"));
    }

    #[test]
    fn the_whole_sheet_still_names_every_colour() {
        // The crate's founding property, asserted over the component layer and
        // not only the primitives.
        let css = stylesheet(&Emit::default());
        assert!(!css.contains('#'));
        assert!(!css.contains("rgb"));
        for line in css.lines() {
            // Declarations only: a selector or an at-rule can carry a colon of
            // its own (`:root`, `:hover`, `@media (hover: hover)`) and declares
            // nothing. Keyed on the trailing semicolon rather than on leading
            // indentation, which only ever worked as a proxy for nesting depth
            // and stopped when the sheet gained a cascade layer around it.
            let trimmed = line.trim();
            if !trimmed.ends_with(';') {
                continue;
            }
            let Some((_, value)) = trimmed.split_once(": ") else {
                continue;
            };
            if value.contains("var(--") {
                continue;
            }
            // Everything left has to be a keyword, a number or a
            // caller-supplied length, never a colour.
            //
            // The length arm is what the comment above always claimed and the
            // list never covered: `border_width` arrives from `Emit` and lands
            // bare in the focus ring's offset, where the bevel had only ever
            // used it inside an `inset` shadow.
            let opts = Emit::default();
            assert!(
                value.contains("inset")
                    || value.contains(opts.border_width)
                    || value.contains(opts.focus_width)
                    // 0.12.0's two: a sortable header is a control and says so
                    // with the pointer, and the caret is this renderer's own
                    // expression of `aria-sort`. Neither is a colour, which is
                    // what this test is actually about, and neither is a size,
                    // which is the other thing this crate must not name. The
                    // leading space inside the glyph is the same thing the other
                    // two renderers write into theirs, so it is part of the
                    // caret rather than spacing this crate decided on.
                    || value
                        .trim_start_matches('"')
                        .trim_start()
                        .starts_with("\\2")
                    || matches!(
                        value.trim_end_matches(';'),
                        "0" | "1"
                            | "none"
                            | "auto"
                            | "not-allowed"
                            | "pointer"
                            // The caret's reserved box. Visibility is presence,
                            // not magnitude and not colour.
                            | "hidden"
                            | "visible"
                            // The link's two signals. `underline` is a line and
                            // `inherit` defers to whatever the app set, so
                            // neither names a colour or a magnitude.
                            | "underline"
                            | "inherit"
                            // The table frame. `display` is structure and not a
                            // size; `nowrap` is what makes a content column
                            // content. The two widths are the awkward pair and
                            // they are still not sizes: `100%` is "all of
                            // whatever you were given" and `1%` is the CSS
                            // table idiom for "shrink to fit", which is a
                            // behaviour spelled as a number because CSS has no
                            // keyword for it. Neither names a magnitude, which
                            // is the thing this crate leaves to
                            // makeover-geometry.
                            | "table"
                            | "table-row"
                            | "table-cell"
                            | "nowrap"
                            | "100%"
                            | "1%"
                            // The time axis, 0.42.0. `position` is the one
                            // property whose whole job is where a thing sits,
                            // which is exactly what this crate spent its life
                            // refusing to say -- so it is worth being exact
                            // about why these two are not that refusal
                            // breaking.
                            //
                            // Neither names a magnitude. `relative` says the
                            // track is what its entries resolve against, and
                            // `absolute` says an entry is placed rather than
                            // flowed. *Where* each entry lands is
                            // `--track-at` and `--track-for`, custom
                            // properties the caller sets from
                            // `Track::fraction`, and they are skipped by the
                            // `var(--` arm above like every other value this
                            // crate refuses to decide.
                            //
                            // The rule that would break the refusal is a slot
                            // height, and there is none: the track's height is
                            // the app's, so the percentages have something to
                            // resolve against and this crate still never says
                            // how tall a day is.
                            | "relative"
                            | "absolute"
                            // A run's five, 0.49.0. `flex`, `wrap` and
                            // `center` are structure and alignment, the same
                            // reading `table` gets: which way members are laid
                            // out and how they line up, never how much of
                            // anything.
                            //
                            // The two intrinsic keywords are the interesting
                            // pair and they are the opposite of a size. A
                            // magnitude is a number somebody chose;
                            // `min-content` and `max-content` are the browser
                            // being asked what the members themselves come to,
                            // which is the derived minimum the room ruling
                            // requires and the reason no breakpoint appears
                            // anywhere in these rules. `1 1 max-content` is
                            // grow, shrink and that basis, so its two digits
                            // are ratios rather than lengths.
                            | "flex"
                            | "wrap"
                            | "center"
                            | "min-content"
                            | "1 1 max-content"
                            // A picture's three, 0.36.0. `block` is structure
                            // for the reason `table` is: an inline image sits
                            // on the baseline and carries a descender's worth
                            // of space under it, which is a fact about
                            // replaced elements rather than a size this crate
                            // chose. `cover` and `contain` are `Fit`'s two
                            // named members reaching CSS unchanged, which is
                            // an intent arriving rather than a value being
                            // picked.
                            | "block"
                            | "cover"
                            | "contain"
                            // A relaxed part's three, and the third is the
                            // awkward one. `-webkit-box` and `vertical` are
                            // structure: they say the part is a box of lines
                            // stacked downward, which is the only way CSS lets
                            // anyone ask for a clamp at all.
                            //
                            // `2` is a count of lines, not a length. The
                            // distinction this crate holds is between naming a
                            // magnitude -- a padding, a height, a font size,
                            // all of which belong to makeover-geometry -- and
                            // naming how many of something there are. A line's
                            // height is still the app's, so two lines is
                            // whatever two of the app's lines come to, and
                            // nothing here decides how tall that is. It is also
                            // not a value picked here: it is `Flow::Relaxed`'s
                            // own answer arriving unchanged, the same way
                            // `cover` and `contain` are `Fit`'s.
                            | "-webkit-box"
                            | "vertical"
                            | "2"
                    ),
                "unrecognised literal value: {line}"
            );
        }
    }

    #[test]
    fn flat_emits_nothing_at_all() {
        assert_eq!(depth_class(Depth::Flat, &Emit::default()), None);
        assert!(!depth_rules(&Emit::default()).contains("flat"));
    }

    #[test]
    fn a_prefix_namespaces_every_class() {
        let opts = Emit {
            class_prefix: "mo-",
            ..Emit::default()
        };
        let css = depth_rules(&opts);
        assert!(css.contains(".mo-raised {"));
        assert!(css.contains(".mo-well {"));
        assert!(!css.contains(".raised {"));
    }

    #[test]
    fn the_border_width_is_the_callers() {
        let opts = Emit {
            border_width: "2px",
            ..Emit::default()
        };
        assert!(bevel_shadow(Bevel::Raised, &opts).contains("inset 2px 2px 0"));
    }

    #[test]
    fn edges_agree_with_the_description() {
        // Not a tautology: it is the guard that a CSS-shaped convenience never
        // quietly reverses which side is lit.
        let (tl, br) = Bevel::Raised.edges();
        assert_eq!(tl.token(), Edge::Light.token());
        assert_eq!(br.token(), Edge::Dark.token());
    }
}