@codenhub/styles 0.0.3 → 0.1.0

package/docs/usage/aesthetics.md

@@ -0,0 +1,197 @@
+---
+title: Aesthetics
+description: The four shipped aesthetics in depth, including their documented exceptions.
+---
+
+# Aesthetics
+
+An aesthetic decides what a component is _made of_: its radius, border
+thickness, shadow, and shape. Aesthetics ship from opt-in entrypoints, so
+importing the stylesheet is what makes the classes available:
+
+```css
+@import "@codenhub/styles";
+@import "@codenhub/styles/aesthetics";
+```
+
+Import them after the base stylesheet. `.neobrutalism` and `.pixel` replace
+the neutral border color, and they do so at zero specificity, so source order
+is what lets them win.
+
+Like presentation, an aesthetic class cascades to any subtree:
+
+```html
+<section class="neobrutalism">
+  <button class="btn primary">Thick ink and a hard shadow</button>
+  <div class="card destructive">The intent still wins over the aesthetic ink</div>
+</section>
+```
+
+| Class           | Look                                                                                                                            |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `.neobrutalism` | No radius, a thick ink outline, a hard unblurred offset shadow, and a press that moves the element into it.                     |
+| `.glass`        | Translucent surfaces over a blurred backdrop with a hairline highlight edge.                                                    |
+| `.pixel`        | Corners cut by one grid unit, a chunky outline drawn as an inset ring, and the consumer-supplied `--font-pixel` over monospace. |
+| `.chunky-tile`  | Rounded slabs seated on a darker shade of themselves, with a press that moves the element down into its own bar.                |
+
+Aesthetics compose with every supported fill and edge pair. `.ghost.edgeless`
+intentionally removes the visible material traits from components whose
+aesthetic is expressed only through their fill, edge, or elevation.
+
+An explicit presentation on the element still wins over the aesthetic's
+defaults. The aesthetic supplies edge thickness; presentation only decides
+whether that edge is drawn.
+
+An aesthetic directly on a component likewise wins over an inherited
+aesthetic. This includes tooltip pseudo-elements: `.tooltip.glass` gets the
+complete glass bubble under a pixel ancestor, and `.tooltip.pixel` gets the
+complete stepped bubble under a glass ancestor.
+
+Each aesthetic that scales from one number publishes it as a knob — see
+[Customizing → Aesthetic tokens](./customizing.md#aesthetic-tokens) for how
+knobs resolve and where they can be set. This page covers what each
+aesthetic looks like and where it makes documented exceptions.
+
+## Neobrutalism
+
+The shadow is cast in the component's own intent, so a success button throws
+a green shadow and a destructive card a red one. With no intent, both the
+outline and the shadow use the ink, which follows the theme rather than the
+palette.
+
+`--neo-offset` is the knob: the shadow offset and the distance the press
+travels are the same number, so scaling the look scales both at once.
+
+```html
+<section class="neobrutalism" style="--neo-offset: 6px">
+  <button class="btn primary">A longer throw</button>
+</section>
+```
+
+**Exceptions:**
+
+- Content chips are left alone. A `.kbd`, `.code`, or `.pre` is content
+  rather than structure, and an ink edge on one reads as a defect: a key cap
+  keeps the quiet border color and a code chip keeps no border at all.
+- Only `.btn` and `.card.interactive` respond to hover and press. A card
+  becomes a control when it opts in with `.interactive`; a plain card, an
+  alert, or a panel is a container and stays put.
+- An alert rests on the slab under this aesthetic and nowhere else. Here the
+  slab is a second ink line rather than depth, and an alert is the only
+  container the package rests flat, so without it a neobrutalist alert is
+  the one box on the page that reads as unfinished. It is a resting default,
+  so `.flat` still takes it off and `.floating` still doubles it.
+
+## Glass
+
+`.glass` needs something behind it to blur. On a flat page background it
+renders as a plain translucent panel.
+
+`--glass-radius` and `--glass-radius-surface` are the corners, at `0.75rem`
+and `1rem`. Glass is rounder than the base geometry because a translucent
+panel with a tight corner reads as a cut-out rather than as a pane.
+
+```html
+<section class="glass" style="--glass-radius-surface: 1.5rem">
+  <div class="card">Softer</div>
+</section>
+```
+
+**Exceptions:**
+
+- The blur applies to `.card`, `.panel`, `.alert`, and the tooltip bubble
+  only. Controls stay solid and sit on the glass: a blur under every control
+  of a dense cluster costs a composited layer apiece and reads as noise.
+  Controls still take the aesthetic's radius, border, and shadow.
+- Under `prefers-reduced-transparency: reduce`, glass surfaces drop the blur
+  and become opaque.
+
+## Pixel
+
+`--pixel-unit` is one pixel of the imaginary low-resolution grid, `4px` by
+default. One square unit is cut from each corner and the outline is one unit
+thick, so the cut and what covers it are the same size.
+
+```html
+<section class="pixel" style="--pixel-unit: 6px">
+  <button class="btn primary">Chunkier</button>
+</section>
+```
+
+**Exceptions:**
+
+- Corners are one unit or nothing. Chips square instead of stepping —
+  badges, key caps, code, checkboxes, and switches all read
+  `--ui-clip-tight`, which this aesthetic sets to none, because one unit off
+  each corner of a 24px badge is a bite rather than a corner. Tables,
+  progress bars, and skeletons square too, each for its own reason: a
+  table's `overflow: hidden` fights the clip and the corners square off
+  where the two meet, and progress and skeleton never read a clip at all —
+  a squaring aesthetic reaches them through `border-radius` alone. `.pre` is
+  the one exception that steps: it carries no clip override, so it inherits
+  the same polygon a button or a card gets, and with no border by default
+  the cut shows with no ring around it.
+- The outline is an inset ring, because a clip removes a real border — and
+  the focus ring, for the same reason, is a second inset layer rather than
+  an outline. Both are the element's own edge rather than a shadow, so the
+  border answers `.edged` and `.edgeless` the way a border does: a
+  `.edgeless` badge and a `.solid` button draw none, a `.edged` card draws
+  one, and a field keeps one whatever a container asks for.
+- The tooltip trigger and `.radio` are hardcoded past the clip rather than
+  reached by it. `.tooltip-icon` forces `clip-path: none`, since a stepped
+  badge would clip its own bubble away with it. `.radio` forces the same,
+  because the circle is the only thing telling it from a checkbox at a
+  glance, and a stepped polygon would square it.
+- `--font-pixel` is yours to supply. The package ships no font binary, so the
+  aesthetic has no network side effect and falls back to the monospace
+  stack.
+
+## Chunky tile
+
+Rounded slabs sitting on a darker shade of themselves, pressed flat on
+click. The look mobile learning and game apps use; it is named for what it
+is made of rather than for any one product.
+
+`--tile-lift` is how deep the bar is and how far a press travels, `4px` by
+default. One number drives both, so the top edge drops by exactly the bar's
+depth and the bottom edge does not move. `--tile-radius` is the corner,
+`0.75rem`, and it is one value rather than a control/surface pair on
+purpose — the shared corner is what makes a button and the card it sits in
+read as the same object.
+
+```html
+<section class="chunky-tile" style="--tile-lift: 6px; --tile-radius: 0.5rem">
+  <button class="btn success">Continue</button>
+</section>
+```
+
+The bar is a darker shade of the element's own colour rather than a shadow
+under it, so it follows every intent: a success button sits on a dark green
+edge, a destructive one on a dark red edge, and a plain card on a grey edge
+that matches the line it already draws. Measured on the light palette,
+`.btn.success` is `#007a55` on `#004c34`. On a dark page a near-black
+surface cannot go darker, so its bar lands lighter and reads as a rim.
+
+**Exceptions:**
+
+- Only what the registry rests above zero sits on a bar — buttons and cards.
+  A badge, chip, field, or tooltip is flat until it asks for depth with
+  `.raised`, and `.flat` takes the bar off anything:
+
+  ```html
+  <div class="card soft edgeless info flat">Promo panel, deliberately flat</div>
+  ```
+
+- `--font-rounded` is yours to supply. A heavy rounded grotesque is most of
+  this look and the package ships no font binary, so with nothing supplied
+  the page's own stack is used.
+- Action labels are drawn heavier and slightly tracked. Casing is left
+  alone: how a label is worded is the application's decision, so if you want
+  uppercase buttons, write that rule in your own stylesheet.
+- `.card.interactive` presses like a `.btn`, so a chunky answer tile drops
+  onto its bar on click. A plain `.card` stays put.
+- The shipped `.primary` is a near-black monochrome, which leaves a primary
+  button's bar almost invisible against its own plate; give `.primary` a hue
+  if it is the call to action.
+- Depth in this aesthetic is the bar, never a blurred drop shadow. Anything
+  the registry rests flat sits flush on the page.

package/docs/usage/buttons.md

@@ -0,0 +1,74 @@
+---
+title: Buttons
+description: Button classes, intents, sizes, and states.
+---
+
+# Buttons
+
+Use `.btn` with one optional intent class, one optional fill class, one
+optional edge class, optional size class, and optional state. See
+[Composing](./composing.md) for how the intent, presentation, and aesthetic
+axes combine on any component.
+
+Intent classes map color tokens into button tone slots.
+[Presentation](./composing.md#presentation) decides how much of that intent
+reaches background, text, border, and hover.
+
+Intent classes:
+
+| Class                               | Meaning                        |
+| ----------------------------------- | ------------------------------ |
+| `.neutral` _(default)_              | No specific intent.            |
+| `.primary`                          | Primary action.                |
+| `.secondary`                        | Secondary/accent action.       |
+| `.success`                          | Successful or positive action. |
+| `.warning`                          | Warning/caution action.        |
+| `.destructive`, `.danger`, `.error` | Destructive or error action.   |
+| `.info`                             | Informational action.          |
+
+Every component that supports intent accepts the same list and reads the
+same [intent tokens](./theming.md#intent-tokens), so a custom intent class
+works everywhere without touching a component.
+
+`.neutral` is the only intent that does not fill all the way. Its color is
+the page's own text color, so a full fill of it would be a black or white
+slab — the loudest element on the page, for the intent that means nothing in
+particular. It stops at `--intent-fill-max`, which is why a `.solid` neutral
+is a quiet plate a step past `.soft` rather than a block of ink. Set the slot
+on your own intent classes; see [Theming → Intent tokens](./theming.md#intent-tokens).
+
+Size and shape classes:
+
+| Class                                                                  | Purpose                                                     |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `.pill`                                                                | Fully rounded button corners (`border-radius: 9999px`).     |
+| `.sm`                                                                  | Smaller button.                                             |
+| `.lg`                                                                  | Larger button.                                              |
+| `.p-sm`, `.compact`                                                    | Compact padding modifier (`px-2.5 py-1`).                   |
+| `.p-lg`, `.spacious`                                                   | Spacious padding modifier (`px-6 py-3`).                    |
+| `.icon`                                                                | Square icon button. Use an accessible name in HTML.         |
+| `.loading`                                                             | Loading state. Hides text and shows CSS activity indicator. |
+| `.disabled`, `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` | Disabled styling.                                           |
+
+Examples:
+
+```html
+<button class="btn primary">Primary</button>
+<button class="btn success ghost edged">Success outline</button>
+<button class="btn warning soft">Warning soft</button>
+<button class="btn destructive ghost edgeless">Danger ghost</button>
+<button class="btn icon primary" aria-label="Create">+</button>
+<button class="btn primary loading" disabled>Saving</button>
+```
+
+`.loading` is a state, not a color or presentation class. Prefer combining
+it with disabled behavior so users cannot trigger duplicate work. Loading
+buttons keep only opacity and transform transitions active so spinner and
+surface colors stay synchronized when theme tokens change.
+
+On the base look a press scales the button down a little
+(`--ui-active-transform`, `scale(0.97)`). [Aesthetics](./aesthetics.md) swap
+in their own press gesture, and `prefers-reduced-motion` turns it off.
+
+Use `<button>` for actions or an accessible link for navigation; see
+[Accessibility](../accessibility.md).

package/docs/usage/composing.md

@@ -0,0 +1,218 @@
+---
+title: Composing
+description: Combining intent, presentation, and aesthetic on a component, and the axis-support matrix.
+---
+
+# Composing the three axes
+
+See [Concepts](../concepts.md#the-three-axes) for what each axis means. This
+page covers how they combine in markup, what the presentation classes mean in
+depth, which components support which axis, and elevation.
+
+## Combining axes
+
+```html
+<div class="soft">
+  <button class="btn primary">Soft primary button</button>
+  <span class="badge success">Soft success badge</span>
+  <button class="btn primary ghost edged">Outlined; the element wins</button>
+</div>
+```
+
+A declaration on the element always beats one inherited from a container, so
+a container sets the default look for its subtree and any element opts out.
+
+Intent classes do not cascade. `.primary` and its siblings stay on the
+element that shows the intent, because a container silently recoloring every
+descendant is a trap rather than a feature — see
+[Theming → Intent tokens](./theming.md#intent-tokens). Use `.neutral` to opt
+an element back out of an inherited intent context. Presentation and
+[material tokens](./customizing.md#material-tokens) do cascade, so a
+container can set the look of its whole subtree while any element overrides
+it.
+
+## Presentation
+
+Presentation has two independent axes. `.solid`, `.soft`, and `.ghost`
+decide how much intent fills a component; `.edged` and `.edgeless` decide
+whether it draws a boundary. They set
+[presentation tokens](./customizing.md#presentation-tokens) and nothing
+else, so they work on the component itself or on any ancestor.
+
+| Class       | Look                                                       |
+| ----------- | ---------------------------------------------------------- |
+| `.solid`    | Intent-colored fill with contrast text.                    |
+| `.soft`     | Lightly tinted fill with intent-colored text.              |
+| `.ghost`    | No fill at rest, with intent-colored text.                 |
+| `.edged`    | Intent-colored boundary at the aesthetic's material width. |
+| `.edgeless` | No boundary.                                               |
+
+Values each class ships:
+
+| Class       | `--ui-fill` | `--ui-fg-on-fill` | `--ui-border` |
+| ----------- | ----------- | ----------------- | ------------- |
+| `.solid`    | `100%`      | `100%`            |               |
+| `.soft`     | `12%`       | `0%`              |               |
+| `.ghost`    | `0%`        | `0%`              |               |
+| `.edged`    |             |                   | `100%`        |
+| `.edgeless` |             |                   | `0%`          |
+
+The combinations mean exactly what they spell:
+
+```html
+<button class="btn primary">Solid, the button default</button>
+<button class="btn soft edged">Tinted with a border</button>
+<button class="btn primary ghost edged">Outline</button>
+<button class="btn ghost">Ghost; picks up a tint on hover</button>
+<input class="ipt soft edgeless" />
+<!-- A field sunk into the page -->
+```
+
+A fill class never decides an edge and an edge class never decides a fill.
+Use `.solid.edgeless` for a filled box with no line — and prefer it on a
+neutral one, because a capped fill leaves the box translucent and the edge
+blend then paints a second coat of the same tint rather than disappearing
+into it (measured 1.53:1 against its own plate in light, 1.82:1 in dark).
+
+The edge is the silhouette and nothing else. Rules _inside_ a component that
+has an inside are a separate switch — see
+[Content and layout → Table rules](./content-and-layout.md#table-rules) —
+because tying them to this axis made them arrive by implication rather than
+by request.
+
+With no presentation class in scope, each component keeps its own default:
+buttons are filled, alerts and badges are tinted, surfaces and controls are
+neutral and bordered.
+
+| Component                                       | Reads                                       |
+| ----------------------------------------------- | ------------------------------------------- |
+| `.btn`, `.alert`, `.badge`, `.card`, `.panel`   | Fill, text, border, and border width.       |
+| `.kbd`                                          | Fill, text, border, and border width.       |
+| `.data-table`                                   | Header fill and text, border, border width. |
+| `.ipt`, `.textarea`, `.select`, `.text-control` | Border, border width, and a capped fill.    |
+| `.input-group`                                  | Border, border width, and a capped fill.    |
+| `.checkbox`, `.radio`                           | A capped fill, checked and unchecked.       |
+| `.switch`                                       | Border, border width, and a capped fill.    |
+| `.quote`                                        | Fill, text, border, and width.              |
+| `.code`, `.pre`, `.tooltip`                     | Fill, text, border, and material.           |
+| `.loader`, `.skeleton`, `.progress`, `.divider` | Intent only, not presentation.              |
+
+Text controls and toggles cap a **cascaded** fill at `6%`, keeping typed
+text legible when a `.solid` container reaches a field nobody classed. A
+fill class written on the control itself names its own cap instead, because
+that is a consumer describing what they want: `.soft` takes `12%` and
+`.solid` takes `20%`. A switch caps at `40%`, where its three fills separate
+far enough to read on a track.
+
+| On a text control | fill |
+| ----------------- | ---- |
+| `.ghost`          | 0%   |
+| cascaded `.solid` | 6%   |
+| `.soft`           | 12%  |
+| `.solid`          | 20%  |
+
+The same split governs the edge: a cascaded `.edgeless` is floored and the
+element's own is honoured — except on `.checkbox` and `.radio`, which never
+drop their line at all. See [Forms](./forms.md) for the full toggle and text
+control reference.
+
+A tooltip bubble is filled, over a tinted ground. An intent fills it with
+that intent's own color: `.tooltip.primary` is the primary color, black on a
+light page and white on a dark one, and `.tooltip.destructive` is a red
+bubble.
+
+With no intent the bubble is `--color-tooltip`, the one plate in the package
+chosen per theme rather than derived from an intent. Composed like
+everything else it was `20%` of the page's ink over the surface tone, which
+steps _lighter_ than the surface on a dark page and _darker_ on a light
+one — so the dark bubble read as lifted and the light one as a mid-grey
+slab two steps darker than every card on the screen. The token states each
+direction instead: near-white over a light page, a mid grey over a dark
+one. `--color-tooltip-contrast` is its ink.
+
+Near-white is only 1.04:1 against a light page, so the bubble draws a
+hairline as well, and floors it: a container's `.solid` or `.edgeless`
+cannot take the boundary away from a bubble nobody classed, while
+`.tooltip.edgeless` still can. The ground keeps the bubble opaque at every
+fill, so a cascaded presentation leaves it readable over whatever it floats
+above. It reads the material tokens too, so an [aesthetic](./aesthetics.md)
+in scope shapes the bubble like any other component. See
+[Tooltips](./tooltips.md) for the full tooltip reference.
+
+## Component axis reference
+
+This table is the authoritative axis map for demonstrated components. "Shape"
+means the component reads applicable radius, border-width, shadow, hover, or
+clip/edge material tokens; an aesthetic may intentionally affect only the
+materials that component draws.
+
+Presentation is two independent axes, so they get a column each. A `Yes` means
+the class changes what the component computes, which
+`tests/browser/axes.spec.ts` asserts against `registry.json` in both
+directions: an axis marked `Yes` must move, and an axis marked `No` must not.
+
+| Components                                                | Intent | Fill | Edge | Aesthetic material |
+| --------------------------------------------------------- | ------ | ---- | ---- | ------------------ |
+| `.btn`, `.alert`, `.badge`, `.card`, `.panel`             | Yes    | Yes  | Yes  | Shape              |
+| `.loader`                                                 | Yes    | No   | No   | No                 |
+| `.kbd`, `.data-table`                                     | Yes    | Yes  | Yes  | Radius and edge    |
+| `.quote`                                                  | Yes    | Yes  | Yes  | Edge width         |
+| `.divider`, `.skeleton`                                   | Yes    | No   | No   | No                 |
+| `.ipt`, `.textarea`, `.select`, `.text-control`           | Yes    | Yes  | Yes  | Shape              |
+| `.input-group`                                            | Yes    | Yes  | Yes  | Shape              |
+| `.surface`                                                | Yes    | Yes  | Yes  | Shape              |
+| `.checkbox`, `.radio`                                     | Yes    | Yes  | No   | Radius and edge    |
+| `.switch`                                                 | Yes    | Yes  | Yes  | Radius and edge    |
+| `.progress`                                               | Yes    | No   | No   | No                 |
+| `.code`, `.pre`                                           | Yes    | Yes  | Yes  | Radius and clip    |
+| `.tooltip`                                                | Yes    | Yes  | Yes  | Shape and overlay  |
+| `.table-wrap`, `.quote-inline`, layout and text utilities | No     | No   | No   | No                 |
+
+`.checkbox` and `.radio` are the only components that read one axis and not
+the other. Their line is the only thing marking an unchecked box, so it is
+drawn whatever the edge class says, from a container or from the element
+itself. `.edgeless` on either is unsupported rather than merely discouraged.
+
+Every other text control floors a _cascaded_ `.edgeless` and honours its own:
+a `.edgeless` toolbar will not erase the line of a field nobody classed, while
+`.ipt.edgeless` is a consumer describing what they want and gets it.
+
+Intent aliases such as `.danger` and `.error` occupy the same intent axis as
+`.destructive`; they do not add component behavior. State and modifier
+classes such as `.interactive`, `.loading`, `.invalid`, `.compact`, and
+`.vertical` sit above this map and are documented with their component.
+
+## Elevation
+
+Depth is a modifier, not an axis. Nothing is raised until an
+[aesthetic](./aesthetics.md) draws depth or one of these classes asks for it.
+
+| Class             | Alias       | Depth                                                                    |
+| ----------------- | ----------- | ------------------------------------------------------------------------ |
+| `.elevation-none` | `.flat`     | Removes part-based elevation; glass surfaces keep their complete shadow. |
+| `.elevation-sm`   | `.raised`   | One unit of the depth in scope. Cards, tiles, popovers that sit close.   |
+| `.elevation-md`   | `.floating` | Twice it, for menus and popovers.                                        |
+
+Both names in a row are equivalent, interchangeable classes — `.elevation-sm`
+and `.raised` are aliases, not a canonical form and a deprecated one, the way
+`.destructive` and `.danger` are on the intent axis. The `none`/`sm`/`md`
+naming matches the raw `--elevation-*` tokens in
+[Theming](./theming.md#foundation-tokens) for the same weight of depth, even
+though the two are read from different places.
+
+Each is one unitless multiplier over whatever shadow geometry is in scope, so
+the same class reads as a soft blur on a plain page and as a hard offset slab
+under `.neobrutalism` — the aesthetic decides what depth looks like, the
+class decides how much of it this element takes.
+
+```html
+<article class="card elevation-sm">Lifted</article>
+<div class="elevation-md panel">A menu surface</div>
+<article class="card elevation-none">Flat, whatever the page or container says</article>
+```
+
+The multiplier is a plain number, so it inherits: a container lifts or
+flattens a whole region and any element inside it still opts out on itself.
+Spread is deliberately left out of the multiplication, because an aesthetic
+that draws its edge as an inset ring spends spread on it and scaling that
+would erase the edge.