actual-css 0.9.1 → 0.10.0

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.

package/skills/actual-css/references/review-checklist.md

@@ -0,0 +1,51 @@
+# Consumer review checklist
+
+## Vocabulary and imports
+
+- Every framework-looking class exists in the installed Actual CSS version.
+- Intent/variant composition is used instead of invented compound names.
+- Runtime `is-*` state is not authored as application API.
+- The project imports the family/module that owns the markup it uses.
+- `forms` vs `forms/all` is intentional.
+- JS imports match the behavior actually enabled.
+
+## CSS ownership
+
+- Application CSS is not recreating an existing layout/component/focus behavior unnecessarily.
+- Public hooks were considered before replacement CSS.
+- Palette values remain centralized in theme/token definitions.
+- `--gap` is only rebound when inherited rhythm should change.
+- Component-scoped hooks are not read elsewhere without an intentional fallback.
+
+## Layout
+
+- Primitive choice follows child relationships, not a single mockup's item count.
+- `.app-layout` is used only for its actual shell contract.
+- Exact track needs use the appropriate grid hook before a new generic primitive is invented.
+
+## Forms
+
+- `inputmode` is not treated as validation/filtering.
+- `data-filter` is used only when destructive rewriting is intended.
+- Masks are not mistaken for semantic validity.
+- Server/application validation remains authoritative for domain rules.
+- Help/errors and invalid state are connected accessibly.
+
+## Enhancements
+
+- Presentation, semantics, behavior opt-in, and configuration remain separate.
+- Enhancement tokens and feature attributes are documented by the installed version.
+- Application code does not fight Actual for Popover or positioning ownership.
+- Interactive floating content is not placed in a tooltip.
+
+## Accessibility
+
+- Keyboard focus remains visible.
+- Icon-only controls are named.
+- Disabled/current/selected/expanded semantics match visible state.
+- Keyboard behavior matches claimed ARIA roles.
+- Custom states consider forced colors and reduced motion where relevant.
+
+## Version safety
+
+When uncertain, inspect the installed manifests, package exports, source, and docs instead of extrapolating from this starter skill.