actual-css 0.1.0

package/docs/tokens.md

@@ -0,0 +1,455 @@
+# Tokens
+
+Tokens are the public theming surface. They should make the library feel easy to restyle without requiring users to understand every component implementation detail.
+
+The surface stays small by keeping most tokens semantic, not component-specific.
+
+- Global tokens are public API.
+- Component-local tokens are implementation details unless documented by that component.
+- Components should map global tokens to local variables internally.
+- Themes override tokens, not selectors.
+- Defaults must work without modern color features or build tooling.
+- Modern enhancements can derive better values with `color-mix()`, `light-dark()`, or container queries.
+
+## Public Surface
+
+> Tokens exposed as the public theming API, kept small and semantic.
+
+### Color
+
+Intent tokens are used by `.primary`, `.secondary`, `.success`, `.warning`, `.danger`, and `.neutral`.
+They are curated color/foreground pairs. Actual CSS does not compute foregrounds automatically in the core theme contract.
+
+```css
+:root {
+  --primary: hsl(270 24% 32%);
+  --primary-fg: hsl(0 0% 98%);
+  --secondary: hsl(18 24% 36%);
+  --secondary-fg: hsl(0 0% 98%);
+  --success: hsl(145 55% 32%);
+  --success-fg: hsl(0 0% 98%);
+  --warning: hsl(38 76% 34%);
+  --warning-fg: hsl(0 0% 98%);
+  --danger: hsl(2 62% 45%);
+  --danger-fg: hsl(0 0% 98%);
+  --neutral: hsl(220 8% 42%);
+  --neutral-fg: hsl(0 0% 98%);
+}
+```
+
+Surface tokens describe the canvas and elevation model. Components should prefer these over hard-coded colors.
+
+```css
+:root {
+  --surface: hsl(0 0% 100%);
+  --surface-raised: hsl(0 0% 100%);
+  --surface-subtle: hsl(220 14% 96%);
+  --surface-solid: hsl(222 18% 12%);
+
+  --text: hsl(222 18% 12%);
+  --text-muted: hsl(220 8% 42%);
+  --text-subtle: hsl(220 7% 58%);
+
+  --border: hsl(220 12% 88%);
+  --focus: var(--primary);
+  --focus-outline: 2px solid var(--focus);
+  --focus-outline-offset: 2px;
+  --focus-ring: hsl(258 21% 32% / 0.22);
+  --hover-overlay: hsl(220 20% 10% / 0.04);
+}
+```
+
+The surface levels are: `surface` (canvas), `surface-raised` (cards, raised surfaces), `surface-subtle` (the working subtle level — for hover overlays, form fields, table headers), and `surface-solid` (the dark inverse surface, used for accent areas).
+
+Use `*-fg` pairs only for solid backgrounds where the component controls both foreground and background. Do not require a foreground token for every surface token.
+
+Focus styling is outline-first. A global focus baseline uses `--focus-outline`
+and `--focus-outline-offset` for the guaranteed visible affordance: older
+browsers show it on `:focus`, while modern browsers limit it to
+`:focus-visible`. Components add `--focus-ring-shadow` only where a softer
+halo helps.
+`forced-colors: active` disables the shadow and maps the outline to
+`Highlight`.
+
+### Default theme philosophy
+
+The default theme is intentionally calm. `primary` is a near-neutral dark grey rather than a saturated brand color, `secondary` is a neutral surface rather than a colored intent, and the semantic states are desaturated. Optional themes can re-introduce vivid intent palettes on top of this foundation; the default is meant to be the adult, editorial baseline.
+
+Soft surfaces (`.btn.soft`, `.badge.soft`, and the default `.alert`) are generated from intent colors through `color-mix()`. Themes can tune the mix globally instead of rewriting component selectors.
+
+```css
+:root {
+  --soft-bg-mix: 88%;
+  --soft-border-mix: 65%;
+  --soft-hover-alpha: 12%;
+}
+```
+
+### Shape
+
+Shape is intentionally small. Components can derive local radii from these.
+
+```css
+:root {
+  --radius-sm: 0.25rem;
+  --radius: 0.5rem;
+  --radius-lg: 0.75rem;
+  --border-width: 1px;
+}
+```
+
+Do not create shape APIs like `.rounded`, `.pill`, or `.square` for every component. Prefer theme-level changes, for example a square theme can set all radius tokens to `0`.
+
+### Spacing
+
+Spacing should be useful without becoming a design-token encyclopedia.
+
+```css
+:root {
+  --gap: 0.75rem;
+  --space-1: 0.25rem;
+  --space-2: 0.5rem;
+  --space-3: 0.75rem;
+  --space-4: 1rem;
+  --space-5: 1.5rem;
+  --space-6: 2rem;
+}
+```
+
+Use `em` for spacing that should scale with the component text size, such as button gaps and inline padding. Use `rem` for global rhythm, layouts, and fixed density.
+
+### Typography
+
+Typography tokens should cover the document baseline and common component needs.
+
+```css
+:root {
+  --font-sans: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+
+  --line-height: 1.5;
+  --font-weight: 400;
+  --font-weight-strong: 650;
+
+  /* Type scale */
+  --font-size-xs: 0.8125rem;
+  --font-size-sm: 0.875rem;
+  --font-size-md: 1rem;       /* base */
+  --font-size-lg: 1.125rem;
+}
+```
+
+Components can use local font variables for their own mapping, but should inherit by default. `--font-size-md` is the baseline — going smaller (`.sm`/`--font-size-sm`/`-xs`) is the easy direction; going larger adjusts line-heights and surrounding paddings, so prefer keeping base body text at `--font-size-md`.
+
+### Controls
+
+Controls share sizing so buttons, inputs, selects, and compact app UI always align. `.sm`/`.lg` set shared density tokens for controls, content components, and compact labels.
+
+```css
+:root {
+  --control-size-sm: 2rem;      /* 32px → .sm */
+  --control-size-md: 2.375rem;  /* 38px → default */
+  --control-size-lg: 2.75rem;   /* 44px → .lg */
+  --control-size: var(--control-size-md);
+  --control-pad-x: 1em;
+  --control-font-size: var(--font-size-md);
+}
+```
+
+- `.lg` — 44px control height, `--font-size-lg` (18px)
+- default — 38px control height, `--font-size-md` (16px, the baseline)
+- `.sm` — 32px control height, `--font-size-sm` (14px)
+
+Size modifiers swap the shared control tokens:
+
+```css
+.sm {
+  --control-size: var(--control-size-sm);
+  --control-font-size: var(--font-size-sm);
+  --variant-font-size: var(--font-size-sm);
+  --variant-icon-size: 1rem;
+  --variant-pad-block: var(--space-3);
+  --variant-compact-size: 1.25rem;
+  --variant-compact-font-size: 0.75rem;
+}
+
+.lg {
+  --control-size: var(--control-size-lg);
+  --control-font-size: var(--font-size-lg);
+  --variant-font-size: var(--font-size-lg);
+  --variant-icon-size: 1.5rem;
+  --variant-pad-block: var(--space-5);
+  --variant-compact-size: 1.875rem;
+  --variant-compact-font-size: var(--font-size-sm);
+}
+```
+
+Content components can consume `--variant-*` for local density. Compact labels such as `.badge` consume `--variant-compact-*`; display elements with special geometry, such as avatar and spinner, keep their own size scales.
+
+### Elevation
+
+Use a tiny elevation surface. Components should not invent their own shadow scales.
+
+```css
+:root {
+  --shadow: 0 0.5rem 1.5rem hsl(220 30% 10% / 0.08);
+  --shadow-popout: 0 0.25rem 0.75rem hsl(220 30% 10% / 0.15);
+}
+```
+
+### Motion
+
+Motion tokens keep transitions consistent and easy to disable.
+
+```css
+:root {
+  --duration: 150ms;          /* component transitions (hover/focus) */
+  --duration-slow: 200ms;     /* one-shot open/close (.drawer animation) */
+  --duration-spin: 0.75s;     /* continuous spin (.spinner) */
+  --duration-shimmer: 1.2s;   /* continuous shimmer (.skeleton, indeterminate .progress) */
+  --ease: ease;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --duration: 0.01ms;
+  }
+}
+```
+
+`reset.css` clamps raw animation and transition durations to `0.01ms`, resets
+their delays, and restores `html` scroll behavior under
+`prefers-reduced-motion: reduce` in addition to the `--duration` token above.
+Decorative loops effectively complete immediately without blanket-disabling
+animation support.
+
+### Icons
+
+Icons used by CSS-only controls are public tokens because users may need to replace them.
+
+```css
+:root {
+  --icon-chevron-mask: url("data:image/svg+xml,...stroke='black'...");
+  --icon-check-mask: url("data:image/svg+xml,...stroke='black'...");
+  --icon-chevron-image: url("data:image/svg+xml,...");
+}
+```
+
+Prefer `*-mask` tokens for CSS icons so components can color them with `background-color: currentColor` or a semantic token. Use image tokens only where the platform requires `background-image` (native select chevrons cannot use `currentColor`). Only add an icon token when CSS needs the icon. Markup icons should stay in markup.
+
+### Composition tokens
+
+A few cross-component helpers:
+
+- `--indicator-offset` / `--indicator-ring` — positioning and contrast ring for a status dot attached to `.avatar > .badge:empty`.
+- `--backdrop-color` / `--backdrop-opacity` / `--backdrop-fill` — scrim color and opacity shared by `dialog.modal::backdrop`, `dialog.drawer::backdrop`, and `.surface-backdrop`. Override `--backdrop-opacity` per theme for a denser or lighter scrim.
+
+```css
+:root {
+  --indicator-offset: 14.65%;      /* circle-aware inset */
+  --indicator-ring: var(--surface);
+  --backdrop-color: var(--surface-solid);
+  --backdrop-opacity: 0.45;
+}
+```
+
+## Internal Tokens
+
+> Component-local tokens allowed when they reduce duplication or make component code clearer.
+
+Internal tokens are allowed when they reduce duplication or make component code clearer.
+
+### Variant Plumbing
+
+The shared visual variants are:
+
+- `.solid`: full background, paired foreground. This is the default for buttons and badges.
+- `.soft`: lightly tinted background, colored text. Good for alerts and secondary badges.
+- `.outline`: transparent background, colored border and text.
+
+Buttons also support two button-only variants:
+
+- `.ghost`: transparent button with hover affordance.
+- `.link`: button semantics with link presentation.
+
+Do not force `.ghost` or `.link` onto components where the interaction model does not fit. Shared API should follow shared use.
+
+```css
+.btn {
+  --btn-bg: var(--ui-bg, var(--btn-default-bg, var(--intent, var(--neutral))));
+  --btn-fg: var(--ui-fg, var(--btn-default-fg, var(--intent-fg, var(--neutral-fg))));
+  --btn-border: var(--ui-border, var(--btn-default-border, transparent));
+
+  border: var(--border-width) solid var(--btn-border-color, var(--btn-border));
+  border-block-end-color: var(
+    --btn-border-block-end-color,
+    var(--btn-border-color, var(--btn-border))
+  );
+  border-block-end-width: var(--btn-border-block-end-width, var(--border-width));
+}
+```
+
+Button-local defaults are intentionally inherited extension points for themes
+that change button grammar, such as turning the default solid button into a
+surface button with an intent-colored lower edge. Keep them local until the
+same need appears across multiple components.
+
+Text controls (`.input`/`.textarea`/`.select`, forms/control.css) expose the
+same lower-edge extension point: `--control-border-block-end-color` and
+`--control-border-block-end-width` are unset by default and fall back to the
+regular border, so a theme can give inputs an underline-style lower edge the
+same way `edge.css` does for buttons, without fighting the hover/focus/disabled
+state rules that still own `--control-border` itself.
+
+Alerts (components/alert.css) expose the same idea on the leading edge instead
+of the lower one: `--alert-border-inline-start-color` and
+`--alert-border-inline-start-width` are unset by default and fall back to the
+regular `--ui-border`, so a theme can turn an alert into a callout with a
+colored flag on the inline-start side, matching the classic notice pattern,
+without a per-variant override.
+
+A theme is not limited to the tokens above; it can restate any component-local
+token under a state selector to change the interaction recipe itself, not just
+the palette. `edge.css` does this for focus: the base input recipe
+(forms/control.css) flips `--control-border` to `--focus` on top of the shared
+outline + ring, which triples up with the lower-edge accent above. Edge drops
+the border-color flip under `:focus-visible` (thickening the accent edge
+instead) and also thins `--focus-outline` and tightens `--focus-outline-offset`
+so the outline hugs the control rather than floating a second ring around it.
+
+Buttons don't consume `--focus-outline` — button.css computes its own outline
+inline so the color can follow `--btn-focus-color` (intent-aware, unlike the
+plain `--focus` the shared token is hardcoded to), so it exposes a matching
+local token, `--btn-focus-outline-width`, defaulting to the same
+`calc(var(--border-width) * 2)` the old hardcoded value used. `edge.css`
+overrides it the same way it overrides `--focus-outline` for inputs.
+
+The outline overrides are gated in `@media not (forced-colors: active)`. Under
+forced-colors, `theme.css` repoints `--focus-outline` to a Highlight-colored
+system outline via a `:root, [data-theme="light"], [data-theme="dark"]` rule —
+`:root` always matches the root element regardless of its `data-theme`
+attribute, so that fallback reaches every theme, edge included. But it is a
+lower-specificity, inherited value: an unguarded same-property override
+declared directly on `.input` would out-specificity it in every color mode,
+including forced-colors, because direct beats inherited regardless of the
+media condition either rule was written under. Any theme that restyles
+`--focus-outline`, `--btn-focus-outline-width`, or `--focus-ring-shadow` needs
+the same guard.
+
+Rules:
+
+- Prefix internal component tokens with the component name (`--btn-*`, `--alert-*`, `--card-*`).
+- Prefix shared variant plumbing with `--ui-*`.
+- Keep component-specific variants in component code when they do not generalize.
+- Do not require users to override internal tokens for ordinary theming.
+- Promote an internal token to public only when there is a repeated, reasonable customization need.
+
+## Theme Contract
+
+> What a theme must override to restyle the library without touching components.
+
+Themes override tokens, not selectors. The themes in `src/css/themes/` are demo examples, not shipped by the default stylesheet; they exist to show valid ways to use this contract.
+
+A minimal recolor theme overrides the intent pairs, surfaces, text colors, border, focus, focus ring, and hover overlay.
+
+Shape, shadow, motion, typography, and soft-variant mix tokens are optional knobs. Override them only when the theme actually changes that part of the system.
+
+A full theme can override:
+
+- intent colors and foreground pairs
+- surface, text, border, focus, and overlay colors
+- radius tokens
+- optional shadow, motion, typography, and soft-variant mix tokens
+
+```css
+[data-theme="brand"] {
+  color-scheme: light;
+
+  --primary: hsl(260 70% 54%);
+  --primary-fg: white;
+  --secondary: hsl(190 70% 38%);
+  --secondary-fg: white;
+  --success: hsl(150 58% 34%);
+  --success-fg: white;
+  --warning: hsl(42 92% 52%);
+  --warning-fg: hsl(35 35% 10%);
+  --danger: hsl(355 72% 52%);
+  --danger-fg: white;
+  --neutral: hsl(250 8% 42%);
+  --neutral-fg: white;
+
+  --surface: hsl(260 45% 98%);
+  --surface-raised: white;
+  --surface-subtle: hsl(260 35% 94%);
+  --surface-solid: hsl(260 28% 16%);
+
+  --text: hsl(260 24% 14%);
+  --text-muted: hsl(260 10% 42%);
+  --text-subtle: hsl(260 8% 56%);
+  --border: hsl(260 24% 84%);
+  --focus: var(--primary);
+  --focus-ring: hsl(260 70% 54% / 0.22);
+  --hover-overlay: hsl(260 30% 10% / 0.04);
+  --soft-bg-mix: 84%;
+  --soft-border-mix: 58%;
+
+  --radius: 0.625rem;
+  --radius-sm: 0.3125rem;
+  --radius-lg: 0.875rem;
+}
+```
+
+Without `data-theme`, the default theme advertises `color-scheme: light dark`
+and follows the user's OS preference in browsers that support `light-dark()`.
+Dark themes should set `color-scheme: dark`. Light themes should set
+`color-scheme: light`. Browsers without `light-dark()` receive the light
+fallback.
+
+Because the native select chevron is an SVG background image and cannot inherit
+`currentColor`, the select hands the arrow back to the browser under
+`prefers-contrast: more` (same treatment as `forced-colors: active`) instead of
+shipping a recolored chevron per theme — one native fallback covers every
+theme without a high-contrast icon variant to maintain.
+
+In `forced-colors: active`, the default theme maps the public color tokens to
+system colors (`Canvas`, `CanvasText`, `ButtonText`, `Highlight`, and
+`HighlightText`) and removes decorative shadows. Components should inherit
+that token mode by default; keep local forced-color rules only for custom
+control geometry, native bar parts, disabled states, or selected states that
+would otherwise be communicated only by background color.
+
+## Component Mapping
+
+> How components map global tokens to local aliases for a clear theme and variant contract.
+
+Components should map global tokens once at the top of the component and use local tokens afterwards.
+
+```css
+.alert {
+  --alert-bg: var(--ui-bg, var(--surface-subtle));
+  --alert-fg: var(--ui-fg, var(--text));
+  --alert-border: var(--ui-border, var(--border));
+  --alert-radius: var(--radius-lg);
+
+  border: var(--border-width) solid var(--alert-border);
+  border-radius: var(--alert-radius);
+  background: var(--alert-bg);
+  color: var(--alert-fg);
+}
+```
+
+This makes the contract obvious:
+
+- theme authors adjust global tokens
+- variant code adjusts `--ui-*`
+- component code consumes local aliases
+
+## Non-Goals
+
+> Decisions deliberately excluded from the token surface to keep it small.
+
+- Do not expose a separate token for every selector.
+- Do not mirror Pico-style component-specific variables unless there is a clear need.
+- Do not add Tailwind-like color scales as public API.
+- Do not rely on Sass, PostCSS, or generated token files.
+- Do not make dark mode required for old browsers. Light mode is the fallback.

package/docs/typography.md

@@ -0,0 +1,159 @@
+# Typography
+
+## Overview
+
+> Quiet global defaults plus an opt-in prose scope for long-form content, with a separate optional module for fluid display type.
+
+Typography has three layers:
+
+- global defaults that make plain HTML readable without becoming classless CSS
+- `.prose`, an opt-in rich-text scope for articles, documentation, markdown, CMS content, and long-form text
+- a small optional fluid module for display, title, and lead sizes that scale with the viewport
+
+Components must not depend on `.prose`. App screens, forms, cards, tables, navigation, dashboards, and component examples should use their own component or layout rules.
+
+Use `.prose` directly on a semantic content container, usually an `article`.
+
+## Why this shape
+
+The framework is a components-oriented, theme-oriented library, not a classless stylesheet and not a utility-first framework. The typography system reflects that.
+
+Global typography should stay mild because:
+
+- a card, a dialog, a sidebar, or a dashboard must not be accidentally reshaped by selectors that target `h1` or `p` outside `.prose`
+- form controls, navigation, and dense app UI need predictable inheritance rather than decorative defaults
+- the only place where headings, paragraphs, lists, and blockquotes can be styled as a hierarchy is the `.prose` scope
+
+The framework avoids exposing a large public type scale. There is no `fs-1` to `fs-7`, no Bootstrap-like heading utilities, no `text-display` / `text-h1` / `text-h2` ladder on day one. Theme work, real components, and repeated use cases are what justify new type tokens — not a speculative API.
+
+The framework avoids RFS-style fluid typography as a foundation. Fluid sizes are useful for display text on marketing pages, but they make body text and app UI harder to reason about. A small optional module covers the display use case without dragging the rest of the system along.
+
+## Boundaries
+
+The typography system is split into three layers with strict responsibilities.
+
+### Global baseline
+
+The baseline owns the minimum needed to make plain HTML readable.
+
+It applies everywhere — cards, dialogs, heroes, app shells — not only in prose.
+
+It does not own visual hierarchy. No global `font-size` on headings, no global `font-weight` on headings, no global margins on headings, no global `text-decoration` on links. These choices would shape app UI in ways the framework cannot predict.
+
+The only mildly opinionated defaults at the baseline are: line-height on headings (tight, so multi-line headings stay readable), `text-wrap: balance` on headings where supported, the `hr` rule, the `::selection` rule, the `code` / `kbd` / `samp` / `pre` font family, and `small` font size. Everything else stays neutral so components and `.prose` can take over without fighting the baseline.
+
+Global links inherit color. The visual affordance of a link is the responsibility of `.prose` (for authored content) or of a component (for nav links, button-like links, tabs, breadcrumbs, etc.). Underlining every `a` globally would collide with all of those.
+
+### `.prose` scope
+
+`.prose` is the opt-in rich-text scope. It owns the visual hierarchy of authored content.
+
+It owns: readable measure, vertical rhythm between common text elements, heading hierarchy, link affordance, list spacing, code and keyboard treatment, blockquote treatment, table treatment, image / figure / figcaption treatment, mark, and `text-wrap` balance / pretty for prose elements.
+
+It does not own: page layout, app cards, alerts, forms, app tables, navigation, component variants, or any automatic styling outside the `.prose` subtree.
+
+The reason for that boundary: a dialog title, a card heading, or a sidebar section heading should not become a "prose h1". Components own those. If a card or a dialog wants a richer heading, it can use a component-level rule, not a global selector.
+
+### Optional fluid module
+
+`src/css/optional/typography-fluid.css` is a small file that is not imported by `actual.css`. Projects that need display, title, and lead sizes that scale with the viewport (landing pages, marketing pages, hero sections, documentation homepages) import it manually after `actual.css`.
+
+The module exposes three size tokens (`--fluid-display`, `--fluid-title`, `--fluid-lead`) and three composed classes (`.text-display`, `.text-title`, `.text-lead`). It is deliberately not the foundation: body text, app UI, and the default prose scale stay static.
+
+There is also a non-fluid `.lead` utility in the core, for a simple readable intro paragraph. The optional module does not redefine `.lead`; it adds a separate `.text-lead` for display contexts. This avoids an optional import silently changing how existing markup renders.
+
+## Link treatment
+
+Global links are intentionally neutral. Only `.prose` styles them as prose links, and only components style their own link-like elements (nav links, button-as-link, tabs, breadcrumbs, etc.). The reason is that underlining every `a` globally fights against button-like links, nav links, clickable cards, menu items, and tab triggers. Components that need link semantics should opt in with their own rule.
+
+The `--link-decoration-thickness`, `--link-decoration-thickness-hover`, and `--link-underline-offset` tokens have been removed because no global rule consumes them. Prose and components set their own underline metrics inline.
+
+## Type scale
+
+There is no exposed type scale.
+
+The framework exposes font weights, line heights, and the prose-specific overrides. It does not expose `fs-1` through `fs-7`, heading-level tokens, or heading-level utility classes. The reason is the same as for the baseline: a public scale is a contract, and adding it now would lock in choices before theme work and real component use tell us what is actually needed.
+
+When a scale is needed, the optional fluid module is the right place to start. A future theme can override its tokens, not invent a parallel scale in components.
+
+## Font weights
+
+The framework exposes a small set of weights:
+
+- `--font-weight` (400) — body default
+- `--font-weight-medium` (500) — slightly heavier than body, for nav links
+- `--font-weight-strong` (650) — emphasis, prose headings, badges, tabs, table headers
+- `--font-weight-bold` (700) — the strongest weight exposed, used by the navbar brand and the accordion summary
+
+No `--font-weight-light`. Light weights depend on the typeface, are rarely a good default, and add surface area without a recurring need.
+
+These weights are also the values used by components. Components do not use literal `font-weight: 600` or `font-weight: 750`; they reference the tokens. Theme authors can re-map them in one place.
+
+## Line heights
+
+The framework exposes three line-height tokens:
+
+- `--line-height-tight` (1.25) — used by global headings and by display / title classes
+- `--line-height` (1.5) — body default
+- `--line-height-relaxed` (1.75) — used by `.lead` and `.text-lead` for intro text
+
+There is no `--line-height-normal`. It would be redundant with `--line-height`. Prose overrides line-height through `--prose-line-height` and `--prose-heading-line-height` because the readable values for long-form text are different from app UI.
+
+## text-wrap
+
+`text-wrap: balance` and `text-wrap: pretty` are used at three levels:
+
+- global headings, where supported
+- inside `.prose` for headings (balance) and for paragraphs, list items, and blockquotes (pretty)
+- as opt-in utilities `.text-balance` and `.text-pretty` for any element outside `.prose`
+
+These declarations degrade naturally: browsers that do not support a `text-wrap` value ignore it and keep normal wrapping. There is no `text-align: center` hidden inside `.text-balance`: balance is about wrapping, not alignment.
+
+## Headings
+
+Headings are split between the global baseline and `.prose`.
+
+Globally, headings get a tight line-height, a color from `--heading` (or inherited), and progressive `text-wrap: balance`. They do not get a `font-size`, a `font-weight`, or margins. The reason is that a card heading, a dialog title, or a sidebar section should not be auto-magically enlarged by selector.
+
+Inside `.prose`, headings get a `font-weight` from `--font-weight-strong`, a tighter line-height from `--prose-heading-line-height`, a margin-block rhythm, and an explicit `text-wrap: balance`. The `h1` to `h4` font sizes are also scoped to `.prose` and are not exposed as a public scale.
+
+The `hgroup` element gets only structural styling: a grid layout, a gap, and a reset of internal margins. No font-size, no color, no weight. Its visual identity is the responsibility of the headings and paragraphs it contains.
+
+## Links and text utilities
+
+Three logical alignment utilities exist (`.text-start`, `.text-center`, `.text-end`) because alignment is independent of typography hierarchy and is useful in many contexts. They use logical properties so they follow writing direction.
+
+`text-wrap` balance and pretty are exposed as utilities so they can be applied outside `.prose` (e.g. on a card title, a dialog description, a hero subtitle).
+
+`transition: all` is not used. Transitions target specific properties. This is a general rule, not just a typography rule.
+
+## Small elements
+
+`small` gets a smaller font size globally (`0.875em`) because it is a semantic element, not a utility. There is no `.small` class competing with the element.
+
+`code`, `kbd`, `samp`, and `pre` get the mono font family globally. Visual treatment (background, padding, radius) is left to `.prose` or to code-block components.
+
+## Tables
+
+Prose tables are a different concern from app data tables. Long-form content can contain a small table, but a sortable, dense, row-actionable app table belongs to the table component. The `.prose table` rule is intentionally minimal: it does not define sticky headers, selection states, row actions, or density variants.
+
+## Optional module — how to use it
+
+To enable fluid display type on a marketing or documentation surface, import the optional module after `actual.css` in the project's stylesheet entry point. The module does not change anything in the core: it adds three size tokens and three classes. Body text, app UI, and the default prose scale are not affected.
+
+Projects that do not need fluid display type do nothing — the optional module is not part of the default bundle.
+
+## What not to reintroduce
+
+These are decisions that the framework has already made. Re-introducing them silently would regress the system.
+
+- Do not add `font-size` on global `h1` to `h6`. Headings inherit size from context (component or `.prose`).
+- Do not add `font-weight` on global `h1` to `h6`. Strong weight is scoped to `.prose` and to components that need it.
+- Do not add global `text-decoration: underline` on `a`. Links get their visual affordance from `.prose` or from their component.
+- Do not add `transition: all`. Transitions target specific properties.
+- Do not add a `--font-weight-light`. It is rarely a good default and depends on the typeface.
+- Do not add a `text-align: center` shortcut to `.text-balance`. Balance is about wrapping, not alignment.
+- Do not add RFS-style fluid type to the foundation. Fluid sizing is for display text in the optional module.
+- Do not add heading-level utility classes (`h1`, `h2`, …) or a public `fs-*` scale until theme work and real components prove they are needed.
+- Do not extend `.prose` to style cards, alerts, app tables, or navigation. Those belong to their components.
+