nk_jtb 0.26.0 → 0.27.1

package/.ai/skills/jtb-best-practices/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: jtb-best-practices
+description: >-
+  Use this skill whenever writing, reviewing, or auditing HTML and CSS that
+  uses the NK JTB framework — including component composition, utility
+  application, and layout work. Do not wait for an explicit request — if JTB
+  classes or components are being written or reviewed, this skill applies.
+---
+
+# NK JTB Best Practices
+
+## Verify Before Using
+
+Never use a class without confirming it exists in JTB source or documentation.
+Pattern-matching from one scale to another is the most common source of invalid
+classes in JTB — each scale is generated independently.
+
+If a class cannot be confirmed in the SCSS source or docs, stop and check before using it.
+
+## Quick Reference
+
+Read the relevant rule file before writing markup. Summaries below are for
+navigation only — the rule files take precedence.
+
+### Units & Naming → `rules/units-and-naming.md`
+
+- `m-1` = 1rem, `gap-05` = 0.5rem — sub-1 values drop the leading zero and decimal
+- Values ≥ 1 with decimals use the literal decimal in HTML: `gap-1.5`, not `gap-15`
+- All-sides shorthand is `pxy` / `mxy`, not `p` / `m`
+- Context-aware modifiers on the component: `<button class="btn primary">`, not `.btn-primary`
+- Logical properties by default — `margin-inline-start` not `margin-left`
+
+### Responsive → `rules/responsive.md`
+
+- Ask whether responsive behaviour is needed before writing any grid, flex, or visibility utility
+- `{bp}:` for progressive layout, `to-{bp}:` for visibility windows, `on-{bp}:` for exact-range only
+- `on-` and `to-` are only generated for `display` and `visibility`
+- Build mobile-first — base styles first, breakpoint prefixes upward
+
+### Components & Tokens → `rules/components.md`
+
+- Use `bx` for bordered/padded containers — not `bg-white bdr rounded shadow`
+- Use `btn` for all button-like controls
+- Use `badge` for small label/tag UI before building from scratch
+- Use `txt-muted`, `txt-primary` before reaching for palette utilities
+- Use a local helper class when JTB cannot express a requirement — never inline styles
+
+### Conversion → `rules/conversion.md`
+
+- Only for converting existing non-JTB code to JTB — not for design-to-code work or building new components from scratch
+- Treat source classes as intent references, not direct mappings
+- Snap arbitrary values to the closest JTB token — do not preserve exact values
+- Record actionable gaps in `jtb-conversion-notes.md` — missing utilities, token mismatches
+- Do not create new classes just to make a single conversion easier
+
+### Layouts & Structures → `rules/layouts.md`
+
+- `grid` with `cols-*` for column-based structures, `flex` for single-axis arrangements
+- Build mobile-first — add `{bp}:` utilities only when no higher-level pattern fits
+- Fewest structural elements that cleanly express the layout
+- Default section rhythm: `py-4-3-2` standard, `py-5-3-2` prominent

package/.ai/skills/jtb-best-practices/rules/components.md

@@ -0,0 +1,57 @@
+# Components & Tokens
+
+## Framework Components First
+
+Always check whether a framework component already expresses the structure
+before rebuilding it with low-level utilities.
+
+### `bx`
+
+Use for any bordered, padded content container:
+
+```html +code
+<!-- correct -->
+<div class="bx">...</div>
+
+<!-- wrong — rebuilding what bx already does -->
+<div class="bg-white bdr rounded shadow pxy-1">...</div>
+```
+
+Sub-elements: `bx-header`, `bx-content`, `bx-footer` bleed to the box edges.
+Use them for image regions, section headers, and footers within the card.
+
+### `btn`
+
+Use for all button-like controls. Apply theme and size as context-aware modifiers:
+
+```html +code
+<button class="btn primary">Enrol Now</button>
+<button class="btn sm">Cancel</button>
+```
+
+Do not rebuild pill or button shapes with low-level utilities.
+
+### `badge`
+
+Use for small label/tag UI before assembling the same shape from scratch.
+Check existing badge variants before adding a new one.
+
+## Semantic Tokens
+
+Prefer semantic utility tokens over palette utilities when they match the intent:
+
+| Token         | Use for                         |
+| ------------- | ------------------------------- |
+| `txt-muted`   | Secondary or de-emphasised text |
+| `txt-primary` | Brand-coloured text             |
+| `bg-primary`  | Brand-coloured background       |
+
+Reach for palette utilities (`txt-stone-600`, `bg-teal-100`) only when no
+semantic token is a reasonable match.
+
+## Local Helper Classes
+
+When JTB cannot express a requirement, create a local helper class. Never use
+inline styles — a class is visible, searchable, and signals a gap clearly.
+
+Inline styles are only permitted if explicitly instructed by the developer.

package/.ai/skills/jtb-best-practices/rules/conversion.md

@@ -0,0 +1,43 @@
+# Conversion
+
+Only for converting existing non-JTB code to JTB. Do not use for
+design-to-code work from screenshots/mockups or building new components from scratch.
+
+If the output file is not specified, ask before proceeding.
+
+## Conversion Order
+
+1. Replace source classes with documented JTB utilities or components.
+2. When the source uses arbitrary/custom values, snap to the closest existing
+   JTB token or utility instead of preserving the exact value.
+3. Do not create new classes as a conversion shortcut.
+4. If something appears to need a class, consider whether it should become a
+   real framework component, utility, or documented pattern.
+5. Record only actionable gaps in `jtb-conversion-notes.md` — missing
+   utilities, unsupported patterns, or token mismatches that need a follow-up
+   decision. Do not record resolved matches, clean conversions, or decisions
+   made.
+6. Only add local CSS when JTB cannot express the requirement.
+
+## Rules
+
+- Treat source classes as intent references, not direct mappings.
+- For color, reach for the closest JTB palette utility first (`bg-stone-50`,
+  `txt-stone-900` etc.). If the brand color maps to a semantic role, override
+  the JTB token via `:root` (e.g. `--primary`). If no palette utility or
+  semantic token is a reasonable match, record it in `jtb-conversion-notes.md`
+  and leave the decision to the developer — do not create a custom color class.
+- Remove no-op or default classes that do not materially change the layout or
+  styling.
+- When Tailwind transition syntax depends on unsupported `duration-*`, easing,
+  or delay utilities, simplify to the closest supported JTB transition pattern
+  and record the missing utility coverage.
+- Keep Alpine `x-data` scoped to the element that directly owns or uses the
+  state. Do not move it to a broader parent unless multiple descendants
+  genuinely share the same state.
+
+## Review Checklist
+
+- Remove source-only syntax such as arbitrary value classes where a JTB utility exists.
+- Remove classes that only restate the default behavior.
+- Document missing utilities or unsupported patterns in `jtb-conversion-notes.md`.

package/.ai/skills/{jtb-layouts-and-structures/SKILL.md → jtb-best-practices/rules/layouts.md}

@@ -1,36 +1,8 @@
----
-name: jtb-layouts-and-structures
-description: >-
-  Use this skill whenever making layout or structural decisions — choosing
-  between grid and flex, building page shells, or structuring internal
-  component layouts. Do not wait for an explicit request — if layout or
-  structural decisions are being made, this skill applies.
----
-
-For layout or responsive work, read:
-
-- `docs/responsive-design.md`
-- `docs/layouts-and-structures.md`
-- `docs/magic-classes.md`
-
-## Scope
-
-Use this skill for structural layout decisions:
-
-- page shells
-- layout patterns
-- reusable internal structures
-- split layouts
-- grid vs flex choices
-- container and width strategy
-- responsive visibility strategy
-
-Do not use this skill for general documentation or for framework-internals work.
+# Layouts & Structures
 
 ## Decision Order
 
-1. Classify the problem first — page-level layout or internal component
-   structure?
+1. Classify the problem first — page-level layout or internal component structure?
 2. Choose the right primitive:
    - `grid` with `cols-*` for column-based structures
    - `flex` for linear, single-axis arrangements
@@ -42,13 +14,9 @@ Do not use this skill for general documentation or for framework-internals work.
 5. Only escalate to custom solutions when documented primitives cannot express
    the need cleanly.
 
-## Markup
-
-- Do not add `data-*` attributes unless explicitly requested.
-
 ## Rules
 
-- Prefer mobile-first base layouts with responsive enhancement.
+- Do not add `data-*` attributes unless explicitly requested.
 - Default to the fewest structural elements that cleanly express the layout.
 - Combine width, rhythm, and internal layout on the same element when they do
   not need isolation.
@@ -66,5 +34,3 @@ Do not use this skill for general documentation or for framework-internals work.
 - Prefer approved magic/composite classes when they express an established
   responsive pattern more clearly than explicit breakpoint chains. Common
   examples include `py-*`, `gap-*`, and `cols-*` patterns.
-- Use `{bp}:` for progressive layout changes.
-- Use `to-` and `on-` primarily for visibility windows, not layout progression.

package/.ai/skills/jtb-best-practices/rules/responsive.md

@@ -0,0 +1,34 @@
+# Responsive
+
+## Ask First
+
+Before writing any grid, flex layout, or visibility utility, ask:
+
+> Does this need to be responsive?
+
+If the task or design does not specify responsive behaviour, ask before assuming.
+Do not add or omit responsive prefixes without knowing the answer.
+
+## Prefix Types
+
+Three distinct prefix types — do not substitute one for another:
+
+| Prefix      | Example         | Applies when                          |
+| ----------- | --------------- | ------------------------------------- |
+| `{bp}:`     | `md:flex`       | From breakpoint upward (min-width)    |
+| `to-{bp}:`  | `to-md:hidden`  | Below breakpoint (max-width)          |
+| `on-{bp}:`  | `on-md:hidden`  | Exactly at that breakpoint range only |
+
+`on-` and `to-` are only generated for `display` and `visibility` utilities.
+Do not use them for layout, spacing, or other properties — use mixins for
+custom responsive behaviour on other properties.
+
+## Mobile-First
+
+Build the base layout for the smallest viewport. Add `{bp}:` prefixes to
+progressively enhance upward. Do not start from desktop and work down.
+
+## Common Breakpoints
+
+`sm`, `md`, `lg`, `xl`, `xxl` — always confirm against the JTB breakpoint map
+before using a breakpoint that is not already present in the codebase.

package/.ai/skills/jtb-best-practices/rules/units-and-naming.md

@@ -0,0 +1,68 @@
+# Units & Naming
+
+## Scale
+
+All numeric class values are rem. `m-1` = 1rem, `p-2` = 2rem, `gap-05` = 0.5rem.
+
+Before using any numeric utility, confirm the value exists in the relevant map
+in `src/maps_and_variables/`. Each utility (spacing, gap, sizing, border-radius)
+has its own independent scale — do not assume a value is valid because it exists
+in a different scale.
+
+## Decimal Class Names
+
+The class name format depends on whether the value is below or above 1:
+
+| Value | Class name          | Example            |
+| ----- | ------------------- | ------------------ |
+| `0.5` | Drop `0.` prefix    | `gap-05`, `p-025`  |
+| `1.5` | Use literal decimal | `gap-1.5`, `p-1.5` |
+
+Sub-1 values (starting with `0.`) strip the leading zero and decimal point.
+Values ≥ 1 with decimals are escaped in CSS (`.gap-1\.5`) but written with the
+literal decimal in HTML. Do not apply the sub-1 rule to values ≥ 1 — `gap-15`
+is not a valid class for 1.5rem.
+
+## Shorthand
+
+- All-sides padding and margin use `pxy` and `mxy`, not `p` or `m`
+- Directional variants: `px`, `py`, `pt`, `pb`, `pl`, `pr` (and `mx`, `my`, etc.)
+
+## Property = Class Name
+
+Use the CSS property value directly as the class name. Do not prefix with the property name:
+
+- `flex` not `display-flex`
+- `relative` not `position-relative`
+- `hidden` not `display-none`
+
+## Axis Modifiers & Logical Properties
+
+Axis modifiers map to logical properties internally:
+
+| Modifier | Logical property              |
+| -------- | ----------------------------- |
+| `-t`     | `block-start`                 |
+| `-b`     | `block-end`                   |
+| `-l`     | `inline-start`                |
+| `-r`     | `inline-end`                  |
+| `-x`     | `inline-start` + `inline-end` |
+| `-y`     | `block-start` + `block-end`   |
+
+Use logical properties in SCSS (`margin-inline-start`, not `margin-left`).
+Physical properties are only appropriate in explicitly positioned contexts.
+
+## Context-Aware Modifiers
+
+Theme and size modifiers are applied directly to the component, not as
+hyphenated suffixes:
+
+```html +code
+<!-- correct -->
+<button class="btn primary">Submit</button>
+<button class="btn sm">Cancel</button>
+
+<!-- wrong -->
+<button class="btn-primary">Submit</button>
+<button class="btn-sm">Cancel</button>
+```

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

@@ -6,106 +6,108 @@ description: >-
   updated, this skill applies.
 ---
 
-Extends `nk-documentation-best-practices` — apply both, this skill takes
+Apply both this skill and `nk-documentation-best-practices`. This skill takes
 precedence where they conflict.
 
-## Nav Management
+## Documentation Types
 
-Nav lives in `scripts/jtb-nav.json`. Route names follow `docs.jtb.{path}`:
+### Component Documentation
 
-- `docs/components/list.md` → `docs.jtb.components.list`
-- `docs/variable-system.md` → `docs.jtb.variable-system`
+Use for named structural classes such as `navbar`, `menu`, `bx`, or form controls.
 
-Add a new entry to the appropriate group when a doc is confirmed complete.
+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.
 
-## Completion Follow-Through
+**Single-component page structure:**
 
-- Add confirmed doc to `scripts/jtb-nav.json`.
-- Update the relevant row in `docs/jtb-status.md`.
+1. One-line lead
+2. `## Basic Usage` — minimum working markup
+3. Additional `##` sections — simple to fuller usage
+4. `## SCSS Variables` — if the component exposes overridable variables
+5. `## Utility Examples` — utility-based alternatives, always last
 
-## Documentation Locations
+**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.
 
-- **All documentation** → `docs/`
+**Rules:**
 
-## Workflow
+- The lead describes purpose, not implementation. Do not mention specific CSS properties.
+- 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 SCSS Variables directly before Utility Examples.
+- Link to `/docs/jtb/variable-system` for override instructions rather than explaining inline.
 
-- Create new documentation directly in `docs/`.
-- On section confirmation: if the section is in a component or utility doc (not
-  a skill, reference doc, or api doc), ask: "Do you want this added to a
-  showcase?"
-- If yes, add it to the appropriate showcase file before moving on.
+### Utility Documentation
 
-## Showcases
+Use for class-based APIs such as spacing, sizing, border, position, transforms,
+and typography helpers.
 
-Showcases are quick visual references — not comprehensive docs. Three files:
+**Structure:**
 
-- `docs/showcase-typography.md` — font sizes, weights, families, text utilities
-- `docs/showcase-ui.md` — components and UI elements: buttons, badges, checklist, box etc.
-- `docs/showcase-layouts.md` — grid, flex patterns, page structures
+1. Major utility groups as `##` headings when the page covers more than one family
+2. Example groups within those sections as `###` headings when needed
+3. Optional compact table of available properties or value groups
+4. Available values at the end, when useful
 
-Two reasons something belongs in a showcase:
+**Rules:**
 
-1. **Syntax reminder** — enough variations exist that you forget the class names
-2. **Existence reminder** — a single component worth flagging so it doesn't get overlooked
+- Keep utility heading levels parallel.
+- Use a compact table near the top when it helps scan the utility API quickly.
+- Only add notes when behaviour is non-obvious.
+- Group examples by usage, not by SCSS implementation detail.
+- Use `+demo-folded class="bx"` for interactive examples.
 
-Format depends on content type:
+## Code Block Attributes
 
-- **UI components** (`showcase-ui.md`) — use `+demo-folded` so markup is visible and copyable
-- **Typography/syntax** (`showcase-typography.md`) — raw HTML pairing `<code>` class names with output
-- **Layouts** (`showcase-layouts.md`) — case by case
+- `class="..."` → outer demo wrapper class
+- `preview-class="..."` → class applied to the preview container only, keeps copied code clean
+- `+demo` / `+demo-folded` → render preview and code together
 
-Group by component family under `##` headings. Variants sit under `###` within that group.
+For layout/responsive docs, use:
 
-Do not create a new showcase file for a single component — if it doesn't fit the three above, discuss with the user.
+```md
++demo-folded class="resizable-container with-docs-only-overrides"
+```
 
-## Documentation Types
+## Examples Files
 
-### Utility Documentation
+Quick visual references — not comprehensive docs. Two files:
 
-Use for class-based APIs such as spacing, sizing, border, position, transforms, and typography helpers.
+- `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.
 
-Structure:
+Two reasons something belongs in an examples file:
 
-1. Major utility groups as `##` headings when the page covers more than one family
-2. Example groups within those sections as `###` headings when needed
-3. Optional compact table of available properties or value groups
-4. Available values at the end, when useful
+1. **Syntax reminder** — enough variations exist that you forget the class names
+2. **Existence reminder** — a single component worth flagging so it doesn't get overlooked
 
-Rules:
+Format depends on content type:
 
-- Keep utility heading levels parallel.
-- Use a compact table near the top when it helps scan the utility API quickly.
-- Only add notes when behaviour is non-obvious.
-- Group examples by usage, not by SCSS implementation detail.
-- Use `+demo-folded class="bx"` for interactive examples.
-- Use `preview-class="..."` for preview-only layout so copied code stays clean.
-- Use `class="..."` for the outer demo wrapper when the preview needs a container such as `bx`.
+- **UI components** (`showcase-ui.md`) — use `+demo-folded class="bx"` so markup is visible and copyable
+- **Typography/syntax** (`showcase-typography.md`) — raw HTML pairing `<code>` class names with output
 
-### Component Documentation
+Group by component family under `##` headings. Variants sit under `###` within that group.
 
-Use for named structural classes such as `navbar`, `menu`, `bx`, or form controls.
+Do not create a new examples file for a single component. If it does not fit the two above, discuss with the user.
 
-Every component doc must cover:
+When a section of a component or utility doc is complete, ask:
 
-1. What it is — one-line lead
-2. Minimum working markup — shown early with `+code`
-3. Examples — simple to fuller usage
-4. Customisation — variables, modifiers, or overrides
+> Do you want this added to an examples file?
 
-Rules:
+Do not ask this for skill, reference, or API docs.
 
-- The lead describes purpose, not implementation. Do not mention specific CSS properties.
-- Wrap all interactive examples in `class="bx"`.
-- Include an SCSS Variables table when the component exposes overridable variables. Link to `/docs/jtb/variable-system` for override instructions rather than explaining inline.
-- Include a `## Utility Examples` section when a utility-based approach is viable. Lives in the component doc — not a separate file.
+## Nav & Completion
 
-## Code Block Attributes
+Nav lives in `scripts/jtb-nav.json`. Route names follow `docs.jtb.{path}`:
 
-- `class="..."` → outer demo wrapper class
-- `preview-class="..."` → class applied to the preview container
-- `+demo` / `+demo-folded` → render preview and code together
+- `docs/components/list.md` → `docs.jtb.components.list`
+- `docs/variable-system.md` → `docs.jtb.variable-system`
 
-For layout/responsive docs, use `class="resizable-container with-docs-only-overrides"`.
+All documentation lives in `docs/`. Create new documentation directly in `docs/`.
+
+When a doc is confirmed complete:
+
+- Add it to `scripts/jtb-nav.json`.
+- Update the relevant row in `docs/jtb-status.md`.
 
 ## Links
 

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.