nk_jtb 0.27.1 → 0.27.3

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

@@ -6,26 +6,15 @@ description: >-
   updated, this skill applies.
 ---
 
-Apply both this skill and `nk-documentation-best-practices`. This skill takes
+Extends `nk-documentation-best-practices` — apply both, this skill takes
 precedence where they conflict.
 
 ## Documentation Types
 
 ### Component Documentation
 
-Use for named structural classes such as `navbar`, `menu`, `bx`, or form controls.
-
-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 `##` sections — simple to fuller usage
-4. `## SCSS Variables` — if the component exposes overridable variables
-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.
+Follow the shared component-doc rules in `nk-documentation-best-practices` first.
+Then apply these JTB-specific additions.
 
 **Rules:**
 
@@ -33,7 +22,7 @@ A class-based component has a named CSS class (e.g. `.spinner`, `.accordion`) th
 - 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.
+- Place `## SCSS Variables` directly before `## Utility Examples`.
 - Link to `/docs/jtb/variable-system` for override instructions rather than explaining inline.
 
 ### Utility Documentation
@@ -120,7 +109,3 @@ Base path is `/docs/jtb/` + directory and filename without extension:
 
 - `docs/components/list.md` → `/docs/jtb/components/list`
 - `docs/variable-system.md` → `/docs/jtb/variable-system`
-
-## Formatting Rules
-
-- **No `<hr>` in demo markup** — never use horizontal rules in examples

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

@@ -4,61 +4,39 @@ Page loaders and spinners to communicate in-progress and waiting states.
 
 ## Spinners
 
-The `.spinner` class provides a CSS-only animated border spinner.
+### SVG Arc
 
-### Border Spinner
+Apply `animate-spin` to an SVG with a dashed stroke to create a spinner.
 
-Apply the `.spinner` class to a `div` for an animated loading indicator.
+Use `wh-*` utilities to control size.
 
-#### 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">
+```html +demo-folded class="bx example-utils" preview-class="flex-centered vac gap-2"
+<svg class="animate-spin wh-2" 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-3" 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-4" 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.
+Use `txt-*` utilities to control colour.
 
 ```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">
+<svg class="animate-spin wh-2 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">
+<svg class="animate-spin wh-2 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">
+<svg class="animate-spin wh-2 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>
@@ -68,18 +46,3 @@ Use text color utilities to control the spinner color.
 
 `.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,16 +1,5 @@
 # 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,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 | Border Spinner confirmed. Loader Container, CSS Custom Properties, SVG Arc utility example still pending. |
+| `components/loaders-and-spinners.md` | partial | Spinners section confirmed (SVG Arc utility approach). Loader Container still pending. |
 | `components/example-navigations.md` | stub    | Bare HTML, no explanation                        |
 
 ### Utilities

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "nk_jtb",
     "description": "Yet another utility based framework.",
-    "version": "0.27.1",
+    "version": "0.27.3",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/naykel76/nk_jtb.git"

package/skills-lock.json

@@ -5,7 +5,7 @@
       "source": "naykel76/skills-and-guidelines",
       "sourceType": "github",
       "skillPath": "code-review/SKILL.md",
-      "computedHash": "80927ef183fc7c52837e829dcffa37c3b737f7570d56a259bd2e31ce6627b31d"
+      "computedHash": "83753a3d13c03a429372077ba6e6f0f98d4bad1b448d5b4bc0dbe0f45acfad04"
     },
     "grill-me": {
       "source": "naykel76/skills-and-guidelines",
@@ -23,7 +23,7 @@
       "source": "naykel76/skills-and-guidelines",
       "sourceType": "github",
       "skillPath": "nk-documentation-best-practices/SKILL.md",
-      "computedHash": "ba3237364f6aac95b43c792df0a363e2b83fb9f4c0c4a3cc68b83071e793a600"
+      "computedHash": "ad8bdd5e8b52cd29d50caf9a1be1615fd107e37b1b00114e4447f3656b22f956"
     },
     "skill-creation": {
       "source": "naykel76/skills-and-guidelines",

package/src/base/_root.scss

@@ -2,16 +2,6 @@
 @use '../maps_and_variables/colors' as *;
 @use '../maps_and_variables/components' as *;
 @use '../maps_and_variables/typography' as *;
-@use '../functions/color-functions' as *;
-@use 'sass:map';
-
-@mixin define-runtime-theme-vars($theme-name, $theme-color) {
-    --#{$theme-name}: #{$theme-color};
-    --#{$theme-name}-hover: color-mix(in srgb, var(--#{$theme-name}), white 5%);
-    --#{$theme-name}-active: color-mix(in srgb, var(--#{$theme-name}), black 5%);
-    --#{$theme-name}-border: #{border-contrast($theme-color)};
-    --on-#{$theme-name}: #{text-color($theme-color)};
-}
 
 :root {
     // create css variables including brand colors
@@ -47,10 +37,10 @@
     --bg-toggle-on: var(--primary);
     --bg-toggle-ball: var(--white);
 
-    // -- Runtime Semantic Theme Colors --
-    @each $theme-name in $runtime-theme-colors {
-        @include define-runtime-theme-vars($theme-name, map.get($base-colors, $theme-name));
-    }
+    // -- Brand Colors --
+    --primary: #{$primary};
+    --secondary: #{$secondary};
+    --accent: #{$accent};
 
     // -- Text Colors --
     --text-color: #{$text-color};

package/src/components/_button.scss

@@ -37,13 +37,6 @@
         opacity: 0.5;
     }
 
-    // ICON SUPPORT
-    > svg,
-    > i {
-        flex-shrink: 0; // prevent the icon from shrinking when button resizes or text wraps
-        height: var(--icon-size, 1em); // match the icon height to the button's font-size for automatic scaling
-        width: var(--icon-size, 1em); // match the icon width to the button's font-size for consistent sizing
-    }
 
     &:where(.xs) {
         padding-inline: 0.625rem;
@@ -80,6 +73,14 @@
     }
 }
 
+// ICON SUPPORT — :where() gives zero specificity so wh-* utilities can override
+:where(.#{$button-prefix}) > svg,
+:where(.#{$button-prefix}) > i {
+    flex-shrink: 0;
+    height: var(--icon-size, 1em);
+    width: var(--icon-size, 1em);
+}
+
 // ============================================================================
 // -- THEMES AND VARIATIONS --
 // ============================================================================
@@ -108,19 +109,3 @@
         @include active($color);
     }
 }
-
-@each $theme-name in $runtime-theme-colors {
-    .#{$button-prefix}.#{$theme-name} {
-        &:hover {
-            background-color: var(--#{$theme-name}-hover);
-            border-color: var(--#{$theme-name}-border);
-            color: var(--on-#{$theme-name});
-        }
-
-        &:active {
-            background-color: var(--#{$theme-name}-active);
-            border-color: var(--#{$theme-name}-border);
-            color: var(--on-#{$theme-name});
-        }
-    }
-}

package/src/components/_loaders-and-spinners.scss

@@ -1,43 +1,9 @@
-.spinner {
-    --size: 2.5rem;
-    --thickness: 0.08;
-
-    animation: spin 1.5s linear infinite;
-    border: calc(var(--size) * var(--thickness)) solid #f3f3f3;
-    border-radius: 50%;
-    border-top: calc(var(--size) * var(--thickness)) solid #3498db;
-    height: var(--size);
-    width: var(--size);
-
-    &.sm {
-        --size: 1.25rem;
-    }
-
-    &.lg {
-        --size: 5rem;
-    }
-
-    &.thick {
-        --thickness: 0.15;
-    }
-}
-
 .loader-container {
     align-items: center;
     display: flex;
     flex-direction: column;
     justify-content: center;
 
-    .spinner {
-        animation: spin 1.5s linear infinite;
-        border: 4px solid rgb(255 255 255 / 30%);
-        border-radius: 50%;
-        border-top-color: #fff;
-        height: 60px;
-        margin: 0 auto 20px;
-        width: 60px;
-    }
-
     .loading-text {
         color: #fff;
         font-size: 18px;

package/src/maps_and_variables/_colors.scss

@@ -51,10 +51,6 @@ $theme-colors: (
     'warning': #ffdd57
 ) !default;
 
-// Semantic theme names that should remain runtime-swappable via CSS custom
-// properties. Hue and scale colors stay compile-time tokens.
-$runtime-theme-colors: ('primary', 'secondary', 'accent') !default;
-
 // based on Tailwind 500 series colors
 $base-colors: (
     'primary': base.$primary,

package/src/utilities/_backgrounds.scss

@@ -22,18 +22,4 @@ $background-color-properties: (
     )
 );
 
-$runtime-background-colors: ();
-
-@each $theme-name in $runtime-theme-colors {
-    $runtime-background-colors: map.set($runtime-background-colors, $theme-name, var(--#{$theme-name}));
-}
-
-$runtime-background-color-properties: (
-    background-color: (
-        prefix: 'bg-',
-        values: $runtime-background-colors
-    )
-);
-
 @include build-classes($background-color-properties, $responsive: false, $with-state: true);
-@include build-classes($runtime-background-color-properties, $responsive: false, $with-state: true);

package/src/utilities/_border.scss

@@ -51,23 +51,6 @@ $divider-properties-map: (
     )
 ) !default;
 
-$runtime-border-colors: ();
-
-@each $theme-name in $runtime-theme-colors {
-    $runtime-border-colors: map.set($runtime-border-colors, $theme-name, var(--#{$theme-name}));
-}
-
-$runtime-border-properties-map: (
-    border-color: (
-        prefix: #{$border-prefix},
-        values: $runtime-border-colors
-    ),
-    outline-color: (
-        prefix: 'outline-',
-        values: $runtime-border-colors
-    )
-);
-
 .divide-y-gradient > :not(:last-child) {
     border-block-end-width: 3px;
     border-image-slice: 1;
@@ -85,5 +68,4 @@ $runtime-border-properties-map: (
 // Builds
 // ============================================================================
 @include build-classes($border-properties-map, $responsive: true);
-@include build-classes($runtime-border-properties-map, $responsive: true);
 @include build-composite-classes($divider-properties-map, $responsive: true);

package/src/utilities/_themes.scss

@@ -50,22 +50,3 @@ $themes-map: ();
 @each $color, $value in map.merge($base-colors, $theme-colors) {
     @include build-outline-theme('#{$color}-outline', $value);
 }
-
-@each $theme-name in $runtime-theme-colors {
-    .#{$theme-name} {
-        background-color: var(--#{$theme-name});
-        border: 1px solid var(--#{$theme-name}-border);
-        color: var(--on-#{$theme-name});
-    }
-
-    .#{$theme-name}-outline {
-        background-color: transparent;
-        border: 1px solid var(--#{$theme-name});
-        color: var(--#{$theme-name});
-
-        &:hover:not(:disabled, .disabled) {
-            background-color: var(--#{$theme-name});
-            color: var(--on-#{$theme-name});
-        }
-    }
-}

package/src/utilities/_typography.scss

@@ -124,23 +124,8 @@ $text-classes-map: (
     )
 );
 
-$runtime-text-colors: ();
-
-@each $theme-name in $runtime-theme-colors {
-    $runtime-text-colors: map.set($runtime-text-colors, $theme-name, var(--#{$theme-name}));
-}
-
-$runtime-typography-properties-map: (
-    color: (
-        prefix: '#{$text-prefix}',
-        values: $runtime-text-colors,
-        states: ('hover', 'focus')
-    )
-);
-
 // ============================================================================
 // BUILDS
 // ============================================================================
 @include build-classes($typography-properties-map, $responsive: true);
-@include build-classes($runtime-typography-properties-map, $responsive: true);
 @include build-composite-classes($text-classes-map, $responsive: true);

package/tasks.md

@@ -6,14 +6,8 @@ now, it goes here before the topic changes.
 
 ## Planned
 
-- **Complete `loaders-and-spinners.md`** — three sections still pending:
+- **Complete `loaders-and-spinners.md`** — one section still pending:
   - `## Loader Container (review)` — needs proper content, currently just a one-liner pointing to UI examples
-  - `## CSS Custom Properties (review)` — content exists, needs confirmation; also has an inline style in the code example that should be a local helper
-  - `### SVG Arc` utility example — base demo done, intro sentence still missing
-- **Fix `.spinner` SCSS** — three issues in `src/components/_loaders-and-spinners.scss`:
-  - `border-top` → `border-block-start` (physical property)
-  - Hardcoded colours (`#f3f3f3`, `#3498db`) — add CSS custom properties for track and accent colour
-  - `.loader-container .spinner` abandons the variable system — hardcodes `60px`, `4px`, `margin: 0 auto 20px`
 
 ## Parked
 
@@ -23,6 +17,5 @@ now, it goes here before the topic changes.
 
 - **JTB nav is authored in `nk_jtb`** — keep the nav file updated there as the
   source of truth, then copy it into the Laravel docs app when needed.
-- **`loaders-and-spinners.md` structure** — `## Spinners` currently wraps only `### Border Spinner`. Consider flattening once the full page is settled (would shift `###` sections back to `##`).
-- **SVG Arc approach decided** — uses two-circle stroke pattern (track circle at 25% opacity + arc circle). No local CSS needed beyond `animate-spin`. `stroke-linecap="butt"` for square ends, `stroke-dasharray="22 66"` for quarter-arc. The fill-based two-path SVG and the `@keyframes dash` approach were both considered and set aside.
-- **`jtb-conversion-notes.md`** — open gaps recorded there: positional border-color (`bdr-t-{color}` not generated), `flex-shrink: 0` no utility, percentage widths not in scale, spinner colour theming, icon-only button variant.
+- **Spinner approach decided** — no `.spinner` component class. SVG Arc utility pattern only: two-circle stroke approach (`stroke-opacity="0.25"` track + `stroke-dasharray="22 66"` arc, `stroke-linecap="butt"`). Size via `wh-*`, colour via `txt-*`. CSS border spinner and `@keyframes dash` approaches considered and set aside.
+- **`jtb-conversion-notes.md`** — open gaps recorded there: positional border-color (`bdr-t-{color}` not generated), `flex-shrink: 0` no utility, percentage widths not in scale, icon-only button variant.