@codenhub/styles 0.0.3 → 0.1.0

package/docs/usage/content-and-layout.md

@@ -0,0 +1,200 @@
+---
+title: Content and layout
+description: Layout helpers, content chips and tables, surfaces, and typography utilities.
+---
+
+# Content and layout
+
+## Layout
+
+Layout helpers use the shared `--layout-gap` token. `.tight` sets it to
+`0.5rem` and `.loose` sets it to `1.5rem` within a view, stack, cluster, or
+auto-grid.
+
+- `.view` is a flex container; `.vertical` and `.horizontal` set its
+  direction, and horizontal views wrap with centered cross-axis alignment.
+- `.stack` is a vertical flex stack.
+- `.cluster` is a wrapping horizontal flex row; `.between` adds
+  `space-between` alignment.
+- `.auto-grid` is a responsive auto-fit grid using `--layout-grid-min`.
+- `.tight` and `.loose` set the shared gap to `0.5rem` or `1.5rem` on views,
+  stacks, clusters, and auto-grids.
+- `.section` adds responsive block padding and an inline gutter.
+- `.section-content` centers content at `--container-max`; `.narrow` and
+  `.wide` select the corresponding container tokens.
+- `.divider` is horizontal; `.vertical` makes it self-stretch vertically. It
+  takes intent, but presentation classes do not affect it.
+
+The removed `--layout-stack-gap` and `--layout-cluster-gap` tokens have no
+compatibility aliases.
+
+## Content
+
+| Class           | Purpose                                                                                  | Intent affects         |
+| --------------- | ---------------------------------------------------------------------------------------- | ---------------------- |
+| `.table-wrap`   | Full-width horizontal overflow wrapper for wide tables.                                  | Nothing.               |
+| `.data-table`   | Rounded nested table styling for captions, heads, footers, cells, and rows.              | Head, border, hover.   |
+| `.ruled`        | On `.data-table`. Draws a rule between body rows.                                        | Rule color.            |
+| `.ruleless`     | On `.data-table`. Draws no lines inside the table at all.                                | Nothing.               |
+| `.kbd`          | Inline keyboard-input styling.                                                           | Surface, border, text. |
+| `.quote`        | Block quote styling; a nested `cite` is set upright and takes the quotation's own color. | Bar, surface, text.    |
+| `.quote-inline` | Inline quotation styling.                                                                | Nothing.               |
+| `.code`         | Inline code formatting.                                                                  | Surface.               |
+| `.pre`          | Scrollable block code formatting with larger padding.                                    | Surface.               |
+
+### Table rules
+
+A table draws three kinds of line, and `.ruled` and `.ruleless` move all of
+them together:
+
+| Class       | Head and foot boundaries | Rules between body rows |
+| ----------- | ------------------------ | ----------------------- |
+| `.ruleless` | No                       | No                      |
+| _no class_  | Yes                      | No                      |
+| `.ruled`    | Yes                      | Yes                     |
+
+```html
+<table class="data-table">Head and foot boundaries only</table>
+<table class="data-table ruled">Every row separated</table>
+<table class="data-table ruleless">No lines inside the table at all</table>
+```
+
+The boundaries under a head and above a foot separate the parts of a table
+from each other, so they are drawn by default where the row rules are not.
+Rules between body rows used to arrive on their own, because the
+component's published edge default is `edged` and the edge axis wrote the
+rules along with the boundary — so whether you got them depended on a
+registry default rather than on anything in your markup.
+
+`--ui-rule` is the token behind both classes, so a container can set the
+answer for a whole region without classing each table:
+
+```html
+<section style="--ui-rule: 100%">
+  <table class="data-table">Ruled by the region</table>
+</section>
+```
+
+The frame around the table is the edge axis and is asked for the same way:
+`.data-table` publishes `edgeless`, so `.edged` draws one. None of the
+three switches reaches the others — `.data-table.ruleless.edged` is a
+framed table with no lines inside it, and `.data-table.ruled` is a
+frameless one with every row separated.
+
+A table's rows deliberately inherit its intent instead of resetting it, so
+`.data-table.success` tints throughout. A row carrying its own intent still
+wins:
+
+```html
+<table class="data-table success">
+  <tbody>
+    <tr>
+      <td>Inherits the table intent</td>
+    </tr>
+    <tr class="destructive">
+      <td>Overrides it for this row</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+This is the one place intent cascades, because a table's rows are parts of
+the table rather than independent components.
+
+`.data-table`, `.kbd`, `.code`, and `.pre` also read
+[presentation](./composing.md#presentation). A table applies it to its
+header, its rules and its border; a chip to its whole plate:
+
+```html
+<table class="data-table success soft edged">...</table>
+<table class="data-table">A ghost table: rules and type, no header plate</table>
+<kbd class="kbd primary solid">Ctrl</kbd>
+<kbd class="kbd primary soft edged">Shift</kbd>
+```
+
+`.ghost` means two different things on these components, and both are worth
+knowing before you reach for it.
+
+On `.data-table` it removes the header plate along with the body tint, so
+`.data-table.ghost` is boundaries and type alone. The component rests at
+`soft`, so that is something to ask for rather than the default.
+
+On `.kbd`, `.code`, and `.pre` it is **not supported**. All three rest on
+`--intent-subtle`, and that ground draws the plate whatever the fill says —
+so `.ghost` took the fill away and changed nothing visible. Worse, the
+ground alone is a near-page tint: a ghost chip measured the same `#e5e5e5`
+for neutral and primary on the light page, and `#f5f5f5` at 1.04:1 against
+it for secondary. All three rest at `.soft` instead, which puts a real `12%`
+of the intent over the ground and separates them.
+
+Use `.table-wrap` around `.data-table` when table width may exceed its
+container:
+
+```html
+<div class="table-wrap">
+  <table class="data-table">
+    <thead>
+      <tr>
+        <th>Package</th>
+        <th>Status</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>styles</td>
+        <td>Ready</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
+
+## Surfaces
+
+| Class                | Purpose                                                                      |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `.card`              | Bordered container, surface radius, padded. Rests at elevation `1`.          |
+| `.panel`             | Flush container for sidebars, toolbars, and wells. No elevation.             |
+| `.interactive`       | On `.card`. Adds pointer cursor, hover and press response, and a focus ring. |
+| `.p-sm`, `.compact`  | On `.card` or `.panel`. Reduces padding.                                     |
+| `.p-lg`, `.spacious` | On `.card` or `.panel`. Increases padding.                                   |
+| `.flush`             | On `.card` or `.panel`. Removes padding, for edge-to-edge content.           |
+
+Both read intent, [presentation](./composing.md#presentation), and
+[material tokens](./customizing.md#material-tokens). A plain `.card` is a
+neutral bordered container; only an explicit presentation tints it. Resting
+at elevation `1` is not a visible shadow by itself — nothing draws depth
+until an [aesthetic](./aesthetics.md) supplies shadow geometry or
+`.elevation-sm`/`.elevation-md` asks for it; see
+[Composing → Elevation](./composing.md#elevation).
+
+On the base look, `.card.interactive` scales down slightly on press
+(`--ui-active-transform`, `scale(0.97)`); an [aesthetic](./aesthetics.md)
+substitutes its own press gesture, and `prefers-reduced-motion` turns it off.
+
+```html
+<article class="card">Neutral card</article>
+<article class="card success soft">Tinted success card</article>
+<article class="card primary ghost edged">Intent border, no fill</article>
+<a class="card interactive" href="/package">Responds to hover and press</a>
+<aside class="panel">Flush panel</aside>
+```
+
+`.interactive` is styling only. Use a real interactive element and give it
+an accessible name; a `<div class="card interactive">` is not focusable or
+operable by keyboard.
+
+## Typography utilities
+
+All typography classes and `.selection-contrast` are `@utility` classes.
+
+| Class                 | Purpose                                                      |
+| --------------------- | ------------------------------------------------------------ |
+| `.text-display`       | Large display headings.                                      |
+| `.text-title-lg`      | Large section titles.                                        |
+| `.text-title`         | Default section titles.                                      |
+| `.text-title-sm`      | Smaller titles or card titles.                               |
+| `.text-label-lg`      | Large label text.                                            |
+| `.text-label`         | Default label text.                                          |
+| `.text-body`          | Default body copy.                                           |
+| `.selection-contrast` | Inverts `::selection` colors to primary-contrast background. |

package/docs/usage/customizing.md

@@ -0,0 +1,213 @@
+---
+title: Customizing
+description: Presentation and material token reference, and aesthetic knobs.
+---
+
+# Customizing
+
+Presentation tokens decide how much of an intent shows. Material tokens
+decide what a component is made of. Aesthetic tokens are the small set of
+named knobs a shipped aesthetic exposes to scale its own look.
+
+## Presentation tokens
+
+Presentation tokens describe _how much_ of an intent a component shows,
+never _which_ intent it shows. They are unitless numbers and percentages, so
+they carry no color and inherit safely: a container sets them once and every
+component below resolves them against its own intent.
+
+| Token             | Purpose                                                                    |
+| ----------------- | -------------------------------------------------------------------------- |
+| `--ui-fill`       | Percentage of the intent color mixed into the background.                  |
+| `--ui-fg-on-fill` | Percentage blended from the intent readable tone toward its contrast tone. |
+| `--ui-border`     | Percentage of the intent color mixed into the border color.                |
+
+A component resolves them with `color-mix` from its published default. Hover
+is derived by adding `--hover-step` to the resting fill and using
+`--intent-hover`; there are no per-presentation hover tokens.
+
+No fill class writes `--ui-border` and no edge class writes `--ui-fill`. A
+filled box with no line is `.solid.edgeless`, which is worth reaching for on
+a neutral component: neutral caps its fill, so the box stays translucent and
+a border over it paints a second coat of the same tint instead of blending
+into it.
+
+```css
+background: color-mix(in oklab, var(--color-primary) var(--ui-fill, 100%), transparent);
+```
+
+Two choices there are deliberate. Mixing toward `transparent` rather than a
+background token lets a tinted surface adapt to whatever it is placed on.
+Mixing in `oklab` keeps the wide-gamut token palette intact and blends
+perceptually, where `srgb` would clip it.
+
+A computed color therefore reaches the page as a resolved `color-mix` result
+rather than the token's own `oklch` syntax. It is the same color; code that
+compares computed color strings should compare colors instead.
+
+> **Presentation token contract**: only presentation classes and consumer
+> overrides set these tokens; components only read them. Setting a value
+> that no presentation class produces is supported but unvalidated. See
+> [Composing](./composing.md) for the classes that ship these values.
+
+## Material tokens
+
+Material tokens describe what a component is _made of_ rather than which
+intent it shows or how strongly. They control shape, borders, shadows,
+translucency, filters, and transforms.
+
+Components read each with a fallback, so leaving them unset produces the
+default look. Setting them on a container restyles the whole subtree. Only
+shadow geometry is split into colorless parts that inherit safely;
+color-capable inputs such as `--ui-ink` and `--ui-surface-shadow` may
+include their own colors.
+
+| Token                   | Purpose                                                                                                       | Fallback             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------- |
+| `--ui-radius`           | Corner radius for controls.                                                                                   | `--radius-control`   |
+| `--ui-radius-surface`   | Corner radius for surfaces.                                                                                   | `--radius-surface`   |
+| `--ui-border-width`     | Edge thickness.                                                                                               | `--border-width`     |
+| `--ui-border-max`       | Ceiling on computed edge width.                                                                               | `100px`              |
+| `--ui-ink`              | Neutral line color when no intent is set.                                                                     | `--color-border`     |
+| `--ui-rule`             | Lines inside a table. Unset draws the head and foot boundaries only; `0%` draws none; `100%` rules every row. | unset                |
+| `--ui-shadow-x`         | Shadow horizontal offset.                                                                                     | `0px`                |
+| `--ui-shadow-y`         | Shadow vertical offset.                                                                                       | `0px`                |
+| `--ui-shadow-blur`      | Shadow blur radius.                                                                                           | `0px`                |
+| `--ui-shadow-spread`    | Shadow spread radius.                                                                                         | `0px`                |
+| `--ui-shadow-inset`     | The `inset` keyword for an inner ring.                                                                        | Empty                |
+| `--ui-hover-shadow-x`   | Shadow horizontal offset while hovered.                                                                       | `--ui-shadow-x`      |
+| `--ui-hover-shadow-y`   | Shadow vertical offset while hovered.                                                                         | `--ui-shadow-y`      |
+| `--ui-active-shadow-x`  | Shadow horizontal offset while pressed.                                                                       | `--ui-shadow-x`      |
+| `--ui-active-shadow-y`  | Shadow vertical offset while pressed.                                                                         | `--ui-shadow-y`      |
+| `--ui-active-transform` | Transform while pressed. `none` under `prefers-reduced-motion`.                                               | `scale(0.97)`        |
+| `--ui-shadow-ink`       | Percentage of shadow color taken from intent ink.                                                             | `0%`                 |
+| `--ui-shadow-edge`      | Declared, even empty, when the shadow is the element's edge rather than its depth. Read for presence.         | Unset                |
+| `--ui-elevation`        | Unitless multiplier over shadow geometry.                                                                     | `1`                  |
+| `--ui-surface-shadow`   | Complete multi-layer shadow accepted by surfaces only.                                                        | Unset                |
+| `--ui-surface-ground`   | Ground a surface sits on.                                                                                     | `--color-background` |
+| `--ui-bg-alpha`         | Multiplier over fill for translucent materials.                                                               | `1`                  |
+| `--ui-backdrop`         | Backdrop filter accepted by surfaces only.                                                                    | `none`               |
+| `--ui-hover-transform`  | Transform while an interactive element is hovered.                                                            | `none`               |
+| `--ui-clip`             | Structural component silhouette.                                                                              | `none`               |
+| `--ui-clip-tight`       | Compact component silhouette.                                                                                 | `--ui-clip`          |
+| `--ui-focus-inset`      | Inset focus layer width.                                                                                      | Unset                |
+
+```html
+<section style="--ui-radius: 0; --ui-border-width: 3px">
+  <button class="btn primary">Square and heavy</button>
+  <input class="ipt" placeholder="Matches" />
+</section>
+```
+
+> **Material token contract**: components read these; aesthetic classes and
+> consumer overrides set them.
+
+### Shape and ring composition
+
+Clipping removes borders, outlines, and outer shadows. An aesthetic that uses
+a clip can replace the border with an inset shadow by setting
+`--ui-shadow-inset` and the four shadow geometry parts. Set
+`--ui-border-max: 0px` when that ring replaces the component border.
+Focusable components restore the clipped focus outline through
+`--ui-focus-inset`.
+
+Declare `--ui-shadow-edge` when that ring _is_ the border. The ring then
+takes the element's edge color, which carries the edge axis as its alpha, so
+`.edged` draws it and `.edgeless` does not — the same answer a real border
+gives. Without it the ring paints on every component the aesthetic reaches
+and the edge classes have no effect. Use `--ui-shadow-ink` instead when the
+shadow is depth cast in the intent's own ink, such as a hard offset slab,
+which an `.edgeless` element still gets.
+
+The token is read for its presence, not its value: declare it empty to
+switch the ring on, and `initial` to switch it back off in an aesthetic
+nested inside one that declares it.
+
+```css
+.stepped {
+  --ui-clip: polygon(/* structural silhouette */);
+  --ui-clip-tight: none;
+  --ui-border-max: 0px;
+  --ui-shadow-inset: inset;
+  --ui-shadow-edge: ;
+  --ui-shadow-x: 0px;
+  --ui-shadow-y: 0px;
+  --ui-shadow-blur: 0px;
+  --ui-shadow-spread: 4px;
+  --ui-focus-inset: var(--focus-ring-width);
+}
+```
+
+Variables named `--shape-*` are internal composition outputs. Do not set or
+read them; only the `--ui-*` inputs above are public.
+
+## Aesthetic tokens
+
+The shipped [aesthetic classes](./aesthetics.md) set material tokens for you.
+Only aesthetics with a token listed below expose an aesthetic-specific
+token. Tune all other behavior through the shared material tokens above.
+Listed tokens are available only where that aesthetic's stylesheet is
+imported.
+
+| Token                    | Aesthetic       | Purpose                                                     | Default                           |
+| ------------------------ | --------------- | ----------------------------------------------------------- | --------------------------------- |
+| `--neo-offset`           | `.neobrutalism` | Hard shadow offset and distance the press travels.          | `4px`                             |
+| `--glass-radius`         | `.glass`        | Control corner radius.                                      | `0.75rem`                         |
+| `--glass-radius-surface` | `.glass`        | Surface corner radius.                                      | `1rem`                            |
+| `--pixel-unit`           | `.pixel`        | One pixel of the grid. The corner cut and the ring are one. | `4px`                             |
+| `--font-pixel`           | `.pixel`        | Consumer-supplied pixel font stack.                         | Falls back to the monospace stack |
+| `--tile-radius`          | `.chunky-tile`  | Corner radius, on controls and surfaces alike.              | `0.75rem`                         |
+| `--tile-lift`            | `.chunky-tile`  | Depth of the seated bar, and how far a press travels.       | `4px`                             |
+| `--font-rounded`         | `.chunky-tile`  | Consumer-supplied rounded font stack.                       | Falls back to the page stack      |
+
+All four aesthetics reach the same way: each knob is _read_ with its default
+as a `var()` fallback rather than declared, so it resolves once into a
+private on the aesthetic's own class (`--_pixel-unit`, `--_neo-offset`,
+`--_tile-radius`, `--_tile-lift`, and so on). Set a knob on the element
+carrying the aesthetic class, or on any ancestor including `:root`:
+
+```html
+<section class="pixel" style="--pixel-unit: 6px">
+  <button class="btn primary">Chunkier</button>
+</section>
+```
+
+```html
+<html class="pixel" style="--pixel-unit: 6px">
+  <body>
+    <button class="btn primary">Also chunkier, set from the root</button>
+  </body>
+</html>
+```
+
+Knobs and material tokens reach in opposite directions, and telling them
+apart matters. A knob resolves once at the aesthetic's own class and
+inherits down already-resolved, so it reaches the aesthetic **from above**:
+setting it on the element or any ancestor works, but setting it on a
+_descendant_ of the aesthetic class changes nothing — the value has already
+been read. `--ui-radius` and the other material tokens above are read fresh
+by each component as it draws, so they reach **at or below** the element
+carrying them, which is how you round one card differently from its
+neighbours without touching the knob at all.
+
+Shipped aesthetics set the shared material tokens above. `.neobrutalism` and
+`.pixel` set `--ui-ink` for their neutral outline; intent classes still
+override the intent slots on each component.
+
+## Component internals
+
+Component classes may define scoped implementation variables such as
+`--button-*`, `--surface-*`, `--control-*`, `--feedback-*`, and `--tooltip-*`.
+These variables are internal wiring for class composition and are not the
+public token contract.
+
+Consumers should customize broad behavior through color, foundation, motion,
+elevation, radius, layout, and focus tokens first. The only supported
+component-scoped input is `--progress-value` on the `.progress` element,
+because consumers must provide a value such as `64%`.
+
+`--layout-gap` replaces the removed `--layout-stack-gap` and
+`--layout-cluster-gap` tokens. No compatibility aliases are provided.
+
+Next: [Aesthetics](./aesthetics.md) covers each shipped aesthetic's complete
+look and its documented exceptions.

package/docs/usage/feedback.md

@@ -0,0 +1,117 @@
+---
+title: Feedback
+description: Alert, badge, loader, skeleton, and progress class reference.
+---
+
+# Feedback
+
+| Class            | Purpose                                                                      |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `.alert`         | Inline feedback surface.                                                     |
+| `.icon`          | Subclass of `.alert`. Adds a corresponding intent icon and padding.          |
+| `.badge`         | Compact status pill.                                                         |
+| `.loader-mask`   | Low-level activity indicator composition utility. Applies the spinner mask.  |
+| `.loader`        | Standalone inline loader artwork.                                            |
+| `.skeleton`      | Ambient loading placeholder.                                                 |
+| `.progress`      | Progress track. Uses `--progress-value` variable.                            |
+| `.active`        | Optional on `.progress` to add a track shimmer.                              |
+| `.indeterminate` | Optional on `.progress` to animate a moving fill without `--progress-value`. |
+
+Activity indicator modifier classes compose with `.loader`:
+
+| Class                  | Animation style                         |
+| ---------------------- | --------------------------------------- |
+| _(default)_            | Circular spinner (rotating arc).        |
+| `.dots-wave`           | Three dots bouncing up/down in a wave.  |
+| `.dots-fade`           | Three dots fading in and out.           |
+| `.dots-queue`          | Dot queuing from left to right.         |
+| `.dots-rotate`         | Side dots rotating around a center dot. |
+| `.dots-grow`           | Three dots growing and shrinking.       |
+| `.dots-grow-alternate` | Outer dots small, center dot pulses.    |
+| `.dot-bounce`          | Single dot bouncing with squash effect. |
+| `.bars-wave`           | Three vertical bars scaling in a wave.  |
+| `.pulse-ring`          | Two concentric rings pulsing outward.   |
+
+These variants retain their embedded SVG animations normally. Under
+`prefers-reduced-motion: reduce`, loader CSS substitutes a corresponding
+static mask. This fallback is part of focused loader, button, and components
+imports; it does not depend on the global reset. See
+[Accessibility](../accessibility.md).
+
+Loader size modifiers:
+
+| Class    | Size              |
+| -------- | ----------------- |
+| _(none)_ | Default (`2rem`). |
+| `.sm`    | Small (`1.5rem`). |
+| `.lg`    | Large (`2.5rem`). |
+
+Alerts, badges, progress bars, skeletons, and loaders accept `.primary`,
+`.secondary`, `.success`, `.warning`, `.destructive`, `.danger`, `.error`,
+and `.info`. Without an intent, they use the text palette, except `.loader`,
+which keeps `currentColor` so it matches whatever content surrounds it.
+
+Skeletons, loaders, progress bars, and dividers are indicators. They read
+intent but ignore fill and edge [presentation](./composing.md#presentation).
+
+```html
+<span class="loader success" aria-hidden="true"></span>
+<span class="skeleton info"></span>
+```
+
+`.icon` is a subclass of `.alert`. When applied as `.alert.icon`, it
+increases the left padding and adds an embedded SVG. Success, warning, and
+destructive intents use corresponding symbols; other intents use the
+information symbol.
+
+Alerts and badges read the shared [presentation](./composing.md#presentation)
+classes. Without one they use a tinted surface, intent-colored text, and a
+mixed intent border.
+
+## Example
+
+```html
+<div class="alert success" role="status">Saved successfully.</div>
+<div class="alert primary solid" role="status">Deployment started.</div>
+<div class="alert warning soft icon" role="status">Review required.</div>
+<div class="alert destructive ghost edged" role="alert">Deployment failed.</div>
+<span class="badge warning">Queued</span>
+<span class="badge success solid">Live</span>
+<span class="badge info soft">Draft</span>
+<span class="loader" aria-hidden="true"></span>
+<span class="loader dots-wave" aria-hidden="true"></span>
+<span class="loader dots-fade" aria-hidden="true"></span>
+<span class="loader bars-wave" aria-hidden="true"></span>
+<span class="loader pulse-ring sm" aria-hidden="true"></span>
+<span class="loader dots-grow lg" aria-hidden="true"></span>
+<div
+  class="progress"
+  role="progressbar"
+  aria-label="Upload progress"
+  aria-valuemin="0"
+  aria-valuemax="100"
+  aria-valuenow="64"
+  style="--progress-value: 64%"
+></div>
+<div
+  class="progress secondary active"
+  role="progressbar"
+  aria-label="Upload progress"
+  aria-valuemin="0"
+  aria-valuemax="100"
+  aria-valuenow="64"
+  style="--progress-value: 64%"
+></div>
+<div
+  class="progress info indeterminate"
+  role="progressbar"
+  aria-label="Loading"
+  aria-valuemin="0"
+  aria-valuemax="100"
+></div>
+```
+
+Add `role="status"` or `role="alert"` to alerts based on announcement
+urgency, mark decorative loading visuals with `aria-hidden="true"`, and use
+semantic progress elements or ARIA values when numeric progress must be
+announced; see [Accessibility](../accessibility.md).