@codenhub/styles 0.5.0 → 0.7.0

package/docs/changelog/0.7.0.md

@@ -0,0 +1,50 @@
+---
+title: 0.7.0
+date: 2026-11-04
+description: Liquid glass buttons, solo classes that compose with presentation, intent, and elevation, the shipped loaders removed in favor of icon spinners, and fixes to layout gaps, dialog margins, tables, switches, field groups, and forced colors.
+---
+
+# 0.7.0
+
+A button can be a liquid glass pane, the solo classes compose with presentation, intent, and elevation the way components do, the loaders are gone in favor of a spinner from an icon set, and a round of fixes to nested layout gaps, dialog placement, table rows, right-to-left switches, field groups, and forced colors.
+
+## Added
+
+- **Liquid glass buttons.** A `.btn` carrying `.glass-liquid` itself, in a glass scope, takes the blur, lens, and rim of a liquid pane, with a lens sized for a control. The fill is still the presentation's: `.solid` is an opaque plate under the rim, `.ghost` and `.soft` are clear panes. A liquid region alone still leaves its controls solid. See [Aesthetics → Liquid buttons](../usage/aesthetics.md#liquid-buttons).
+- **Solo classes compose with presentation, intent, and elevation.** Fill and edge come from the element or a container, intent and elevation from the element's own class, so `.pixel-solo.edgeless` drops its ring, `.glass-solo.solid.success` is an opaque green pane, and `.neobrutalism-solo.flat` has no slab. With none of those classes a solo element paints what it did. See [Aesthetics → Solo classes](../usage/aesthetics.md#solo-classes).
+- **`--font-mono` is a documented token.** It sets the font of the `kbd`, `code`, and `pre` helpers and of `<kbd>`, `<code>`, and `<pre>` under `/native`, and joins the other font tokens in [Theming → Fonts](../usage/theming.md#fonts), which also shows how to load a web font.
+- **Linking without a bundler.** [Integrating → Without a bundler](../integrating/without-a-bundler.md) covers plain HTML, Rails, Django, and a CDN `<link>`, which load the compiled files by path rather than by package name.
+- **A stated versioning policy.** Below 1.0 a minor release may break and a patch release never does; see [Versioning](../index.md#versioning).
+
+## Changed
+
+- **A solo element inside a `.solid`, `.soft`, or `.ghost` container takes that fill and the theme's text color**, since presentation cascades to it now as it does to components. A solo element whose own background does not follow the theme -- a dark toast on a light page -- inside such a container prints the theme's text; keep it out of the container, or give it `.solid` with an intent.
+- **`.tight` and `.loose` stay on their own element.** They wrote `--layout-gap`, which inherits, so a plain `.stack`, `.view`, `.cluster`, or `.auto-grid` nested inside one took its gap. A nested layout keeps the default gap now; set `--layout-gap` on a container to change the gap of every layout inside it.
+- **Your margin places a component dialog.** The centring of an open `<dialog class="card">` (or `.panel`, `.surface`) overruled your margin utilities and unlayered CSS; it now sits in `utilities` at zero specificity, so `mt-8` or your own rule wins, and it still beats a `base` reset such as Preflight's. A margin reset in a cascade layer of your own, declared after the package's, now wins over the centring too, as it already does over every component property.
+- **`.cyber` glows from the outline.** Its glow is the intent color at 60% with a 1px spread, up from 40% with none, so the brightest point sits on the element's outline. An edgeless button, badge, or panel read as backlit -- a shadow on a dark page -- because the glow just outside it was brighter than its own fill. `.cyber-solo` takes the same glow. In the light theme the near-black glow of a neutral component is heavier too; a hued `--cyber-ink` is still the way to make it read as light there.
+- **The neutral palette values carry no hue.** `--palette-border`, `--palette-surface`, and `--palette-text` are `oklch(… 0 none)` in both themes, where they were `oklch(… 0 0)`. The colors themselves are unchanged, but a missing hue takes its partner's in polar interpolation: `color-mix(in oklch, var(--palette-text), oklch(60% 0.2 240))` now lands on hue 240, a blue, where it travelled from hue 0 and landed on a purple. To keep the old result, give the neutral its old hue: `color-mix(in oklch, oklch(from var(--palette-text) l c 0), oklch(60% 0.2 240))`. Mixing in `oklab` does not, since a hueless neutral adds no hue there and the mix stays blue.
+
+## Removed
+
+- **The loaders.** `.loader`, its `.sm` and `.lg` sizes, the nine variants (`.dots-wave`, `.dots-fade`, `.dots-queue`, `.dots-rotate`, `.dots-grow`, `.dots-grow-alternate`, `.dot-bounce`, `.bars-wave`, `.pulse-ring`), `.loader-mask`, and the `@codenhub/styles/tw/loader` entrypoint are gone. Importing `/tw/loader` now fails to resolve, and `<span class="loader dots-wave">` in the complete CSS renders nothing. `.sm` and `.lg` on other components are unchanged. Use a spinner from an icon set instead, such as `@codenhub/icons`, which this package does not import: a glyph with `ic-anim-spin` (`ic-lucide-loader-circle ic-anim-spin`) or the animated `svg-spinners` family, both in `currentColor`. Under `prefers-reduced-motion: reduce` every loader showed a still ring; a glyph with `ic-anim-spin` stops there too, but `svg-spinners` artwork keeps moving, so choose the glyph where that matters. See [Feedback](../usage/feedback.md) for loading the icons.
+
+## Fixed
+
+- **A focused `.solid.primary` control under `.pixel` shows its focus.** The inset focus ring is the primary color, so it vanished into the fill; a line of the page color now sits inside it. `.pixel-solo` takes the same line.
+- **Controls and surfaces under `.pixel` keep an edge in forced colors.** Pixel draws its edge as an inset shadow, which forced colors remove, so buttons, fields, and cards had no boundary; forced colors now draw a solid border and drop the clip. `.pixel-solo` draws an inward outline there.
+- **A `.disabled` text field holds still under the pointer.** The class spelling of disabled still darkened an `.ipt`'s line on hover, unlike `disabled`, `aria-disabled`, and `data-disabled`.
+- **`.sketch-rounded` beside `.sketch-solo` stays on the solo element.** Its radius tokens inherited into the element's contents, so a `.btn` inside a rounded sketch toast drew a sketch outline on a page with no sketch in scope.
+- **A checked native radio looks like a checked `.radio` in forced colors.** Under `/native` it drew a Highlight ring and dot on Canvas, where `.radio` draws a Highlight disc with a HighlightText dot, so `<input type="radio" class="radio">` changed look with the entrypoint. Both draw the disc now.
+- **`/theme` declares every documented color and foundation token**, except `--focus-ring-offset`, which is computed on the focused element, and the `/tw`-only `--breakpoint-xs`. The compiled entry left out `--color-background`, `--color-foreground`, `--color-text-secondary`, and `--font-default`, because nothing in it read them, so `var(--color-background)` in your own CSS over `/theme` alone resolved to nothing.
+- **A liquid region blurs what takes no liquid layers.** A bare `<table>` under `/native` or your own `@apply surface` inside a `.glass-liquid` region took its clearer ground with nothing blurred behind it; it takes liquid's lighter blur now.
+- **Liquid's corners stay off a solo element's contents.** `.glass-solo.glass-liquid` no longer hands liquid's corner tokens to what it holds, so a `.btn` inside a liquid solo toast keeps the page's corners.
+- **A checked `.switch` stays in its track right to left.** Under `dir="rtl"` the checked knob moved the left-to-right way, out past the track's right edge; it sits at the inline end, the left, now.
+- **A table row shows its own intent.** A `<tr class="destructive">` in a `.data-table.success` kept the table's green text, rule, and hover, because the table resolved them before the row's intent applied. A row with an intent draws them in its own now; on a `.solid` table its text keeps the table's ink -- the contrast ink on a hued table, the table's own text color on a neutral one -- which that plate needs. Other rows keep the table's.
+- **A button in an `.input-group` keeps its own edge.** The field's line reached every component inside the group, so a `.ghost` or `.edgeless` clear button drew a border the field's color. It rests as it does outside the group now, and the group keeps its line.
+- **An `.alert` in another aesthetic nested under `.neobrutalism` casts no slab.** Neobrutalism raised the elevation of every alert below it, so one inside a `.chunky-tile`, `.glass`, `.pixel`, `.cyber`, or `.sketch` region took neobrutalism's shadow, unlike a card there. It takes the nested aesthetic's look now, and a `.neobrutalism` region nested inside that one still rests its alerts on the slab.
+- **A select keeps its drop-down arrow in forced colors.** The chevron is drawn with gradients, which forced colors remove, so in Chromium and Firefox a `.select` or a native `<select>` under `/native` read as a text field. A single-row select shows the platform's arrow there now.
+- **An `.input-group` holding a disabled control holds still under the pointer.** The group dimmed and showed the not-allowed cursor, but its line still darkened on hover; it no longer does.
+- **A padding modifier pads only its own card or panel.** `.p-xs`, `.p-sm`, `.p-lg`, and `.flush` on a `.card` or `.panel` reached every card and panel nested inside it, so a card in a `.card.p-xs` sat at 8px instead of its 20px, and one in a `.flush` card had none. A nested surface keeps its own padding now; give it a modifier of its own to change it.
+- **A long select label in an `.input-group` stops short of the chevron.** The group took the select's inline padding, so a label too long for the field ran under the drop-down arrow, at the right or, right to left, at the left. A single-row select keeps room for its chevron at the inline end now.
+- **Typed text in a hued or invalid field reads at 4.5:1.** The text in `.ipt`, `.textarea`, and `.select` was the intent's base color, which fell as low as 2.5:1 against the field: a `.warning` field in the light theme, and `.success`, `.destructive`, `.info`, and `aria-invalid="true"` fields in the dark one, worst on `.soft` and `.solid`. It is the intent's strong tone now, darker in light and lighter in dark, at 4.5:1 or better for every intent and presentation in both themes. The field's line, focus ring, and fill are unchanged. Native fields under `/native` take the same text. A field with no intent class takes the neutral strong tone too, so its text is a shade different from 0.6.
+- **The package's NOTICE covers the checkbox marks' Feather origin.** The checkbox check and indeterminate minus come from Lucide icons derived from Feather, and NOTICE now carries Feather's MIT notice beside Lucide's ISC one.

package/docs/changelog/index.md

@@ -6,6 +6,8 @@ group: Changelog
 
 # Changelog
 
+- [0.7.0](0.7.0.md)
+- [0.6.0](0.6.0.md)
 - [0.5.0](0.5.0.md)
 - [0.4.0](0.4.0.md)
 - [0.3.0](0.3.0.md)

package/docs/concepts.md

@@ -1,69 +1,211 @@
 ---
-title: Concepts
-description: The three-axis model, the token system, and how theme selection works.
-order: 2
+title: Building a screen
+description: Lay out the settings page, set its type, and add cards and buttons while learning intent, fill, edge, and aesthetic.
+order: 3
 ---
 
-# Concepts
+# Building a screen
 
-Read this before the usage guides. It explains the mental model every component, token, and class in this package shares.
+This page turns the empty shell from [Setup](./setup.md) into the first real part of the settings screen: a page header, a profile card with Save and Cancel buttons, and a plan summary beside a usage card. On the way it introduces the three choices every component makes, intent, presentation, and aesthetic, at the moment the screen needs each one. Everything else in these docs builds on this model.
 
-## The three axes
+## The smallest screen
 
-Every component separates three independent choices, so each can change without a component-specific variant:
+A page header and one card with one button:
 
-| 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`, `.cyber` from an optional aesthetic stylesheet | Cascades     |
+```html
+<main class="section">
+  <div class="section-content narrow stack">
+    <h1 class="text-title">Account settings</h1>
+    <section class="card stack">
+      <h2 class="text-title-sm">Profile</h2>
+      <p>Your name appears on invoices and shared projects.</p>
+      <button class="btn primary" type="button">Save changes</button>
+    </section>
+  </div>
+</main>
+```
+
+Each class does one job:
+
+- `.section` pads the page: a responsive gutter at the sides (1 to 2rem) and generous space above and below (4 to 7rem).
+- `.section-content` centers a column with a maximum width; `.narrow` makes that 48rem instead of 80rem, a comfortable width for a form.
+- `.stack` lays its children out vertically with a 1rem gap.
+- `.text-title` and `.text-title-sm` set heading sizes: 1.875rem bold and 1.25rem semibold.
+- `.card` is a bordered container with rounded corners and 1.25rem of padding.
+- `.btn` makes a button, and `.primary` gives it the primary color.
+
+Headings are not sized by their tag: the reset gives an `<h1>` with no type class the same size and weight as the text around it. That keeps the document structure, which heading level an element is, separate from the size you want it to look. If you want headings styled automatically, see [Setup → Classless HTML](./setup.md#classless-html).
+
+## Lay out the page
+
+Three layout helpers cover most screens, and all three use the same gap, `--layout-gap` (1rem):
+
+- `.stack` for vertical lists of blocks.
+- `.cluster` for a row that wraps when it runs out of room, such as a group of buttons. Add `.between` to push the first and last items to opposite ends.
+- `.auto-grid` for a grid of equal cards that adds or drops columns as the space changes. A column is never narrower than `--layout-grid-min` (16rem) unless the container itself is.
+
+`.tight` (0.5rem) and `.loose` (1.5rem) change the gap of the layout they sit on. A layout nested inside keeps its own gap.
+
+Add a header and put the buttons in a row:
 
 ```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>
+<main class="section">
+  <div class="section-content narrow stack loose">
+    <header class="stack tight">
+      <h1 class="text-title">Account settings</h1>
+      <p>Manage your profile, plan, and security.</p>
+    </header>
+
+    <section class="card stack" aria-labelledby="profile-title">
+      <h2 class="text-title-sm" id="profile-title">Profile</h2>
+      <p>Your name appears on invoices and shared projects.</p>
+      <div class="cluster">
+        <button class="btn primary" type="button">Save changes</button>
+        <button class="btn ghost" type="button">Cancel</button>
+      </div>
+    </section>
+  </div>
+</main>
 ```
 
-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.
+[Content and layout](./usage/content-and-layout.md) lists every layout helper, including `.view`, `.divider`, and `.visually-hidden`, and the full type scale.
+
+## Intent: which color
+
+The Save button is `.primary` and the Cancel button has no intent, which makes it neutral. An intent class picks a color role:
+
+| Class          | Use it for                            | Default color                           |
+| -------------- | ------------------------------------- | --------------------------------------- |
+| _none_         | Anything without a meaning of its own | The page's text and border grays        |
+| `.primary`     | The main action on a screen           | Near-black on light, near-white on dark |
+| `.secondary`   | A second, quieter action              | Mid gray                                |
+| `.success`     | Confirmation and completed states     | Emerald green                           |
+| `.warning`     | Something that needs attention soon   | Amber, with dark text                   |
+| `.destructive` | Deleting, revoking, and errors        | Rose red                                |
+| `.info`        | Neutral notices and help              | Indigo                                  |
+
+Intent stays on the element that carries it. Putting `.destructive` on a `<section>` does not turn every button inside it red; you write it on each button. This is deliberate: a container that silently recolored everything inside it would turn a red danger zone's Cancel button red too.
+
+`.neutral` names the default explicitly. You rarely need it, because no intent class already means neutral; it matters where color would otherwise come from elsewhere, such as a table row, which inherits its table's intent.
+
+## Presentation: how much color
+
+The Cancel button is `.ghost`: no fill, just colored text, so it reads as less important than Save. That is the presentation axis, two independent choices:
+
+- **Fill:** `.solid` fills the component with its intent color and switches the text to the contrasting color. `.soft` mixes in a light 12% tint and keeps the text in the intent color. `.ghost` has no fill at rest.
+- **Edge:** `.edged` draws a border in the intent color; `.edgeless` draws none.
+
+```html
+<button class="btn primary">Save changes</button>
+<button class="btn primary soft">Preview</button>
+<button class="btn primary ghost edged">Export data</button>
+<button class="btn ghost">Cancel</button>
+```
+
+Every component has its own default when no presentation class applies. A button is solid with no border. A card has no fill and a border. A form field has no fill and a border. [Composing](./usage/composing.md#component-defaults) lists the default of every component.
+
+Unlike intent, presentation passes down. A `.soft` on a container makes everything inside it soft unless an element says otherwise, and a class on the element itself always beats one inherited from a container:
+
+```html
+<div class="cluster soft">
+  <button class="btn primary">Soft primary</button>
+  <button class="btn success">Soft success</button>
+  <button class="btn primary solid">Solid: its own class wins</button>
+</div>
+```
+
+Some components limit what presentation can do, to protect something they need. A form field inherited into a `.solid` container fills to only 6%, so typed text stays readable. A checkbox always keeps its border, because the border is the only thing that shows an unchecked box. These limits are listed with each component and collected in [Composing](./usage/composing.md).
+
+## Finish the first screen
+
+Add a plan summary next to a usage card in a grid, and give the summary a soft primary tint so it stands out as the account's current state:
+
+```html
+<main class="section">
+  <div class="section-content narrow stack loose">
+    <header class="stack tight">
+      <h1 class="text-title">Account settings</h1>
+      <p>Manage your profile, plan, and security.</p>
+    </header>
+
+    <section class="card stack" aria-labelledby="profile-title">
+      <h2 class="text-title-sm" id="profile-title">Profile</h2>
+      <p>Your name appears on invoices and shared projects.</p>
+      <div class="cluster">
+        <button class="btn primary" type="button">Save changes</button>
+        <button class="btn ghost" type="button">Cancel</button>
+      </div>
+    </section>
+
+    <div class="auto-grid">
+      <section class="card soft primary stack tight" aria-labelledby="plan-title">
+        <h2 class="text-label" id="plan-title">Current plan</h2>
+        <p class="text-title-sm">Team, billed yearly</p>
+        <p class="text-body">Renews on 12 March 2027.</p>
+      </section>
+      <section class="card stack tight" aria-labelledby="usage-title">
+        <h2 class="text-label" id="usage-title">Storage</h2>
+        <p class="text-title-sm">48 GB of 100 GB</p>
+        <p class="text-body">Shared by 6 members.</p>
+      </section>
+    </div>
+  </div>
+</main>
+```
+
+On a wide window the two cards sit side by side; when the column is too narrow for two 16rem columns and the gap between them, they stack. The [Feedback](./usage/feedback.md) page turns the storage card's number into a usage bar.
+
+A `.card` rests at one unit of depth, but on the base look that depth has no visible shadow; it appears when an aesthetic draws one or when you add `.raised` or `.floating`. [Composing → Elevation](./usage/composing.md#elevation) covers depth.
+
+## Aesthetic: what it is made of
+
+The third axis changes the material of everything inside it: corners, border width, shadows, and sometimes the font. It needs its own import (see [Setup → Add an aesthetic](./setup.md#add-an-aesthetic-optional)):
+
+```html
+<main class="section neobrutalism">
+  <!-- The same settings screen: square corners, thick dark lines, hard offset shadows -->
+</main>
+```
 
-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.
+Like presentation, an aesthetic passes down, and a component inside it can carry a different one. You do not need it to build the screen; [Aesthetics](./usage/aesthetics.md) compares all six.
 
-- [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.
+## Words these docs use
 
-## The token system
+Some pages describe how a component is painted. These words have one meaning each:
 
-Tokens are CSS custom properties, grouped by what they control rather than where they're used:
+| Word      | Meaning                                                                                                                                                          |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Fill      | How much of the intent color covers the component, from 0% (`.ghost`) to 100% (`.solid`).                                                                        |
+| Cap       | The highest fill a component allows. A form field caps an inherited fill at 6%, for example.                                                                     |
+| Plate     | The component's painted background: the fill, mixed over the ground.                                                                                             |
+| Ground    | The color the fill is mixed over. Usually the page itself shows through; a few components set their own, such as the light intent tint under `.kbd` and `.code`. |
+| Edge      | The border around the component. It is separate from rules, the lines inside a table.                                                                            |
+| Ink       | A color used to draw lines: the edge, a table's rules, a checkbox's mark. "Text ink" means the color of text printed on a plate.                                 |
+| Material  | What an aesthetic changes: corner radius and shape, border width and style, shadow, and transparency.                                                            |
+| Slab      | A hard, unblurred shadow offset down and to one side, as `.neobrutalism` and `.chunky-tile` draw.                                                                |
+| Elevation | How much of the shadow in scope an element takes: none (`.flat`), one unit (`.raised`), or two (`.floating`).                                                    |
 
-| 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)    |
+## Tokens behind the classes
 
-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.
+Every class reads CSS custom properties, called tokens, so you can change the result without rewriting a class:
 
-## Theme selection
+| Kind         | Controls                                                                        | Where it is listed                                                              |
+| ------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Color        | The palette: intent colors, text, borders, and backgrounds, for light and dark. | [Theming → Color tokens](./usage/theming.md#color-tokens)                       |
+| Foundation   | Layout widths and gaps, corner radii, control height, focus, motion.            | [Theming → Foundation tokens](./usage/theming.md#foundation-tokens)             |
+| Intent       | The color slots a component reads after an intent class picks a role.           | [Theming → Intent tokens](./usage/theming.md#intent-tokens)                     |
+| Presentation | The fill and border percentages the presentation classes set.                   | [Customizing → Presentation tokens](./usage/customizing.md#presentation-tokens) |
+| Material     | Radius, border width, shadow geometry, and transparency.                        | [Customizing → Material tokens](./usage/customizing.md#material-tokens)         |
+| Aesthetic    | One knob per aesthetic, such as `--pixel-unit` or `--tile-lift`.                | [Customizing → Aesthetic tokens](./usage/customizing.md#aesthetic-tokens)       |
 
-The root follows the operating-system `color-scheme` preference until an explicit selector overrides it.
+Color and foundation tokens are what most apps change first, to match a brand. The rest are lower level: components read them, and the presentation and aesthetic classes set them for you.
 
-| Theme | Equivalent selectors                             |
-| ----- | ------------------------------------------------ |
-| Light | `.light`, `.theme-light`, `[data-theme="light"]` |
-| Dark  | `.dark`, `.theme-dark`, `[data-theme="dark"]`    |
+## Limits to know now
 
-- 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.
-- The Tailwind source entrypoints' `dark:` variant tracks this rule for the explicit-selector-versus-system-preference choice: it fires under an explicit dark selector, or under the system preference when the subtree carries no explicit selector at all. It does not track the previous rule the same way: that one holds because `color-scheme` inherits, so the nearest declaration always wins regardless of depth, while `dark:` matches by selector -- `.dark *` matches every descendant of a `.dark` element, with no way to stop at a nearer `.light` in between. A `.light` subtree nested inside `.dark` themes its tokens correctly but still matches `dark:`'s explicit arm. See [Setup → Dark variant](./setup.md#dark-variant).
+- **Intent does not pass down.** Write it on each element that shows it. The only exception is table rows.
+- **Classes are styling only.** `<div class="btn">` looks like a button but cannot be focused or pressed with a keyboard. Use `<button>` or `<a href>`, and see [Accessibility](./accessibility.md).
+- **A combination the docs do not describe is not supported.** It may render, but it can change in any release; see [Introduction → What counts as supported](./index.md#what-counts-as-supported).
 
-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.
+## Next
 
-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)).
+The screen has one primary action and one quiet one. [Buttons](./usage/buttons.md) adds the rest: a destructive action for the danger zone, icon buttons, sizes, and disabled states.

package/docs/es/accessibility.md

@@ -0,0 +1,150 @@
+---
+title: Accesibilidad
+description: Lo que hace el CSS con el foco, los estados, el movimiento, el contraste, los colores forzados y el texto de derecha a izquierda, y lo que tu aplicación todavía les debe a sus usuarios.
+order: 5
+source: dc1a745e9e6853a31ca4a8cf7a334031bab1ec7d
+---
+
+# Accesibilidad
+
+La pantalla de ajustes está construida, y el CSS ha hecho su parte por el camino: cada campo muestra dónde está el foco, un email inválido se vuelve rojo y el spinner se detiene para los usuarios que piden menos movimiento. El resto depende de tu HTML y tu JavaScript. Este paquete da estilo a los estados; no aporta elementos semánticos, atributos ARIA, comportamiento de teclado, gestión del foco, validación ni el momento de los anuncios.
+
+Esta página enumera las dos mitades: lo que aporta el CSS y lo que tu aplicación tiene que añadir.
+
+## Lo que aporta el CSS
+
+### Foco y estado
+
+| Característica                  | Comportamiento                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `:focus-visible`                | Un contorno de foco en cada elemento, dibujado con `--focus-ring`, `--focus-ring-width` y `--focus-ring-offset`.                                                                                                                                                                                                                                  |
+| Foco en controles de formulario | `.ipt`, `.textarea` y `.select` dibujan el contorno de foco y cambian su borde al color de la intención. El texto escrito en un campo con una clase de intención usa el tono legible de esa intención, `--intent-strong`.                                                                                                                         |
+| Controles inválidos             | `aria-invalid="true"` en un control de formulario vuelve destructivos su borde, su color de foco y el texto escrito, este último en el tono legible destructivo.                                                                                                                                                                                  |
+| Controles deshabilitados        | `disabled`, `aria-disabled="true"`, `data-disabled` y `.disabled` muestran el cursor y la opacidad de deshabilitado, y un control deshabilitado no reacciona al hover, tampoco dentro de un `.input-group`.                                                                                                                                       |
+| Estado abierto                  | `data-state="open"` en un `.tooltip` muestra su burbuja sin hover ni foco, y `data-state="closed"` la oculta aunque tenga hover o foco. Ningún otro componente lee ninguno de los dos.                                                                                                                                                            |
+| `<dialog>` nativo               | Un `<dialog>` con `.card`, `.panel` o `.surface` permanece oculto hasta que se abre, y se abre centrado. Un margen que pongas en el diálogo, como utilidad o en tu propio CSS, sigue sobrescribiendo el centrado. Los demás diálogos no se tocan. Atrapar el foco, cerrar con Escape y dejar inerte la página de detrás es cosa de tu aplicación. |
+
+### Contenido visualmente oculto
+
+`.visually-hidden` oculta contenido en pantalla y lo mantiene para los lectores de pantalla, como hace el `<caption>` de la tabla de claves de API en [Contenido y layout → Tablas](./usage/content-and-layout.md#tablas). Viene con las utilidades de layout: en `.`, `./native`, `./tw`, `./tw/native` y `./tw/utilities`. No está en `./components` ni en los puntos de entrada de componentes `./tw/components` y `./tw/*`.
+
+### Límites de los controles
+
+WCAG 1.4.11 pide que el límite de un control que necesitas ver para usarlo tenga un contraste de al menos 3:1 con lo que lo rodea.
+
+| Característica                  | Comportamiento                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Controles de texto en reposo    | El borde de un control de texto reposa más claro que el borde completo de su intención, por debajo de 3:1 a propósito, para que el hover y el foco tengan un tono más intenso al que cambiar.                                                                                                                                                                                                                                                                                                           |
+| Toggles                         | `.checkbox`, `.radio` y `.switch` dibujan su borde completo, porque el borde es lo único que muestra una casilla sin marcar. Un `.switch` con su propio `.edgeless` es la excepción, más abajo.                                                                                                                                                                                                                                                                                                         |
+| `.edgeless` desde un contenedor | Lo ignoran todos los controles de texto y toggles: un contenedor no puede quitar el borde de un campo o toggle que contiene.                                                                                                                                                                                                                                                                                                                                                                            |
+| `.edgeless` en el control       | `.ipt`, `.textarea`, `.select` y `.switch` pierden su borde y dejan de cumplir 1.4.11 en reposo. `.switch.ghost` conserva su borde incluso entonces, porque sin relleno y sin borde nada mostraría el carril.                                                                                                                                                                                                                                                                                           |
+| `.checkbox`, `.radio`           | Siempre dibujan su borde, venga `.edgeless` de un contenedor o lo lleven ellos mismos. `.edgeless` en ellos no está soportado.                                                                                                                                                                                                                                                                                                                                                                          |
+| Carril de progreso              | A propósito, la parte rellena lleva el valor y el carril es un fondo discreto. El carril por defecto, `.soft.edgeless`, mide aproximadamente de 1.1:1 a 1.3:1 frente a la página. La parte rellena mide al menos 3:1 frente a ese carril para todas las intenciones excepto warning en claro (unos 2.7:1) e info en oscuro (unos 2.9:1). Donde el propio carril deba cumplir 1.4.11, usa `.ghost.edged` con una clase de intención; consulta [Contornos de progreso](#contornos-de-progreso) más abajo. |
+
+### Contornos de progreso
+
+En un `.progress.ghost.edged`, el carril es la página, y tanto su contorno como la parte rellena se dibujan en el color de la intención. Medido frente a la página, sin estética:
+
+| Intención      | Página clara | Página oscura | Cumple 3:1                                                                    |
+| -------------- | ------------ | ------------- | ----------------------------------------------------------------------------- |
+| `.primary`     | 18.96:1      | 18.96:1       | Sí                                                                            |
+| `.secondary`   | 7.47:1       | 7.63:1        | Sí                                                                            |
+| `.success`     | 5.14:1       | 3.69:1        | Sí                                                                            |
+| `.warning`     | 3.06:1       | 6.20:1        | Sí                                                                            |
+| `.destructive` | 5.80:1       | 3.27:1        | Sí                                                                            |
+| `.info`        | 6.17:1       | 3.07:1        | Sí                                                                            |
+| Sin intención  | 2.48:1       | 1.91:1        | No: el contorno no cumple, aunque la parte rellena, en el color del texto, sí |
+
+Sin clase de intención, el contorno es el gris discreto de los bordes, `--color-border`. Para que un carril neutro cumpla 1.4.11, dale a la barra una clase de intención, o define `--progress-edge` con un color más intenso, como `var(--color-accent)`, que mide 7.47:1 en una página clara y 7.63:1 en una oscura. Warning en una página clara e info en una oscura superan 3:1 por poco margen, así que vuelve a medir si cambias esos colores.
+
+### Movimiento y transparencia
+
+| Característica                      | Comportamiento                                                                                                                                                                                                             |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Movimiento reducido, componentes    | Con `prefers-reduced-motion: reduce`, cada componente detiene sus propias transiciones y animaciones: el brillo del skeleton y del progreso, la barra indeterminada, el tooltip, las marcas de los toggles y la pulsación. |
+| Movimiento reducido, toda la página | El reset también acorta todas las demás animaciones y transiciones de la página.                                                                                                                                           |
+| Transparencia reducida              | Con `prefers-reduced-transparency: reduce`, `.glass` y `.glass-liquid` pierden su desenfoque y su lente y se vuelven opacos.                                                                                               |
+
+La regla de movimiento reducido de cada componente viene con el componente, así que cada punto de entrada que lo incluye respeta el movimiento reducido sin el reset, incluidos `@codenhub/styles/components`, `@codenhub/styles/tw/components` y cada punto de entrada de componente `/tw/*`. Los puntos de entrada completo y native añaden la regla del reset para toda la página.
+
+La regla del reset es `!important` dentro de la capa `base`, y un `!important` con capa gana a uno sin capa, así que tu propio `!important` no puede volver a activar una animación. Para mantener una en marcha para los usuarios que piden movimiento reducido, como un spinner de subida que consideres esencial, declárala `!important` en una capa ordenada antes de `base`. La primera sentencia `@layer` que lee el navegador fija el orden, así que la tuya va antes del paquete:
+
+```css
+@layer essential-motion, theme, base, components, utilities;
+@import "@codenhub/styles";
+
+@layer essential-motion {
+  @media (prefers-reduced-motion: reduce) {
+    .upload-spinner {
+      animation-duration: 1s !important;
+      animation-iteration-count: infinite !important;
+    }
+  }
+}
+```
+
+Respetar el movimiento reducido no es todo lo que se pide. El movimiento que sigue en marcha junto al contenido, como un brillo que queda en una tarjeta después de que ha cargado, necesita una forma de detenerlo para todos los usuarios; consulta [Feedback → Animación que no se detiene](./usage/feedback.md#animación-que-no-se-detiene).
+
+### Color y contraste
+
+Las mediciones de abajo corresponden a los colores incluidos. En cuanto cambies un token de color, vuelve a medir tus propios pares; [Temas → Cambiar el color de marca](./usage/theming.md#cambiar-el-color-de-marca) muestra qué pares comprobar.
+
+| Característica               | Comportamiento                                                                                                                                                                                                                                                      |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Etiquetas rellenas           | La etiqueta `.solid` de cada intención cumple 4.5:1 (WCAG 1.4.3) como texto normal, en ambos temas. La más baja es success, con 5.14:1.                                                                                                                             |
+| Texto de warning             | `--color-warning-contrast` es casi negro, no el color de la página, porque un ámbar lo bastante oscuro para llevar texto blanco ya no parece ámbar.                                                                                                                 |
+| Rellenos parciales           | El color de texto de contraste solo aparece en rellenos por encima de la mitad de intensidad, así que el relleno limitado de un control de texto conserva el color de texto propio de la intención.                                                                 |
+| Color de intención en oscuro | En modo oscuro, una etiqueta `.soft` o `.ghost` usa el tono `-300` de su intención, así que conserva su matiz en lugar de volverse blanca.                                                                                                                          |
+| Marcas de los toggles        | Una marca activada mide al menos 3:1 frente a cada relleno que su presentación pueda darle, en ambos temas.                                                                                                                                                         |
+| Rellenos soft con borde      | `.edged` en un `.alert`, `.panel`, `.badge`, `.kbd`, `.code` o `.pre` `.soft` dibuja un borde que mide menos de 3:1 frente al relleno del 12% en algunas intenciones, cuáles depende del tema. Mide el par antes de confiar en ese borde como límite de un control. |
+
+### Colores forzados y dirección
+
+| Característica      | Comportamiento                                                                                                                                                                                                                                                                       |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Colores forzados    | Con `forced-colors: active`, los bordes, los estados activados y el chevron de un `.select` siguen visibles, dibujados con colores del sistema, bajo cualquier estética. Una estética que dibuja su borde como una sombra interior, como `.pixel`, dibuja en su lugar un borde real. |
+| Dirección del texto | Con `dir="rtl"`, la barra de las citas, el icono de la alerta, el relleno del progreso, el divisor vertical, la perilla del switch, la alineación de las tablas y el chevron de un select cambian de lado. No hace falta ninguna clase.                                              |
+
+Con colores forzados, `.text-control`, `.ipt`, `.textarea`, `.select` y los toggles muestran un contorno de foco `Highlight` de 2px. El punto de entrada native da el mismo contorno a los inputs de texto, selects, textareas, checkboxes y radios sin clase.
+
+Los checkboxes, radios y switches usan los colores del sistema `Canvas`, `CanvasText`, `Highlight` y `HighlightText`, así que activado y desactivado siguen siendo distinguibles: un toggle activado se rellena con `Highlight` y su marca es `HighlightText`, tanto en las clases como en el punto de entrada native. La forma, el tamaño y el espaciado no cambian.
+
+## Lo que hace falta fuera del CSS
+
+Usa el elemento HTML que corresponde a lo que hace el componente, y añade el comportamiento que el CSS no puede dar.
+
+| Interfaz            | Lo que añade tu aplicación                                                                                                                                                                                                                                       |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Botones             | `<button>` para acciones y `<a href>` para navegación. Un nombre accesible, como `aria-label`, en cada `.btn.icon`.                                                                                                                                              |
+| Formularios         | Un `<label>` para cada control, el `type` correcto, validación y `aria-describedby` enlazando pistas y errores. Mantén las pistas y los errores fuera del `<label>`, y dale a un `.switch` `role="switch"`.                                                      |
+| Alertas             | `role="status"` para una confirmación como "Perfil guardado", o `role="alert"` para un error que necesita atención inmediata.                                                                                                                                    |
+| Toasts              | Una región live, una forma de cerrarlo, reglas de foco y una pausa en cualquier temporizador.                                                                                                                                                                    |
+| Tooltips            | Un `id` real y `role="tooltip"` en la burbuja, referenciado desde el `aria-describedby` del disparador. El cierre con Escape escribiendo `data-state="closed"`; consulta [Tooltips](./usage/tooltips.md#hover-permanencia-y-escape). La burbuja ya admite hover. |
+| Progreso            | Un elemento `<progress>`, o `role="progressbar"` o `role="meter"` con valores ARIA, cuando el valor debe anunciarse.                                                                                                                                             |
+| Skeletons           | `aria-hidden="true"` en los elementos visuales de carga, incluido un spinner que aportes tú, y el estado de carga anunciado de otra forma cuando haga falta.                                                                                                     |
+| Movimiento continuo | Una forma de pausar, detener u ocultar el movimiento que no es esencial; consulta [Feedback → Animación que no se detiene](./usage/feedback.md#animación-que-no-se-detiene).                                                                                     |
+| Popovers, modales   | Atrapar el foco, cerrar con Escape, un fondo inerte, etiquetas y roles.                                                                                                                                                                                          |
+
+## Atributos de estado
+
+Prefiere los atributos nativos:
+
+```html
+<button class="btn primary" disabled>Saving…</button> <input class="ipt" type="email" aria-invalid="true" aria-describedby="email-error" />
+```
+
+Usa atributos ARIA o data donde el elemento o tu librería de componentes no tenga uno nativo:
+
+```html
+<a class="btn secondary" aria-disabled="true">Export data</a>
+<span class="tooltip" data-state="open">
+  <button type="button" class="tooltip-icon" aria-label="About public profiles" aria-describedby="public-profile-help">?</button>
+  <span class="tooltip-bubble" role="tooltip" id="public-profile-help">Anyone with the link can see your name and photo.</span>
+</span>
+```
+
+`aria-disabled="true"` indica a las tecnologías de asistencia que el control está deshabilitado, pero no impide un clic ni una pulsación de tecla. Usa el atributo `disabled`, o detén la acción en JavaScript.
+
+## Siguiente paso
+
+Con esto termina el orden de lectura. La [Introducción](./index.md) enlaza todas las páginas, y [Composición](./usage/composing.md), [Personalización](./usage/customizing.md) y [Contenido y layout](./usage/content-and-layout.md) son las páginas de consulta para más adelante.