@codenhub/styles 0.0.4 → 0.1.0

package/docs/index.md

@@ -0,0 +1,62 @@
+---
+title: Introduction
+description: What @codenhub/styles is, what it covers, and where to go next.
+---
+
+# @codenhub/styles
+
+`@codenhub/styles` is a CSS-only design system: tokens, a reset, typography and
+layout utilities, and composable classes for buttons, forms, feedback,
+surfaces, and tooltips. Every component separates three independent choices —
+which color, how much of it, and what it's made of — so changing one never
+requires a component-specific variant. Four optional aesthetics
+(`.neobrutalism`, `.glass`, `.pixel`, `.chunky-tile`) restyle that same
+component set without touching markup.
+
+The package ships as ready-to-import compiled CSS, or as Tailwind CSS v4
+source entrypoints for a project that already runs Tailwind. Both cover the
+same classes; the difference is which build processes them.
+
+## What it does
+
+- Publishes color, foundation, intent, presentation, and material design
+  tokens as CSS custom properties, themed with `light-dark()`.
+- Provides a reset, focus-visible handling, and responsive layout/content
+  utilities.
+- Provides composable classes for buttons, form controls and toggles, alerts,
+  badges, loaders, progress, cards/panels, tables, quotes, code, and
+  tooltips.
+- Provides four opt-in aesthetics that restyle the same components by setting
+  material tokens, not by adding component variants.
+- Provides classless mappings so plain HTML elements pick up base styling
+  without added classes, from a dedicated entrypoint.
+- Publishes Tailwind CSS v4 source entrypoints alongside the compiled output.
+
+## What it does not do
+
+- No JavaScript. There is no runtime, no framework bindings, and no build-time
+  code generation beyond the CSS itself.
+- No semantic HTML, ARIA, keyboard behavior, focus management, validation, or
+  announcement timing. See [Accessibility](./accessibility.md) for the exact
+  line between what the CSS provides and what an application must still add.
+- No theme-toggling logic. Theme selection is a class or attribute a consumer
+  applies; wiring a toggle to system preference, storage, or a user setting is
+  outside this package. The `@codenhub/theme` package covers that need for
+  consumers who want it.
+- No shipped font binaries. `.pixel` and `.chunky-tile` accept a
+  consumer-supplied font and fall back to a system stack when none is given.
+- No compatibility layer for removed tokens or classes. Breaking changes are
+  documented, not silently aliased.
+
+## Next steps
+
+- [Setup](./setup.md): Install the package, choose an entrypoint, and render a
+  first component.
+- [Concepts](./concepts.md): The three-axis model, the token system, and how
+  theme selection works — read this before the usage guides.
+- [Usage](./usage/index.md): Guides for composing axes, theming, customizing,
+  aesthetics, and each component family.
+- [Integrating](./integrating/index.md): Wiring the stylesheet into Next.js,
+  Vue, Svelte, Astro, or a Tailwind CSS v4 build.
+- [Accessibility](./accessibility.md): CSS accessibility hooks and what
+  remains an application responsibility.

package/docs/integrating/astro.md

@@ -0,0 +1,29 @@
+---
+title: Astro
+description: Loading the stylesheet in an Astro app.
+---
+
+# Astro
+
+Import the package from a shared layout's frontmatter so every page that
+uses that layout loads it once:
+
+```astro
+---
+// src/layouts/Layout.astro
+import "@codenhub/styles";
+---
+
+<html lang="en">
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
+Apply `.dark` or `.light` on `<html>` to force a theme instead of following
+the system preference; see [Setup → Configuration](../setup.md#configuration).
+
+A project running Tailwind CSS v4 imports `@codenhub/styles/tw` through
+Astro's Tailwind integration instead; see [Tailwind CSS v4](./tailwind.md)
+for the `@source` directive Astro needs to scan `src/`.

package/docs/integrating/index.md

@@ -0,0 +1,32 @@
+---
+title: Integrating
+description: Wiring the stylesheet into a framework or build target.
+---
+
+# Integrating
+
+This package has no JavaScript and no framework bindings; see
+[Introduction](../index.md#what-it-does-not-do). Integrating it into a
+framework is entirely about where that framework loads a global stylesheet,
+and whether the project runs Tailwind CSS v4.
+
+Every stack does the same two things:
+
+1. Import one [entrypoint](../setup.md#import-paths) — the compiled
+   `@codenhub/styles` for any build, or `@codenhub/styles/tw` when the
+   project already runs Tailwind CSS v4 — from wherever that framework loads
+   global CSS.
+2. Import `@codenhub/styles/aesthetics` (or `/tw/aesthetics`) after it, only
+   if the project uses an [aesthetic](../usage/aesthetics.md).
+
+| Stack                                    | Guide                            |
+| ---------------------------------------- | -------------------------------- |
+| A Tailwind CSS v4 project on any bundler | [Tailwind CSS v4](./tailwind.md) |
+| Next.js / React                          | [Next.js](./nextjs.md)           |
+| Vue                                      | [Vue](./vue.md)                  |
+| Svelte / SvelteKit                       | [Svelte](./svelte.md)            |
+| Astro                                    | [Astro](./astro.md)              |
+
+A project with no framework — a plain Vite, webpack, or Parcel build — needs
+nothing beyond [Setup](../setup.md#quick-start): import the compiled
+stylesheet from the project's existing global CSS entry.

package/docs/integrating/nextjs.md

@@ -0,0 +1,44 @@
+---
+title: Next.js
+description: Loading the stylesheet in a Next.js / React app.
+---
+
+# Next.js
+
+Next.js only allows global CSS to be imported from one place. Import the
+package from the root layout in the App Router, or from the custom App in
+the Pages Router — not from a page or component further down the tree.
+
+```tsx
+// app/layout.tsx
+import "@codenhub/styles";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+```tsx
+// pages/_app.tsx
+import "@codenhub/styles";
+import type { AppProps } from "next/app";
+
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />;
+}
+```
+
+Apply `.dark` or `.light` on `<html>` to force a theme instead of following
+the system preference; see [Setup → Configuration](../setup.md#configuration).
+
+```tsx
+<html lang="en" className="dark">
+```
+
+A project running Tailwind CSS v4 imports `@codenhub/styles/tw` from the
+same file instead; see [Tailwind CSS v4](./tailwind.md) for the `@source`
+directive Next.js needs to scan its own `app`/`src` directories.

package/docs/integrating/svelte.md

@@ -0,0 +1,37 @@
+---
+title: Svelte
+description: Loading the stylesheet in a Svelte / SvelteKit app.
+---
+
+# Svelte
+
+In SvelteKit, import the package from the root layout so it loads once for
+every route:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import "@codenhub/styles";
+  let { children } = $props();
+</script>
+
+{@render children()}
+```
+
+In a plain Svelte + Vite app, import it from the entry file instead:
+
+```ts
+// main.ts
+import "@codenhub/styles";
+import { mount } from "svelte";
+import App from "./App.svelte";
+
+mount(App, { target: document.getElementById("app")! });
+```
+
+Apply `.dark` or `.light` on `<html>` (edit `src/app.html` in SvelteKit) to
+force a theme instead of following the system preference; see
+[Setup → Configuration](../setup.md#configuration).
+
+A project running Tailwind CSS v4 imports `@codenhub/styles/tw` from the
+app's CSS entry instead; see [Tailwind CSS v4](./tailwind.md).

package/docs/integrating/tailwind.md

@@ -0,0 +1,40 @@
+---
+title: Tailwind CSS v4
+description: Using the /tw source entrypoints in a Tailwind CSS v4 project.
+---
+
+# Tailwind CSS v4
+
+A project that already runs Tailwind CSS v4 can process this package's
+source instead of its compiled output. `/tw` entrypoints publish copied,
+uncompiled source from `dist/tw`; your own Tailwind build compiles it
+alongside your app, so its `@theme`, `@utility`, and `@apply` directives
+resolve together with yours.
+
+```css
+@import "tailwindcss";
+@import "@codenhub/styles/tw";
+
+@source "./src";
+```
+
+`@source` tells Tailwind's build where to scan for the utility and component
+class names actually used in your markup, so it can generate only what is
+referenced. Point it at your app's source, not at this package — `/tw`
+already ships every class definition it publishes.
+
+Add aesthetics from the source entrypoint the same way as the compiled one,
+after the base import:
+
+```css
+@import "tailwindcss";
+@import "@codenhub/styles/tw";
+@import "@codenhub/styles/tw/aesthetics";
+
+@source "./src";
+```
+
+Import a focused `/tw/*` entrypoint instead of the combined one — such as
+`/tw/button` or `/tw/form` — when a build only needs one component family;
+see the full [import path table](../setup.md#import-paths) for what each one
+composes. Tailwind CSS 4 or newer is required for every `/tw` entrypoint.

package/docs/integrating/vue.md

@@ -0,0 +1,25 @@
+---
+title: Vue
+description: Loading the stylesheet in a Vue / Vite app.
+---
+
+# Vue
+
+Import the package once, from the app's entry file, before the app mounts:
+
+```ts
+// main.ts
+import "@codenhub/styles";
+import { createApp } from "vue";
+import App from "./App.vue";
+
+createApp(App).mount("#app");
+```
+
+Apply `.dark` or `.light` on the root element to force a theme instead of
+following the system preference; see
+[Setup → Configuration](../setup.md#configuration).
+
+A project running Tailwind CSS v4 imports `@codenhub/styles/tw` from a CSS
+entry file instead of `main.ts`, using the `@tailwindcss/vite` plugin; see
+[Tailwind CSS v4](./tailwind.md).

package/docs/setup.md

@@ -0,0 +1,116 @@
+---
+title: Setup
+description: Install the package, pick an entrypoint, and render a first component.
+---
+
+# Setup
+
+## Installation
+
+```sh
+pnpm add @codenhub/styles
+```
+
+## Quick start
+
+Import the compiled stylesheet for the complete token, reset, utility, and
+component-class surface, then compose helper classes in markup:
+
+```css
+@import "@codenhub/styles";
+```
+
+```html
+<main class="stack">
+  <p class="text-label">Status</p>
+  <h1 class="text-title">Ready to publish</h1>
+  <button class="btn primary">Continue</button>
+</main>
+```
+
+The full stylesheet applies global reset and focus-visible rules, but does not
+apply the optional classless native-element mappings, and does not include
+aesthetics. Import focused entrypoints when global rules are not appropriate;
+see [Import paths](#import-paths) below.
+
+Aesthetics are opt-in. Import the combined aesthetics stylesheet, or one
+aesthetic on its own, after the base stylesheet so its rules win:
+
+```css
+@import "@codenhub/styles";
+@import "@codenhub/styles/aesthetics";
+```
+
+```html
+<section class="neobrutalism">
+  <button class="btn primary">Thick ink and a hard shadow</button>
+</section>
+```
+
+A project already running Tailwind CSS v4 imports the source entrypoint
+instead; see [Integrating → Tailwind CSS v4](./integrating/tailwind.md).
+
+## Configuration
+
+The root follows the operating-system color-scheme preference. Apply `.light`
+or `.dark` to the root or any ancestor to force token values for that subtree.
+`.theme-light`, `.theme-dark`, and `data-theme="light|dark"` are aliases.
+
+```html
+<html class="dark">
+  <body>
+    <button class="btn primary">Dark themed button</button>
+  </body>
+</html>
+```
+
+See [Concepts → Theme selection](./concepts.md#theme-selection) for how
+selectors resolve and [Usage → Theming](./usage/theming.md) for the full color
+token reference.
+
+## Import paths
+
+Compiled entrypoints are ready-to-import CSS and require only tooling that can
+resolve package CSS imports. `/tw` entrypoints publish copied, uncompiled
+source from `dist/tw`; a Tailwind v4 build must still process their `@theme`,
+`@utility`, `@apply`, and related directives. Focused source component
+entrypoints include theme tokens so their classes can work independently.
+
+| Import path                      | Composition and effects                                                                                                                                                                                           |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@codenhub/styles`               | Compiled complete surface: Tailwind base/theme output, tokens, typography, utilities, components, and reset. Applies global reset, root theme, and focus rules.                                                   |
+| `@codenhub/styles/theme`         | Compiled Tailwind theme variables, Codenhub tokens, and the presentation classes. Sets root theme properties and system/explicit theme selectors; no reset or component classes.                                  |
+| `@codenhub/styles/components`    | Compiled theme tokens, typography utilities, and every component class. Includes static reduced-motion loader masks; no reset, layout/content utilities, or native mappings.                                      |
+| `@codenhub/styles/native`        | Compiled complete surface plus classless mappings for headings, text, content elements, form controls, and buttons. Applies the reset and broad element selectors.                                                |
+| `@codenhub/styles/aesthetics`    | Compiled `.neobrutalism`, `.glass`, `.pixel`, and `.chunky-tile` classes. Adds no tokens or components of its own; import after the base stylesheet.                                                              |
+| `@codenhub/styles/aesthetics/*`  | One compiled aesthetic: `/neobrutalism`, `/glass`, `/pixel`, or `/chunky-tile`. Same rules and ordering as the combined file.                                                                                     |
+| `@codenhub/styles/tw`            | Source equivalent of the complete stylesheet. Imports Tailwind itself, theme, typography, utilities, components, and reset; applies the same global rules.                                                        |
+| `@codenhub/styles/tw/theme`      | Source theme, tokens, and presentation classes. Imports Tailwind's theme layer; emits root/system/explicit theme selectors and defines the package's custom `dark:` variant.                                      |
+| `@codenhub/styles/tw/components` | Published Tailwind source for theme, typography, buttons, feedback, forms, loaders, surfaces, and tooltips, including static reduced-motion loader masks. No reset, layout/content utilities, or native mappings. |
+| `@codenhub/styles/tw/surface`    | Source theme plus `.surface`, `.card`, and `.panel`.                                                                                                                                                              |
+| `@codenhub/styles/tw/button`     | Published Tailwind source for theme, activity indicators, and `.btn`; includes static reduced-motion masks because buttons compose `.loader-mask` for loading state.                                              |
+| `@codenhub/styles/tw/form`       | Source theme plus field, public `text-control`, input, textarea, select, checkbox, radio, and switch utilities.                                                                                                   |
+| `@codenhub/styles/tw/feedback`   | Source theme plus alert, badge, skeleton, and progress utilities and their keyframes.                                                                                                                             |
+| `@codenhub/styles/tw/loader`     | Published Tailwind source for activity indicators and loaders, including static reduced-motion masks. It has no theme or reset side effects and uses `currentColor`.                                              |
+| `@codenhub/styles/tw/tooltip`    | Source theme plus tooltip utilities.                                                                                                                                                                              |
+| `@codenhub/styles/tw/reset`      | Source theme, typography utilities, and global reset/accessibility rules. It changes root/body/elements and selection, motion, focus, scrollbar, and forced colors.                                               |
+| `@codenhub/styles/tw/native`     | Source complete surface plus reset and classless native-element mappings; broadest global effects.                                                                                                                |
+| `@codenhub/styles/tw/typography` | Source theme plus typography utilities; sets theme selectors but no reset or classless mappings.                                                                                                                  |
+| `@codenhub/styles/tw/utilities`  | Source theme and typography composition plus layout and content utilities; safelists the package utility names.                                                                                                   |
+| `@codenhub/styles/tw/aesthetics` | Source aesthetics, combined. `/tw/aesthetics/neobrutalism`, `/glass`, `/pixel`, and `/chunky-tile` publish one apiece. Plain CSS with no theme or reset side effects.                                             |
+
+Avoid importing overlapping entrypoints in the same build unless duplicate
+generated CSS is acceptable; pick the narrowest entrypoint that covers what a
+page needs.
+
+## Requirements
+
+- Consumer tooling must resolve package CSS imports.
+- Chrome 123, Safari 17.5, or Firefox 121 and newer. Color tokens are declared
+  with `light-dark()` and selected by `color-scheme` (Firefox 120), and
+  `.input-group` propagates a nested control's invalid and disabled state with
+  `:has()` (Firefox 121).
+- Tailwind CSS 4 or newer is required only for `/tw` source entrypoints.
+- The package has no JavaScript runtime. Apps must provide semantic HTML,
+  ARIA, keyboard behavior, focus management, validation, and announcements;
+  see [Accessibility](./accessibility.md).

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).