actual-css 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,8 +1,72 @@
-# Changelog
+# Actual CSS 0.4.0 — Changelog
 
-All notable changes will be documented here.
+# 0.4.0 — unreleased
+
+### Added
+
+* Modular CSS architecture with `core`, `layout`, `typography`, `forms`, `components`, `effects`, and `utilities` families, with family and individual-module imports.
+* `actual-css/full` / `actual.full.*` bundles for the complete CSS and JS framework.
+* `.column-layout` with `column-span-1…12` and `column-start-1…12` for explicit opt-in 12-column composition.
+* Intrinsic `.switcher` and `.sidebar-layout` layout recipes, plus explicit layout-selection guidance.
+* `.scroll-target` with `--scroll-target-offset` for hash links and `scrollIntoView()` below sticky UI.
+* Dedicated `typography/lead.css` and `layout/measure.css`; `.measure` exposes `--measure`.
+* Generated and published `reserved-classes.json` for the framework-owned class namespace.
+* Native `accent-color` theming for unstyled platform controls, recomputed across `[data-theme]` islands.
+* “Building with Actual CSS” integration guide covering theme tokens, layout selection, hooks, utilities, and application CSS.
+* Expanded build, architecture, compatibility, browser-layout, package, and generated-output guardrails, including real `npm pack` verification.
+* `brutalist` theme.
+* `--soft-fg-mix` tunes soft foreground ink; at its `100%` default soft text stays the raw intent, and lowering it rebates the ink toward `--text` for palettes whose intents are too light or too saturated to carry text on their own soft surface.
+* Optional `--link` overrides `.prose` link ink when a theme's `--primary` works as an accent but not as inline body text.
+* `check:color-space` guardrail: an intent tinted against a theme-controlled surface or border must interpolate in `oklab`, with an `intentional-oklch` escape hatch.
+* Bundle tool.
+
+### Changed
+
+* The bare `actual-css` entrypoint is now the minimal core; use `actual-css/full` for all CSS families.
+* `actual-css/js` is now the enhancement loader only; use `actual-css/js/full` or `actual.full.js` for the complete pre-registered runtime.
+* `.grid` remains space-driven through `--grid-min`; `.grid-2/3/4/6` now express bounded structural density and degrade responsively.
+* `.container-query` optionally gives `.grid-N` balanced divisor-based subdivisions (`2→1`, `3→1`, `4→2→1`, `6→3→2→1`) instead of being required for responsiveness.
+* `--grid-columns` is the explicit escape hatch for exact custom tracks, including arbitrary structural counts, asymmetric ratios, and mixed intrinsic/flexible tracks; applications own their narrow behavior.
+* `.sidebar-layout` now uses intrinsic flex wrapping instead of a hidden container-query/viewport breakpoint contract.
+* Grid primitives remove the automatic `min-inline-size` floor from their direct children to preserve overflow-safe track sizing.
+* `.card` is now a column flex container; a direct `<footer>` anchors to the bottom when extra space is available, aligning actions across equal-height cards.
+* Focus is a core invariant and no longer depends on loading focus styles after components.
+* Focus rings are derived from each `[data-theme]` island's own `--focus`; preset palettes only keep intentional overrides such as neon.
+* `.prose` now includes sane native description-list (`dt` / `dd`) styling.
+* `.lead` and `.measure` are independent from `.prose`.
+* Utilities distinguish compact framework shortcuts from verbose optional property/value helpers; optional helpers include semantic gap sizes and common sizing, alignment, overflow, spacing, text, border, and surface escape hatches.
+* Preset theme palettes are reference/demo material rather than package API; their bundle is generated for demos/docs instead of `dist/`.
+* `llms.txt` now documents the core/full package split, layout-selection model, class manifest, and application-CSS integration workflow.
+* Biome now covers `src/`, `scripts/`, and `tests/`, and lint runs as part of `build:all`.
+* Use OKLab for intent/context color mixes to keep custom themes stable when surfaces or borders are chromatic.
+* Docs syntax highlighting uses a purpose-built local palette instead of the theme intents, which do not hold contrast as small text under most presets and are too close together on the monochromatic ones to stay distinguishable.
+* CI and browser diagnostics are updated for Bun 1.4 and verify committed `dist/`, `site/`, and `size-report.json` against fresh builds.
+
+### Fixed
+
+* Forced-colors and theme-island focus/state handling.
+* Grid child min-content overflow in narrow tracks.
+* Drawer RTL behavior now follows resolved direction through `:dir(rtl)`.
+* Badge typography uses shared font-size/density tokens instead of private literals.
+* `.sr-only` now combines modern `clip-path` hiding with the legacy `clip` fallback.
+* `dim` and `indigo` shadows use palette-appropriate shadow colors.
+* Vendor pseudo-element handling for color inputs and meters.
+* Tooltip Escape handling and LIFO surface dismissal, including pinned tooltips.
+* OTP, switch, joined-control, floating-field, validation, and native color-control focus/state edge cases.
+* Flyout panel lifecycle cleanup.
+* Prose spacing and component focus regressions.
+* Compatibility checks ignore feature names appearing only in CSS comments.
+* Navbar and status-bar guidance now makes responsive trigger placement and transient-feedback semantics explicit.
+
+### Breaking
+
+* `actual-css` now contains only the core. Replace it with `actual-css/full` when the previous full-framework behavior is required.
+* `actual-css/js` / `actual.js` now contain only the enhancement loader. Use `actual-css/js/full` / `actual.full.js` for the previous complete runtime.
+* `.grid-N` no longer means a fixed N-column grid at every width; it is a responsive structural-density preset, with balanced divisor layouts available through `.container-query`.
+* `.sidebar-layout` no longer depends on `.container-query` or the old fixed breakpoint; direct children now participate in its intrinsic flex sizing contract.
+* `.card` now establishes a column flex formatting context so direct structural footers can anchor to the bottom; code relying on block margin collapsing inside cards should be reviewed.
+* Direct imports of `typography/prose` no longer include `.lead` or `.measure`; import `typography/lead` and `layout/measure` explicitly when needed.
 
-This project follows Keep a Changelog and uses semver, including during 0.x.
 
 ## [0.3.1] - 2026-08-20
 

package/README.md

@@ -2,9 +2,11 @@
 
 Plain CSS component framework for new projects. Semantic classes, shared variants, small tokens, theme hooks, and progressive enhancement.
 
-Actual CSS claims a small set (see `reserved-classes.json`) of global class names. 
+Actual CSS claims a documented set of global class names; the package publishes
+it as [`actual-css/reserved-classes.json`](scripts/reserved-classes.json).
 
-For existing projects: cascade layers, import order, or an optional prefix transform.
+For existing projects: use cascade layers, import order, or your own build-time
+prefix transform.
 
 ## Install
 
@@ -15,38 +17,39 @@ 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 import 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/components/button";
 @import "actual-css/css/components/card";
 @import "actual-css/css/forms";
 @import "actual-css/css/components/flyout";
 @import "actual-css/css/utilities";
-@import "actual-css/css/components/join";
-/* 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/components`, `css/typography`, `css/effects`, `css/utilities`) and
+their modules map one-to-one to `src/css/`; `css/forms` is the exception —
+it points at the native-controls base, with `css/forms/all` exposing the
+complete Forms family. See the
+[modular import guide](docs/pages/guides/modular-import.md) for the full map.
+
+For a flattened custom bundle, import the source entrypoints you want from
+`actual-css/css` and run `npx actual-css bundle src/app.css --out public/app.css --minify`.
+The CLI resolves package subpaths and relative files, then inlines them without
+transpiling modern CSS.
 
-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">
 ```
 
 ## Usage
@@ -96,14 +99,14 @@ Undocumented `is-*` classes are runtime internals.
 
 **Theme hooks** — public tokens for color, radius, shadow, motion, and typography. Reference presets in `src/css/themes/` are demo material, not default CSS or public package entrypoints.
 
-## Optional CSS
-
-```css
-@import "actual-css/css/layer";
-@import "actual-css/css/optional/index";
-```
+## Modular CSS
 
-Browse [`src/css/optional/`](src/css/optional/) for available modules such as custom scrollbars, scroll snap rails, extra utilities, and optional layout helpers.
+The family manifests are the module catalog: `core`, `layout`, `typography`,
+`forms`, `components`, `effects`, and `utilities` under `src/css/`, each with
+an `index.css` manifest and per-module files. Import a manifest to get the
+family, or a single file for one module. See the
+[modular import guide](docs/pages/guides/modular-import.md) for the full map
+of module names to import paths.
 
 ## JavaScript enhancers
 
@@ -114,7 +117,7 @@ Presentation (`class`) and behaviour (`data-enhance`) are separate layers — im
 Use the full module:
 
 ```html
-<script src="actual.js" type="module"></script>
+<script src="actual.full.js" type="module"></script>
 ```
 
 Or import only the enhancers you need:
@@ -127,18 +130,20 @@ import "actual-css/js/mask";
 import "actual-css/js/tooltip";
 ```
 
-The package does not maintain separate partial bundles. Modular entrypoints map to source files, so each project can compose the framework shape it needs. To customize the full runtime, comment the imports you do not want in `src/js/index.js` and rebuild the JavaScript bundle. JavaScript modules are safe to import during server-side rendering; outside a browser, registration is a no-op.
+The package does not maintain separate partial bundles. Modular entrypoints map to source files, so each project can compose the framework shape it needs. To customize the full runtime, comment the imports you do not want in `src/js/full.js` and rebuild the JavaScript bundle. JavaScript modules are safe to import during server-side rendering; outside a browser, registration is a no-op.
 
 For project-specific behavior, use `actual-css/js/enhance` and the small input helpers rather than patching built-in modules. See [Progressive Enhancements](docs/pages/enhancements/overview.md) for custom filters, textarea autogrow, ajax forms, and htmx-like patterns.
 
 ## Distribution
 
-* `dist/actual.css` — readable modern CSS.
-* `dist/actual.min.css` — the same CSS, minified for production.
+* `dist/actual.css` — readable core CSS.
+* `dist/actual.min.css` — the core, minified for production.
+* `dist/actual.full.css` — readable full-bundle CSS (every family).
+* `dist/actual.full.min.css` — the full bundle, minified for production.
 
 Modern syntax such as `light-dark()`, `color-mix()`, `@container`, `:has()`, `100dvh`, and `100vi` is preserved in the distributed files.
 
-Actual CSS does not currently ship a separate compatibility build. It is designed as progressive enhancement: modern features are guarded with `@supports` where needed, while older browsers still receive core layout, forms, and components.
+Actual CSS does not currently ship a separate compatibility build. It is designed as progressive enhancement: modern features are guarded with `@supports` where needed, while older browsers still receive the core styles and the layout, forms, and components.
 
 For more conservative fallbacks, import and compose the source entrypoints directly.