/* Structural half of the token contract: everything that is not colour. Themes override what differs; these are the defaults both build on. */ /* The layer order, stated once so it never depends on which file loads first. Extensions sit above components: they build on the library, and a project that declares one gets the last word inside its own attributes. */ @layer ulex.theme, ulex.base, ulex.components, ulex.extensions; @layer ulex.theme { :root { --ulex-space-1: 0.25rem; --ulex-space-2: 0.5rem; --ulex-space-3: 0.75rem; --ulex-space-4: 1rem; --ulex-space-5: 1.25rem; --ulex-space-6: 1.5rem; --ulex-space-8: 2rem; --ulex-space-10: 2.5rem; --ulex-space-12: 3rem; --ulex-space-16: 4rem; /* rem throughout: px font sizes break 1.4.4 Resize Text */ --ulex-text-1: clamp(1.75rem, 1.5rem + 1.1vw, 2.25rem); --ulex-text-2: clamp(1.5rem, 1.3rem + 0.8vw, 1.875rem); --ulex-text-3: clamp(1.25rem, 1.1rem + 0.5vw, 1.5rem); --ulex-text-4: 1.125rem; --ulex-text-5: 1rem; --ulex-text-6: 0.9375rem; --ulex-text-7: 0.875rem; --ulex-text-8: 0.8125rem; --ulex-leading: 1.5; /* 1.4.8 floor */ --ulex-leading-prose: 1.6; --ulex-weight-normal: 400; --ulex-weight-medium: 500; --ulex-weight-semibold: 600; --ulex-transition-fast: 120ms cubic-bezier(0.4, 0, 0.2, 1); --ulex-transition: 200ms cubic-bezier(0.4, 0, 0.2, 1); --ulex-z-nav: 10; --ulex-z-dropdown: 50; --ulex-z-modal: 200; /* Published by the shell so sticky offsets never need measuring. */ --ulex-nav-h: 3rem; --ulex-sidebar-w: 15rem; --ulex-toc-w: 13rem; --ulex-radius-full: 9999px; /* Stacked bar. --ulex-bar-part is set per segment, inline, as its proportion; the default keeps a segment visible if nothing sets it. */ --ulex-bar-h: 0.4375rem; --ulex-bar-part: 1; /* 2.5.8 Target Size (Minimum), AA. CSS px, deliberately: the success criterion is defined in CSS px, not in the user's font size. */ --ulex-target-min: 24px; --ulex-ring-width: 2px; /* 2.4.13 floor */ --ulex-ring-offset: 2px; } /* 2.5.5 Target Size (Enhanced) */ [data-ulex-level="aaa"] { --ulex-target-min: 44px; } } /* Base. Applies to bare semantic markup with no attributes at all -- zero-attribute HTML must look right and be conformant on its own. */ @layer ulex.base { *, *::before, *::after { box-sizing: border-box; } body { margin: 0; background: var(--ulex-bg); color: var(--ulex-text); font-family: var(--ulex-font-sans); font-size: var(--ulex-text-5); line-height: var(--ulex-leading); -webkit-font-smoothing: antialiased; } /* 2.4.7 / 2.4.13. One ring, everywhere, never removed without replacement. --ulex-ring is contrast-checked at >= 3:1 against every surface. */ :focus-visible { outline: var(--ulex-ring-width) solid var(--ulex-ring); outline-offset: var(--ulex-ring-offset); border-radius: var(--ulex-radius-sm); } /* Only suppress the default ring where :focus-visible is honoured. */ :focus:not(:focus-visible) { outline: none; } /* 2.5.8 -- every interactive target clears the floor, at every size. min-block-size rather than height so 1.4.12 Text Spacing still holds. */ :is(a[href], button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"])) { min-block-size: var(--ulex-target-min); } :is(button, input, select, textarea) { min-inline-size: var(--ulex-target-min); font: inherit; color: inherit; } /* 2.3.3 -- honour the user's setting globally rather than per component. */ @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; transition-duration: 0.01ms !important; scroll-behavior: auto !important; } } a { color: var(--ulex-accent); } a:hover { text-decoration-thickness: 2px; } /* Headings take their sizes from the scale, so a theme retunes the whole hierarchy by retuning the scale rather than by patching headings. */ :is(h1, h2, h3, h4, h5, h6) { line-height: 1.25; text-wrap: balance; margin-block: var(--ulex-space-6) var(--ulex-space-3); font-weight: var(--ulex-weight-semibold); } :is(h1, h2, h3, h4, h5, h6):first-child { margin-block-start: 0; } h1 { font-size: var(--ulex-text-2); } h2 { font-size: var(--ulex-text-3); } h3 { font-size: var(--ulex-text-4); } h4 { font-size: var(--ulex-text-5); } :is(h5, h6) { font-size: var(--ulex-text-6); } p { margin-block: 0 var(--ulex-space-4); } /* Inline code reads as code without an attribute: the meta face and a raised chip. Text keeps its inherited colour, and every text level is verified on surface-hi, so the chip cannot cost contrast. Code inside a 
 is a block's business, not this rule's. */
  :where(code, samp):not(pre > *) {
    font-family: var(--ulex-font-mono);
    font-size: 0.875em;
    padding: 0.1em 0.35em;
    background: var(--ulex-surface-hi);
    border: 1px solid var(--ulex-edge-subtle);
    border-radius: var(--ulex-radius-sm);
    overflow-wrap: anywhere;   /* 1.4.10 -- a long identifier wraps, never scrolls the page */
  }
  /* A key, from the element:  already means this. */

  :where(kbd) {
    display: inline-block;
    padding: 0.1em 0.4em;
    font-family: var(--ulex-font-mono);
    font-size: 0.85em;
    line-height: 1.4;
    color: var(--ulex-text);
    background: var(--ulex-surface-hi);
    border: 1px solid var(--ulex-edge-control);
    border-block-end-width: 2px;
    border-radius: var(--ulex-radius-sm);
    white-space: nowrap;
  }

  /* A bare 
 is a block of code or output, and looks like one with no
     attribute. It scrolls itself rather than the page (1.4.10). */
  :where(pre) {
    margin: 0;
    padding: var(--ulex-space-3);
    overflow-x: auto;
    font-family: var(--ulex-font-mono);
    font-size: var(--ulex-text-8);
    line-height: 1.5;
    background: var(--ulex-surface);
    border: 1px solid var(--ulex-edge-subtle);
    border-radius: var(--ulex-radius-md);
  }
  /* Inside a code block the block draws the frame. */
  :where([data-ulex-code]) > pre { border: 0; border-radius: 0; background: none; }

  img, svg, video { max-inline-size: 100%; height: auto; }

  /* 1.1.1 -- a decorative graphic must say so; anything else needs a name.
     Made visible rather than silent, because a missing alt is invisible. */
  img:not([alt]) { outline: 2px dashed var(--ulex-tone-danger); }
}

@layer ulex.components {
  /* Clipped, never display:none -- it must stay in the accessibility tree. */
  [data-ulex-visually-hidden]:not(:focus):not(:active) {
    position: absolute;
    inline-size: 1px; block-size: 1px;
    margin: -1px; padding: 0; border: 0;
    overflow: hidden; white-space: nowrap;
    clip-path: inset(50%);
  }

  /* 1.4.8 -- measure, leading, spacing, and never justified. */
  [data-ulex-prose] {
    max-inline-size: var(--ulex-measure);
    line-height: var(--ulex-leading-prose);
    text-align: start;
  }
  [data-ulex-prose] > * + * { margin-block-start: var(--ulex-space-4); }
  [data-ulex-prose] :is(p, li) { text-align: start !important; }
  /* A quieter or louder voice for a whole passage -- a caption, a note, a
     lede. Inherited, so everything inside the passage follows. */
  [data-ulex-prose][data-ulex-emphasis] {
    color: var(--_emph, inherit);
    font-weight: var(--_emph-weight, inherit);
  }
}
/* The tone axis.
 *
 * Lives here rather than inside a component because an axis is cross-cutting:
 * button, alert, badge and tag all read the same four internal properties, so
 * `tone` means exactly the same thing on each. That is what lets an agent move
 * a value it has seen on one component onto another and be right.
 *
 * These rules only set custom properties. On an element whose component does
 * not consume them they are inert, which is why the linter -- not the CSS --
 * is what rejects an axis on a component that does not support it.
 *
 *   --_ink   text and border colour
 *   --_fill  background for fill="solid"
 *   --_on    label colour on that fill
 *   --_edge  border colour for the default fill
 */

@layer ulex.components {
  [data-ulex-tone="accent"]  { --_ink: var(--ulex-tone-accent);
                               --_fill: var(--ulex-tone-accent);
                               --_on: var(--ulex-on-tone); --_edge: var(--_fill); }
  [data-ulex-tone="danger"]  { --_ink: var(--ulex-tone-danger);
                               --_fill: var(--ulex-tone-danger);
                               --_on: var(--ulex-on-tone); --_edge: var(--_fill); }
  [data-ulex-tone="success"] { --_ink: var(--ulex-tone-success);
                               --_fill: var(--ulex-tone-success);
                               --_on: var(--ulex-on-tone); --_edge: var(--_fill); }
  [data-ulex-tone="warning"] { --_ink: var(--ulex-tone-warning);
                               --_fill: var(--ulex-tone-warning);
                               --_on: var(--ulex-on-tone); --_edge: var(--_fill); }
  [data-ulex-tone="info"]    { --_ink: var(--ulex-tone-info);
                               --_fill: var(--ulex-tone-info);
                               --_on: var(--ulex-on-tone); --_edge: var(--_fill); }
  [data-ulex-tone="neutral"] { --_ink: var(--ulex-tone-neutral);
                               --_fill: var(--ulex-neutral-fill);
                               --_on: var(--ulex-neutral-on);
                               --_edge: var(--ulex-edge-control); }
}

/* The emphasis axis.
 *
 * tone selects *meaning* -- danger, success. emphasis selects *loudness*, and
 * the two are orthogonal: a figure can be quiet without being neutral, and
 * danger stays danger whether it is shouted or muttered. Collapsing loudness
 * into tone was the alternative considered in ULX-2 and rejected, because it
 * would make the tone enum mean two things and the axes exist to each mean one.
 *
 * `quiet` replaces the text colour with the subtle level, whatever the tone;
 * `strong` only adds weight, so a toned figure keeps its colour and gets
 * louder. Unlike tone this sets `--_emph`, not `--_ink`, so a component opts in by
 * reading `var(--_emph, )`. On a component that does not, the
 * property is inert -- the linter, not the cascade, is what rejects it.
 *
 * `normal` sets the guaranteed-invalid value, so `var(--_emph, x)` falls back
 * to `x`. That is what lets the default level mean "whatever this component
 * already does" without this file having to know what that is.
 *
 * Every level is one of the three verified text tokens. Nothing here mixes or
 * fades a colour, because a mixed colour is not a measured one, and
 * tools/contrast.mjs can only hold the library to pairs it can name. At AAA
 * --ulex-text-dim and --ulex-text-subtle converge, so `quiet` gets quieter in
 * weight but not in contrast -- which is the correct behaviour, not a bug.
 */

@layer ulex.components {
  /* strong is weight alone. Setting a colour here replaced a tone's ink with
     plain text, so danger + strong rendered as an ordinary figure -- louder in
     weight, but no longer saying danger. quiet does replace the colour, because
     muting is what it is for. */
  [data-ulex-emphasis="strong"] { --_emph: initial;
                                  --_emph-weight: var(--ulex-weight-semibold); }
  [data-ulex-emphasis="normal"] { --_emph: initial;
                                  --_emph-weight: initial; }
  [data-ulex-emphasis="quiet"]  { --_emph: var(--ulex-text-subtle);
                                  --_emph-weight: var(--ulex-weight-normal); }
}
/* Layout primitives -- the whole utility surface, and it stays this size.
 *
 * Justified by evidence rather than preference: both example pages
 * independently hand-rolled the same two things in page CSS, a vertical stack
 * and a wrapping cluster. That is the gap. A spacing-utility scale
 * (.mt-2, .mb-6, .p-4) is not, so it is not here.
 *
 * Neither invents an axis. Gap comes from `size` and horizontal placement from
 * `align`, both meaning what they already mean elsewhere -- which is also the
 * first consumer the align axis has had.
 */

@layer ulex.components {

  :where([data-ulex-stack]) {
    display: flex;
    flex-direction: column;
    gap: var(--ulex-space-4);
  }

  :where([data-ulex-row]) {
    display: flex;
    flex-wrap: wrap;          /* 1.4.10 -- a row never forces sideways scroll */
    align-items: center;
    gap: var(--ulex-space-2);
  }

  /* The gap is the spacing. A child's own block margins -- a heading's, a
     code block's -- would add to it and double the rhythm, so inside a stack
     or row they are zeroed. :where keeps this at zero specificity, so any
     component that genuinely needs a margin inside a stack still wins. */
  :where([data-ulex-stack], [data-ulex-row]) > * { margin-block: 0; }

  :is([data-ulex-stack], [data-ulex-row])[data-ulex-size="sm"] { gap: var(--ulex-space-1); }
  :is([data-ulex-stack], [data-ulex-row])[data-ulex-size="lg"] { gap: var(--ulex-space-6); }

  /* `align` is horizontal placement in both, which is what keeps it one idea:
     the main axis of a row, the cross axis of a stack. */
  [data-ulex-row][data-ulex-align="center"] { justify-content: center; }
  [data-ulex-row][data-ulex-align="end"]    { justify-content: flex-end; }
  [data-ulex-stack][data-ulex-align="center"] { align-items: center; }
  [data-ulex-stack][data-ulex-align="end"]    { align-items: flex-end; }
}
/* Shell -- nav, sidebar and main as one coordinated primitive.
 *
 * Three components that each assume they are alone is the classic bug: a
 * topnav and a sidebar styled separately, publishing neither's height, so
 * the app has to measure the nav in JavaScript into a --nav-h of its own.
 * A measured height is a missing token, and here it is a conformance
 * problem too -- 2.4.11 Focus Not Obscured needs the sticky offset to be
 * known in CSS.
 *
 * So the shell publishes --ulex-nav-h. Keeping that honest is the whole
 * design problem, because a nav that WRAPS is taller than its token says,
 * and a stale offset hides the focused element behind the header. Rather
 * than measure, the shell removes the case: above the breakpoint the nav is
 * one row and sticky, and below it the nav may wrap and is not sticky. The
 * offset is therefore only ever consulted when it is known to be correct.
 *
 * The breakpoint is 48rem, written literally: media queries cannot read
 * custom properties, so a --ulex-shell-bp token would be a token that only
 * pretends to control the layout.
 */

@layer ulex.components {

  [data-ulex-shell] {
    display: grid;
    grid-template-columns: 1fr;
    grid-template-rows: auto 1fr;
    min-block-size: 100dvh;
  }

  [data-ulex-shell]:has(> [data-ulex-sidebar]) {
    grid-template-columns: var(--ulex-sidebar-w) 1fr;
  }

  /* The documentation shell: tree, document, contents. Still one primitive —
     a third column, not a second component — so --ulex-nav-h and the sticky
     rules below go on holding for all three. */
  [data-ulex-shell]:has(> [data-ulex-toc]) {
    grid-template-columns: var(--ulex-sidebar-w) 1fr var(--ulex-toc-w);
  }
  [data-ulex-shell]:has(> [data-ulex-toc]):not(:has(> [data-ulex-sidebar])) {
    grid-template-columns: 1fr var(--ulex-toc-w);
  }
  [data-ulex-toc] { padding: var(--ulex-space-4); min-inline-size: 0; }

  /* ---------- skip link (2.4.1) ---------- */

  [data-ulex-skip-link] {
    position: absolute;
    z-index: calc(var(--ulex-z-nav) + 1);
    margin: var(--ulex-space-2);
    padding: var(--ulex-space-2) var(--ulex-space-4);
    background: var(--ulex-surface);
    color: var(--ulex-text);
    border: 1px solid var(--ulex-edge-control);
    border-radius: var(--ulex-radius-md);
    text-decoration: none;
    transform: translateY(-200%);
  }
  [data-ulex-skip-link]:focus-visible {
    transform: none;   /* 2.4.7 -- it must become visible, not just focusable */
  }

  /* ---------- nav ---------- */

  [data-ulex-nav] {
    grid-column: 1 / -1;
    display: flex;
    flex-wrap: wrap;                     /* 1.4.10 -- never scroll sideways */
    align-items: center;
    gap: var(--ulex-space-1) var(--ulex-space-3);
    min-block-size: var(--ulex-nav-h);   /* min-, not height: 1.4.12 */
    padding-inline: var(--ulex-space-4);
    padding-block: var(--ulex-space-2);
    background: var(--ulex-surface);
    border-block-end: 1px solid var(--ulex-edge-subtle);
    box-shadow: var(--ulex-shadow-sm);
  }

  [data-ulex-nav] a {
    display: inline-flex;
    align-items: center;
    min-block-size: var(--ulex-target-min);
    padding-inline: var(--ulex-space-3);
    border-radius: var(--ulex-radius-md);
    color: var(--ulex-text-dim);
    text-decoration: none;
    white-space: nowrap;
    transition: background-color var(--ulex-transition-fast),
                color var(--ulex-transition-fast);
  }
  [data-ulex-nav] a:hover {
    background: var(--ulex-surface-hi);
    color: var(--ulex-text);
  }

  /* The current item is marked by aria-current -- the same hook that
     announces it. 1.4.1: colour is not the only channel, so it also carries
     a weight change and a rule beneath it. */
  [data-ulex-nav] a[aria-current] {
    background: var(--ulex-surface-hi);
    color: var(--ulex-text);
    font-weight: var(--ulex-weight-semibold);
    box-shadow: inset 0 -2px 0 0 var(--ulex-accent);
  }

  [data-ulex-nav] [data-ulex-nav-spacer] { margin-inline-start: auto; }

  /* ---------- sidebar ---------- */

  [data-ulex-sidebar] {
    display: flex;
    flex-direction: column;
    gap: var(--ulex-space-1);
    padding: var(--ulex-space-4);
    border-inline-end: 1px solid var(--ulex-edge-subtle);
    background: var(--ulex-surface);
  }
  [data-ulex-sidebar] a {
    min-block-size: var(--ulex-target-min);
    display: flex;
    align-items: center;
    padding-inline: var(--ulex-space-3);
    border-radius: var(--ulex-radius-md);
    color: var(--ulex-text-dim);
    text-decoration: none;
  }
  [data-ulex-sidebar] a:hover { background: var(--ulex-surface-hi); color: var(--ulex-text); }
  [data-ulex-sidebar] a[aria-current] {
    background: var(--ulex-surface-hi);
    color: var(--ulex-text);
    font-weight: var(--ulex-weight-semibold);
    box-shadow: inset 2px 0 0 0 var(--ulex-accent);
  }

  /* ---------- main ---------- */

  [data-ulex-main] {
    min-inline-size: 0;                  /* 1.4.10 -- let wide children shrink */
    padding: var(--ulex-space-6) var(--ulex-space-4);
  }
  [data-ulex-main]:focus { outline: none; }   /* skip-link target, not a control */

  /* Wide content scrolls inside itself rather than scrolling the page. */
  [data-ulex-main] :is(table, pre) {
    display: block;
    max-inline-size: 100%;
    overflow-x: auto;
  }

  /* ---------- sticky, and the offset it publishes ---------- */

  @media (min-width: 48rem) {
    [data-ulex-nav] {
      position: sticky;
      inset-block-start: 0;
      z-index: var(--ulex-z-nav);
      flex-wrap: nowrap;                 /* one row, so --ulex-nav-h is true */
      overflow-x: auto;                  /* a long nav scrolls itself, not the page */
    }

    /* 2.4.11 Focus Not Obscured -- anything scrolled to under the sticky nav
       clears it. This is what --ulex-nav-h exists for. */
    [data-ulex-main] :is(:target, [id], a[href], button, input, select, textarea,
                         summary, [tabindex]:not([tabindex="-1"])) {
      scroll-margin-block-start: calc(var(--ulex-nav-h) + var(--ulex-space-3));
    }

    [data-ulex-sidebar] {
      position: sticky;
      inset-block-start: var(--ulex-nav-h);
      block-size: calc(100dvh - var(--ulex-nav-h));
      overflow-y: auto;
    }
  }

  /* Below the breakpoint the nav wraps and is static, so no stale offset can
     exist, and the sidebar stacks above main instead of beside it. */
  @media (max-width: 47.999rem) {
    [data-ulex-shell]:has(> [data-ulex-sidebar]) { grid-template-columns: 1fr; }
    [data-ulex-shell]:has(> [data-ulex-toc]) { grid-template-columns: 1fr; }
    [data-ulex-sidebar] {
      flex-direction: row;
      flex-wrap: wrap;
      border-inline-end: 0;
      border-block-end: 1px solid var(--ulex-edge-subtle);
    }
  }
}
/* Breadcrumb -- where you are, as a trail.
 *
 * A