actual-css 0.3.1 → 0.4.0

package/docs/pages/foundations/tokens.md

@@ -87,9 +87,20 @@ Soft surfaces (`.btn.soft`, `.badge.soft`, and the default `.alert`) are generat
   --soft-bg-mix: 88%;
   --soft-border-mix: 65%;
   --soft-hover-alpha: 12%;
+  --soft-fg-mix: 100%;
 }
 ```
 
+`--soft-fg-mix` is the share of raw intent in soft *text*. At its `100%` default soft ink is the intent color itself, which is what a palette of dark, muted intents wants. A vivid or light palette cannot afford that: a soft badge then paints intent-tinted ink on an intent-tinted surface, and the two converge. Lowering the mix rebates the ink toward `--text`, which is the right direction in both schemes because `--text` is dark on a light theme and light on a dark one. Around `45%` a fully saturated palette recovers AA while the ink still reads as its intent.
+
+**When an intent is tinted against a theme-controlled surface or border, the mix interpolates in `oklab`.** That covers the soft recipe, the checked `.choice-card` tint, and the `.overline.pill` border.
+
+Not because rectangular interpolation is more faithful to the intent hue — across the shipped presets it is a few degrees *less* faithful. A browser treats hue as powerless below a small chroma epsilon, so for the low-chroma surfaces and borders the presets actually use, a polar mix snaps cleanly onto the intent and wins.
+
+The reason is continuity. A theme owns `--surface` and `--border`, and may put them anywhere from achromatic to vivid. Under polar interpolation that range contains a cliff: below the epsilon the mix tracks the intent, above it the surface hue starts winning, and crossing it moves the result into a different color family — 116 degrees, a soft `.secondary` landing in the greens. Cartesian interpolation responds smoothly across the whole range a public token allows. A recipe that is only correct while an adopter's surface stays under an unstated, implementation-defined threshold is not a contract, so the framework trades a small continuous error for a predictable one. The present cost is imperceptible: the largest difference the rule introduces in any preset is 3/255 on one channel.
+
+Mixing against `black`, `white`, `transparent`, or `currentColor` is exempt and stays in `oklch`: those have no hue to interpolate, so both spaces give byte-identical results. Polar interpolation also stays legitimate where hue rotation is the point, such as sweeping a gradient through hues. `bun run check:color-space` enforces the rule for contextual tints and takes an `intentional-oklch` comment as an escape hatch.
+
 ### Shape
 
 Shape is intentionally small. Components can derive local radii from these.
@@ -261,12 +272,12 @@ Under `forced-colors: active`, `--backdrop-fill` maps to `Canvas`.
 
 A small z-index scale orders non-dialog overlays. Native `<dialog>` elements (modal, drawer) render on the platform top-layer, which has no numeric z-index and always paints above the page — they never compete with this scale.
 
-| Token | Value | Used by |
-|---|---|---|
-| `--z-sticky` | 10 | Sticky page chrome (`form-actions.sticky`, `topbar`). |
-| `--z-menu` | 20 | Floating menus (`flyout`); `.surface-backdrop` sits at `calc(var(--z-menu) - 1)`. |
-| `--z-tooltip` | 50 | Tooltips. |
-| `--z-status` | 60 | `status-bar`. |
+| Token         | Value | Used by                                                                           |
+|---------------|-------|-----------------------------------------------------------------------------------|
+| `--z-sticky`  | 10    | Sticky page chrome (`form-actions.sticky`, `topbar`).                             |
+| `--z-menu`    | 20    | Floating menus (`flyout`); `.surface-backdrop` sits at `calc(var(--z-menu) - 1)`. |
+| `--z-tooltip` | 50    | Tooltips.                                                                         |
+| `--z-status`  | 60    | `status-bar`.                                                                     |
 
 Stacking-context traps: a flyout or tooltip that is a DOM descendant of a dialog, or of a container with `transform`, `filter`, `contain`, `isolation`, or `will-change`, is confined to that ancestor's stacking context. Its z-index token only orders it against siblings within that context. When a dialog's top-layer clips a descendant flyout, move the flyout markup outside the dialog or use a portal/popover to escape the stacking context.
 
@@ -330,9 +341,9 @@ Rules:
 
 ## Theme contract
 
-Themes override tokens, not selectors. The themes in `src/css/themes/` are demo examples, not included in the default stylesheet; they exist to show valid ways to use this contract. They ship in the package as **reference sources for copying** — the `./css/themes` exports are intentionally `null`, so they are not supported import entrypoints.
+Themes override tokens, not selectors. The themes in `src/css/themes/` are repository-only demo examples, not included in the default stylesheet or the npm package; they exist to show valid ways to use this contract, such as `ocean`, `square`, `cyberpunk`, and `brutalist`.
 
-A minimal recolor theme overrides the intent pairs, surfaces, text colors, border, focus, focus ring, and hover overlay.
+A minimal recolor theme overrides the intent pairs, surfaces, text colors, border, focus, and hover overlay. In browsers with `color-mix()` support, the core derives `--focus-ring` from the island's `--focus`; override the ring only for a deliberate visual treatment or when a matching pre-`color-mix()` fallback is required.
 
 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.
 
@@ -372,7 +383,6 @@ A minimal recolor theme (illustrative, not a shipped theme):
   --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%;
@@ -389,6 +399,8 @@ Without `data-theme`, the default theme advertises `color-scheme: light dark` an
 
 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.
 
+Under `prefers-contrast: more`, the user's contrast preference wins over a theme's palette by contract: the core collapses `--text-muted`/`--text-subtle` to `--text` and thickens borders and focus so no theme can defeat a legibility requirement. This is a deliberate decision, not a specificity quirk — the repeated `[data-theme][data-theme]` attribute only outranks a preset theme stylesheet loaded after the core.
+
 Under `forced-colors: active`, the browser automatically remaps `color`, `background`, and `border` properties to system colors. The default theme provides the few necessary system-color overrides for cases the browser cannot handle — `--focus-outline-color`, `--state-selected`/`--state-selected-fg`, `--state-disabled`, `--backdrop-fill`, and decorative shadow removal. Because that rule targets `:root` (which always matches regardless of `data-theme`) and the `[data-theme]` attributes, it reaches every theme. Components should inherit that baseline; 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
@@ -418,4 +430,4 @@ Components map global tokens to local aliases at the top of the component, then
 - 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.
+- Do not make dark mode required for old browsers. Light mode is the fallback.

package/docs/pages/foundations/typography.md

@@ -10,7 +10,7 @@ Typography has three layers:
 
 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`.
+Use `.prose` directly on a semantic content container, usually an `article`. It is not a page-level wrapper: component demos, navigation, forms, and other application UI belong outside it. Compose prose sections with those siblings using a layout primitive such as `.stack`.
 
 ## Why this shape
 
@@ -46,31 +46,47 @@ Global links inherit color. The visual affordance of a link is the responsibilit
 
 `.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 owns: readable measure, vertical rhythm, heading hierarchy, link affordance, list spacing, description-list treatment, code and keyboard treatment, blockquote treatment, table treatment, image / figure / figcaption treatment, mark, and `text-wrap` balance / pretty for authored or generated rich-text descendants.
 
 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.
+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. Put the component next to the prose section in a layout container; do not ask `.prose` to infer where an embedded component begins.
 
-### Optional fluid module
+### 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`.
+`src/css/typography/fluid.css` is a small module 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:
+
+```css
+@import "actual-css/css/typography/fluid";
+```
 
 The module exposes three size tokens and three composed classes. It is deliberately not the foundation: body text, app UI, and the default prose scale stay static.
 
-| Token | Class | Purpose |
-|---|---|---|
-| `--fluid-display` | `.text-display` | Hero / display sizes. |
-| `--fluid-title` | `.text-title` | Section titles. |
-| `--fluid-lead` | `.text-lead` | Intro paragraphs on display surfaces. |
+| Token             | Class           | Purpose                               |
+|-------------------|-----------------|---------------------------------------|
+| `--fluid-display` | `.text-display` | Hero / display sizes.                 |
+| `--fluid-title`   | `.text-title`   | Section titles.                       |
+| `--fluid-lead`    | `.text-lead`    | Intro paragraphs on display surfaces. |
 
-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.
+There is also a non-fluid `.lead` utility in the core, for a simple readable intro paragraph. The fluid module does not redefine `.lead`; it adds a separate `.text-lead` for display contexts. This avoids a fluid 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.
 
-There are no `--link-decoration-thickness`, `--link-decoration-thickness-hover`, or `--link-underline-offset` tokens; no global rule consumes them. Prose and components set their own underline metrics inline.
+Prose links take `--primary`. That breaks down for a theme whose primary is a light or fully saturated accent: it can carry a filled button, where it is the background under its own `--primary-fg`, but not inline body text, where it has to hold contrast against `--surface` on its own. `--link` is the optional override for exactly that case — a theme sets it and `.prose` link ink follows, hover included, with no rule to restate. Unset, it falls back to `--primary`, so existing themes are unaffected.
+
+```css
+[data-theme="vivid"] {
+  --primary: hsl(48 100% 50%); /* fine as a button fill */
+  --link: hsl(215 100% 30%);   /* 1.4:1 as body ink, so lend a darker hue */
+}
+```
+
+It is a color token only. There are still no `--link-decoration-thickness`, `--link-decoration-thickness-hover`, or `--link-underline-offset` tokens; no global rule consumes them. Prose and components set their own underline metrics inline.
 
 ## Type scale
 
@@ -113,10 +129,11 @@ There is no `--line-height-normal`. It would be redundant with `--line-height`.
 
 ### Prose hooks
 
-- `--prose-measure` — readable line length cap, shared with `.measure`.
+- `--prose-measure` — readable line length cap for `.prose` (the standalone `.measure` helper reads its own `--measure`).
 - `--prose-line-height` — body line height inside `.prose`.
 - `--prose-heading-line-height` — heading line height inside `.prose`.
 - `--prose-flow` — vertical rhythm between sibling blocks inside `.prose`.
+- `--link` — prose link ink; falls back to `--primary` when a theme leaves it unset.
 
 ## text-wrap
 
@@ -134,7 +151,7 @@ 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 keep the global `text-wrap: balance`. The `h1` to `h4` font sizes are also scoped to `.prose` and are not exposed as a public scale.
+Inside `.prose`, headings get a `font-weight` from `--font-weight-strong`, a tighter line-height from `--prose-heading-line-height`, margin rhythm, and keep the global `text-wrap: balance`. Their color follows the contextual `--heading` alias, so prose also composes correctly with a contextual surface. The `h1` to `h4` font sizes are scoped to `.prose`, remain low-specificity, 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.
 
@@ -154,13 +171,26 @@ Three logical alignment utilities exist (`.text-start`, `.text-center`, `.text-e
 
 ## 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.
+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 outside the prose boundary. The prose table recipe is intentionally minimal: it does not define sticky headers, selection states, row actions, or density variants.
+
+## Description lists
+
+`.prose` renders `dl` / `dt` / `dd` in document flow: terms take the strong weight, definitions keep a modest indent, and a term that follows a definition gets breathing room.
+
+There is no grid-based key/value layout by default. A valid `<dl>` may pair several terms with one definition or the reverse, and a two-column grid silently assumes strict pairs. For true key/value metadata, compose a grid layout around the list yourself.
+
+## Fluid module — how to use it
+
+To enable fluid display type on a marketing or documentation surface, import the module after `actual.css` in the project's stylesheet entry point:
 
-## Optional module — how to use it
+```css
+@import "actual-css/css";
+@import "actual-css/css/typography/fluid";
+```
 
-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.
+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.
+Projects that do not need fluid display type do nothing — the module is not part of the default bundle.
 
 ## What not to reintroduce
 
@@ -172,6 +202,6 @@ These are decisions that the framework has already made. Re-introducing them sil
 - 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 RFS-style fluid type to the foundation. Fluid sizing is for display text in the fluid 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.
+- Do not extend `.prose` to style cards, alerts, app tables, or navigation. Those belong to their components.

package/docs/pages/guides/bootstrap.md

@@ -24,14 +24,14 @@ The layered import is the cleanest way to keep both stylesheets during the
 migration:
 
 ```css
-/* Migration setup — Actual rules sit in @layer actual */
 @import "bootstrap.css";
-@import "actual-css/css/layer";
+@layer actual;
+@import "actual-css/full" layer(actual);
 /* Unlayered project overrides stay on top */
 @import "app.css";
 ```
 
-`actual.layer.css` wraps every Actual rule in a single `@layer actual`, so
+The full import places every Actual rule in a single `actual` layer, so
 unlayered Bootstrap and project CSS keep precedence while the migration runs.
 See [Cascade layer strategy](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/cascade-layer.md) for the
 limitations of the approach.
@@ -131,11 +131,9 @@ A Bootstrap layout such as:
 usually becomes an Actual grid:
 
 ```html
-<div class="container-query">
-  <div class="grid-2">
-    <div>...</div>
-    <div>...</div>
-  </div>
+<div class="grid" style="--grid-min: 18rem">
+  <div>...</div>
+  <div>...</div>
 </div>
 ```
 
@@ -150,8 +148,10 @@ Or use the intrinsic grid when the real requirement is simply “fit as many use
 For asymmetric layouts, express the layout directly:
 
 ```html
-<div class="dashboard-grid grid">
-  ...
+<div class="container-query">
+  <div class="dashboard-grid grid">
+    ...
+  </div>
 </div>
 ```
 
@@ -216,7 +216,7 @@ Typical choices are:
 |--------------------------------------------|--------------------------------------------|
 | flex row that may wrap                     | `.cluster`                                 |
 | vertical flex stack                        | `.stack`                                   |
-| equal columns                              | `.grid-2`, `.grid-3`, `.grid-4`, `.grid-6` |
+| exact structural columns                   | `.grid-2`, `.grid-3`, `.grid-4`, `.grid-6` |
 | intrinsically responsive cards             | `.grid`                                    |
 | row that becomes a column when constrained | `.switcher`                                |
 | sidebar/content layout                     | `.sidebar-layout`                          |

package/docs/pages/guides/integrating-actual-css.md

@@ -0,0 +1,186 @@
+# Building with Actual CSS
+
+Use Actual CSS as a vocabulary before writing application CSS.
+
+The goal is not to eliminate custom CSS. The goal is to keep framework concerns in the framework and application identity in the application.
+
+## 1. Start with the theme
+
+Define palette values once, then derive decorative colors from them.
+
+```css
+[data-theme="brand"] {
+  --primary: hsl(326 100% 60%);
+  --secondary: hsl(187 100% 52%);
+
+  --brand-glow:
+    color-mix(in oklch, var(--primary) 40%, transparent);
+  --brand-line:
+    color-mix(in oklch, var(--secondary) 25%, transparent);
+}
+```
+
+Avoid repeating literal palette colors elsewhere:
+
+```css
+/* Avoid */
+.hero {
+  box-shadow: 0 0 2rem hsl(326 100% 60% / 0.4);
+}
+
+/* Prefer */
+.hero {
+  box-shadow: 0 0 2rem var(--brand-glow);
+}
+```
+
+**Rule:** keep palette literals inside the theme/token layer. Application styles should consume or derive tokens.
+
+## 2. Choose layout by relationship
+
+Do not choose a primitive because of the number of visible columns.
+
+```text
+Repeated items, intrinsic reflow   → .grid
+Known equal peer density           → .grid-N
+Peers that switch together         → .switcher
+Main content + secondary region    → .sidebar-layout
+Media + flexible content           → .media
+Explicit 12-column placement       → .column-layout
+Custom exact track template        → --grid-columns
+```
+
+For example, three panels that must all stack together are a `.switcher`, not automatically a `.grid-3`.
+
+If local CSS mainly makes one layout primitive behave like another, reconsider the primitive first.
+
+## 3. Tune before replacing
+
+Actual primitives expose public hooks for common adjustments.
+
+Prefer:
+
+```css
+.feature-grid {
+  --grid-min: 18rem;
+  --gap: var(--space-50);
+}
+
+.product-card {
+  --card-pad: var(--space-50);
+}
+
+.actions {
+  --cluster-justify: space-between;
+}
+```
+
+over reimplementing their layout:
+
+```css
+/* Avoid when an Actual primitive already owns this behavior */
+.feature-grid {
+  display: grid;
+  grid-template-columns: repeat(...);
+}
+```
+
+**Rule:** tune the recipe before replacing the recipe.
+
+## 4. Reuse the existing vocabulary
+
+Before introducing a generic application class, check whether Actual already expresses the idea.
+
+Examples:
+
+```text
+Small uppercase label     → .overline
+Unstyled list             → .list-reset
+Readable line length      → .measure
+Simple separator/dot      → .dot
+Small alignment change    → existing utility
+```
+
+Application classes should primarily describe product-specific concepts, not recreate generic framework utilities.
+
+## 5. Use structural component markup
+
+When a component exposes meaningful structure, use it.
+
+For cards, prefer semantic regions such as direct `header` and `footer` elements instead of reproducing their behavior inside arbitrary wrappers.
+
+For transient application feedback, use `.status-bar`.
+
+```html
+<div
+  class="status-bar"
+  data-status
+  role="status"
+  aria-live="polite"
+  aria-atomic="true"></div>
+```
+
+A status bar is for messages such as:
+
+```text
+Saved.
+Item added.
+Connection restored.
+```
+
+Persistent state such as metrics, availability, queue size or account information belongs in normal page content.
+
+## 6. Keep application CSS for application identity
+
+Custom CSS is expected for things such as:
+
+* brand marks and decorative treatments;
+* unusual geometry;
+* illustrations and visual effects;
+* bespoke animation;
+* product-specific compositions;
+* product-specific responsive decisions.
+
+These are healthy application styles:
+
+```css
+.brand-mark { ... }
+.neon-glow { ... }
+.ticket-cut { ... }
+.signal-animation { ... }
+```
+
+The target is **not zero custom CSS**.
+
+A better target is:
+
+> No duplicated framework behavior and no palette literals outside the token layer.
+
+## 7. Before adding a CSS rule
+
+Ask, in this order:
+
+1. Is there already a suitable layout primitive?
+2. Is there already a component for this structure?
+3. Can a public hook configure it?
+4. Does an existing utility express the adjustment?
+5. Can the color be derived from a theme token?
+6. Is this genuinely application-specific CSS?
+
+If the answer reaches step 6, write the CSS.
+
+That is the intended integration model:
+
+```text
+Theme
+  ↓
+Choose the relationship
+  ↓
+Use the component
+  ↓
+Tune its hooks
+  ↓
+Use small utilities
+  ↓
+Add application identity
+```

package/docs/pages/guides/introduction.md

@@ -4,8 +4,8 @@
 
 Actual CSS claims a small set of global class names and keeps everything opt-in:
 components define structure, variants change the style, and intents set the
-color. It is designed for new projects and works as-is in existing ones through
-cascade layers, import order, or an optional prefix transform.
+color. It is designed for new projects and can coexist in existing ones through
+cascade layers, import order, or a project-owned build-time prefix transform.
 
 ## CSS-first philosophy
 
@@ -26,44 +26,41 @@ ARIA and native HTML, and per-widget configuration uses self-describing
 
 ## Install
 
-```text
+```sh
 npm install actual-css
 ```
 
 Import the full framework in your CSS:
 
 ```css
-@import "actual-css";
+@import "actual-css/full";
 ```
 
+`actual-css/full` ships every functional family. The bare `actual-css` entrypoint
+is the minimal core (reset, tokens, theme, base, intents, variants, focus,
+print).
+
 Or compose only the pieces you use:
 
 ```css
-@import "actual-css/css/reset";
-@import "actual-css/css/base";
-@import "actual-css/css/tokens";
-@import "actual-css/css/theme";
-@import "actual-css/css/intents";
-@import "actual-css/css/variants";
+@import "actual-css/css";
 @import "actual-css/css/layout";
-@import "actual-css/css/grid";
-@import "actual-css/css/forms";
 @import "actual-css/css/components/button";
 @import "actual-css/css/components/card";
+@import "actual-css/css/forms";
 @import "actual-css/css/components/flyout";
 @import "actual-css/css/utilities";
-/* Keep the focus baseline after components and controls. */
-@import "actual-css/css/focus";
 ```
 
-`focus` is the final interactive baseline in modular builds: older browsers
-retain a visible `:focus` outline, while browsers with `:focus-visible` avoid
-showing it for pointer focus.
+`actual-css/css` is the minimal core. Family manifests (`css/layout`,
+`css/forms`, `css/components`, `css/typography`, `css/effects`,
+`css/utilities`) and their modules map one-to-one to `src/css/`. See the
+[modular import guide](modular-import.md) for the full map.
 
-You can also use the compiled file directly:
+You can also use the compiled full bundle directly:
 
 ```html
-<link rel="stylesheet" href="actual.min.css">
+<link rel="stylesheet" href="actual.full.min.css">
 ```
 
 The package does not maintain separate partial bundles. Modular entrypoints map
@@ -99,7 +96,7 @@ filtering, and input masks. Presentation and behavior are separate layers —
 import the full runtime or any primitive independently to build custom widgets.
 
 ```html
-<script src="actual.js" type="module"></script>
+<script src="actual.full.js" type="module"></script>
 ```
 
 ```js
@@ -142,12 +139,12 @@ internal design documents for contributors.
 
 Actual CSS is built around progressive enhancement.
 
-| Tier | Firefox | Safari | Chromium |
-|---|---|---|---|
-| Degraded | 78+ | 14+ | 88+ |
-| **Minimal** | **98+** | **15.4+** | **99+** |
-| Intermediate | 121+ | 16+ | 106+ |
-| Recommended | 129+ | 17.5+ | 123+ |
+| Tier         | Firefox | Safari    | Chromium |
+|--------------|---------|-----------|----------|
+| Degraded     | 78+     | 14+       | 88+      |
+| **Minimal**  | **98+** | **15.4+** | **99+**  |
+| Intermediate | 121+    | 16+       | 106+     |
+| Recommended  | 129+    | 17.5+     | 123+     |
 
 **Degraded** — semantic HTML and core CSS remain usable. JavaScript
 enhancements are outside the supported contract.