nk_jtb 0.27.3 → 0.28.1

package/.ai/skills/jtb-documentation/SKILL.md

@@ -51,6 +51,8 @@ and typography helpers.
 - `preview-class="..."` → class applied to the preview container only, keeps copied code clean
 - `+demo` / `+demo-folded` → render preview and code together
 
+Use raw HTML (no demo attribute) when the block is purely visual demonstration and the markup is scaffold — showing the code would add noise rather than value.
+
 For layout/responsive docs, use:
 
 ```md
@@ -59,7 +61,9 @@ For layout/responsive docs, use:
 
 ## Examples Files
 
-Quick visual references — not comprehensive docs. Two files:
+Quick visual references — not comprehensive docs.
+
+**Default files:**
 
 - `docs/examples/showcase-typography.md` — font sizes, weights, families, text utilities
 - `docs/examples/showcase-ui.md` — components and UI elements: buttons, badges, checklist, box etc.
@@ -76,8 +80,6 @@ Format depends on content type:
 
 Group by component family under `##` headings. Variants sit under `###` within that group.
 
-Do not create a new examples file for a single component. If it does not fit the two above, discuss with the user.
-
 When a section of a component or utility doc is complete, ask:
 
 > Do you want this added to an examples file?

package/AGENTS.md

@@ -198,16 +198,26 @@ follow the direction.
 - When a skill system is available and a skill applies, invoke it before
   proceeding unless it conflicts with the user's explicit request.
 - Do not treat reading a `SKILL.md` file as a substitute for invoking the skill.
-- When updating prompts, guidelines, or skills, first identify the project's
-  source-of-truth file before editing.
 - Skills and guidelines are always edited via `.ai/` — never agent-managed
-  directories (`.claude/`, `.cursor/`, `.windsurf/`, etc.) directly.
-- Check whether the `.ai/` entry is a local file or a symlink before editing.
-  If it is a symlink, follow it to the target and edit there.
+  directories (`.claude/`, `.cursor/`, `.windsurf/`, etc.) directly. The path
+  you read from when a skill is invoked is never the path you edit.
+- Before editing any skill or guideline, run `ls -la .ai/skills/` or
+  `ls -la .ai/guidelines/` to confirm the correct source path. Do this every
+  time — do not skip it, do not rely on Glob, do not edit the path you read from.
+- Glob does not follow or reveal symlinks and will return misleading results.
+  Always use `ls -la` to locate files in `.ai/`.
+- If the file cannot be found after checking with `ls -la`, stop and ask.
+  Do not assume it does not exist, do not fall back to agent-managed
+  directories, and do not proceed without knowing the correct location.
+- Check whether the `.ai/` entry is a local file or a symlink. If it is a
+  symlink, follow it to the target and edit there.
 - Do not update matching copies in parallel or alternate locations unless they
   are the confirmed source of truth or the user explicitly asks.
-- After changing project guidelines or adding/updating skills, run
-  `php artisan boost:update` in the project so the changes take effect.
+- After changing project guidelines or adding/updating skills, run the
+  project's sync command to propagate changes to agent-managed directories.
+  Check `package.json` for an `ai:sync` script or equivalent. If no sync
+  command is available, note that the change will not propagate until the next
+  sync.
 - When a skill or prompt references a file that cannot be read, first try
   resolving it from the repository root.
 - If the file still cannot be found, stop and ask before proceeding.

package/CLAUDE.md

@@ -198,16 +198,26 @@ follow the direction.
 - When a skill system is available and a skill applies, invoke it before
   proceeding unless it conflicts with the user's explicit request.
 - Do not treat reading a `SKILL.md` file as a substitute for invoking the skill.
-- When updating prompts, guidelines, or skills, first identify the project's
-  source-of-truth file before editing.
 - Skills and guidelines are always edited via `.ai/` — never agent-managed
-  directories (`.claude/`, `.cursor/`, `.windsurf/`, etc.) directly.
-- Check whether the `.ai/` entry is a local file or a symlink before editing.
-  If it is a symlink, follow it to the target and edit there.
+  directories (`.claude/`, `.cursor/`, `.windsurf/`, etc.) directly. The path
+  you read from when a skill is invoked is never the path you edit.
+- Before editing any skill or guideline, run `ls -la .ai/skills/` or
+  `ls -la .ai/guidelines/` to confirm the correct source path. Do this every
+  time — do not skip it, do not rely on Glob, do not edit the path you read from.
+- Glob does not follow or reveal symlinks and will return misleading results.
+  Always use `ls -la` to locate files in `.ai/`.
+- If the file cannot be found after checking with `ls -la`, stop and ask.
+  Do not assume it does not exist, do not fall back to agent-managed
+  directories, and do not proceed without knowing the correct location.
+- Check whether the `.ai/` entry is a local file or a symlink. If it is a
+  symlink, follow it to the target and edit there.
 - Do not update matching copies in parallel or alternate locations unless they
   are the confirmed source of truth or the user explicitly asks.
-- After changing project guidelines or adding/updating skills, run
-  `php artisan boost:update` in the project so the changes take effect.
+- After changing project guidelines or adding/updating skills, run the
+  project's sync command to propagate changes to agent-managed directories.
+  Check `package.json` for an `ai:sync` script or equivalent. If no sync
+  command is available, note that the change will not propagate until the next
+  sync.
 - When a skill or prompt references a file that cannot be read, first try
   resolving it from the repository root.
 - If the file still cannot be found, stop and ask before proceeding.

package/docs/automatic-spacing.md

@@ -1,47 +1,14 @@
-# Auto Spacing System (review)
+# Auto Spacing
 
 <p class="lead">Automatic vertical spacing between block elements without
-requiring margin utilities on every element. Content flows naturally with
-consistent gaps.</p>
+requiring margin utilities on every element.</p>
 
-- **Relationship-Based** - Spacing determined by what elements follow each other
-- **Semantic-Aware** - Distinguishes between content and layout wrappers
 - **Flex/Grid Safe** - Automatically opts out when using gap-based layouts
 - **Low Specificity** - Uses `:where()` for easy overrides
 
-## How It Works (review)
+## Examples
 
-Two rules apply `margin-top: $base-gap` based on element relationships. Spacing
-targets (`p`, `h1-h6`, `table`, `ul`, etc.) add spacing when followed by other
-elements. Layout wrappers (`div`, `section`, `article`) only add spacing when
-followed by content—not other wrappers.
-
-## The Rules (review)
-
-### Rule 1: Spacing Targets (review)
-
-Content elements followed by any block element.
-
-```scss +code
-:where(#{$spacing-targets}, #{$common-classes}) + :where(*:not(#{$inline-exclusions})) {
-    margin-block-start: $base-gap;
-}
-```
-
-### Rule 2: Layout to Content (review)
-
-Layout wrappers followed by content elements. This prevents `div + div` spacing
-while catching `div + p`.
-
-```scss +code
-:where(div, section, article) + :where(#{$spacing-targets}) {
-    margin-block-start: $base-gap;
-}
-```
-
-## Visual Tests (review)
-
-### Should Space (review)
+### Should Space
 
 <div class="bx bg-stripes-pink">
     <h2 class="pxy-075 warning-light rounded-05">Heading 2</h2>
@@ -55,7 +22,7 @@ while catching `div + p`.
     <pre class="pxy-075 warning-light rounded-05">Pre</pre>
 </div>
 
-### Should NOT Space (review)
+### Should NOT Space
 
 <div class="bx bg-stripes-blue">
     <div class="pxy-075 info-light rounded-05">Div</div>
@@ -66,16 +33,10 @@ while catching `div + p`.
     <footer class="pxy-075 info-light rounded-05">Footer</footer>
 </div>
 
-## Flex and Grid (review)
+### Flex and Grid
 
 Elements inside flex or grid containers have margins reset—these layouts use `gap` instead.
 
-```scss +code
-:where([class*='flex'], [class*='grid']) > * {
-    margin: 0;
-}
-```
-
 <div class="grid cols-2 gap-1">
     <div>
         <p class="txt-sm">Flex (uses gap)</p>
@@ -95,3 +56,17 @@ Elements inside flex or grid containers have margins reset—these layouts use `
         </div>
     </div>
 </div>
+
+## How It Works
+
+Spacing is applied by element relationship, not position. Two categories determine behaviour:
+
+**Spacing targets** — `p`, headings, `ul`, `table`, `form`, `blockquote`, `pre` — add
+`margin-block-start` to whatever follows them.
+
+**Layout wrappers** — `div`, `section`, `article` — only add spacing when followed by
+content, not other wrappers. This prevents `div + div` from being spaced while
+still catching `div + p`.
+
+Elements inside flex or grid containers are exempt — margins reset to zero and
+`gap` handles spacing instead.

package/docs/components/loaders-and-spinners.md

@@ -4,9 +4,9 @@ Page loaders and spinners to communicate in-progress and waiting states.
 
 ## Spinners
 
-### SVG Arc
+### SVG Border
 
-Apply `animate-spin` to an SVG with a dashed stroke to create a spinner.
+A static arc on a faint circular track. Apply `animate-spin` to the SVG.
 
 Use `wh-*` utilities to control size.
 
@@ -28,21 +28,82 @@ Use `wh-*` utilities to control size.
 Use `txt-*` utilities to control colour.
 
 ```html +demo-folded class="bx example-utils" preview-class="flex-centered gap"
-<svg class="animate-spin wh-2 txt-blue" viewBox="0 0 36 36">
+<svg class="animate-spin wh-3 txt-blue" viewBox="0 0 36 36">
     <circle cx="18" cy="18" r="14" fill="none" stroke="currentColor" stroke-width="3" stroke-opacity="0.25" />
     <circle cx="18" cy="18" r="14" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="butt" stroke-dasharray="22 66" />
 </svg>
-<svg class="animate-spin wh-2 txt-blue-900" viewBox="0 0 36 36">
+<svg class="animate-spin wh-3 txt-blue-900" viewBox="0 0 36 36">
     <circle cx="18" cy="18" r="14" fill="none" stroke="currentColor" stroke-width="3" stroke-opacity="0.25" />
     <circle cx="18" cy="18" r="14" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="butt" stroke-dasharray="22 66" />
 </svg>
-<svg class="animate-spin wh-2 txt-orange-400" viewBox="0 0 36 36">
+<svg class="animate-spin wh-3 txt-orange-400" viewBox="0 0 36 36">
     <circle cx="18" cy="18" r="14" fill="none" stroke="currentColor" stroke-width="3" stroke-opacity="0.25" />
     <circle cx="18" cy="18" r="14" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="butt" stroke-dasharray="22 66" />
 </svg>
 ```
 
-## Loader Container (review)
+### SVG Arc
+
+Apply `animate-dash` to an SVG element. A single class handles both rotation and
+stroke morphing. Use `wh-*` to control size and `txt-*` to control colour.
+
+```html +demo-folded class="bx example-utils" preview-class="flex-centered vac gap-2"
+<svg class="animate-dash wh-2 txt-primary" viewBox="0 0 44 44">
+    <circle cx="22" cy="22" r="16" stroke="currentColor" />
+</svg>
+<svg class="animate-dash wh-3 txt-primary" viewBox="0 0 44 44">
+    <circle cx="22" cy="22" r="16" stroke="currentColor" />
+</svg>
+<svg class="animate-dash wh-4 txt-primary" viewBox="0 0 44 44">
+    <circle cx="22" cy="22" r="16" stroke="currentColor" />
+</svg>
+```
+
+Use `txt-*` utilities to control colour.
+
+```html +demo-folded class="bx example-utils" preview-class="flex-centered gap"
+<svg class="animate-dash wh-3 txt-blue" viewBox="0 0 44 44">
+    <circle cx="22" cy="22" r="16" stroke="currentColor" />
+</svg>
+<svg class="animate-dash wh-3 txt-blue-900" viewBox="0 0 44 44">
+    <circle cx="22" cy="22" r="16" stroke="currentColor" />
+</svg>
+<svg class="animate-dash wh-3 txt-orange-400" viewBox="0 0 44 44">
+    <circle cx="22" cy="22" r="16" stroke="currentColor" />
+</svg>
+```
+
+### Dots (review)
 
-`.loader-container` centers a spinner and loading text as a column. For a
-composed example see [UI Examples](/docs/jtb/examples/showcase-ui).
+Eight dots arranged in a circle, fading in sequence. Use `wh-*` to control size
+and `txt-*` to control colour.
+
+```html +demo-folded class="bx example-jtb" preview-class="flex-centered vac gap-2"
+<div class="spinner-dots wh-2 txt-primary">
+    <div></div><div></div><div></div><div></div>
+    <div></div><div></div><div></div><div></div>
+</div>
+<div class="spinner-dots wh-3 txt-primary">
+    <div></div><div></div><div></div><div></div>
+    <div></div><div></div><div></div><div></div>
+</div>
+<div class="spinner-dots wh-4 txt-primary">
+    <div></div><div></div><div></div><div></div>
+    <div></div><div></div><div></div><div></div>
+</div>
+```
+
+## Page Loader
+
+Compose a page loader with utilities. Use `flex flex-col flex-centered` to
+centre the spinner and text as a column. Add `animate-dots` for an animated
+ellipsis alongside the loading label.
+
+```html +demo-folded class="bx example-utils" preview-class="flex-centered"
+<div class="flex flex-col flex-centered gap-1">
+    <svg class="animate-dash wh-4 txt-primary" viewBox="0 0 44 44">
+        <circle cx="22" cy="22" r="16" stroke="currentColor" />
+    </svg>
+    <span>Loading<span class="animate-dots"></span></span>
+</div>
+```

package/docs/jtb-status.md

@@ -52,7 +52,7 @@ a doc is confirmed accurate or a utility is completed.
 
 | Utility     | Framework | Docs   | Notes                 |
 | ----------- | --------- | ------ | --------------------- |
-| `animation` | review    | Review | `animate-*` utilities |
+| `animation` | ✅         | ✅      | `animate-*` utilities |
 
 ### Backgrounds (review)
 
@@ -242,7 +242,7 @@ a doc is confirmed accurate or a utility is completed.
 | `layouts-and-structures.md`                | ✅       |                                                                                        |
 | `responsive-design-patterns.md`            | review  |                                                                                        |
 | `responsive-design.md`                     | review  |                                                                                        |
-| `automatic-spacing.md`                     | review  |                                                                                        |
+| `automatic-spacing.md`                     | ✅       |                                                                                        |
 | `conventions-and-architecture-rules.md`    | review  |                                                                                        |
 | `magic-classes.md`                         | ✅       |                                                                                        |
 | `themes.md`                                | review  |                                                                                        |
@@ -295,7 +295,7 @@ Files parked in `docs/review/` — purpose or audience unclear.
 | `components/menu.md`                | review  |                                                  |
 | `components/navbar.md`              | review  |                                                  |
 | `components/table.md`               | review  |                                                  |
-| `components/loaders-and-spinners.md` | partial | Spinners section confirmed (SVG Arc utility approach). Loader Container still pending. |
+| `components/loaders-and-spinners.md` | partial | SVG Border, SVG Arc, Page Loader confirmed. Dots section still under review. |
 | `components/example-navigations.md` | stub    | Bare HTML, no explanation                        |
 
 ### Utilities
@@ -304,7 +304,7 @@ Files parked in `docs/review/` — purpose or audience unclear.
 | ------------------------------------- | ------ | --------------------------------------------------- |
 | `utilities/border.md`                 | review | Border, outline, and divider utilities              |
 | `utilities/typography.md`             | review | New — needs review pass                             |
-| `utilities/animation.md`              | review | Rewritten — loader/spinner content moved to components/loaders-and-spinners.md |
+| `utilities/animation.md`              | ✅      |                                                                                 |
 | `utilities/display-and-visibility.md` | review |                                                     |
 | `utilities/effects.md`                | review |                                                     |
 | `utilities/position.md`               | review |                                                     |

package/docs/utilities/animation.md

@@ -2,26 +2,28 @@
 
 Utility classes for applying CSS animations.
 
-| Class                 | Animation           |
-| --------------------- | ------------------- |
-| `animate-spin`        | Continuous rotation |
-| `animate-bounce`      | Vertical bounce     |
-| `animate-pulse`       | Opacity fade        |
-| `animate-pulse-ring`  | Expanding ring      |
-| `animate-ping`        | Scale and fade out  |
-| `animate-checkmark`   | SVG stroke draw-in  |
-| `animate-circle`      | SVG stroke draw-in  |
-| `animate-none`        | Removes animation   |
-
-## Spin (review)
-
-Rotates an element continuously. Commonly used for loading indicators.
-
-```html +demo-folded class="bx"
-<div class="animate-spin wh-3 bdr-4 bdr-gray-200 bdr-t-blue-500 rounded-full"></div>
+| Class                | Animation               |
+| -------------------- | ----------------------- |
+| `animate-spin`       | Continuous rotation     |
+| `animate-bounce`     | Vertical bounce         |
+| `animate-pulse`      | Opacity fade            |
+| `animate-pulse-ring` | Expanding ring          |
+| `animate-ping`       | Scale and fade out      |
+| `animate-dash`       | SVG stroke arc morphing |
+| `animate-dots`       | Animated ellipsis       |
+| `animate-checkmark`  | SVG stroke draw-in      |
+| `animate-circle`     | SVG stroke draw-in      |
+| `animate-none`       | Removes animation       |
+
+## Spin
+
+Rotates an element continuously.
+
+```html +demo-folded class="bx" preview-class="flex-centered"
+<div class="animate-spin wh-3 bdr-4 bdr-blue-500 rounded-full"></div>
 ```
 
-## Bounce (review)
+## Bounce
 
 Applies a vertical bounce. Stagger `animation-delay` across sibling elements for
 a sequential effect.
@@ -32,16 +34,15 @@ a sequential effect.
 <div class="wh-1 bg-blue-600 rounded-full animate-bounce" style="animation-delay: 0.2s;"></div>
 ```
 
-## Pulse (review)
+## Pulse
 
-Fades an element's opacity in and out. Use for skeleton loaders or ambient
-status indicators.
+Fades an element's opacity in and out.
 
 ```html +demo-folded class="bx"
 <div class="wh-4 bg-teal-500 rounded-full animate-pulse"></div>
 ```
 
-## Pulse Ring (review)
+## Pulse Ring
 
 Scales and fades an element outward to create an expanding ring effect. Use
 `relative` positioning with overlapping siblings for layered rings.
@@ -54,7 +55,7 @@ Scales and fades an element outward to create an expanding ring effect. Use
 </div>
 ```
 
-## Ping (review)
+## Ping
 
 Scales an element to twice its size while fading it out — a one-shot burst
 effect. Commonly used as a notification indicator layered over a badge or dot.
@@ -66,14 +67,35 @@ effect. Commonly used as a notification indicator layered over a badge or dot.
 </div>
 ```
 
-## SVG Animations (review)
+## Dots
+
+Animates a `::after` pseudo-element to cycle through an ellipsis sequence.
+
+```html +demo-folded class="bx" preview-class="flex-centered"
+<span>Loading<span class="animate-dots"></span></span>
+```
+
+## SVG Animations
+
+### Dash
+
+Rotates an SVG while morphing its child circle's `stroke-dasharray`. A single
+class handles both the rotation and the stroke animation.
+
+```html +demo-folded class="bx" preview-class="flex-centered"
+<svg class="animate-dash wh-4 txt-blue-500" viewBox="0 0 44 44">
+    <circle cx="22" cy="22" r="16" stroke="currentColor" />
+</svg>
+```
+
+### Draw-in
 
 `animate-circle` draws a circular stroke in from nothing to full.
-`animate-checkmark` does the same for a path. Both classes set `stroke-dasharray`
+`animate-checkmark` does the same for a path. Both set `stroke-dasharray`
 and animate `stroke-dashoffset`. The SVG path or circle length must be no greater
 than the class's `stroke-dasharray` value (166 for circle, 100 for checkmark).
 
-```html +demo-folded class="bx"
+```html +demo-folded class="bx" preview-class="flex-centered"
 <svg viewBox="0 0 52 52" class="wh-4 txt-green-600" fill="none">
     <circle cx="26" cy="26" r="25" stroke="currentColor" stroke-width="2" class="animate-circle" />
     <path d="M14 27l8 8 16-16" stroke="currentColor" stroke-width="2" class="animate-checkmark" />