actual-css 0.1.0 → 0.3.0

package/dist/optional.min.css

@@ -0,0 +1 @@
+.otp { --otp-cell-size: var(--control-size); --otp-gap: var(--space-10); --otp-font-size: 1.5rem; --otp-cell-border: var(--border); --otp-cell-bg: var(--surface); position: relative; display: inline-grid; grid-auto-flow: column; grid-auto-columns: var(--otp-cell-size); inline-size: fit-content; max-inline-size: 100%; gap: var(--otp-gap); border-radius: var(--radius); direction: ltr; } .otp > span { inline-size: var(--otp-cell-size); block-size: var(--otp-cell-size); border: var(--border-width) solid var(--otp-cell-border); border-radius: var(--radius); background: var(--otp-cell-bg); transition: border-color var(--duration), background-color var(--duration), box-shadow var(--duration); } .otp > input { position: absolute; z-index: 1; inset: 0; inline-size: 100%; block-size: 100%; margin: 0; padding: 0 calc((var(--otp-cell-size) - 1ch) / 2); border: 0; outline: 2px solid transparent; box-shadow: none; background: transparent; color: var(--text); font-family: var(--font-mono); font-size: var(--otp-font-size); font-variant-numeric: tabular-nums; line-height: var(--otp-cell-size); letter-spacing: calc(var(--otp-cell-size) + var(--otp-gap) - 1ch); text-align: start; appearance: none; } .otp:focus-within { box-shadow: var(--focus-ring-shadow); } .otp > input:focus ~ span { --otp-cell-border: var(--focus); } .otp > input[aria-invalid="true"] ~ span, .needs-validation.was-validated .otp > input:invalid ~ span { --otp-cell-border: var(--danger); } @supports selector(:user-invalid) { .needs-validation .otp > input:user-invalid ~ span { --otp-cell-border: var(--danger); } } .otp > input:disabled { color: var(--state-disabled); cursor: not-allowed; } .otp > input:disabled ~ span { --otp-cell-bg: var(--surface-subtle); opacity: var(--disabled-opacity); } @media (forced-colors: active) { .otp:focus-within { outline: var(--focus-outline); outline-offset: var(--focus-outline-offset); box-shadow: none; } .otp > input:focus ~ span { --otp-cell-border: Highlight; } .otp > input[aria-invalid="true"] ~ span, .needs-validation.was-validated .otp > input:invalid ~ span { --otp-cell-border: Mark; } } .chat { --chat-gap: var(--space-30); --chat-max-size: min(85%, 40rem); display: grid; grid-auto-rows: min-content; column-gap: var(--chat-gap); } .chat-start { grid-template-columns: auto minmax(0, 1fr); justify-items: start; } .chat-end { grid-template-columns: minmax(0, 1fr) auto; justify-items: end; } .chat-avatar { grid-row: 1 / span 3; align-self: end; } .chat-start > .chat-avatar { grid-column: 1; } .chat-end > .chat-avatar { grid-column: 2; } .chat-header, .chat-footer { display: flex; gap: var(--space-10); color: var(--text-muted); font-size: var(--font-size-xs); } .chat-start > :is(.chat-header, .chat-bubble, .chat-footer) { grid-column: 2; } .chat-end > :is(.chat-header, .chat-bubble, .chat-footer) { grid-column: 1; } :where(.chat-bubble) { --intent: initial; --intent-fg: initial; --ui-bg: initial; --ui-fg: initial; --ui-border: initial; } .chat-bubble { --chat-bubble-bg: var(--ui-bg, var(--intent, var(--surface-subtle))); --chat-bubble-fg: var(--ui-fg, var(--intent-fg, var(--text))); --chat-bubble-border: var(--ui-border, transparent); inline-size: fit-content; max-inline-size: var(--chat-max-size); padding: var(--space-20) var(--space-30); border: var(--border-width) solid var(--chat-bubble-border); border-radius: var(--radius-lg); background: var(--chat-bubble-bg); color: var(--chat-bubble-fg); overflow-wrap: anywhere; } .chat-start > .chat-bubble { border-end-start-radius: var(--radius-sm); } .chat-end > .chat-bubble { border-end-end-radius: var(--radius-sm); } @supports selector(:has(*)) { .chat:not(:has(> .chat-avatar)) { column-gap: 0; } } @media (forced-colors: active) { .chat-bubble { border-color: CanvasText; } } @property --aura-angle { syntax: "<angle>"; inherits: false; initial-value: 0deg; } :where(.aura) { --intent: initial; --intent-fg: initial; } .aura { --aura-color: var(--intent, var(--primary)); --aura-width: 2px; --aura-blur: 0.75rem; --aura-radius: var(--radius-lg); --aura-duration: 6s; position: relative; isolation: isolate; display: inline-grid; padding: var(--aura-width); border-radius: calc(var(--aura-radius) + var(--aura-width)); background: var(--aura-color); background: conic-gradient(from var(--aura-angle), transparent 0 65%, var(--aura-color)); } .aura::before { position: absolute; z-index: -1; inset: 0; border-radius: inherit; background: inherit; filter: blur(var(--aura-blur)); opacity: 0.45; pointer-events: none; content: ""; } .aura > * { position: relative; } .aura-glow { background: var(--aura-color); } @media (prefers-reduced-motion: no-preference) { .aura:not(.aura-glow) { animation: aura-rotate var(--aura-duration) linear infinite; } } @keyframes aura-rotate { to { --aura-angle: 360deg; } } @supports selector(:has(*)) { .aura:has(> .btn) { --aura-radius: var(--radius); } .aura:has(> :is(.card, .alert)) { --aura-radius: var(--radius-lg); } .aura:has(> .badge) { --aura-radius: var(--radius-full); } } @media (forced-colors: active) { .aura { background: CanvasText; } .aura::before { display: none; } } .fab { --fab-offset: var(--space-40); --fab-gap: var(--space-20); position: fixed; z-index: var(--z-menu); inset-block-end: max(var(--fab-offset), env(safe-area-inset-bottom)); inset-inline-end: var(--fab-offset); } .fab > summary { list-style: none; cursor: pointer; } .fab > summary::-webkit-details-marker { display: none; } .fab > summary > [aria-hidden="true"]:only-child { display: inline-block; transition: transform var(--duration); } .fab-actions { position: absolute; inset-inline-end: 0; inset-block-end: calc(100% + var(--fab-gap)); display: flex; flex-direction: column; align-items: flex-end; gap: var(--fab-gap); opacity: 0; visibility: hidden; pointer-events: none; transform: translateY(var(--space-10)); transition: opacity var(--duration), transform var(--duration), visibility 0s linear var(--duration); } .fab-action { display: flex; align-items: center; justify-content: flex-end; gap: var(--fab-gap); inline-size: max-content; max-inline-size: calc(var(--viewport-inline) - var(--fab-offset) - var(--fab-offset)); } .fab-label { flex: 0 1 auto; overflow: hidden; max-inline-size: 16rem; padding: var(--space-10) var(--space-20); border-radius: var(--radius); background: var(--surface); color: var(--text); box-shadow: var(--shadow); font-size: var(--font-size-xs); font-weight: var(--font-weight-medium); line-height: var(--line-height-tight); text-overflow: ellipsis; white-space: nowrap; } .fab[open] > .fab-actions { opacity: 1; visibility: visible; pointer-events: auto; transform: translateY(0); transition-delay: 0s; } .fab[open] > summary > [aria-hidden="true"]:only-child { transform: rotate(45deg); } @media (forced-colors: active) { .fab-label { border: var(--border-width) solid CanvasText; box-shadow: none; } } @media print { .fab { display: none; } } .floating-field { --floating-pad-block-start: calc(var(--control-size) / 2 + var(--space-20)); position: relative; display: grid; } .floating-field > :is(.input, .textarea, .select) { padding-block-start: var(--floating-pad-block-start); padding-block-end: var(--space-10); } .floating-field > .field-label { position: absolute; inset-block-start: 50%; inset-inline-start: calc(var(--space-30) + var(--border-width)); transform: translateY(-50%); color: var(--text-muted); font-size: var(--control-font-size); font-weight: var(--font-weight); pointer-events: none; transition: inset-block-start var(--duration), transform var(--duration), font-size var(--duration), color var(--duration); } .floating-field > .textarea + .field-label { inset-block-start: var(--floating-pad-block-start); transform: none; } .floating-field > :is(.input, .textarea):is(:focus, :autofill, :not(:placeholder-shown)) + .field-label { inset-block-start: var(--space-10); transform: none; font-size: var(--font-size-xs); } .floating-field > :is( .select, .input[type="date"], .input[type="time"], .input[type="datetime-local"], .input[type="month"], .input[type="week"] ) + .field-label { inset-block-start: var(--space-10); transform: none; font-size: var(--font-size-xs); } .scroller { --scroller-size: 0.625rem; --scroller-padding: 0.125rem; --scroller-track: transparent; --scroller-thumb: var(--border); --scroller-thumb-hover: var(--text-muted); scrollbar-color: var(--scroller-thumb) var(--scroller-track); scrollbar-width: thin; } .scroller.stable-gutter { scrollbar-gutter: stable; } .scroller::-webkit-scrollbar { width: var(--scroller-size); height: var(--scroller-size); } .scroller::-webkit-scrollbar-track { background: var(--scroller-track); } .scroller::-webkit-scrollbar-thumb { border: var(--scroller-padding) solid transparent; border-radius: var(--radius-full); background: var(--scroller-thumb); background-clip: content-box; } .scroller::-webkit-scrollbar-thumb:hover { background: var(--scroller-thumb-hover); background-clip: content-box; } .scroller::-webkit-scrollbar-corner { background: var(--scroller-track); } @supports (color: color-mix(in oklch, red, white)) { .scroller { --scroller-thumb: color-mix(in oklch, var(--text-muted), transparent 55%); --scroller-thumb-hover: color-mix(in oklch, var(--text-muted), transparent 30%); } } .scroll-snap { --scroll-snap-gap: var(--gap); --scroll-snap-align: start; --scroll-snap-item-size: auto; display: flex; gap: var(--scroll-snap-gap); overflow-x: auto; } .scroll-snap > * { flex: 0 0 var(--scroll-snap-item-size); } @supports (scroll-snap-type: x mandatory) { .scroll-snap { overscroll-behavior-inline: contain; scroll-padding-inline: var(--scroll-snap-padding, var(--scroll-snap-gap)); scroll-snap-type: x mandatory; } .scroll-snap > * { scroll-snap-align: var(--scroll-snap-align); } .scroll-snap[data-snap="center"] { --scroll-snap-align: center; } } @supports (scroll-snap-type: inline mandatory) { .scroll-snap { scroll-snap-type: inline mandatory; } } .scroll-snap[data-scrollbar="hidden"] { scrollbar-width: none; } .scroll-snap[data-scrollbar="hidden"]::-webkit-scrollbar { display: none; } :root { --fluid-display: clamp(2.75rem, calc(2.25rem + 2.222vw), 4.25rem); --fluid-title: clamp(2rem, calc(1.75rem + 1.111vw), 2.75rem); --fluid-lead: clamp(1.125rem, calc(1.0833rem + 0.185vw), 1.25rem); } @supports (inline-size: 100vi) { :root { --fluid-display: clamp(2.75rem, calc(2.25rem + 2.222vi), 4.25rem); --fluid-title: clamp(2rem, calc(1.75rem + 1.111vi), 2.75rem); --fluid-lead: clamp(1.125rem, calc(1.0833rem + 0.185vi), 1.25rem); } } .text-display { font-size: var(--fluid-display); line-height: var(--line-height-tight); text-wrap: balance; } .text-title { font-size: var(--fluid-title); line-height: var(--line-height-tight); text-wrap: balance; } .text-lead { font-size: var(--fluid-lead); line-height: var(--line-height-relaxed); } .display-block { display: block; } .display-inline { display: inline; } .display-inline-block { display: inline-block; } .display-flex { display: flex; } .display-inline-flex { display: inline-flex; } .display-grid { display: grid; } .position-relative { position: relative; } .position-absolute { position: absolute; } .position-fixed { position: fixed; } .position-sticky { position: sticky; } .inline-size-full { inline-size: 100%; } .block-size-full { block-size: 100%; } .min-inline-size-0 { min-inline-size: 0; } .min-block-size-0 { min-block-size: 0; } .max-inline-size-none { max-inline-size: none; } .flex-wrap { flex-wrap: wrap; } .flex-nowrap { flex-wrap: nowrap; } .gap-sm { gap: var(--space-20); } .gap-md { gap: var(--space-40); } .gap-lg { gap: var(--space-50); } .justify-content-start { --cluster-justify: flex-start; justify-content: flex-start; } .justify-content-center { --cluster-justify: center; justify-content: center; } .justify-content-end { --cluster-justify: flex-end; justify-content: flex-end; } .justify-content-space-between { --cluster-justify: space-between; justify-content: space-between; } .align-self-start { align-self: start; } .align-self-center { align-self: center; } .align-self-end { align-self: end; } .padding-context { padding: var(--density-space); } .margin-inline-auto { margin-inline: auto; } .margin-inline-start-auto { margin-inline-start: auto; } .margin-inline-end-auto { margin-inline-end: auto; } .margin-block-start-auto { margin-block-start: auto; } .margin-block-end-auto { margin-block-end: auto; } .gap-context { gap: var(--gap); } .row-gap-context { row-gap: var(--gap); } .column-gap-context { column-gap: var(--gap); } .overflow-hidden { overflow: hidden; } .overflow-clip { overflow: clip; } .overflow-x-auto { overflow-x: auto; } .overflow-y-auto { overflow-y: auto; } .white-space-normal { white-space: normal; } .text-break { overflow-wrap: break-word; } .text-uppercase { text-transform: uppercase; } .text-lowercase { text-transform: lowercase; } .text-capitalize { text-transform: capitalize; } .font-weight-normal { font-weight: var(--font-weight); } .font-weight-medium { font-weight: var(--font-weight-medium); } .font-weight-strong { font-weight: var(--font-weight-strong); } .font-weight-bold { font-weight: var(--font-weight-bold); } .radius-sm-context { border-radius: var(--radius-sm); } .radius-context { border-radius: var(--radius); } .radius-lg-context { border-radius: var(--radius-lg); } .border-context { border: var(--border-width) solid var(--border); } .border-block-start { border-block-start: var(--border-width) solid var(--border); } .border-block-end { border-block-end: var(--border-width) solid var(--border); } .border-inline-start { border-inline-start: var(--border-width) solid var(--border); } .border-inline-end { border-inline-end: var(--border-width) solid var(--border); } .background-surface { background: var(--surface); color: var(--text); } .background-raised { background: var(--surface-raised); color: var(--text); } .background-subtle { background: var(--surface-subtle); color: var(--text); } .shadow-context { box-shadow: var(--shadow); } .shadow-popout-context { box-shadow: var(--shadow-popout); } .cursor-pointer { cursor: pointer; } .pointer-events-none { pointer-events: none; } .user-select-none { -webkit-user-select: none; user-select: none; } .display-none { display: none; } .visibility-hidden { visibility: hidden; } .switcher { display: flex; flex-wrap: wrap; gap: var(--gap); } .switcher > * { flex-basis: calc((var(--switcher-threshold, 40rem) - 100%) * 999); flex-grow: 1; min-inline-size: 0; } .topbar { position: sticky; inset-block-start: 0; z-index: var(--z-sticky); isolation: isolate; display: flex; align-items: center; gap: var(--gap); padding-block: var(--space-30); padding-inline: var(--space-40); border-block-end: var(--border-width) solid var(--border); background: var(--surface); } @supports ((backdrop-filter: blur(1rem)) or (-webkit-backdrop-filter: blur(1rem))) and (background: color-mix(in oklch, red 50%, transparent)) { .topbar { background: color-mix(in oklch, var(--surface) 88%, transparent); backdrop-filter: blur(0.75rem); -webkit-backdrop-filter: blur(0.75rem); } }

package/docs/design-notes/browser-support.md

@@ -1,21 +1,94 @@
 # Browser support strategy
 
+## Actual tiers
+
+The compatibility contract is expressed in browser versions, not ECMAScript
+edition labels. Each tier is defined by what it guarantees.
+
+| Actual tier  | Firefox |    Safari | Chromium | Contract                                       |
+| ------------ | ------: | --------: | -------: | ---------------------------------------------- |
+| Degraded     |     78+ |       14+ |      88+ | Semantic HTML + core CSS; JS unsupported       |
+| **Minimal**  | **98+** | **15.4+** |  **99+** | Full supported Actual experience, including JS |
+| Intermediate |    121+ |       16+ |     106+ | More modern platform enhancements              |
+| Recommended  |    129+ |     17.5+ |     123+ | Target experience                              |
+
+- **Degraded** keeps useful HTML and CSS on older browsers. JavaScript is
+  explicitly outside the supported contract there.
+- **Minimal** is the JavaScript baseline: the complete Actual experience,
+  including the runtime, is supported from this tier up. The runtime assumes
+  modern platform primitives available across the whole tier and ships no
+  legacy compatibility layer or polyfill.
+
+Degraded browsers may still run some JavaScript successfully, but that
+behavior is not tested, documented as supported, or preserved when the
+runtime evolves.
+
+## JavaScript philosophy
+
+> The Degraded tier exists primarily to preserve useful HTML and CSS on older
+> browsers. It does not constrain the JavaScript runtime.
+
+> Minimal is the JavaScript baseline.
+
+Modern JavaScript supported by all Minimal browsers may be used directly.
+Actual does not transpile, polyfill, or wrap platform APIs solely to extend
+JavaScript support below Minimal.
+
+### Abortable listeners
+
+Abortable event listeners predate the Minimal floor: Firefox 86, Chrome 88,
+and WebKit (early 2021) all shipped the capability before the Safari 15.4
+threshold. ([Bugzilla][1], [Chrome][2], [WebKit][3])
+
+> `addEventListener({ signal })` is a baseline runtime primitive.
+
+Do not introduce compatibility wrappers (`listen`, `on`,
+`addAbortableListener`, `supportsSignal`) solely to reproduce a capability
+that is already native throughout Minimal.
+
+### Native `<dialog>`
+
+The Minimal floor sits at the point where Safari 15.4 and Firefox 98 ship
+native `<dialog>`, and Chromium already had it. ([WebKit][4])
+
+> Native dialog is assumed by the runtime; no dialog polyfill is shipped.
+
+### Future-direction invariants
+
+1. **Minimal drives JavaScript compatibility; Degraded does not.**
+2. **Prefer native platform APIs over compatibility abstractions when they are
+   available throughout Minimal.**
+3. **Browser versions are the compatibility contract, not ECMAScript edition
+   labels.**
+4. **Raise Minimal only when doing so buys a concrete simplification, removal
+   of a fallback, or materially better implementation.**
+
+> Do not preserve an older JavaScript idiom solely because it happens to run
+> in the Degraded tier. If the clearer native alternative is supported
+> throughout Minimal, prefer it.
+
+---
+
 ## Philosophy
 
 Works everywhere, works best on modern browsers. Wide browser support (even older browsers, not IE 11).
 
-- No compile or build step (just CSS).
+- No consumer build step is required (just CSS).
 - No post-processing — use only necessary browser-specific prefixes and engine hooks.
 - CSS nesting is not used — code must be findable in the inspector. Rules are organized as if nesting were used, grouped together without nesting syntax. Exception: see [CSS nesting inside @supports](#css-nesting-inside-supports).
 
-## Baseline
+## Platform feature baseline
+
+The tiers above are Actual's own contract. The table below tracks the Web
+Platform Baseline of the individual CSS features the framework uses; it is a
+different notion from an Actual tier.
 
 | Feature area     | Baseline    | Progressive enhancement       |
 |------------------|-------------|-------------------------------|
 | Layout (flex, grid, position) | Baseline 2023 | —                  |
 | CSS custom properties         | Baseline 2023 | —                  |
 | `:has()`                      | Baseline 2023 | —                  |
-| `<dialog>` element            | Baseline 2023 | Below that: rudimentary shim (`dialog-fallback.js` + `dialog-fallback.css`, both standalone and omittable in custom builds), no top layer or focus trap |
+| `<dialog>` element            | Baseline 2023 | —                  |
 | `color-mix()`                 | Baseline 2023 | Fallback flat color |
 | `light-dark()`                | 2024+        | Manual theme override |
 | `:user-invalid`               | 2024+        | `[aria-invalid]` attribute |
@@ -47,7 +120,7 @@ Modern features are gated with `@supports`; unsupported browsers keep the core l
 
 ### @supports usage
 
-Use `@supports` positively (no `@supports not`) only when it protects a dependent group of rules or a real fallback/modern branch. Do not gate a single progressive declaration whose unsupported value is simply ignored by the browser, such as `text-wrap: balance`.
+Use positive `@supports` by default. Use `@supports not` only for a genuine fallback branch that cannot safely coexist with the enhanced rules. Do not gate a single progressive declaration whose unsupported value is simply ignored by the browser, such as `text-wrap: balance`.
 
 When a baseline declaration is already a valid fallback, prefer the normal cascade to an `@supports` wrapper. For example, older browsers keep the opaque surface here, while newer ones replace it with the translucent value:
 
@@ -75,7 +148,19 @@ Every `color-mix()` declaration needs a flat fallback outside `@supports` (older
 
 ### Hover rules
 
-Hover rules that change surface colors go inside `@media (hover: hover)`. `:active` feedback stays unguarded.
+Use `:hover` directly for standard interactive feedback (links, buttons, table rows,
+form controls, menu items, tabs, badges). The browser already knows when `:hover` can
+apply; guarding it behind `@media (hover: hover)` needlessly suppresses hover on hybrid
+devices whose primary pointer is touch but that also have a mouse or trackpad.
+
+Reserve `@media (hover: hover)` only when hover:
+
+- reveals controls or content,
+- triggers heavy animation,
+- changes layout,
+- or is part of an interaction specifically designed for a mouse.
+
+`:active` feedback stays unguarded.
 
 ### forced-colors
 
@@ -90,4 +175,8 @@ only through background color.
 
 - Grouping works with `role="group"` and `:has()`: it is a progressive enhancement; UI should still be functional without it.
 - Keep `:has()` out of selector lists that also contain legacy-safe selectors. Put the `:has()` branch in `@supports selector(...)` if necessary.
-- Use `:has()` to improve simple structure, but do not turn it into a monolithic selector.
+
+[1]: https://bugzilla.mozilla.org/show_bug.cgi?id=1679204 "1679204 - Consider to add signal to addEventListener"
+[2]: https://developer.chrome.com/blog/new-in-chrome-88 "New in Chrome 88 | Blog"
+[3]: https://trac.webkit.org/timeline "WebKit timeline, January 2021"
+[4]: https://webkit.org/blog/12209/introducing-the-dialog-element/ "Introducing the Dialog Element"

package/docs/design-notes/cascade-layer.md

@@ -21,7 +21,7 @@ Replace `actual.css` with `actual.layer.css`:
 
 Author styles outside any layer will win over layer styles with equal specificity.
 
-## Layer structure (v0.1)
+## Layer structure
 
 A single `actual` layer. The internal import order is a contract: later imports
 can override earlier ones within the layer. Sublayers (`actual.reset`,

package/docs/design-notes/enhancement-contract.md

@@ -0,0 +1,101 @@
+# Enhancement contract
+
+Actual CSS splits CSS and JavaScript into two independent layers with a shared
+opt-in mechanism. Every component uses the same grammar.
+
+## The four-layer contract
+
+```text
+class          = presentation           (.tabs, .flyout, .needs-validation)
+data-enhance   = JavaScript behavior    (data-enhance="tabs")
+ARIA / HTML    = semantics              (role="tab", aria-controls, hidden)
+data-*         = behavior configuration (data-mask, data-tooltip, data-filter)
+```
+
+The duplication is deliberate:
+
+```html
+<div class="tabs" data-enhance="tabs" role="tablist">
+```
+
+- `.tabs` opts into the Actual CSS presentation;
+- `data-enhance="tabs"` opts into the JavaScript behavior;
+- `role="tablist"` declares semantics to assistive technology.
+
+Each layer can be removed independently:
+
+```html
+<!-- CSS only: no JS behavior, just styling -->
+<div class="tabs" role="tablist">…</div>
+
+<!-- JS only: custom CSS, Actual behavior -->
+<div class="my-tabs" data-enhance="tabs" role="tablist">…</div>
+
+<!-- Both: standard Actual look and behavior -->
+<div class="tabs" data-enhance="tabs" role="tablist">…</div>
+
+<!-- Semantic only: author handles everything else -->
+<div role="tablist">…</div>
+```
+
+## `data-enhance` grammar
+
+Tokens are whitespace-separated, matched with the `~=` attribute selector, case-sensitive,
+and must match `[a-z][a-z0-9-]*`. Order is irrelevant; duplicates are harmless.
+
+```html
+<form data-enhance="validation autosubmit">  <!-- two behaviors -->
+```
+
+## When a token, when a `data-*`
+
+> `data-enhance` is a generic opt-in for when HTML does not already provide an unambiguous one.
+
+- **A token** is for a root controller — a behavior that owns a subtree and manages
+  descendants (tabs, flyout, scrollspy, validation).
+- **A self-describing `data-*`** is for a leaf whose attribute is simultaneously the opt-in
+  and the configuration (`data-tooltip`, `data-mask`, `data-filter`,
+  `data-context-menu`).
+- **Elements that are their own opt-in** need nothing (`<dialog>`).
+
+`data-enhance` is explicitly **not** a mandatory prefix for every module.
+
+## One registration per enhancement per root
+
+`registerEnhancement()` owns a name per root. Registering the same token twice
+on the same root throws; `disconnect()` releases the name; re-registration
+after disconnect is allowed; the same token on a different root is independent.
+
+`enhance()` stays generic and unguarded — registering the same selector twice
+creates two independent records that both run.
+
+The owner of a custom enhancement root must call `disconnect()` when disposing
+that root; the default `document.documentElement` root is not affected.
+
+## CSS must never select on `data-enhance`
+
+CSS rules must not select on `data-enhance` or the runtime marker
+`data-actual-surface`. Selecting on either would make the CSS API depend on the JS API,
+defeating the split.
+
+## Design decisions recorded
+
+| # | Decision | Rationale |
+|---|----------|-----------|
+| D2 | `selectors.js` drops its 5 discovery entries, keeps 11 write-side state entries | The file's job changes from *CSS↔init bridge* to *state vocabulary the runtime writes*. It stays the single file to alias for another CSS framework. |
+| D4 | `status.js` uses `[data-status][role="status"]` — no class, no token | The markup already carries `role="status"` everywhere. Semantics alone scope the document-wide lookup. |
+| D5 | `<dialog>` gets no token | `<dialog>` is its own opt-in: semantic, native, CSS-agnostic. |
+| D6 | `validation.js` accepts `[data-field-error]` as an alias for `.field-error` and keeps `.field` / `.danger` as an optional, degrading presentation adapter | Validation is the one module with intentional, optional CSS coupling. The adapter degrades to a no-op under foreign CSS while `aria-invalid`, focus management, custom rules, and server errors all keep working. |
+| D7 | Context-menu reuses `surface`, not `flyout` | The panel gets no token; `menuFor()` validates semantically (`menu, [role="menu"]`). A context menu may legitimately want the flyout *look* without the flyout *behavior*. |
+| D9 | Orphaned mounted surfaces closed from the origin's disconnect handler | A `fix:`, not part of the contract itself. Landed independently. |
+
+## Token vocabulary
+
+| Token | Behavior | Existing class |
+|-------|----------|---------------|
+| `tabs` | Tab panel switching, arrow-key navigation | `.tabs` |
+| `flyout` | Trigger → panel positioning, open/close | `.flyout` |
+| `scrollspy` | Scroll-driven nav highlighting | `.scrollspy` |
+| `validation` | Form validation, focus management, server errors | `.needs-validation` |
+
+Four tokens. Everything else stays self-describing.

package/docs/design-notes/forced-colors.md

@@ -0,0 +1,105 @@
+# Forced Colors (HCM) Strategy
+
+## Principle: let the browser do the work
+
+When `forced-colors: active`, the browser automatically remaps these properties to
+the system palette:
+
+- `border-color` → `ButtonText`
+- `background` / `background-color` → `Canvas`
+- `color` → `CanvasText`
+
+This is the default behavior with `forced-color-adjust: auto` — and it applies to
+**every** element, including pseudo-elements. Components do not need to redeclare
+these properties in a forced-colors block.
+
+## What the browser cannot understand
+
+The browser sees `background-color`, `box-shadow`, `border-color`, `text-shadow`,
+and non-URL `background-image` — it remaps or drops them all. It does **not**
+understand:
+
+- `mask-image` (SVG masks applied via `background-color`)
+- Pseudo-elements whose `background-color` is used as a mask fill
+- `box-shadow` used as a focus ring or shape indicator (the browser drops them)
+- `background-image` carrying essential state or shape
+
+These are the most common cases that need explicit forced-colors rules.
+Add local overrides only when testing shows that browser remapping removes
+an essential shape, state, or affordance.
+
+## Pattern: custom property + single override
+
+```css
+.component {
+  --cmp-marker-color: var(--text-muted);
+
+  background: ...
+  color: ...
+  border: ...
+}
+
+.component::marker {
+  background-color: var(--cmp-marker-color);
+  mask-image: url(...);
+}
+
+@media (forced-colors: active) {
+  .component {
+    --cmp-marker-color: CanvasText;
+  }
+}
+```
+
+## Color system keywords by role
+
+| Context | Color | Why |
+|---|---|---|
+| Disclosure / accordion marker | `CanvasText` | Summary is on Canvas, not a button |
+| Button, switch, checkbox | `ButtonText` / `ButtonFace` / `Highlight` / `HighlightText` | Interactive controls |
+| Selected / current state | `Highlight` / `HighlightText` | Matches OS selection |
+| Disabled state | `GrayText` | Standard disabled system color |
+| Hover indicator | `ButtonText` outline or `CanvasText` underline | Avoids blocked backgrounds |
+
+Prefer `CanvasText` for non-interactive mark-up content. `CanvasText` and
+`ButtonText` are **not guaranteed identical** — custom HCM palettes can set
+them differently.
+
+## What to avoid
+
+### `forced-color-adjust: none`
+Only use when the color **must not** be remapped — e.g., a `background-color`
+whose value is `currentColor` (the system would turn it into `Canvas` and make
+the element invisible). Every `forced-color-adjust: none` blocks the browser
+from fixing contrast issues automatically. Most components need zero instances.
+
+### Redundant rules
+```css
+/* DON'T — the browser already does this */
+@media (forced-colors: active) {
+  .component {
+    border-color: ButtonText;
+    background: Canvas;
+    color: CanvasText;
+  }
+}
+```
+
+### Redundant hover outlines
+If the default focus is an outline on `:focus-visible`, it's already handled.
+Hover doesn't need an outline duplicate. Reserve hover HCM rules for cases
+where text-decoration (underline) is a better visual than an outline.
+
+## Exemptions from forced-colors rules
+
+Some components need **no** forced-color block at all because the default
+remapping is perfect:
+
+- `.card` — `background: Canvas`, `color: CanvasText` are already the defaults
+- `.flyout` / `.menu` — `Canvas`/`CanvasText` for content, `ButtonText` for borders
+- `.accordion` / `.breadcrumb` — pure remapping gets everything right
+- `.status-bar` — `CanvasText` on `Canvas` background
+
+The only forced-colors rules that should remain after a full audit are the ones
+truly required by pseudo-element masks (`::after` / `::before` chevrons, custom
+check/radio marks), non-native focus rings, and `currentColor` dependencies.

package/docs/design-notes/naming.md

@@ -33,5 +33,7 @@ Actual CSS is intended for new projects. Existing projects with class collisions
 - Prefer the shortest established term when it improves searchability without drifting from the component vocabulary (`.btn`, not `.button`).
 - Classes name roles and boolean modifiers; `data-*` carries configurable values.
 - `is-*` classes are runtime internals, not author API.
-- Public JS data attributes are namespaced by feature (`data-flyout-*`, `data-context-menu-*`, `data-dialog-*`, `data-tooltip-*`; `data-toast-*` is reserved). Do not expose shared implementation names such as `surface` unless they are meant as a stable author concept.
+- Public JS data attributes are namespaced by feature (`data-flyout-*`, `data-context-menu-*`, `data-dialog-*`, `data-tooltip-*`; `data-toast-*` is reserved).
+- Shared runtime primitives may have public JavaScript APIs without becoming author-facing CSS or HTML vocabulary. Do not introduce `.surface` or `data-surface-*`; components keep their feature-specific author APIs (`data-flyout-*`, `data-context-menu-*`, CSS `.flyout`, `.menu`, …).
+- `data-enhance` is the one un-namespaced attribute — it carries *opt-in* for any feature, not *configuration* for one feature. Feature-namespaced attributes carry configuration.
 - Custom events use the `actual:*` namespace.