/* ════════════════════════════════════════════════════════════════════════
   typography.css — THE type scale. Every app, every page, every component.
   AB#13470.

   WHY THIS FILE EXISTS. Before it, the portal drew text at 31 different pixel
   values across 3,504 declarations, and none of them was a decision anyone
   made twice. "A column header" existed at 10, 11, 11, 11, 12, 12, 13, 13 and
   13px across nine rules; "a view tab" at three sizes inside Chaos alone, two
   of them in the same file; "an empty state" at five sizes across 89 rules.
   Nothing enforced the clustering, so the tail kept growing — four of the 31
   values appeared exactly once.

   That is not a Chaos problem or a Chat problem. It is the absence of a scale,
   and it is why AB#13470 arrived as "make Chaos 1px bigger": the complaint was
   real, but the cause was that 27% of the portal's text sits at 11px or below
   and nothing says it may not.

   WHAT THE SCALE IS. Fourteen roles, named for WHAT THE TEXT IS rather than how
   big it is. A call site reads `font-size: var(--fs-body)`. The name says the
   role; this file says the number. Changing a size afterwards is one line,
   once, for the whole portal — which is the property that was asked for and
   the one a per-app override can never provide.

   NO FALLBACK LITERALS. A call site writes `var(--fs-body)`, never
   `var(--fs-body, 13px)`. A fallback would be a second copy of the number,
   free to drift, and it would mask a token that failed to load rather than
   failing loudly. This file is linked FIRST in index.html, before every other
   stylesheet and before any dynamically loaded one, so the tokens are always
   defined — including for the surfaces appended to document.body (dialogs,
   context menus, toasts, popovers), which inherit from :root like everything
   else and which no app-scoped selector could reach.

   NOT IN core.css. index.html does not link core.css — only controls-lab does
   — so a token declared there resolves to nothing in the app and every
   `var()` reading it silently drops its property. See
   .claude/rules/ui-design-scope.md.

   REM, NOT PX (P7a). Every value below is rem, carrying the px it replaces as
   a comment. A px font-size ignores the browser's text-size setting outright —
   WCAG 1.4.4 asks that text scale to 200% — so a portal built on px literals
   cannot be enlarged by the people who most need to enlarge it. The comment is
   the px AT THE DEFAULT 16px ROOT; it stops being the truth the moment a reader
   changes that setting, which is the entire point of the conversion.

   The prerequisite, verified 2026-09-18: no `html` or `:root` px font-size
   exists anywhere in Shell, CSS or JS. A px root silently defeats rem by
   pinning the very thing rem is relative to. If one is ever added, this file's
   promise breaks and nothing will say so.

   Glyph literals stay px — see the note at the foot of this file. A 48px
   empty-state emoji growing with a reader's text setting is not obviously
   right.

   THE RATCHET. src/Tests/Unit-Tests-JS/architecture/typography-scale.test.js
   fails the build when a stylesheet declares a literal `font-size: <N>px`
   outside this file and outside the glyph allow-list. Without it the tail
   regrows; 31 values is what happens when nothing says no.
   ════════════════════════════════════════════════════════════════════════ */

:root {
    /* ── Text ────────────────────────────────────────────────────────────
       The bottom five roles are one step above what the portal drew before
       AB#13470 — that is the ticket's "+1px", applied by ROLE across every
       app rather than to one app, so nothing diverges. 16px and above only
       CONSOLIDATES: headings were never the complaint, and growing them costs
       vertical space on every page that has one.

       Each role's comment names what it absorbed, so a reader chasing a
       changed size can see which of the old values landed here.

       ── T-634: SEVEN ROLES NOW READ THE DESIGN SYSTEM ──────────────────────
       Paired BY VALUE, never by name, and only after U-E8.0c made the system's
       scale rem — while it was px, `--fs-body: var(--lp-fs-body)` would have
       turned this whole scale absolute and taken WCAG 1.4.4 text scaling with
       it. The px in each comment is still the value at a 16px root.

         --fs-micro -> --lp-fs-micro      --fs-body-lg    -> --lp-fs-panel
         --fs-meta  -> --lp-fs-meta       --fs-title-lg   -> --lp-fs-h2
         --fs-ui    -> --lp-fs-small      --fs-display-lg -> --lp-fs-h1
         --fs-body  -> --lp-fs-body

       BY VALUE MATTERS. --fs-display is 24px here and --lp-fs-display is 36px:
       one name, two sizes. A name-led alias would have resized every display
       element by twelve pixels and looked like tidying.

       SIX ROLES HAVE NO COUNTERPART and keep their own numbers, declared here
       so their absence is a fact on the record rather than an oversight:

         --fs-subtitle  16px   --fs-display  24px     --fs-headline-lg  44px
         --fs-title     18px   --fs-hero     34px     --fs-masthead     56px

       The system's scale jumps 15 -> 22 -> 28 -> 36; this one carries 16, 18,
       24 and 34 between those steps because the portal has roles there. It also
       carries 44 and 56 above the system's top step, for the briefing. Either
       the system grows them or these stay local — a design decision, not a
       refactor's to make. Until then these six are the only sizes in this file
       that are ours alone. */

    /* Badge digits, counters, timestamps. Was 7 / 8 / 9 / 9.5 / 10 / 10.5px —
       220 declarations, and the band that made the portal hard to read. This
       is the floor now: nothing draws type below 11px. */
    --fs-micro: var(--lp-fs-micro);  /* 11px */

    /* Captions, chips, tags, secondary meta. Was 11 / 11.5px (419). */
    --fs-meta: var(--lp-fs-meta);  /* 12px */

    /* Dense UI — toolbars, form labels, table cells, column headers.
       Was 12 / 12.5px (619 declarations, the single largest group). */
    --fs-ui: var(--lp-fs-small);  /* 13px */

    /* THE DEFAULT. Rows, cards, menu items, buttons, body copy.
       Was 13 / 13.5px (584). When in doubt, a surface wants this one. */
    --fs-body: var(--lp-fs-body);  /* 14px */

    /* Input and textarea text, emphasised body. Was 14 / 15px (262).
       Inputs sit one step above body deliberately — text being typed is read
       at a different distance from text being scanned. */
    --fs-body-lg: var(--lp-fs-panel);  /* 15px */

    /* Section heading inside a page. Was 16px (48) — unchanged. */
    --fs-subtitle: 1rem;  /* 16px */

    /* Panel and dialog title. Was 17 / 18 / 19px (57). */
    --fs-title: 1.125rem;  /* 18px */

    /* Page title. Was 20 / 22 / 23px (20). */
    --fs-title-lg: var(--lp-fs-h2);  /* 22px */

    /* The front and inspector card title of the Sanity lenses (design_handoff_sanity_lenses: "new 26 for
       front/inspector titles"). Pinned to the exact rem the literal carried, so adding it moved no pixel. */
    --fs-title-xl: 1.625rem;  /* 26px */

    /* Large page title. Was 24 / 25px (12). */
    --fs-display: 1.5rem;  /* 24px */

    /* Welcome and hero headings. Was 26 / 27 / 28px (12). */
    --fs-display-lg: var(--lp-fs-h1);  /* 28px */

    /* The largest reading-surface type — the intro, the doc editor's title.
       Was 32 / 34 / 36px (7). */
    --fs-hero: 2.125rem;  /* 34px */

    /* ── Display headlines, above the hero ───────────────────────────────
       Three steps above --fs-hero for a surface whose headline IS the page:
       the crew briefing (FB-541, controls/briefing.css), drawn from the Claude
       Design handoff at 44 / 56px with a 36px narrow-viewport title. Before
       these existed it carried them as rem literals, which the ratchet cannot
       see - a size the scale does not own is a size nobody can change once.

       Each is the handoff's px at the default root, unchanged: adding the
       tokens moved no pixel. --fs-headline equals the design system's
       --lp-fs-display (both 36px) but does NOT alias it: the standalone Sift page
       links this file without design-system/typography.css, so an alias would resolve to
       nothing there - which is already true of the seven T-634 aliases above. */

    /* A page title on a narrow viewport; the headline of a reading column. */
    --fs-headline: 2.25rem;  /* 36px */

    /* A lead headline — the one sentence a page exists to say. */
    --fs-headline-lg: 2.75rem;  /* 44px */

    /* A masthead — the page's own name at the top of a full-bleed surface.
       The largest type in the product. */
    --fs-masthead: 3.5rem;  /* 56px */

    /* ── The one carve-out ───────────────────────────────────────────────
       The sidebar app title ("Chaos", "Chat", "Signals"), drawn by the shared
       frame in controls/sidebar-layout.css. AB#13470's acceptance criteria
       name a SIZE for this one element rather than a delta — it must render at
       17px — where every other criterion names a delta. --fs-title would take
       it to 18px and fail the criterion that asked for 17.

       It is a token rather than a literal so the exception is visible HERE, at
       the scale, instead of hiding as a stray number in a component file where
       the next reader would have to guess whether it was deliberate.

       If the criterion is ever revised, delete this and let the title read
       --fs-title like every other title. */
    --lp-sidebar-title-size: 1.0625rem;  /* 17px */

    /* ── Line height ─────────────────────────────────────────────────────
       A2. There was no line-height system at all — 455 declarations across
       30 distinct values, which is the same sprawl the size scale replaced
       (31 values), arrived at the same way: nothing said no.

       Five roles, each backed by 30+ real declarations rather than invented.
       The value is the CENTRE of the cluster it absorbs. Measured when the call
       sites were migrated (A2b), the honest bound is 0.1 rather than the 0.05
       this comment first claimed: the clusters are not symmetrical, and six
       sites move that far - 1.1 -> 1.2 on two h1s and both .rail-label rules,
       1.7 -> 1.6 on .docs-article and .overview-rendered. Everything else moves
       by 0.05 or not at all:

         --lh-tight    1.2    absorbs 1.1 / 1.15 / 1.18 / 1.2 / 1.25    31
         --lh-snug     1.35   absorbs 1.3 / 1.35                        33
         --lh-body     1.45   absorbs 1.4 / 1.42 / 1.45 / 1.48          83
         --lh-relaxed  1.5    absorbs 1.5 / 1.55                        87
         --lh-loose    1.6    absorbs 1.6 / 1.65 / 1.7                  34

       268 of the 455. The remaining 187 are NOT text rhythm and are
       deliberately outside this: `line-height: 1` (125) and `normal` (35) are
       resets, `0` (4) collapses a box, and 20 are px — of which four are the
       `line-height == box height` idiom that centres a single glyph and must
       stay px to keep centring.

       UNITLESS, ALWAYS. A unitless line-height is a multiplier of the
       element's own font-size; a px one is a fixed distance that does not
       move when the font does. Since P7a the scale is rem, so text grows with
       a reader's browser setting — and a px line-height does not, which makes
       lines overlap at large settings. The 16 px text line-heights still in
       the tree are that defect, and are recorded in the plan rather than
       silently converted here: each needs its own ratio computed against the
       font-size it pairs with.

       MIGRATED 2026-09-18 (A2b). 321 call sites across 85 files read these,
       and the ratchet now refuses a literal that belongs to one of the roles,
       so the tail cannot regrow. Between authoring and that migration these
       tokens had ZERO readers - correct, and spoken by nobody - which is worth
       remembering the next time a scale ships without its call sites.

       Five values stay literal, each a singleton at an extreme these roles were
       never designed around: .98 and 1.08 are display leading BELOW the tight
       cluster, 1.72 and 1.85 are prose and log leading ABOVE the loose one.
       See docs/plans/PORTAL-TYPOGRAPHY-NORMALIZATION.md §16.12. */
    --lh-tight: 1.2;
    --lh-snug: 1.35;
    --lh-body: 1.45;
    --lh-relaxed: 1.5;
    --lh-loose: 1.6;

    /* ── Tracking ────────────────────────────────────────────────────────
       C3. 220 letter-spacing declarations across ~40 distinct values, of
       which 139 sit on a rule that also sets `text-transform: uppercase` —
       one role, argued 22 ways, and split almost evenly between px (62) and
       em (67) for the same thing.

       Two roles, each the CENTRE of its cluster:

         --ls-caps       0.04em   the standard uppercase label, chip, badge,
                                  column header, pill.  107 sites
         --ls-caps-wide  0.1em    the eyebrow / kicker / section heading.
                                  22 sites, spanning 0.07-0.12em

       The wide cluster is one role by selector, not by value:
       .spr-brain-eyebrow, .sp-section-eyebrow, .san-sec-kicker,
       .signal-sidebar-group h3, .lp-sidebar-spaces-heading and their
       siblings. 0.1em is its centre, so the largest move is 0.03em; 0.12em
       would have moved the nine 0.07/0.08 sites by up to 0.05.

       EM, NOT PX. Letter-spacing in em is a fraction of the element's own
       font-size, so it moves when the font does. A px value does not — the
       same defect class as a px line-height, and since P7a the scale is rem,
       so text grows with the reader's browser setting while px tracking
       stays put. The 62 px sites converted here were 0.25-1px, which on caps
       text (10-13px) is 0.02-0.09em.

       NOT EVERY letter-spacing. 81 declarations are outside this: negative
       tracking that tightens large display text is its own role and is left
       alone, as are `0`, `normal` and `inherit`. */
    --ls-caps: 0.04em;
    --ls-caps-wide: 0.1em;

    /* ── Family ──────────────────────────────────────────────────────────
       D3 (owner, 2026-09-18): two families across the whole product and
       nothing else. A developer should only ever choose between these two.

       WHY SELF-HOSTED, and not a preference. chat.css carried
       `@import url('https://fonts.googleapis.com/...')`, and the Shell's CSP
       is `style-src 'self' 'unsafe-inline'` with `font-src 'self'` — no
       Google host on either. Dev serves that policy REPORT-ONLY, so the
       import worked locally and Inter never loaded in production at all.
       `font-src 'self'` is exactly what a vendored file needs, so this
       requires no CSP change.

       WHAT IS VENDORED. css/fonts/InterVariable.woff2 — Inter v4.1 from
       github.com/rsms/inter, one variable file covering 100-900, so all four
       approved weights come from a single request. SIL OFL 1.1; the
       upstream LICENSE.txt sits beside it, which is what the licence
       requires of a redistributed copy. No Reserved Font Name is declared,
       so aliasing the family to `Inter` below is unrestricted.

       COVERAGE, measured against the font's own cmap rather than assumed:
       every non-ASCII character in the en and de locales renders in Inter
       except 日本語 (the language picker naming Japanese in its own script)
       and one emoji. For the ja locale, 533 of 539 characters fall back.
       Inter contains NO CJK in any distribution — Google's subsets stop at
       U+FFFD — so this is unchanged behaviour, not a regression. Read the
       rule honestly as INTER FOR LATIN, THE OS FONT FOR JAPANESE. */
    --font-sans:
        "Inter",
        ui-sans-serif,
        system-ui,
        -apple-system,
        BlinkMacSystemFont,
        "Segoe UI",
        Roboto,
        sans-serif;

    /* Technical/system text: code, ids, hashes, api keys, developer tools,
       status readouts.

       THIS LIST MIRRORS --prose-mono EXACTLY (the chat response's inline code,
       js/controls/chat-widget/prose-css.js). Mirroring the list rather than
       merely picking the same first name is what makes the app's mono and the
       chat response's inline code the same face on EVERY platform: pick a
       different order and the two agree only where the leading font happens to
       be installed, and diverge silently everywhere else. If one list changes,
       change the other with it.

       NO MONO FACE IS VENDORED. D3 named JetBrains Mono and this token led with
       it until 2026-09-18, but nothing ever vendored the file and the CSP is
       font-src 'self' - so a font we do not ship can only come from the
       reader's own machine. Measured rather than assumed: on a default Windows
       machine JetBrains Mono is ABSENT and "JetBrains Mono" measures exactly as
       an unknown family does, so the leading name resolved for nobody while
       reading as a decision already implemented. It is gone. Vendoring it is
       still the only thing that would make that name true, and would cost four
       weight files - 400, 500, 600 and 700 are all in use.

       Every name here is a real face rather than a vendored one, so what paints
       depends on the reader's machine: Cascadia Code ships with Windows
       Terminal, Fira Code is a developer install, SF Mono and Menlo are macOS,
       Consolas is Windows, and ui-monospace asks the platform for its own. The
       tail is what keeps it monospaced when none of the named faces exist. */
    --font-mono:
        "Cascadia Code",
        "Fira Code",
        Consolas,
        ui-monospace,
        monospace;

    /* THE SECOND MONO ROLE, and the only reason there are two. Owner ruled
       2026-09-18 that a fenced CODE BLOCK should take the reader's own platform
       code face rather than the portal's voice, so this leads with
       ui-monospace: a Mac gets SF Mono, Windows gets Consolas, and a Linux
       reader gets whatever they configured. --font-mono above leads with
       Cascadia Code, which would otherwise hand a Mac reader Cascadia or -
       where Office is installed - Consolas, ahead of their own SF Mono.

       Named for its surface rather than its stack, because that is the honest
       scope: it is the code block's face, not a general-purpose second mono.
       Use --font-mono for the portal's own technical text - ids, hashes, api
       keys, chips, developer tools, inline code. If you are reaching for this
       one anywhere but a block of code, you want --font-mono.

       It is DECLARED here rather than in controls/code-block.css so that every
       font stack in the portal still lives in one file - a stack defined beside
       the component that reads it is the sprawl this scale replaced.

       Until this landed the code block had no font-family at all and rendered
       at the browser's UA default for <pre>, so it was a default rather than a
       decision; this does not breach D3 exception 3, which preserves the chat
       faces that EXIST. */
    --code-block-mono:
        ui-monospace,
        SFMono-Regular,
        Menlo,
        Consolas,
        monospace;
}

/* ── The one web font ────────────────────────────────────────────────────
   Inter v4.1, self-hosted (D3). One variable file covers 100-900, so the
   four approved weights - 400 Regular, 500 Medium, 600 Semibold, 700 Bold -
   come from a single request rather than four.

   The family is declared as `Inter` rather than upstream's own
   `InterVariable`, so --font-sans reads one name and a machine that happens
   to have Inter installed locally resolves identically. The OFL declares no
   Reserved Font Name, so the alias is unrestricted; the licence text ships
   beside the file at css/fonts/LICENSE.txt, which is what condition 2
   requires of each redistributed copy.

   font-display: swap - text paints immediately in the fallback and reflows
   when the font lands, rather than blocking on 352KB. index.html preloads it
   so that window is short.
   ────────────────────────────────────────────────────────────────────── */
@font-face {
    font-family: 'Inter';
    font-style: normal;
    font-weight: 100 900;
    font-display: swap;
    src: url('fonts/InterVariable.woff2') format('woff2');
}

/* ── Glyph sizing is NOT typography ──────────────────────────────────────
   206 declarations in this tree use `font-size` to size something that is not
   text: an X on a close button, an emoji in an empty state, a play arrow, a
   chevron. They span 8px to 48px and they are deliberately NOT part of the
   scale above — folding them in would resize icons and hit targets alongside
   the words, which is a different decision with different acceptance criteria.

   They keep literal px values, and the ratchet allow-lists them by selector.
   AB#13470's own note — "icons should be re-checked for optical balance with
   the new text size and bumped only where they now look too small" — is a
   judgement pass per surface AFTER the type lands, not an automated mapping.
   ────────────────────────────────────────────────────────────────────── */
