@codenhub/styles 0.0.4 → 0.1.0

package/dist/tw/utilities/content.css

@@ -0,0 +1,349 @@
+@reference "tailwindcss";
+@reference "../box.css";
+
+@utility table-wrap {
+  @apply w-full overflow-x-auto;
+}
+
+/* The one component that takes the frame of `box` and not the whole of it. The
+   border, the radius and the clip come from the box; the head tone, the cell
+   rules and the row hover are private tokens, because none of the three axes has
+   a vocabulary for the inside of a table.
+
+   Its `overflow: hidden` is what keeps `border-separate` corners inside the
+   radius, and it does not compose with an aesthetic's `clip-path`: where both
+   apply, the clip wins and the corners square off. Recorded in `registry.json`
+   beside the decision. */
+@utility data-table {
+  @apply box text-body w-full border-separate text-left;
+
+  --_d-fill: 12%;
+  --_d-fg-on-fill: 0%;
+  /* Edgeless, so the frame is asked for rather than inherited from a default
+     nobody can see in their own markup. Published `edged`, `.edged` on a table
+     computed exactly what no class computed -- a switch that could not move
+     anything -- and the frame arrived because of a line in `registry.json`.
+     `.edged` draws it now, and the two boundaries a table keeps whatever else it
+     draws mean a frameless one still reads as a table. */
+  --_d-border: 0%;
+  --_d-elevation: 0;
+
+  /* Capped the way `box` caps, because the head is a fill of the intent like any
+     other and a neutral table head is otherwise a slab of the page's ink with
+     ink printed on it. */
+  --table-fill: calc(min(var(--ui-fill, var(--_d-fill)), var(--intent-fill-max, 100%)) * var(--ui-bg-alpha, 1));
+  /* The head's plate is the tint, so a table carrying no fill has no head plate.
+     `.ghost` means no tint here the way it means no fill everywhere else, and a
+     ghost table is boundaries and type and nothing else -- which is what `.ghost`
+     is for on this component, since the published resting fill is `soft`.
+
+     Any fill at all brings the ground back whole rather than in proportion. A
+     soft head mixed onto the page instead of onto `--intent-subtle` is a
+     different colour from the one this component has always drawn, and the fill
+     is meant to read as a step past the tint rather than as a replacement for
+     it. A saturating ramp says that, because the signal is a percentage and
+     there is no branch to hang off one: the smallest fill any presentation asks
+     for is 12%, so a multiplier of 100 puts every non-zero fill over the top and
+     leaves zero where it is.
+
+     It reads `--ui-fill` rather than `--table-fill` because that is the question
+     being asked: what the presentation wanted, not what the intent cap and an
+     aesthetic's alpha left of it. A glass `.soft` table still wants its head
+     plate, and neutral's 20% cap has no bearing on whether there is one. Reading
+     the raw class value also keeps the expression a `calc()` over one `var()`
+     rather than over `--table-fill`'s own `calc()`/`min()` chain, which matters
+     for the reason `--table-rule-plated` below records. */
+  --table-ground: min(100%, calc(var(--ui-fill, var(--_d-fill)) * 100));
+  --table-head-plate: color-mix(in oklab, var(--intent-subtle) var(--table-ground), transparent);
+  --table-head-bg: color-mix(in oklab, var(--intent-color) var(--table-fill), var(--table-head-plate));
+  --table-head-fg: color-mix(in oklab, var(--intent-contrast) var(--_on-fill), var(--intent-strong));
+  /* How much rule there is between body rows, and none unless asked for. Ruling
+     every row is a style choice rather than part of what a table is, and tying it
+     to the edge axis made it arrive by implication instead: a table drew rules
+     because its published edge default happened to be `edged`, which is a fact
+     about the registry rather than anything the markup says. A consumer reading
+     their own HTML could not tell whether they had asked for rules.
+
+     `.ruled` is that ask and `.ruleless` is its opposite, with `--ui-rule` behind
+     both -- so a consumer who wants a whole region ruled, or a whole region bare,
+     sets the token on a container instead of classing every table.
+
+     One token covers three positions because the two places that read it take
+     different fallbacks. Unset, each site answers for itself: no rules between
+     rows, but the boundaries below still drawn. Set, the answer is the same at
+     both. So `.ruled` writes 100% and gets rules everywhere, `.ruleless` writes 0%
+     and gets a table with no lines in it at all, and a table nobody classed sits
+     between them. A second token would have said the same thing with more parts,
+     and would have let the two drift. */
+  --table-rule-amount: var(--ui-rule, 0%);
+  --table-boundary-amount: var(--ui-rule, 100%);
+  /* What the rule is drawn in, which is not the same tone at every fill.
+     `.ghost` and `.soft` keep `--intent-border` -- the slot an aesthetic restates
+     through `--ui-ink` -- because at those fills the plate has not swallowed it.
+     `.solid` is where it has: at a full fill `--intent-border` *is* the plate for
+     every intent, and at neutral's capped fill it is a near shade of the same
+     grey, so the rule the rows are separated by disappears exactly where the
+     plate is busiest.
+
+     The filled case draws in `currentColor` instead, at a fifth. That is the ink
+     the cell is already printing -- `--table-head-fg` on a head, `box`'s own
+     `--_fg` in the body -- so it reads on a light plate and a dark one without a
+     per-intent branch, and it lands *over* the plate because a translucent border
+     composites onto the background the element already painted.
+
+     Naming the ink rather than composing it is also what keeps this expression
+     cheap, and cheap is a requirement here rather than a preference. Written as
+     `color-mix(--table-head-fg 20%, --_bg)` the rule expanded, through four levels
+     of substitution, into a `color-mix()` over two more `color-mix()`es over a
+     `min()`/`max()`/`calc()` chain -- and every `th` and `td` on a page resolves it.
+     WebKit's renderer crashed outright on the two routes that draw tables, taking
+     22 specs across four files with it, while Chromium and Firefox rendered them
+     correctly. Neither the depth nor the table alone did it: bisected, the new
+     tokens were fine until the cells consumed them.
+
+     `currentColor` and `transparent` are leaves the engine has resolved already,
+     which is what takes the expression back down to something every engine can
+     carry. `--table-row-hover` below is written the same way, for the same
+     reason. */
+  --table-rule-plated: color-mix(in oklab, currentColor 20%, transparent);
+  --table-rule-tone: color-mix(in oklab, var(--table-rule-plated) var(--ui-fill, var(--_d-fill)), var(--intent-border));
+  --table-rule: color-mix(in oklab, var(--table-rule-tone) var(--table-rule-amount), transparent);
+  --table-boundary: color-mix(in oklab, var(--table-rule-tone) var(--table-boundary-amount), transparent);
+  /* A hovered row is a step from the table it is in, not from a tone the page
+     happens to own. Mixed into `--color-foreground` it was neither: a solid
+     table paints its body with the intent, so a primary table in dark theme is
+     white and its hovered row came out near-black -- a dark band across a light
+     table. Painting a translucent step instead makes it relative at every fill,
+     the way `box-hover` is: the row composites onto whatever plate the table
+     drew, so a filled table shifts within its own colour, a soft one deepens its
+     tint, and a ghost one picks up a faint wash of the page.
+
+     Which tone it steps toward has to move with the fill as well. On a bare or
+     tinted plate that is `--intent-hover`, the deepening every other component
+     gets. On a filled one it cannot be: `--intent-hover` is
+     `mix(--intent-color 82%, --intent-strong)`, which is very nearly the colour
+     the plate is already painted, so a step toward it is no step. Measured, a
+     solid success table moved 1.00:1 in light and a solid destructive one
+     1.008:1 -- the feedback was declared and invisible. A filled plate steps
+     toward `currentColor` instead, which is the ink that plate already carries
+     and therefore always contrasts with it.
+
+     Both ends are leaves, and the step lands on `transparent` rather than on
+     `--_bg`, for the reason `--table-rule-plated` above gives: compositing is
+     what the browser does with a translucent background anyway, so naming `--_bg`
+     buys the same colour for two more levels of substitution. */
+  --table-hover-tone: color-mix(in oklab, currentColor var(--ui-fill, var(--_d-fill)), var(--intent-hover));
+  --table-row-hover: color-mix(in oklab, var(--table-hover-tone) 12%, transparent);
+
+  border-spacing: 0;
+  overflow: hidden;
+
+  & caption {
+    @apply text-label text-text-secondary pb-2 text-left;
+  }
+
+  & thead,
+  & tfoot {
+    background-color: var(--table-head-bg);
+    color: var(--table-head-fg);
+  }
+
+  /* Every cell carries the hairline; what varies is whether it is painted. A rule
+     is structure rather than the silhouette, so it stays hairline under an
+     aesthetic that draws a thick edge, and it survives a fill that would
+     otherwise paint over it. */
+  & th,
+  & td {
+    @apply border-b px-4 py-3 align-top;
+
+    border-color: var(--table-rule);
+  }
+
+  /* The two lines that separate the parts of a table from each other: under the
+     head and above the foot. They are boundaries rather than decoration on the
+     rows, so they are drawn by default where the row rules are not, and they do
+     not answer to the edge axis -- `.edgeless` takes the silhouette off the box,
+     and a head that runs into its own body is not a silhouette question.
+
+     The foot draws upward rather than relying on the last body row drawing down,
+     because with rules off that row paints nothing. Stated on the foot, the
+     boundary holds at every setting. */
+  & thead tr:last-child > * {
+    border-bottom-color: var(--table-boundary);
+  }
+
+  & tfoot tr:first-child > * {
+    @apply border-t;
+
+    border-top-color: var(--table-boundary);
+  }
+
+  /* Rules between body rows, on request -- and every line off, on the opposite
+     request. `.ruleless` is declared second so it wins the nonsense combination
+     rather than leaving it to whichever class the author typed first. */
+  &.ruled {
+    --ui-rule: 100%;
+  }
+
+  &.ruleless {
+    --ui-rule: 0%;
+  }
+
+  & th {
+    @apply text-label font-semibold;
+  }
+
+  /* Rows deliberately inherit the table's intent instead of resetting it, so a
+     `.data-table.success` tints its own rows. A `<tr class="warning">` still wins,
+     because an intent class on the element beats an inherited value. */
+  & tbody tr {
+    transition: background-color var(--motion-duration-fast) var(--motion-ease);
+  }
+
+  & tbody tr:hover {
+    background-color: var(--table-row-hover);
+  }
+
+  /* The rule comes off the row that is visually last, which is not always the
+     last row of the body. Written as `tbody tr:last-child` it came off the body's
+     last row unconditionally, so a table with a footer lost the one rule that
+     separates the two -- the summary ran straight on from the rows it summarises --
+     while the footer kept a bottom rule of its own, drawing a hairline immediately
+     inside the frame. A missing line where one belongs and a doubled one where it
+     does not, from the same declaration.
+
+     Both selectors are `:last-child` on the section, so whichever section the
+     markup puts last is the one that loses its rule. That covers a footer written
+     before the body, which HTML still allows, and multiple bodies, where only the
+     last one ends the table.
+
+     It went unseen because it was invisible until this release: `thead` and
+     `tfoot` shared an unconditional `--intent-subtle` plate, so the footer was a
+     band and the band did the separating. `.ghost` dropping that plate is what
+     left the rule doing the job alone. */
+  & tbody:last-child tr:last-child > *,
+  & tfoot:last-child tr:last-child > * {
+    @apply border-b-0;
+  }
+}
+
+/* Three components rest on a ground rather than on nothing: a key cap, an inline
+   code chip and a code block are each a quiet tinted plate at rest, and that tone
+   is `--intent-subtle` rather than a fill of the component's own intent.
+
+   All three rest at `soft`, and `.ghost` is published as unsupported on them.
+   The ground is what makes a chip a chip, and `.ghost` asks for no fill while
+   the ground stays -- so on these three it drew the plate anyway and meant
+   nothing, which is the opposite of what it means everywhere else. Worse, at
+   zero fill the plate is `--intent-subtle` alone, and that slot is a near-page
+   tint: measured on the light page, a ghost `code` chip was `#e5e5e5` for both
+   neutral and primary, and `#f5f5f5` for secondary at 1.04:1 against a `#fafafa`
+   page. A class that renders four intents as the same invisible chip is not a
+   variation. Resting at `soft` puts a real 12% of the intent over the ground, so
+   the plate is a step past the page and the intents separate.
+
+   Each used to restate its foreground too, because `box` mixed toward
+   `--intent-color` -- the tone meant to sit *on* a page rather than on a tint of
+   itself, and amber-600 on amber-100 is a smudge. `box` now mixes toward
+   `--intent-strong`, which is what these three were reaching for, so the three
+   copies are gone and the ground is the only thing left to declare. */
+@utility kbd {
+  @apply box inline-flex items-center px-1.5 py-0.5 font-mono text-xs font-medium;
+
+  --_d-fill: 12%;
+  --_d-fg-on-fill: 0%;
+  --_d-border: 100%;
+  --_d-elevation: 0;
+  --_d-ground: var(--intent-subtle);
+
+  /* Capped at its own radius: a control radius is sized for a control, and a key
+     cap this small would read as a lozenge. A squaring aesthetic still reaches it. */
+  border-radius: min(var(--ui-radius, var(--radius-small)), var(--radius-small));
+  clip-path: var(--ui-clip-tight, var(--ui-clip, none));
+}
+
+/* The same plate with no line around it. */
+@utility code {
+  @apply box px-1.25 py-0.75 font-mono;
+
+  --_d-fill: 12%;
+  --_d-fg-on-fill: 0%;
+  --_d-border: 0%;
+  --_d-elevation: 0;
+  --_d-ground: var(--intent-subtle);
+
+  border-radius: min(var(--ui-radius, var(--radius-small)), var(--radius-small));
+  clip-path: var(--ui-clip-tight, var(--ui-clip, none));
+}
+
+/* And at block scale, where the radius is a control's rather than a chip's. */
+@utility pre {
+  @apply box block overflow-x-auto px-2.5 py-1.5 font-mono;
+
+  --_d-fill: 12%;
+  --_d-fg-on-fill: 0%;
+  --_d-border: 0%;
+  --_d-elevation: 0;
+  --_d-ground: var(--intent-subtle);
+}
+
+/* Typography wearing a component's name, so it composes none of `box`: `box`
+   draws a border on four sides and a quotation wants one, and a radius, a clip
+   and a shadow are inert on a left bar and an indent. What is left of `box`
+   after removing the border is not worth composing.
+
+   The cost is the fill and edge blends below, which repeat `box` and have to
+   agree with it. Recorded in `registry.json` beside the
+   decision.
+
+   The bar is twice the line width the aesthetic asks for, plus a pixel, which is
+   this component's own choice about what a quotation looks like rather than a
+   scale applied to an edge -- there is no such scale any more. The constant is
+   what makes the bar read as a bar at the default hairline: doubling 1px gives
+   2px, and a quotation mark needs more presence than a table rule. */
+@utility quote {
+  --_d-fill: 0%;
+  --_d-fg-on-fill: 0%;
+  --_d-border: 100%;
+  --_d-elevation: 0;
+  --quote-fill: calc(min(var(--ui-fill, var(--_d-fill)), var(--intent-fill-max, 100%)) * var(--ui-bg-alpha, 1));
+  --quote-bg: color-mix(in oklab, var(--intent-color) var(--quote-fill), transparent);
+  /* The same edge blend `box` draws, in the same order and for the same reason:
+     the blend is the line's colour, and how much line there is comes after it.
+     Written the other way round -- how much line, then blend the fill into it --
+     `.edgeless` lands on the fill colour rather than on nothing, and the border
+     box paints that over the fill it already drew, so a quotation that asked for
+     no bar got a bar of two coats of its own tint.
+
+     That this had to be fixed twice is the cost of a quotation drawing its own
+     edge instead of taking `box`'s. Recorded in `registry.json` beside the
+     decision to compose none of `box`. */
+  --quote-line: color-mix(in oklab, var(--quote-bg) var(--ui-fill, var(--_d-fill)), var(--intent-border));
+  --quote-edge: color-mix(in oklab, var(--quote-line) var(--ui-border, var(--_d-border)), transparent);
+  --quote-width: calc(var(--ui-border-width, var(--border-width)) * 2 + 1px);
+
+  @apply my-0 border-s py-2 ps-4 italic;
+
+  background-color: var(--quote-bg);
+  border-inline-start-color: var(--quote-edge);
+  border-inline-start-width: var(--quote-width);
+  color: color-mix(
+    in oklab,
+    var(--intent-contrast) min(var(--ui-fg-on-fill, var(--_d-fg-on-fill)), var(--intent-fill-max, 100%)),
+    var(--intent-strong)
+  );
+
+  /* The attribution takes no colour of its own, so it follows the quotation's.
+     Pinning it to a neutral secondary tone loses both the intent-specific strong
+     tone at zero fill and the contrast tone as the fill comes up.
+
+     Type and posture are what separate an attribution from the quotation: it is
+     upright where the quote is italic, and it sits on its own line. */
+  & cite {
+    @apply text-body mt-2 block not-italic;
+  }
+}
+
+@utility quote-inline {
+  @apply text-text-secondary italic;
+}

package/dist/tw/utilities/index.css

@@ -0,0 +1,6 @@
+@import "../theme.css";
+@import "../typography.css";
+@import "./layout.css";
+@import "./content.css";
+
+@source inline("view vertical horizontal stack tight loose cluster between auto-grid section section-content narrow wide divider selection-contrast table-wrap data-table kbd quote quote-inline code pre");

package/dist/tw/utilities/layout.css

@@ -0,0 +1,107 @@
+@reference "tailwindcss";
+
+@utility view {
+  @apply flex gap-(--layout-gap);
+
+  &.vertical {
+    @apply flex-col;
+  }
+
+  &.horizontal {
+    @apply flex-row flex-wrap items-center;
+  }
+
+  &.tight {
+    --layout-gap: 0.5rem;
+  }
+
+  &.loose {
+    --layout-gap: 1.5rem;
+  }
+}
+
+@utility stack {
+  @apply flex flex-col gap-(--layout-gap);
+
+  &.tight {
+    --layout-gap: 0.5rem;
+  }
+
+  &.loose {
+    --layout-gap: 1.5rem;
+  }
+}
+
+@utility cluster {
+  @apply flex flex-wrap items-center gap-(--layout-gap);
+
+  &.between {
+    @apply justify-between;
+  }
+
+  &.tight {
+    --layout-gap: 0.5rem;
+  }
+
+  &.loose {
+    --layout-gap: 1.5rem;
+  }
+}
+
+@utility auto-grid {
+  @apply grid gap-(--layout-gap);
+
+  grid-template-columns: repeat(auto-fit, minmax(min(var(--layout-grid-min), 100%), 1fr));
+
+  &.tight {
+    --layout-gap: 0.5rem;
+  }
+
+  &.loose {
+    --layout-gap: 1.5rem;
+  }
+}
+
+@utility section {
+  @apply px-(--layout-gutter) py-(--layout-section-block);
+}
+
+@utility section-content {
+  @apply mx-auto w-full max-w-(--container-max);
+
+  &.narrow {
+    max-width: var(--container-narrow);
+  }
+
+  &.wide {
+    max-width: var(--container-wide);
+  }
+}
+
+/* An indicator: intent only, and no presentation token at all. A rule is a line,
+   and neither a fill class nor an edge class has anything to say about one -- while
+   reading both used to mean a container's `.ghost.edgeless` made every `<hr>`
+   inside it invisible. The width is the aesthetic's line width, unscaled. */
+@utility divider {
+  --divider-color: var(--intent-color);
+  --divider-width: var(--ui-border-width, var(--border-width));
+
+  @apply m-0 w-full border-0 border-t;
+
+  border-color: var(--divider-color);
+  border-top-width: var(--divider-width);
+
+  &.vertical {
+    @apply h-auto w-0 self-stretch border-s border-t-0;
+
+    border-inline-start-width: var(--divider-width);
+  }
+}
+
+@utility selection-contrast {
+  &::selection,
+  & *::selection {
+    background: var(--color-primary-contrast);
+    color: var(--color-primary);
+  }
+}

package/docs/accessibility.md

@@ -0,0 +1,82 @@
+---
+title: Accessibility
+---
+
+# Accessibility responsibilities
+
+This package provides CSS hooks for accessible states. It does not provide semantic HTML, ARIA attributes, keyboard behavior, focus management, validation, announcement timing, or JavaScript behavior.
+
+## Provided By CSS
+
+| Feature                 | Behavior                                                                                                                   |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `:focus-visible`        | Global focus-visible outline using `--focus-ring`, `--focus-ring-width`, and `--focus-ring-offset`.                        |
+| Form control focus      | `.ipt`, `.textarea`, and `.select` draw the global focus ring and move their line to the intent color.                     |
+| Control boundaries      | Text controls rest at `--_line-rest` of their intent, under 3:1 by choice; hover and focus take the tone whole.            |
+| Toggle boundaries       | `.checkbox`, `.radio`, and `.switch` draw their line whole, because it is the only thing marking an unchecked box.         |
+| Cascaded `.edgeless`    | Floored on every text control: a container cannot erase the line of a field or toggle nobody classed.                      |
+| Own `.edgeless`         | On the element, `.ipt`, `.textarea`, `.select`, and `.switch` do drop their line and do not meet 1.4.11 at rest.           |
+| `.checkbox`/`.radio`    | Never drop their line, on the element or from a container. `.edgeless` on them is unsupported, not merely discouraged.     |
+| Invalid controls        | `[aria-invalid="true"]` applies destructive border/focus color on form controls.                                           |
+| Disabled controls       | `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]`, and `.disabled` apply disabled cursor/opacity where supported.  |
+| Current page            | `[aria-current="page"]` applies primary color and stronger font weight.                                                    |
+| Open state              | `[data-state="open"]` styles supported surfaces and tooltips.                                                              |
+| Reduced-motion loaders  | Loader variants use animated embedded SVGs normally and static masks when `prefers-reduced-motion: reduce` matches.        |
+| Reduced-motion document | The reset additionally shortens document animations and transitions when `prefers-reduced-motion: reduce` matches.         |
+| Reduced transparency    | `.glass` drops its blur and becomes an opaque surface when `prefers-reduced-transparency: reduce` matches.                 |
+| Filled labels           | Every intent's `.solid` label meets 1.4.3 (4.5:1) as normal text, in both themes. Lowest is success at 5.14:1.             |
+| Warning ink             | `--color-warning-contrast` is the near-black tone, not the page tone. Amber dark enough to carry white is not amber.       |
+| Partial fills           | Contrast ink appears only past a half fill, so a capped plate keeps `--intent-strong` rather than walking toward the page. |
+| Intent hue in dark      | `--intent-strong` is the `-300` shade in dark, so a soft or ghost label keeps its own hue instead of reading white.        |
+| Toggle marks            | A checked mark meets 3:1 as a state indicator on every plate its fill class can paint, in both themes.                     |
+| Forced colors           | `forced-colors: active` preserves visible borders and checked states using system colors.                                  |
+| Text direction          | Quote bar, alert icon, progress fill, vertical divider, and switch knob mirror under `dir="rtl"`. No class needed.         |
+
+The loader fallback is embedded in loader CSS, so focused imports that include
+loaders honor reduced motion without the reset. This includes
+`@codenhub/styles/components`, `@codenhub/styles/tw/components`,
+`@codenhub/styles/tw/button`, and `@codenhub/styles/tw/loader`. The complete and
+native entrypoints include both that fallback and the reset's broader animation
+and transition shortening.
+
+In forced colors, class-based form controls including `.text-control` receive a
+2px `Highlight` system-color focus outline. The native entrypoint provides the
+same visible system outline for unclassed text inputs, selects, textareas,
+checkboxes, and radios.
+
+Custom checkboxes and radios use the system `Canvas`, `CanvasText`, `Highlight`,
+and `HighlightText` colors in forced-colors mode so checked and unchecked states
+remain distinct. Shape, size, and spacing remain unchanged.
+
+## Required Outside CSS
+
+Use semantic HTML and behavior appropriate for the component.
+
+| UI                | Required outside CSS                                                                                            |
+| ----------------- | --------------------------------------------------------------------------------------------------------------- |
+| Buttons           | Use `<button>` for actions or accessible links for navigation. Add accessible names for `.btn.icon`.            |
+| Forms             | Use labels, `type`, validation logic, `aria-describedby`, and error message relationships.                      |
+| Alerts            | Add `role="status"` or `role="alert"` based on announcement urgency.                                            |
+| Toasts            | Add live-region behavior, dismissal behavior, focus rules, and pause/timeout logic when needed.                 |
+| Tooltips          | Provide accessible names/descriptions. CSS pseudo-element content is not enough for all assistive tech.         |
+| Progress          | Use semantic progress elements or ARIA values when numeric progress must be announced.                          |
+| Skeletons/loaders | Mark decorative loading visuals with `aria-hidden="true"` and expose loading state elsewhere when needed.       |
+| Popovers/modals   | Provide focus trapping, escape handling, inert background behavior, labels, and roles outside this CSS package. |
+
+## State Attribute Guidance
+
+Prefer native attributes first:
+
+```html
+<button class="btn primary" disabled>Saving</button>
+<input class="ipt" aria-invalid="true" aria-describedby="email-error" />
+```
+
+Use ARIA or data attributes when native attributes are not available for the element or library:
+
+```html
+<a class="btn secondary" aria-disabled="true">Unavailable</a>
+<button class="tooltip tooltip-icon" data-state="open" data-tooltip="More details" aria-label="More details">?</button>
+```
+
+`aria-disabled="true"` communicates disabled state but does not prevent activation. JavaScript or element choice must prevent activation when required.

package/docs/concepts.md

@@ -0,0 +1,94 @@
+---
+title: Concepts
+description: The three-axis model, the token system, and how theme selection works.
+---
+
+# Concepts
+
+Read this before the usage guides. It explains the mental model every
+component, token, and class in this package shares.
+
+## The three axes
+
+Every component separates three independent choices, so each can change
+without a component-specific variant:
+
+| Axis         | Question        | Classes                                                                                   | Inheritance  |
+| ------------ | --------------- | ----------------------------------------------------------------------------------------- | ------------ |
+| Intent       | Which color?    | `.primary`, `.secondary`, `.success`, `.warning`, `.destructive`, `.info`                 | Element only |
+| Presentation | How much of it? | `.solid`, `.soft`, `.ghost`, `.edged`, `.edgeless`                                        | Cascades     |
+| Aesthetic    | Made of what?   | `.neobrutalism`, `.glass`, `.pixel`, `.chunky-tile` from an optional aesthetic stylesheet | Cascades     |
+
+```html
+<section class="soft pixel">
+  <button class="btn primary">Soft primary pixel button</button>
+  <button class="btn destructive ghost edged">Outlined destructive override</button>
+</section>
+```
+
+Intent stays on the component so a semantic container cannot accidentally
+recolor nested controls. Presentation and aesthetic cascade from a container;
+putting either class directly on a component overrides the inherited choice.
+Components apply documented clamps when an axis would remove an essential edge
+or overwhelm compact geometry.
+
+The maintained contract is the intersection of the combinations documented in
+[Usage](./usage/index.md) and demonstrated by the playground. Undocumented and
+undemonstrated combinations may produce CSS but are not supported behavior.
+
+- [Usage → Composing](./usage/composing.md) shows how the three axes combine
+  on each component, with the full axis-support matrix.
+- [Usage → Aesthetics](./usage/aesthetics.md) covers each aesthetic and its
+  documented exceptions in depth.
+
+## The token system
+
+Tokens are CSS custom properties, grouped by what they control rather than
+where they're used:
+
+| Category     | Controls                                                                                    | Reference                                                         |
+| ------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Color        | The palette: primary, accent, success, warning, destructive, info, text, borders, surfaces. | [Usage → Theming](./usage/theming.md#color-tokens)                |
+| Intent       | Which color slot a component reads once an intent class is applied.                         | [Usage → Theming](./usage/theming.md#intent-tokens)               |
+| Foundation   | Layout, shape, motion, focus, depth, and layering defaults shared across components.        | [Usage → Theming](./usage/theming.md#foundation-tokens)           |
+| Presentation | How much of an intent a component shows — fill and border percentages.                      | [Usage → Customizing](./usage/customizing.md#presentation-tokens) |
+| Material     | What a component is made of — radius, border width, shadow geometry, translucency.          | [Usage → Customizing](./usage/customizing.md#material-tokens)     |
+| Aesthetic    | Per-aesthetic knobs such as `--pixel-unit` or `--tile-lift`.                                | [Usage → Customizing](./usage/customizing.md#aesthetic-tokens)    |
+
+Color and foundation tokens are the ones most apps touch first, to match a
+brand palette or spacing scale. Intent, presentation, and material tokens are
+lower-level: components read them, and only presentation classes, aesthetic
+classes, or a consumer override should set them.
+
+## Theme selection
+
+The root follows the operating-system `color-scheme` preference until an
+explicit selector overrides it.
+
+| Theme | Equivalent selectors                             |
+| ----- | ------------------------------------------------ |
+| Light | `.light`, `.theme-light`, `[data-theme="light"]` |
+| Dark  | `.dark`, `.theme-dark`, `[data-theme="dark"]`    |
+
+- Theme selectors set `color-scheme` and nothing else. Because `color-scheme`
+  inherits, a selector themes its entire subtree.
+- With no explicit selector, `:root` uses `color-scheme: light dark`, so the
+  system preference decides.
+- A theme selector on `:root` overrides the system preference in either
+  direction.
+- A nested explicit selector overrides an inherited theme, so the nearest
+  themed ancestor controls that subtree at any depth.
+- If conflicting light and dark selectors are placed on the same element, the
+  dark declaration wins because it appears later with equal specificity. Do
+  not rely on this conflict behavior; apply one theme per element.
+- Component colors resolve from tokens or `currentColor`, so they follow the
+  theme without separate dark-variant rules, with no exception: every glyph
+  the package draws is a `currentColor` mask. Icon artwork a consumer brings
+  is theirs to theme.
+
+Setting `color-scheme` yourself on an element also re-themes the tokens below
+it, because that is the only signal the palette reads. This also themes native
+UI such as scrollbars and form-control internals to match.
+
+This mechanism works from Chrome 123, Safari 17.5, and Firefox 120; the package
+overall requires Firefox 121 for `:has()` (see [Setup](./setup.md#requirements)).