actual-css 0.9.2 → 0.10.0

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.

package/skills/actual-css/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: actual-css
+description: Build and review application UI with Actual CSS. Use when choosing Actual CSS imports, classes, layout primitives, theme tokens, component hooks, forms, progressive enhancements, accessibility behavior, or when deciding whether CSS/JS belongs in Actual CSS or application code.
+---
+
+# Actual CSS
+
+Use Actual CSS as a **UI vocabulary and behavior kit**, not as a stylesheet to fight.
+
+The target is not zero application CSS. The target is:
+
+> no duplicated framework behavior, no invented Actual API, and no palette literals scattered outside the theme/token layer.
+
+## Start from the installed API
+
+Actual CSS may evolve between releases. Resolve uncertain API from the version used by the current project, in this order:
+
+1. `actual-css/components.json` — component index: classes, public hooks, states, CSS/JS imports, enhancement tokens.
+2. `actual-css/reserved-classes.json` — framework-owned class namespace.
+3. `actual-css/package.json#exports` — canonical package entrypoints.
+4. `actual-css/src/css/` and `actual-css/src/js/` — exact selectors, defaults, state ownership, and runtime behavior.
+5. `actual-css/docs/` and `actual-css/llms.txt` — intended usage and concise architecture guidance.
+
+If this skill was copied into a consuming project, the installed package wins over examples or summaries in this skill.
+
+Use the bundled inspector when useful:
+
+```sh
+node <skill>/scripts/inspect-actual-css.mjs --source
+node <skill>/scripts/inspect-actual-css.mjs button
+node <skill>/scripts/inspect-actual-css.mjs --class compact
+node <skill>/scripts/inspect-actual-css.mjs --exports
+node <skill>/scripts/inspect-actual-css.mjs --enhancements
+```
+
+If `PROJECT.md` exists beside this file, read it after resolving the Actual CSS API. It contains application-specific choices, not framework API.
+
+## Decision order
+
+Before writing application CSS, ask in this order:
+
+1. **Theme** — can semantic tokens express the visual requirement?
+2. **Layout relationship** — does an Actual layout primitive express how the children relate?
+3. **Component** — is there already a component or pattern for the structure?
+4. **Public hook** — can a documented custom property tune it?
+5. **Utility** — does an existing small utility express the adjustment?
+6. **Application CSS** — is the remaining requirement genuinely product-specific?
+
+Use Actual for generic structure and behavior. Use application CSS for product identity, unusual geometry, bespoke animation, and product-specific composition.
+
+Do not preserve incidental mockup pixels by default. Resolve designs toward the system first.
+
+## Public class grammar
+
+Actual CSS intentionally uses unprefixed global classes:
+
+```text
+.component [intent] [variant] [size] [modifier]
+```
+
+Example:
+
+```html
+<button class="btn primary outline lg">Publish</button>
+<span class="badge success soft">Online</span>
+<section class="card raised stack">...</section>
+```
+
+Rules:
+
+- Compose intents and variants; do not invent `.btn-primary`-style compounds.
+- `.sm` / `.lg` are size modifiers; `.compact` / `.spacious` are density contexts.
+- Undocumented `is-*` classes are runtime state, not author API.
+- Component-specific modifiers only mean what their component documents.
+- Do not invent breakpoint/state utility syntax or arbitrary-value utilities.
+- Do not recreate a generic spacing scale; use layout rhythm, density, hooks, or local CSS.
+- Before introducing a generic-looking application class, check `reserved-classes.json`.
+
+See `references/api-and-vocabulary.md`.
+
+## Imports
+
+Use the smallest package surface consistent with the project's policy.
+
+```css
+@import "actual-css/css";          /* source core */
+@import "actual-css/css/layout";
+@import "actual-css/css/forms/all";
+@import "actual-css/css/components/button";
+
+@import "actual-css/full";         /* complete compiled framework, zero-config */
+```
+
+Forms are intentionally split:
+
+- `actual-css/css/forms` — native-control baseline.
+- `actual-css/css/forms/all` — complete forms family.
+
+The minimal core does not imply that layout, forms, components, typography, effects, or utilities are loaded.
+
+Import JavaScript behavior independently when possible:
+
+```js
+import "actual-css/js/flyout";
+import "actual-css/js/tooltip";
+import "actual-css/js/validation";
+```
+
+Check the installed package exports before assuming an entrypoint exists.
+
+See `references/api-and-vocabulary.md`.
+
+## Layout and theming
+
+Choose layout from the **relationship between children**, not from the number of columns visible in one mockup:
+
+```text
+vertical flow                         -> .stack
+wrapping inline peers                 -> .cluster
+responsive repeated items             -> .grid
+known equal peer density              -> .grid-N
+peers that switch together            -> .switcher
+main content + secondary region       -> .sidebar-layout
+fixed media + flexible content        -> .media
+explicit shared 12-column placement   -> .column-layout
+custom exact tracks                   -> .grid + --grid-columns
+```
+
+Do not choose `.app-layout` merely because the product is an application; it is a specific viewport shell with internal scrolling and adaptive navigation.
+
+Prefer documented public hooks over replacement rules. Keep palette literals in the theme/token layer and derive decorative colors from semantic tokens.
+
+Treat state-owned, derived, relay, runtime-written, or undocumented custom properties as internal unless the docs explicitly expose them.
+
+See `references/layout-and-theming.md`.
+
+## Forms
+
+Prefer native input semantics first. Actual CSS enhances them; it does not replace domain validation.
+
+- `inputmode` is a keyboard hint, not filtering.
+- `data-filter` explicitly rewrites values; an empty `data-filter` does nothing.
+- `data-mask` enforces shape, not domain validity.
+- Do not mask telephone numbers by default. Normalize and validate authoritative phone semantics on the server.
+- Native HTML validation remains the baseline; `data-enhance="validation"` adds state/focus behavior and small custom rules.
+- Connect inline help/errors with `aria-describedby`; synchronize invalid state with `aria-invalid`.
+
+See `references/forms.md`.
+
+## Progressive enhancement
+
+Keep four concerns separate:
+
+```text
+class          = presentation
+HTML / ARIA    = semantics
+data-enhance   = controller opt-in
+data-*         = feature configuration or leaf opt-in
+```
+
+`data-enhance` is not a prefix for every JavaScript feature. Verify the installed enhancement vocabulary rather than inventing a token.
+
+Leaf behaviors can be self-describing through attributes such as `data-tooltip`, `data-mask`, `data-filter`, or `data-context-menu`. Native `<dialog>` is its own semantic opt-in.
+
+CSS must not depend on `data-enhance` or runtime transport markers.
+
+For application-specific widgets, reuse Actual's JS primitives for lifecycle, surfaces, focus, keyboard navigation, input rewriting, and events before recreating those policies.
+
+See `references/enhancements.md`.
+
+## Surface ownership
+
+A floating surface must have one lifecycle owner.
+
+When Actual manages a surface or tooltip, application code must not compete for its Popover lifecycle or runtime positioning. Do not reparent managed surfaces to `body` as a workaround; the native top-layer transport is specifically used to preserve authored DOM context and inheritance.
+
+Use a flyout/dialog for interactive floating content. Tooltips are supplemental, non-interactive content.
+
+See `references/enhancements.md`.
+
+## Accessibility
+
+- Prefer native `button`, `a`, `details`, `dialog`, and form controls.
+- Preserve visible keyboard focus.
+- Name icon-only controls.
+- Do not communicate state with color alone.
+- Match ARIA roles with the keyboard behavior they require.
+- Keep persistent or critical information out of tooltip/status-only UI.
+- Consider reduced motion and forced colors for custom interactive states.
+
+See `references/accessibility.md`.
+
+## Project customization
+
+This starter describes **Actual CSS itself**. A consuming application should add its local choices in `PROJECT.md`, not rewrite framework facts.
+
+Useful project-specific additions include:
+
+- loaded CSS families/modules;
+- loaded JS enhancers;
+- theme root and brand tokens;
+- page-shell conventions;
+- server-side component/template wrappers already available;
+- application class naming rules;
+- stricter browser-support requirements;
+- product-specific composition conventions.
+
+Start from `PROJECT.md.example`.
+
+Project rules may narrow how Actual CSS is used, but must not invent or redefine Actual CSS public API.
+
+## Task index
+
+Use the smallest reference that answers the question:
+
+- classes, components, imports, manifests -> `references/api-and-vocabulary.md`
+- tokens, hooks, layout, custom CSS -> `references/layout-and-theming.md`
+- fields, filtering, masks, validation -> `references/forms.md`
+- flyouts, tooltips, dialogs, custom JS widgets -> `references/enhancements.md`
+- focus, ARIA, browser/runtime assumptions -> `references/accessibility.md`
+- final consumer review -> `references/review-checklist.md`
+
+## Completion check
+
+Before considering an Actual CSS UI change complete:
+
+- No invented Actual class, variant, hook, enhancement token, or package export.
+- Existing framework layout/component behavior was not reimplemented unnecessarily.
+- Public hooks were considered before replacement CSS.
+- Palette literals remain centralized in the theme/token layer unless genuinely product-specific and derived appropriately.
+- Semantic HTML and ARIA do not depend on CSS class names.
+- JavaScript behavior and presentation stay decoupled.
+- Focus and relevant disabled/current/selected/expanded states remain accessible.
+- The implementation matches the Actual CSS version actually used by the project.

package/skills/actual-css/references/accessibility.md

@@ -0,0 +1,44 @@
+# Accessibility and runtime assumptions
+
+## Accessible defaults
+
+- Prefer native interactive elements.
+- Preserve visible keyboard focus.
+- Name icon-only controls.
+- Do not rely on color alone to communicate state.
+- Connect form help/errors to controls.
+- Keep persistent or critical information out of tooltip/status-only UI.
+- Respect reduced motion and forced colors in custom states.
+
+## Focus
+
+Actual's core provides a focus baseline. Components may enhance it, but application styling must not remove visible keyboard focus without an equivalent accessible treatment.
+
+When replacing focus visuals, consider forced-colors behavior as well as normal color modes.
+
+## Roles and keyboard behavior
+
+Do not claim an ARIA role only because it sounds semantically close. Roles such as toolbar, menu, tablist, listbox, or grid imply interaction and keyboard expectations.
+
+Prefer native semantics where they fit, and only add ARIA needed to express behavior that native HTML does not already convey.
+
+## Interactive states
+
+For custom treatment of controls, consider relevant states such as:
+
+```text
+rest
+hover
+active / pressed
+focus-visible
+disabled
+selected / current / expanded
+```
+
+Do not make hover the only indication that something is interactive.
+
+## Browser policy
+
+Read the installed Actual CSS browser-support documentation for exact supported versions. Do not add legacy compatibility wrappers merely from habit.
+
+Actual's runtime intentionally relies on modern platform primitives when they are within its documented JavaScript support floor. Project-specific browser requirements can be stricter and belong in `PROJECT.md`.

package/skills/actual-css/references/api-and-vocabulary.md

@@ -0,0 +1,94 @@
+# API and vocabulary
+
+## Source of truth
+
+Use the installed version rather than guessing from names:
+
+- `components.json` — component classes, hooks, states, CSS/JS imports, enhancement tokens.
+- `reserved-classes.json` — whether Actual CSS owns a class name.
+- `package.json#exports` — supported package entrypoints.
+- CSS/JS source — exact behavior and defaults.
+- docs / `llms.txt` — intended usage and framework map.
+
+`components.json` is an index, not a replacement for component documentation or source.
+
+## Class grammar
+
+```text
+.component [intent] [variant] [size] [modifier]
+```
+
+Typical intent/variant composition looks like:
+
+```html
+<button class="btn primary outline lg">Publish</button>
+<span class="badge success soft">Online</span>
+```
+
+Do not infer API from plausible names.
+
+Actual CSS intentionally does not provide:
+
+- compound intent classes such as `.btn-primary`;
+- Tailwind-style breakpoint/state prefixes;
+- arbitrary-value utilities;
+- a generic spacing scale such as `mt-4` / `p-2`;
+- author-facing `is-*` state conventions;
+- a generic presentation class just because an internal JS primitive has that name.
+
+Before introducing a generic application class (`stacked`, `actions`, `flush`, `muted`, etc.), check the reserved namespace. If Actual owns the name, use its documented meaning or choose a product-specific application name.
+
+## CSS imports
+
+Common aggregate entrypoints:
+
+```css
+@import "actual-css/css";  /* source core */
+@import "actual-css/css/typography";
+@import "actual-css/css/layout";
+@import "actual-css/css/forms";
+@import "actual-css/css/forms/all";
+@import "actual-css/css/components";
+@import "actual-css/css/effects";
+@import "actual-css/css/utilities";
+
+@import "actual-css/full"; /* complete compiled framework, zero-config */
+```
+
+Individual modules are available through domain paths when exported, for example:
+
+```css
+@import "actual-css/css/layout/grid";
+@import "actual-css/css/components/button";
+@import "actual-css/css/components/card";
+```
+
+The minimal core intentionally excludes the functional families above.
+
+Forms have two aggregate entrypoints:
+
+- `forms` = native-control baseline.
+- `forms/all` = complete forms family.
+
+## JavaScript imports
+
+Import only the behavior the application intends to use, or deliberately choose the full runtime.
+
+Examples:
+
+```js
+import "actual-css/js/flyout";
+import "actual-css/js/tooltip";
+import "actual-css/js/validation";
+```
+
+Do not assume `actual-css/js` means "all enhancers". Check the current exports.
+
+## Lookup helper
+
+```sh
+node <skill>/scripts/inspect-actual-css.mjs button
+node <skill>/scripts/inspect-actual-css.mjs --class flyout
+node <skill>/scripts/inspect-actual-css.mjs --exports
+node <skill>/scripts/inspect-actual-css.mjs --enhancements
+```

package/skills/actual-css/references/enhancements.md

@@ -0,0 +1,59 @@
+# Enhancements and floating surfaces
+
+## Four independent layers
+
+```text
+class          presentation
+HTML / ARIA    semantics
+data-enhance   root-controller behavior opt-in
+data-*         feature configuration or leaf opt-in
+```
+
+A component may use all four, but they are not interchangeable.
+
+Do not make CSS selectors depend on `data-enhance` or internal runtime transport markers.
+
+## `data-enhance`
+
+Use a token for a controller that owns a subtree. Verify current supported tokens from the installed version.
+
+Self-describing leaf behavior should use the feature's own documented attribute, such as tooltip/filter/mask/context-menu attributes, rather than inventing an enhancement token.
+
+Native `<dialog>` is semantically self-describing and does not need a generic enhancement token merely to be a dialog.
+
+## Custom widgets
+
+Before implementing lifecycle, focus, Escape handling, keyboard navigation, input rewriting, or floating-surface policy from scratch, inspect the exported Actual JS primitives.
+
+Common responsibilities may already be covered by modules such as:
+
+```text
+enhance
+surface
+focus-group
+keys
+menu
+focus
+input
+filter
+events
+command
+```
+
+Use the current package exports as the source of truth.
+
+## One surface owner
+
+A floating panel must have one lifecycle owner.
+
+When Actual's runtime manages a surface, application code must not simultaneously own its Popover opening/closing or runtime positioning. Do not combine independent native/third-party lifecycle with Actual management on the same panel.
+
+Actual-managed surfaces use top-layer transport while remaining in their authored DOM position. Do not reparent them to `body` to escape clipping; preserving inherited theme/density/custom-property context is part of the transport design.
+
+## Flyout vs tooltip
+
+Use a flyout or dialog for interactive floating content.
+
+Tooltips are supplemental, non-interactive content. Use an explicit tooltip element when local inherited styling context matters; generated shorthand content may be created outside that local context.
+
+Do not override positioning owned by the runtime.

package/skills/actual-css/references/forms.md

@@ -0,0 +1,49 @@
+# Forms
+
+## Native semantics first
+
+Actual CSS styles and progressively enhances native controls. Domain policy remains application/server responsibility.
+
+Use documented form structure instead of recreating field spacing, helper/error layout, and invalid-state styling around anonymous wrappers.
+
+## Keyboard intent vs filtering
+
+`inputmode` changes keyboard intent; it does not constrain the value.
+
+`data-filter` explicitly rewrites input and is therefore a stronger policy. Empty `data-filter` does nothing and should not infer behavior from `inputmode`.
+
+Use application code for locale-specific numeric rules, currency rules, signed input, ranges, or other domain-specific policies.
+
+## Masks
+
+`data-mask` is for fixed shape, not semantic validity.
+
+A value can match a shape and still be an impossible date, invalid account number, or otherwise invalid domain value.
+
+## Telephone input
+
+Do not mask phone numbers by default. Preserve user input and normalize/validate authoritative number semantics on the server.
+
+If the installed Actual version exposes `tel-prefix`, treat it only as a coarse client-side origin policy, not phone-number validation.
+
+## Validation
+
+Native validation is the baseline. The optional validation enhancer adds state/focus behavior and a small rule system; it is not the application's validation architecture.
+
+Typical structure:
+
+```html
+<form class="needs-validation" data-enhance="validation" novalidate>
+  <label class="field">
+    <span class="field-label">Email</span>
+    <input class="input" type="email" required aria-describedby="email-error">
+    <span class="field-error" id="email-error">Enter a valid email.</span>
+  </label>
+</form>
+```
+
+Keep help/error text connected with `aria-describedby`; keep invalid state synchronized with `aria-invalid`.
+
+Server-side or AJAX validation remains authoritative for business rules.
+
+Before depending on a custom rule name or exact enhancer behavior, check the installed docs/source.

package/skills/actual-css/references/layout-and-theming.md

@@ -0,0 +1,82 @@
+# Layout and theming
+
+## Integration order
+
+Translate designs in this order:
+
+```text
+Theme -> relationship -> component -> public hook -> small utility -> application identity
+```
+
+## Theme first
+
+Keep palette literals centralized in a theme/token block. Application rules should consume or derive semantic values rather than copy palette literals repeatedly.
+
+```css
+[data-theme="brand"] {
+  --primary: hsl(326 100% 60%);
+  --brand-glow: color-mix(in oklch, var(--primary) 40%, transparent);
+}
+
+.hero {
+  box-shadow: 0 0 2rem var(--brand-glow);
+}
+```
+
+Global semantic tokens are the first choice for application CSS. Component hooks are local tuning points.
+
+## Choose layout by relationship
+
+```text
+.stack           vertical flow
+.cluster         wrapping inline peers / toolbar-like rows
+.grid            responsive repeated items
+.grid-N          known equal peer density
+.switcher        peer regions that switch together
+.sidebar-layout  main content plus secondary region
+.media           fixed media plus flexible content
+.column-layout   explicit shared-canvas placement
+```
+
+For exact tracks that do not match a built-in contract, use `.grid` with `--grid-columns` rather than inventing a new generic grid primitive.
+
+Do not choose `.app-layout` just because the product is an app. It is a specific viewport-sized shell with internal scrolling and adaptive navigation.
+
+## Tune before replacing
+
+Prefer public hooks:
+
+```css
+.feature-grid {
+  --grid-min: 18rem;
+  --gap: var(--space-50);
+}
+
+.product-card {
+  --card-pad: var(--space-50);
+}
+```
+
+If local CSS mainly reconstructs an Actual primitive with `display`, tracks, gaps, focus styling, or component geometry, reconsider the primitive or its hooks first.
+
+## `--gap` and local `gap`
+
+`--gap` can be an inherited rhythm contract. Rebinding it may intentionally affect nested layout primitives.
+
+If only one element's spacing should change, set the CSS `gap` property directly instead of rebinding inherited rhythm.
+
+## Public vs internal custom properties
+
+Use documented public hooks. Treat runtime-written, state-owned, derived, relay, and undocumented variables as internal.
+
+A component-scoped hook does not exist everywhere. If application CSS intentionally reads one outside its component, provide a fallback:
+
+```css
+.panel {
+  padding: var(--card-pad, var(--space-40));
+}
+```
+
+## Application CSS is expected
+
+Good application CSS includes brand marks, illustrations, unusual geometry, bespoke animation, and product-specific compositions. The goal is not zero custom CSS; it is no duplicated framework behavior.