actual-css 0.9.1 → 0.10.0

package/docs/pages/layout/column-layout.md

@@ -1,22 +1,34 @@
 # Column Layout
 
-`.column-layout` is an explicit twelve-column composition canvas. Place regions
-with `.column-span-N` and `.column-start-N`.
+`.column-layout` is an explicit twelve-column composition canvas. Each direct
+child places itself with two numbers: `--column-span` (how many units) and
+`--column-start` (which line it begins on).
 
 Reach for it when the placement of each region **is** the design. If the regions
 are a collection, a known density, peers that switch together, or a main region
 with an aside, one of the other primitives already says so — and says it with
 intrinsic responsive behavior this one does not have.
 
+```css
+.article-main {
+  --column-span: 8;
+}
+
+.article-aside {
+  --column-span: 4;
+}
+```
+
 ```html demo
 <div class="column-layout">
-  <main class="column-span-8 card">Main — 8 columns</main>
-  <aside class="column-span-4 card">Aside — 4 columns</aside>
+  <main class="card" style="--column-span: 8">Main — 8 columns</main>
+  <aside class="card" style="--column-span: 4">Aside — 4 columns</aside>
 </div>
 ```
 
-Neither child names a start line, so grid auto-placement flows the aside into
-columns 9 through 12.
+The hooks are plain CSS: set them from an application class, or inline as a
+shortcut for a composition that never changes. Neither child names a start
+line, so grid auto-placement flows the aside into columns 9 through 12.
 
 ## Spans
 
@@ -24,26 +36,26 @@ A span declares how many of the twelve units a region occupies.
 
 ```html demo
 <div class="column-layout">
-  <div class="column-span-3 card">3</div>
-  <div class="column-span-6 card">6</div>
-  <div class="column-span-3 card">3</div>
+  <div class="card" style="--column-span: 3">3</div>
+  <div class="card" style="--column-span: 6">6</div>
+  <div class="card" style="--column-span: 3">3</div>
 </div>
 ```
 
-A child with no placement class spans the whole canvas, so a heading can share
-the canvas with placed regions without carrying a class.
+A child with no coordinates spans the whole canvas, so a heading can share the
+canvas with placed regions without setting anything.
 
 ```html demo
 <div class="column-layout">
-  <h3>Full canvas — no class needed</h3>
-  <div class="column-span-4 card">4</div>
-  <div class="column-span-4 card">4</div>
-  <div class="column-span-4 card">4</div>
+  <h3>Full canvas — nothing set</h3>
+  <div class="card" style="--column-span: 4">4</div>
+  <div class="card" style="--column-span: 4">4</div>
+  <div class="card" style="--column-span: 4">4</div>
 </div>
 ```
 
-Regions that do not fit wrap to the next row, as any grid does. Two
-`.column-span-8` regions need sixteen units, so the second moves down.
+Regions that do not fit wrap to the next row, as any grid does. Two eight-unit
+regions need sixteen units, so the second moves down.
 
 ## Starts
 
@@ -53,7 +65,7 @@ placement flips with `dir="rtl"` on its own.
 
 ```html demo
 <div class="column-layout">
-  <article class="column-span-10 column-start-2 card">
+  <article class="card" style="--column-start: 2; --column-span: 10">
     Columns 2 through 11
   </article>
 </div>
@@ -63,15 +75,14 @@ Used without a span, a start runs to the end of the canvas.
 
 ```html demo
 <div class="column-layout">
-  <aside class="column-start-9 card">Columns 9 through 12</aside>
+  <aside class="card" style="--column-start: 9">Columns 9 through 12</aside>
 </div>
 ```
 
-Keep a combined placement inside the canvas: `S + N - 1 <= 12`. So
-`.column-start-9 .column-span-4` is valid and `.column-start-10 .column-span-4`
-is not. Exceeding the canvas adds a thirteenth, content-sized column, and every
-other region shrinks with it — the failure is canvas-wide, not local to the
-region you got wrong.
+Keep a combined placement inside the canvas: `start + span - 1 <= 12`. Start 9
+with span 4 is valid; start 10 with span 4 is not. Exceeding the canvas adds a
+thirteenth, content-sized column, and every other region shrinks with it — the
+failure is canvas-wide, not local to the region you got wrong.
 
 ## Cross-section alignment
 
@@ -82,22 +93,23 @@ guarantee. This is the case no other primitive can replace.
 ```html demo
 <div class="stack">
   <div class="column-layout">
-    <h3 class="column-span-8 column-start-3">Feature title</h3>
-    <p class="muted column-span-8 column-start-3">Kicker aligned to the same line.</p>
+    <h3 style="--column-start: 3; --column-span: 8">Feature title</h3>
+    <p class="muted" style="--column-start: 3; --column-span: 8">Kicker aligned to the same line.</p>
   </div>
 
   <div class="column-layout">
-    <p class="column-span-8 column-start-3">
+    <p style="--column-start: 3; --column-span: 8">
       Body copy starts on the same column as the title above and spans the same
       eight columns.
     </p>
-    <aside class="column-span-2 column-start-11 card">Inline note</aside>
+    <aside class="card" style="--column-start: 11; --column-span: 2">Inline note</aside>
   </div>
 </div>
 ```
 
-Both sections name the same `column-start-3` / `column-span-8`, so their content
-shares a left edge and an alignment gutter without a wrapping grid.
+Both sections use start 3 and span 8, so their content shares a left edge and
+an alignment gutter without a wrapping grid. In an application, give that pair
+one class and reuse it.
 
 ## The responsive contract
 
@@ -110,12 +122,13 @@ three regions to become two before stacking. A single framework threshold would
 be wrong more often than right, and a hidden one would have to be undone rather
 than extended.
 
-The simplest recomposition stacks everything:
+Recomposition sets the same two hooks. The simplest one stacks everything:
 
 ```css
 @container (width < 40rem) {
   .profile-layout > * {
-    grid-column: 1 / -1;
+    --column-start: 1;
+    --column-span: 12;
   }
 }
 ```
@@ -124,20 +137,32 @@ A coordinate system is more useful when you keep it through an intermediate
 state:
 
 ```css
+.profile-main {
+  --column-span: 8;
+}
+
+.profile-aside {
+  --column-start: 9;
+  --column-span: 4;
+}
+
 @container (width < 48rem) {
   .profile-main {
-    grid-column: 1 / span 6;
+    --column-start: 1;
+    --column-span: 6;
   }
 
   .profile-aside {
-    grid-column: 7 / span 6;
+    --column-start: 7;
+    --column-span: 6;
   }
 }
 
 @container (width < 32rem) {
   .profile-main,
   .profile-aside {
-    grid-column: 1 / -1;
+    --column-start: 1;
+    --column-span: 12;
   }
 }
 ```
@@ -145,26 +170,40 @@ state:
 ```html
 <div class="container-query">
   <div class="column-layout profile-layout">
-    <main class="column-span-8 profile-main">...</main>
-    <aside class="column-span-4 column-start-9 profile-aside">...</aside>
+    <main class="profile-main">...</main>
+    <aside class="profile-aside">...</aside>
   </div>
 </div>
 ```
 
+Put coordinates you recompose on a class: an inline `style` outranks every
+rule, including your container query.
+
 The `.container-query` wrapper here enables **your** `@container` rules, not a
 hidden framework behavior. Remove your rules and the wrapper stops mattering.
 This is the opposite of a primitive whose responsive contract depends on a
 wrapper someone else has to remember.
 
-Placement classes carry zero specificity, so a single-class rule of your own
-wins without `!important` and without having to undo a framework declaration
-first.
+## Nesting
+
+A child's coordinates place that child only. A nested `.column-layout` uses the
+ones it carries for its own position in the parent, and its children start from
+nothing.
+
+```html
+<div class="column-layout">
+  <section class="column-layout" style="--column-start: 3; --column-span: 8">
+    <h3>Full width of the nested canvas</h3>
+    <div style="--column-span: 6">Half of it</div>
+  </section>
+</div>
+```
 
 ## Narrow containers
 
 Twelve columns is a wide-context tool. With the default `--gap`, a 279px
 container spends 132px on its eleven gaps and leaves about 12px per unit — a
-`.column-span-4` region is 84px wide.
+four-unit region is 84px wide.
 
 The framework guarantees the canvas itself never overflows its container: the
 tracks are `minmax(0, 1fr)` and every child gets `min-inline-size: 0`, so item
@@ -174,10 +213,10 @@ its track. Define a narrow representation where the composition needs one.
 
 ## Scope
 
-The primitive is horizontal only. There are no `.row-span-*`, `.area-*`, or
-`.order-*` classes, and no breakpoint variants such as `md-column-span-6` —
-those would move responsive strategy back into markup. For genuinely
-two-dimensional placement, use CSS Grid directly on your own class:
+The primitive is horizontal only. There are no row, area, or order hooks, and no
+breakpoint variants — those would move responsive strategy back into markup.
+For genuinely two-dimensional placement, use CSS Grid directly on your own
+class:
 
 ```css
 .dashboard-summary {
@@ -186,7 +225,7 @@ two-dimensional placement, use CSS Grid directly on your own class:
 ```
 
 The column count is fixed at twelve and is not configurable. Twelve is what
-makes the vocabulary shared and lets `6 + 6`, `4 + 4 + 4`, `3 + 3 + 3 + 3`,
+makes the coordinates shared and lets `6 + 6`, `4 + 4 + 4`, `3 + 3 + 3 + 3`,
 `8 + 4`, and `2 + 8 + 2` all land on the same canvas. For a track system whose
 sizes carry meaning rather than twelve interchangeable units, use
 `--grid-columns` on `.grid`.
@@ -194,13 +233,12 @@ sizes carry meaning rather than twelve interchangeable units, use
 Unlike `.grid-N`, the track template does not read `--gap`, so the gap
 utilities are exact here at every width.
 
-A region carrying a placement class must generate a box. `display: contents`
-removes that box and promotes its descendants to grid items, which leaves the
-placement with nothing to apply to.
+A placed region must generate a box. `display: contents` removes that box and
+promotes its descendants to grid items, which leaves the placement with nothing
+to apply to.
 
-### Classes
+### Hooks
 
-- `.column-layout` establishes the twelve-column canvas.
-- `.column-span-1` … `.column-span-12` set the width in canvas units.
-- `.column-start-1` … `.column-start-12` set the starting line, running to the
-  canvas end unless a span refines it.
+- `--column-span` — width in canvas units, 1 to 12. Unset, a region runs to the
+  canvas end.
+- `--column-start` — starting line, 1 to 12. Unset, the region is auto-placed.

package/docs/pages/layout/media.md

@@ -25,4 +25,4 @@ Add `.items-center` to align the leading element with short trailing content. Fo
 </div>
 ```
 
-The media object is the underlying pattern of `.blog-author`, `.blog-comment`, and similar compositions in templates. Components can adopt it instead of repeating the grid rule. The [Workspaces example](../examples/overview.md) shows the card pattern: `card > header` with `.media` plus `hgroup`, and row actions in the header — never a third `.media` child.
+The media object is the underlying pattern of `.blog-author`, `.blog-comment`, and similar compositions in templates. Components can adopt it instead of repeating the grid rule. The [Workspaces example](../examples/overview.md#page-shapes) shows the card pattern: `card > header` with `.media` plus `hgroup`, and row actions in the header — never a third `.media` child.

package/docs/pages/layout/overview.md

@@ -57,4 +57,4 @@ Prefer a parent `gap` for relationships between peers instead of encoding siblin
 
 Before adding a divider or other separating chrome, consider whether additional spacing already expresses the boundary clearly.
 
-Density changes the amount of space available, not the relationships that space communicates. When a composition contains local, group, and section rhythms, preserve their relative hierarchy with nested or local `--gap` values rather than relying on one inherited gap at every level. See [Stack](./stack.md) for the nesting and density mechanics.
+Density changes the amount of space available, not the relationships that space communicates. When a composition contains local, group, and section rhythms, preserve their relative hierarchy with nested or local `--gap` values rather than relying on one inherited gap at every level. See [Choosing a density](./stack.md#choosing-a-density) for the nesting and density mechanics.

package/docs/pages/utilities/overview.md

@@ -37,7 +37,7 @@ list the two layers as separate tables. Every other utility page is base only.
 - No color scales such as `.text-primary` or `.bg-success` — intent colors belong to components and state.
 - No breakpoint utility variants — use container queries or layout primitives.
 - No utility variants for hover, focus, dark mode, or arbitrary selectors — use component states.
-- No full spacing scale with every step and direction — the 17 spacing helpers across the core and extra utilities cover the most common escape hatches.
+- No full spacing scale with every step and direction — the spacing helpers in base and extra cover the common escape hatches and read the inherited rhythm.
 
 ## Display escape hatches
 

package/docs/pages/utilities/sizing-wrapping.md

@@ -8,6 +8,7 @@ Small layout corrections for controls, labels, and compact rails.
 | ------------------------- | ------- | ----------------------------------------- |
 | `.fit`                    | Utility | Shrinks an element to its content width.  |
 | `.text-nowrap`            | Utility | Keeps text on one line.                   |
+| `.text-wrap`              | Utility | Restores wrapping under a nowrap parent.  |
 | `.truncate`               | Utility | Ellipsizes overflowing single-line text.  |
 | `.scroller`               | Layout  | Theme-aware scrollbar density and colour. |
 | `.scroller.stable-gutter` | Variant | Reserves inline-axis scrollbar gutter.    |
@@ -22,9 +23,10 @@ Use `.fit` when a control or element should shrink to its content instead of fil
 </select>
 ```
 
-Use `.text-nowrap` to keep text on one line inside a cell or label. To stop a
-layout primitive from wrapping — for example to force a `.cluster` onto a single
-row — set `--cluster-wrap: nowrap`.
+Use `.text-nowrap` to keep text on one line inside a cell or label, and
+`.text-wrap` to let a long label wrap inside a component that keeps its text on
+one line (`.badge`). To stop a layout primitive from wrapping — for example to
+force a `.cluster` onto a single row — set `--cluster-wrap: nowrap`.
 
 ```html demo
 <div class="cluster compact" style="--cluster-wrap: nowrap;">

package/llms.txt

@@ -12,12 +12,13 @@ Actual CSS uses a small public grammar: `.component [intent] [variant] [size] [m
 
 `package.json#exports` is the canonical package surface.
 
-- `actual-css` — the minimal core: tokens, theme contract, reset, base elements, and universal variants. Components and layout primitives are NOT included.
-- `actual-css/full` — the complete framework: core plus every component, form, layout, typography, effect, and utility family.
+- `actual-css/css` — the source core, the recommended starting point: tokens, theme contract, reset, base elements, and universal variants. Components and layout primitives are NOT included; add them with `actual-css/css/<family>` or `actual-css/css/<family>/<module>`.
+- `actual-css` / `actual-css/full` — the complete compiled framework, for zero-config and CDN use: core plus every component, form, layout, typography, effect, and utility family.
 - `actual-css/js` — the enhancement-loader entry only: it watches `data-enhance-modules` manifest blocks and imports the declared enhancers on demand.
 - `actual-css/js/full` — the complete runtime with all built-in enhancers pre-registered.
 - `actual-css/reserved-classes.json` — machine-readable list of the framework-owned class namespace. Use it to check whether a class belongs to Actual CSS and to validate claimed framework classes; application-specific classes are expected to exist outside this manifest.
 - `actual-css/components.json` — machine-readable component index, derived from the sources (CSS headers, selectors, package exports, `src/js`) by `scripts/build-catalog.js` and verified by `check:catalog`. Gives each component its import paths, owned classes, hooks, states, and registered enhancement tokens — enough to know what exists and where to read more, not a replacement for `docs/pages/components/*.md`.
+- [Starter agent skill](skills/actual-css/SKILL.md) — a copyable skill for building with Actual CSS (vocabulary, hooks, layouts, enhancements); consuming projects extend it with a local `PROJECT.md`.
 - Individual families and modules are importable separately (`actual-css/css/components`, `actual-css/css/layout/grid`, `actual-css/js/dialog`, …); see [README](README.md) and [Modular imports](docs/pages/guides/modular-import.md).
 
 Forms are the one family with two aggregate entrypoints:
@@ -28,13 +29,32 @@ The composition guides in [README](README.md) and [Progressive Enhancements](doc
 show supported CSS modules and individual enhancer imports without duplicating
 the full export list here.
 
-Presentation (`class`) and behavior (`data-enhance`) are separate layers.
+Presentation (`class`) and behavior are separate layers. `data-enhance` takes
+four tokens only — `tabs`, `flyout`, `scrollspy`, `validation`; leaf behaviors
+use their own attribute (`data-tooltip`, `data-mask`, `data-filter`,
+`data-context-menu`) and `<dialog>` needs none. See
+[when a token, when a data-*](docs/design-notes/enhancement-contract.md).
+
 Behaviour primitives are independently importable for building custom widgets,
 including `enhance`, `surface`, `floating`, `focus-group`, `keys`, `input`,
 `command`, `menu`, `focus`, `escape`, and `events`. See
-[enhancement contract](docs/design-notes/enhancement-contract.md) and
 [widget primitives](docs/design-notes/widget-primitives.md).
 
+## What the vocabulary does not have
+
+- No compound intent classes (`.btn-primary`, `.badge-success`): intents and
+  variants are separate classes on the component (`.btn primary outline`).
+- No breakpoint or state prefixes (`md:stack`, `hover:…`) and no arbitrary
+  values: layout primitives and container queries own responsiveness.
+- No spacing scale (`mt-4`, `p-2`): spacing comes from `--gap`, density
+  (`.compact`, `.spacious`), and component hooks.
+- `is-*` classes are written by the runtime, not by authors.
+- Modifiers such as `.ghost`, `.link`, `.flush`, `.raised` only mean something
+  on their component; alone they are inert.
+
+See [naming](docs/design-notes/naming.md) and
+[utilities non-goals](docs/pages/utilities/overview.md#non-goals).
+
 ## Choosing a page shell
 
 Before choosing a content layout, choose the page shell:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actual-css",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
   "type": "module",
   "packageManager": "bun@1.4.2",
@@ -26,7 +26,7 @@
     "progressive-enhancement"
   ],
   "exports": {
-    ".": "./dist/actual.min.css",
+    ".": "./dist/actual.full.min.css",
     "./full": "./dist/actual.full.min.css",
     "./css": "./src/css/actual.css",
     "./css/components": "./src/css/components/index.css",
@@ -80,10 +80,9 @@
   "bin": {
     "actual-css": "./src/cli/actual-css.js"
   },
-  "main": "./dist/actual.js",
-  "style": "./dist/actual.min.css",
-  "unpkg": "./dist/actual.min.css",
-  "jsdelivr": "./dist/actual.min.css",
+  "style": "./dist/actual.full.min.css",
+  "unpkg": "./dist/actual.full.min.css",
+  "jsdelivr": "./dist/actual.full.min.css",
   "sideEffects": true,
   "files": [
     "dist",
@@ -101,6 +100,7 @@
     "reserved-classes.json",
     "components.json",
     "docs",
+    "skills",
     "CHANGELOG.md",
     "llms.txt",
     "LICENSE",
@@ -144,6 +144,7 @@
     "probe": "bun scripts/probe.js",
     "serve": "bun scripts/serve.js",
     "check:sync": "bun scripts/check-sync.js",
+    "release:notes": "bun scripts/release-notes.js",
     "test": "bun test",
     "test:changed": "bun test --changed=master",
     "build:all": "bun run lint && bun run build:dist && bun run build:js && bun run build:size && bun run format:docs && bun run build:docs && bun run check:docs && bun run check:doc-classes && bun run check:compat && bun run check:css-api && bun run check:color-space && bun run check:architecture && bun run check:enhance && bun run generate:reserved && bun run check:reserved && bun run generate:catalog && bun run check:catalog && bun run check:sync && bun run check:links && bun run check:templates && bun run check:markup && bun run test",

package/reserved-classes.json

@@ -4,7 +4,6 @@
   "admonition",
   "alert",
   "alert-body",
-  "alert-dismiss",
   "alert-icon",
   "alert-title",
   "align-self-center",
@@ -43,43 +42,20 @@
   "chat-header",
   "chat-start",
   "check",
+  "chip",
   "choice",
   "choice-card",
   "circle",
+  "close",
   "cluster",
   "color",
   "column-gap-context",
   "column-layout",
-  "column-span-1",
-  "column-span-10",
-  "column-span-11",
-  "column-span-12",
-  "column-span-2",
-  "column-span-3",
-  "column-span-4",
-  "column-span-5",
-  "column-span-6",
-  "column-span-7",
-  "column-span-8",
-  "column-span-9",
-  "column-start-1",
-  "column-start-10",
-  "column-start-11",
-  "column-start-12",
-  "column-start-2",
-  "column-start-3",
-  "column-start-4",
-  "column-start-5",
-  "column-start-6",
-  "column-start-7",
-  "column-start-8",
-  "column-start-9",
   "compact",
   "container-query",
   "cursor-pointer",
   "danger",
   "data-list",
-  "dialog-close",
   "dialog-confirmation",
   "dialog-icon",
   "display-block",
@@ -91,7 +67,6 @@
   "display-none",
   "dot",
   "drawer",
-  "drawer-close",
   "fab",
   "fab-action",
   "fab-actions",
@@ -133,7 +108,6 @@
   "input",
   "input-icon",
   "intent-color",
-  "inverted",
   "is-open",
   "is-static",
   "items-center",
@@ -239,6 +213,7 @@
   "sr-only",
   "stable-gutter",
   "stack",
+  "stacked",
   "start",
   "status-bar",
   "step-complete",
@@ -270,6 +245,7 @@
   "text-start",
   "text-title",
   "text-uppercase",
+  "text-wrap",
   "textarea",
   "tooltip",
   "topbar",
@@ -278,6 +254,5 @@
   "user-select-none",
   "visibility-hidden",
   "warning",
-  "was-validated",
-  "white-space-normal"
+  "was-validated"
 ]

package/skills/actual-css/PROJECT.md.example

@@ -0,0 +1,65 @@
+# Project-specific Actual CSS usage
+
+Copy this file to `PROJECT.md` beside `SKILL.md` and keep only decisions that are true for this application.
+
+This file narrows **how the application uses Actual CSS**. It does not redefine Actual CSS API.
+
+## Imports
+
+CSS loaded by this project:
+
+```text
+- TODO
+```
+
+JavaScript enhancers loaded by this project:
+
+```text
+- TODO
+```
+
+## Theme
+
+Theme root / selector:
+
+```text
+TODO
+```
+
+Application-owned brand tokens or theme conventions:
+
+```text
+- TODO
+```
+
+## Page shell and layout conventions
+
+```text
+- TODO
+```
+
+## Existing application wrappers
+
+List server-side/template components that agents should reuse before writing raw markup.
+
+```text
+- TODO
+```
+
+## Application CSS conventions
+
+```text
+- TODO
+```
+
+## Browser policy
+
+If stricter than Actual CSS itself:
+
+```text
+TODO
+```
+
+## Local decisions
+
+Add only stable, reusable decisions that materially change implementation choices.

package/skills/actual-css/README.md

@@ -0,0 +1,64 @@
+# Actual CSS starter skill
+
+A small, copyable agent skill for **building with Actual CSS**.
+
+It is intentionally not a contributor guide for the Actual CSS repository. Repository development workflow belongs in `AGENTS.md`; this skill teaches consumers how to use the framework without inventing API or duplicating framework behavior.
+
+## Contents
+
+```text
+actual-css/
+├── SKILL.md
+├── README.md
+├── PROJECT.md.example
+├── references/
+│   ├── accessibility.md
+│   ├── api-and-vocabulary.md
+│   ├── enhancements.md
+│   ├── forms.md
+│   ├── layout-and-theming.md
+│   └── review-checklist.md
+└── scripts/
+    └── inspect-actual-css.mjs
+```
+
+## Recommended distribution
+
+Actual CSS can ship this directory as a starter/reference skill. Consuming projects copy it into the location their coding agent uses for skills.
+
+The copied skill should remain mostly framework-generic. Application-specific choices belong in a local `PROJECT.md` created from `PROJECT.md.example`.
+
+This gives a clean split:
+
+```text
+Actual CSS package/docs/manifests
+        -> what exists and how the framework works
+
+SKILL.md + references
+        -> how an agent should build with it
+
+PROJECT.md
+        -> how this application chooses to use it
+```
+
+## Why the skill does not bundle the catalog
+
+`components.json`, `reserved-classes.json`, package exports, CSS source, and JS source are intentionally read from the installed Actual CSS version. Copying those files into the skill would create a second, quickly stale API snapshot.
+
+The bundled inspector makes common lookups cheap:
+
+```sh
+node /path/to/actual-css/scripts/inspect-actual-css.mjs --source
+node /path/to/actual-css/scripts/inspect-actual-css.mjs button
+node /path/to/actual-css/scripts/inspect-actual-css.mjs --class compact
+node /path/to/actual-css/scripts/inspect-actual-css.mjs --exports
+node /path/to/actual-css/scripts/inspect-actual-css.mjs --enhancements
+```
+
+Set `ACTUAL_CSS_ROOT=/path/to/actual-css` to inspect a specific checkout or installed package.
+
+## Customize, do not fork the framework contract
+
+Good project customizations include which modules are loaded, local theme tokens, server/template wrappers, page-shell conventions, browser policy, and application class naming.
+
+Do not use the project layer to redefine Actual CSS class meanings, internal runtime state, package exports, or undocumented hooks.