nk_jtb 0.27.0 → 0.27.1

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

@@ -15,23 +15,26 @@ precedence where they conflict.
 
 Use for named structural classes such as `navbar`, `menu`, `bx`, or form controls.
 
-**Structure:**
+A class-based component has a named CSS class (e.g. `.spinner`, `.accordion`) that drives its core structure. A utility-based pattern achieves a similar result through composition of utility classes with no dedicated component class.
+
+**Single-component page structure:**
 
 1. One-line lead
 2. `## Basic Usage` — minimum working markup
-3. Additional examples — simple to fuller usage
+3. Additional `##` sections — simple to fuller usage
 4. `## SCSS Variables` — if the component exposes overridable variables
-5. `## Utility Examples` — if a utility-based approach is viable, always last
+5. `## Utility Examples` — utility-based alternatives, always last
+
+**Multi-component page:** repeat the same structure for each component, shifted down one heading level. The page title (`#`) becomes the group, each component becomes `##`, and its sections become `###`. A page with many components just repeats this pattern as many times as needed.
 
 **Rules:**
 
 - The lead describes purpose, not implementation. Do not mention specific CSS properties.
-- Open `## Basic Usage` with `Apply the [component class] to...` — directive, not descriptive.
+- Open Basic Usage with `Apply the [component class] to...` — directive, not descriptive.
 - Component class examples use `class="bx example-jtb"`.
 - Utility examples use `class="bx example-utils"`.
-- Place the SCSS Variables table directly after the class examples, before `## Utility Examples`.
+- Place SCSS Variables directly before Utility Examples.
 - Link to `/docs/jtb/variable-system` for override instructions rather than explaining inline.
-- `## Utility Examples` is always last. Lives in the component doc — not a separate file.
 
 ### Utility Documentation
 

package/AGENTS.md

@@ -200,8 +200,10 @@ follow the direction.
 - 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.
-- Files under `.ai/` may be symlinks into a shared prompts/guidelines repo. If
-  so, update the symlink target.
+- 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.
 - 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

package/CLAUDE.md

@@ -200,8 +200,10 @@ follow the direction.
 - 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.
-- Files under `.ai/` may be symlinks into a shared prompts/guidelines repo. If
-  so, update the symlink target.
+- 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.
 - 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

package/code-review-loaders-spinners-260514.md

@@ -0,0 +1,104 @@
+# Code Review — Loaders and Spinners
+**Date:** 2026-05-14
+**Scope:** Component review — loaders and spinners subsystem
+
+---
+
+## Scope Reviewed
+
+- **Type:** Component/package review
+- **Target:** `src/components/_loaders-and-spinners.scss`, `src/utilities/_animation.scss`, `docs/utilities/animation.md`, `docs/review/animation.md`
+- **Coverage:** Full read of all four files; cross-referenced keyframe definitions against class usage
+- **Exclusions:** No UI test harness or compiled output inspected
+
+---
+
+## Findings
+
+### High — `@keyframes dots` is never defined; `.dots` animation is a no-op
+
+- **Impact:** The animated dots in `.loader-container` (e.g. "Loading...") never animate — `animation: dots 1.5s steps(4, end) infinite` silently fails.
+- **Evidence:** `_loaders-and-spinners.scss:54` references `animation: dots`. `_animation.scss` defines `spin`, `bounce`, `pulse-ring`, `pulse`, `checkmark`, `circle` — no `dots` keyframe exists anywhere in the codebase.
+- **Fix:** Define `@keyframes dots` (typically stepping through `""`, `"."`, `".."`, `"..."` via `content`) in `_animation.scss` alongside the other keyframes.
+
+---
+
+### High — `@keyframes ping` is never defined; `.animate-ping` is broken
+
+- **Impact:** `.animate-ping` always resolves to `animation: none` and the `--animate-ping` CSS custom property is dead.
+- **Evidence:** `_animation.scss:66` defines `--animate-ping: ping 1s cubic-bezier(0, 0, 0.2, 1) infinite` and `_animation.scss:88–90` outputs the `.animate-ping` class, but no `@keyframes ping` exists in the file or anywhere else in `src/`.
+- **Fix:** Add `@keyframes ping` (typically a scale-and-fade-out expanding ring) to `_animation.scss`, or remove `.animate-ping` and the `--animate-ping` custom property if ping is not planned.
+
+---
+
+### Medium — `.loader-container .spinner` abandons the variable system with hardcoded values
+
+- **Impact:** The nested `.spinner` is unaffected by `--size` or `--thickness`, so size variants (`sm`, `lg`, `thick`) do nothing inside a loader container. The two `.spinner` implementations are behaviourally inconsistent.
+- **Evidence:** `_loaders-and-spinners.scss:32–39` — hardcoded `border: 4px solid`, `height: 60px`, `width: 60px`, `margin: 0 auto 20px` instead of `--size`/`--thickness`. The outer `.spinner` (lines 1–23) uses the variable system correctly.
+- **Fix:** Remove the nested `.spinner` override; let the outer `.spinner` definition handle sizing, and rely on the `dark` context modifier or a wrapper class for colour changes rather than overriding the element entirely.
+
+---
+
+### Medium — `.loading-text` and `.dots` use hardcoded px values and hex colours
+
+- **Impact:** These values sit outside the framework variable and scale system, making them impossible to theme or override via custom properties.
+- **Evidence:** `_loaders-and-spinners.scss:43–46` — `font-size: 18px`, `color: #fff`, `letter-spacing: 0.5px`; line 51 — `width: 20px`.
+- **Fix:** Replace with framework scale references (e.g. `var(--fs-base)`, a color token or `currentColor`) and rem units.
+
+---
+
+### Medium — `.spinner` uses physical `border-top` shorthand
+
+- **Impact:** Breaks logical-property consistency; does not respect writing-mode.
+- **Evidence:** `_loaders-and-spinners.scss:8` — `border-top: calc(var(--size) * var(--thickness)) solid #3498db`. CLAUDE.md requires logical properties (`border-block-start`) except in explicitly positioned contexts.
+- **Fix:** Replace `border-top` with `border-block-start`.
+
+---
+
+### Medium — Docs examples use class names that are not confirmed JTB utilities
+
+- **Impact:** Examples may not render correctly and set misleading precedent for how the framework is used.
+- **Evidence:** `docs/utilities/animation.md` lines 8–78 use: `rounded-full`, `space-x-05`, `opacity-0`, `opacity-30`, `opacity-80`, `overflow-hidden`, `items-center`, `w-full`, `h-2`, `h-full`, `font-semibold` — none of which appear in JTB docs or confirmed source files.
+- **Fix:** Audit each class against JTB source; replace non-JTB classes with confirmed equivalents or extract to inline styles where no JTB utility exists.
+
+---
+
+### Low — Large dead code block in `_animation.scss`
+
+- **Impact:** Adds noise; the commented code differs from the live implementation, creating confusion about which version is canonical.
+- **Evidence:** `_animation.scss:109–177` — three commented-out `.spinner` implementations spanning 68 lines.
+- **Fix:** Delete the commented block. History is in git.
+
+---
+
+### Low — `docs/utilities/animation.md` and `docs/review/animation.md` are identical
+
+- **Impact:** Any update to one must be manually mirrored to the other; they will diverge.
+- **Evidence:** Both files are byte-for-byte identical — same headings, same content, same `(review)` markers on every section heading.
+- **Fix:** Delete `docs/review/animation.md` or make it a redirect/include. One source of truth.
+
+---
+
+### Low — All section headings carry `(review)` markers; no content is marked final
+
+- **Impact:** The docs page cannot be published or referenced as authoritative in its current state.
+- **Evidence:** `docs/utilities/animation.md:1` — title is "Animation Utilities (review)"; every `##` heading appends `(review)`.
+- **Fix:** Remove `(review)` markers as each section is confirmed; track incomplete sections explicitly.
+
+---
+
+### Low — No dedicated loaders/spinners documentation page
+
+- **Impact:** The `.spinner`, `.loader-container`, `.loading-text`, and `.dots` components are undiscoverable outside the animation utilities page. There is no entry in `docs/components/` for them, despite being defined as a named component file.
+- **Evidence:** `docs/components/` has accordion, box, button, forms, list, menu, navbar, table — no loaders entry. The component is documented only as a subsection of `docs/utilities/animation.md`.
+- **Fix:** Create `docs/components/loaders.md` covering the `.spinner` variants and `.loader-container` pattern, separate from the animation utility reference.
+
+---
+
+## Maintainability Risk: **High**
+
+Two broken animations (`dots`, `ping`), a nested component that silently overrides and breaks the variable system, and documentation that is unfinished and duplicated. The `.loader-container .spinner` inconsistency means any refactor of the variable approach requires tracking two divergent implementations.
+
+## Cross-Boundary Coupling Risk: **Low**
+
+The component is self-contained. The only cross-file dependency is `@keyframes spin` from `_animation.scss`, which is correctly defined.

package/dev.html

@@ -11,64 +11,9 @@
     <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
 </head>
 
-<body class="bg-stone-100 pxy-075">
+<body class="container py-5 bg-gray-200">
 
-    <style>
-        :root {
-            --primary: #6b1a3c;
-            --primary-hover: color-mix(in srgb, var(--primary), white 5%);
-            --primary-active: color-mix(in srgb, var(--primary), black 5%);
-            --primary-border: transparent;
-            --on-primary: #fff;
-        }
-    </style>
-
-    <section class="grid md:cols-2 gap-1">
-        <article class="bx flex-col md:flex-row p-0 overflow-hidden rounded-xl shadow-none bdr-stone-200">
-            <div class="h-8 md:h-auto md:w-8 md:min-w-8 bg-stone-300"></div>
-            <div class="flex-col flex-1 gap-075 pxy-1">
-                <span class="txt-primary txt-xs font-bold tracking-widest uppercase">Program</span>
-                <h3 class="font-serif txt-base font-bold lh-tight txt-stone-950">Ethics Program</h3>
-                <p class="txt-xs lh-relaxed txt-stone-700 flex-1">Two comprehensive courses equipping lactation professionals with practical skills in ethical decision-making and Code-compliant practice</p>
-                <a class="btn primary rounded-full w-full txt-xs">Enrol Now $154.00</a>
-                <a class="txt-primary txt-xs font-semibold">View Details →</a>
-            </div>
-        </article>
-
-        <article class="bx flex-col md:flex-row p-0 overflow-hidden rounded-xl shadow-none bdr-stone-200">
-            <div class="h-8 md:h-auto md:w-8 md:min-w-8 bg-stone-400"></div>
-            <div class="flex-col flex-1 gap-075 pxy-1">
-                <span class="txt-primary txt-xs font-bold tracking-widest uppercase">Program</span>
-                <h3 class="font-serif txt-base font-bold lh-tight txt-stone-950">Lactation Consultant Exam Prep Program</h3>
-                <p class="txt-xs lh-relaxed txt-stone-700 flex-1">13 targeted courses building core lactation science, clinical reasoning and exam strategy skills to help IBCLC candidates feel confident and ready to pass</p>
-                <a class="btn primary rounded-full w-full txt-xs">Enrol Now $1,200.00</a>
-                <a class="txt-primary txt-xs font-semibold">View Details →</a>
-            </div>
-        </article>
-
-        <article class="bx flex-col md:flex-row p-0 overflow-hidden rounded-xl shadow-none bdr-stone-200">
-            <div class="h-8 md:h-auto md:w-8 md:min-w-8 bg-stone-300"></div>
-            <div class="flex-col flex-1 gap-075 pxy-1">
-                <span class="txt-primary txt-xs font-bold tracking-widest uppercase">Program</span>
-                <h3 class="font-serif txt-base font-bold lh-tight txt-stone-950">Recertify, Renew, Refresh</h3>
-                <p class="txt-xs lh-relaxed txt-stone-700 flex-1">7 focused courses mapped to the IBCLC Detailed Content Outline to refresh knowledge, update evidence-based practice for recertification</p>
-                <a class="btn primary rounded-full w-full txt-xs">Enrol Now $385.00</a>
-                <a class="txt-primary txt-xs font-semibold">View Details →</a>
-            </div>
-        </article>
-
-        <article class="bx flex-col md:flex-row p-0 overflow-hidden rounded-xl shadow-none bdr-stone-200">
-            <div class="h-8 md:h-auto md:w-8 md:min-w-8 bg-emerald-200"></div>
-            <div class="flex-col flex-1 gap-075 pxy-1">
-                <span class="txt-primary txt-xs font-bold tracking-widest uppercase">Program</span>
-                <h3 class="font-serif txt-base font-bold lh-tight txt-stone-950">New Program Name</h3>
-                <p class="txt-xs lh-relaxed txt-stone-700 flex-1">Description text here for the new 4th program that your client wants to add to the page</p>
-                <a class="btn primary rounded-full w-full txt-xs">Enrol Now $XXX.00</a>
-                <a class="txt-primary txt-xs font-semibold">View Details →</a>
-            </div>
-        </article>
-    </section>
     <script type="module" src="/main.js"></script>
 </body>
 
-</html>
+</html>

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

@@ -0,0 +1,85 @@
+# Loaders and Spinners
+
+Page loaders and spinners to communicate in-progress and waiting states.
+
+## Spinners
+
+The `.spinner` class provides a CSS-only animated border spinner.
+
+### Border Spinner
+
+Apply the `.spinner` class to a `div` for an animated loading indicator.
+
+#### Basic Usage
+
+```html +demo-folded class="bx example-jtb" preview-class="flex-centered"
+<div class="spinner"></div>
+```
+
+#### Size
+
+Add `.sm` or `.lg` to resize.
+
+```html +demo-folded class="bx example-jtb" preview-class="flex-centered gap"
+<div class="spinner sm"></div>
+<div class="spinner"></div>
+<div class="spinner lg"></div>
+```
+
+#### Thickness
+
+Add `.thick` to increase the border width. Combine with size modifiers.
+
+```html +demo-folded class="bx example-jtb" preview-class="flex-centered gap"
+<div class="spinner sm thick"></div>
+<div class="spinner thick"></div>
+<div class="spinner lg thick"></div>
+```
+
+### Utility Examples
+
+#### SVG Arc
+
+```html +demo-folded class="bx example-utils" preview-class="flex-centered gap"
+<svg class="animate-spin wh-5" 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>
+```
+
+Use text color utilities to control the spinner color.
+
+```html +demo-folded class="bx example-utils" preview-class="flex-centered gap"
+<svg class="animate-spin wh-5 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-5 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-5 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)
+
+`.loader-container` centers a spinner and loading text as a column. For a
+composed example see [UI Examples](/docs/jtb/examples/showcase-ui).
+
+## CSS Custom Properties (review)
+
+| Property      | Default  | Controls                             |
+| ------------- | -------- | ------------------------------------ |
+| `--size`      | `2.5rem` | Spinner diameter                     |
+| `--thickness` | `0.08`   | Border width as a proportion of size |
+
+Override on the element directly or scoped to a parent:
+
+```html +code
+<div class="spinner" style="--size: 4rem; --thickness: 0.12;"></div>
+```
+
+See [Variable System](/docs/jtb/variable-system) for override instructions.

package/docs/examples/showcase-ui.md

@@ -1,5 +1,16 @@
 # JTB UI Showcase
 
+## Loaders
+
+### Loader Container
+
+```html +demo-folded class="bx dark"
+<div class="loader-container">
+    <div class="spinner"></div>
+    <div class="loading-text">Loading<span class="dots"></span></div>
+</div>
+```
+
 ## Lists
 
 ### Checklist

package/docs/jtb-status.md

@@ -295,6 +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 | Border Spinner confirmed. Loader Container, CSS Custom Properties, SVG Arc utility example still pending. |
 | `components/example-navigations.md` | stub    | Bare HTML, no explanation                        |
 
 ### Utilities
@@ -303,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 |                                                     |
+| `utilities/animation.md`              | review | Rewritten — loader/spinner content moved to components/loaders-and-spinners.md |
 | `utilities/display-and-visibility.md` | review |                                                     |
 | `utilities/effects.md`                | review |                                                     |
 | `utilities/position.md`               | review |                                                     |

package/docs/utilities/animation.md

@@ -1,130 +1,81 @@
-# Animation Utilities (review)
-
-<h2>Loading States</h2>
-<div class="grid md:cols-2 lg:cols-3 gap">
-    <!-- Simple Spinner -->
-    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
-        <h3 class="bx-title txt-1 font-semibold">Simple Spinner</h3>
-        <div class="animate-spin rounded-full wh-4 bdr-4 bdr-gray-200 bdr-t-blue-600"></div>
-        <p class="txt-sm txt-gray-600">Sending message...</p>
-    </div>
-    <!-- Ring Spinner (Thicker) -->
-    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
-        <h3 class="bx-title txt-1 font-semibold">Ring Spinner</h3>
-        <div class="animate-spin rounded-full wh-4 bdr-8 bdr-gray-200 bdr-t-indigo-600"></div>
-        <p class="txt-sm txt-gray-600">Processing...</p>
-    </div>
-    <!-- Dual Ring -->
-    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
-        <h3 class="bx-title txt-1 font-semibold">Dual Ring</h3>
-        <div class="relative">
-            <div class="animate-spin rounded-full wh-4 bdr-4 bdr-gray-200 bdr-t-purple-600"></div>
-            <div class="absolute top-05 left-05 animate-spin rounded-full wh-3 bdr-4 bdr-gray-100 bdr-t-purple-400" style="animation-direction: reverse;"></div>
-        </div>
-        <p class="txt-sm txt-gray-600">Loading...</p>
-    </div>
-    <!-- Bouncing Dots -->
-    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
-        <h3 class="bx-title txt-1 font-semibold">Bouncing Dots</h3>
-        <div class="flex space-x-05">
-            <div class="wh-1 bg-blue-600 rounded-full animate-bounce" style="animation-delay: 0s;"></div>
-            <div class="wh-1 bg-blue-600 rounded-full animate-bounce" style="animation-delay: 0.1s;"></div>
-            <div class="wh-1 bg-blue-600 rounded-full animate-bounce" style="animation-delay: 0.2s;"></div>
-        </div>
-        <p class="txt-sm txt-gray-600">Submitting...</p>
-    </div>
-    <!-- Pulsing Circle -->
-    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
-        <h3 class="bx-title txt-1 font-semibold">Pulse</h3>
-        <div class="wh-4 bg-teal-500 rounded-full animate-pulse"></div>
-        <p class="txt-sm txt-gray-600">Please wait...</p>
-    </div>
-    <!-- Pulse Rings -->
-    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
-        <h3 class="bx-title txt-1 font-semibold">Pulse Rings</h3>
-        <div class="relative">
-            <div class="wh-4 bg-emerald-500 rounded-full"></div>
-            <div class="absolute top-0 left-0 wh-4 bg-emerald-400 rounded-full animate-pulse-ring"></div>
-            <div class="absolute top-0 left-0 wh-4 bg-emerald-400 rounded-full animate-pulse-ring" style="animation-delay: 0.5s;"></div>
-        </div>
-        <p class="txt-sm txt-gray-600">Processing...</p>
-    </div>
-    <!-- SVG Spinner -->
-    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
-        <h3 class="bx-title txt-1 font-semibold">SVG Spinner</h3>
-        <svg class="animate-spin wh-4 txt-orange-600" fill="none" viewBox="0 0 24 24">
-            <circle class="opacity-30" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
-            <path class="opacity-80" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
-        </svg>
-        <p class="txt-sm txt-gray-600">Uploading...</p>
-    </div>
-    <!-- Progress Bar -->
-    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
-        <h3 class="bx-title txt-1 font-semibold">Progress Bar</h3>
-        <div class="w-full h-2 bg-gray-200 rounded-full overflow-hidden">
-            <div class="h-full bg-blue-600 rounded-full animate-pulse" style="width: 70%;"></div>
-        </div>
-        <p class="txt-sm txt-gray-600">70% Complete</p>
-    </div>
-    <!-- Sequential Dots -->
-    <div class="bx bdr-none shadow-lg flex-centered flex-col gap">
-        <h3 class="bx-title txt-1 font-semibold">Sequential Dots</h3>
-        <div class="flex space-x-05 items-center h-2">
-            <div class="wh-05 bg-gray-600 rounded-full opacity-0 animate-pulse" style="animation-delay: 0s;"></div>
-            <div class="wh-05 bg-gray-600 rounded-full opacity-0 animate-pulse" style="animation-delay: 0.3s;"></div>
-            <div class="wh-05 bg-gray-600 rounded-full opacity-0 animate-pulse" style="animation-delay: 0.6s;"></div>
-        </div>
-        <p class="txt-sm txt-gray-600">Loading...</p>
-    </div>
-</div>
-
-## Loading Animations (review)
-
-<div class="loader-container bx dark">
-    <div class="spinner"></div>
-    <div class="loading-text">Loading<span class="dots"></span></div>
-</div>
-
-<div class="loader-container bx dark">
-    <div class="loading-text">Loading<span class="dots"></span></div>
-</div>
-
-## SVG Spinners (review)
-
-<div class="bx  flex va-c">
-    <svg class="wh-2 animate-spin" viewBox="0 0 200 200">
-        <circle cx="100" cy="100" r="80" fill="none" class="stroke-gray-400" stroke-width="12" />
-        <circle cx="100" cy="100" r="80" fill="none" class="stroke-gray-100" stroke-width="12" stroke-linecap="round" stroke-dasharray="251.2" stroke-dashoffset="188.4" />
-    </svg>
-    <svg class="wh-3 animate-spin" viewBox="0 0 200 200">
-        <circle cx="100" cy="100" r="80" fill="none" class="stroke-red-300" stroke-width="12" />
-        <circle cx="100" cy="100" r="80" fill="none" class="stroke-blue-500" stroke-width="12" stroke-linecap="round" stroke-dasharray="251.2" stroke-dashoffset="188.4" />
-    </svg>
-    <svg class="wh-4 animate-spin" viewBox="0 0 200 200">
-        <circle cx="100" cy="100" r="80" fill="none" class="stroke-yellow-300" stroke-width="12" />
-        <circle cx="100" cy="100" r="80" fill="none" class="stroke-green-500" stroke-width="12" stroke-linecap="round" stroke-dasharray="251.2" stroke-dashoffset="188.4" />
-    </svg>
-</div>
-
-## Border Animations (review)
-
-### Spinner (review)
-
-```html +demo-folded
-<div class="dark flex-centered gap bx">
-    <div class="spinner sm"></div>
-    <div class="spinner"></div>
-    <div class="spinner lg"></div>
-</div>
-```
-
-**Thick Spinners:**
-
-```html +demo-folded
-<div class="dark flex-centered gap bx">
-    <div class="spinner sm thick"></div>
-    <div class="spinner thick "></div>
-    <div class="spinner lg thick"></div>
-</div>
-```
-
+# Animation Utilities
+
+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>
+```
+
+## Bounce (review)
+
+Applies a vertical bounce. Stagger `animation-delay` across sibling elements for
+a sequential effect.
+
+```html +demo-folded class="bx" preview-class="flex-centered gap-05"
+<div class="wh-1 bg-blue-600 rounded-full animate-bounce" style="animation-delay: 0s;"></div>
+<div class="wh-1 bg-blue-600 rounded-full animate-bounce" style="animation-delay: 0.1s;"></div>
+<div class="wh-1 bg-blue-600 rounded-full animate-bounce" style="animation-delay: 0.2s;"></div>
+```
+
+## Pulse (review)
+
+Fades an element's opacity in and out. Use for skeleton loaders or ambient
+status indicators.
+
+```html +demo-folded class="bx"
+<div class="wh-4 bg-teal-500 rounded-full animate-pulse"></div>
+```
+
+## Pulse Ring (review)
+
+Scales and fades an element outward to create an expanding ring effect. Use
+`relative` positioning with overlapping siblings for layered rings.
+
+```html +demo-folded class="bx"
+<div class="relative">
+    <div class="wh-4 bg-emerald-500 rounded-full"></div>
+    <div class="absolute top-0 left-0 wh-4 bg-emerald-400 rounded-full animate-pulse-ring"></div>
+    <div class="absolute top-0 left-0 wh-4 bg-emerald-400 rounded-full animate-pulse-ring" style="animation-delay: 0.5s;"></div>
+</div>
+```
+
+## Ping (review)
+
+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.
+
+```html +demo-folded class="bx"
+<div class="relative">
+    <div class="wh-2 bg-red-500 rounded-full"></div>
+    <div class="absolute top-0 left-0 wh-2 bg-red-400 rounded-full animate-ping"></div>
+</div>
+```
+
+## SVG Animations (review)
+
+`animate-circle` draws a circular stroke in from nothing to full.
+`animate-checkmark` does the same for a path. Both classes 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"
+<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" />
+</svg>
+```