nk_jtb 0.26.0 → 0.27.0

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,105 @@ 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.
+**Structure:**
 
-## Completion Follow-Through
+1. One-line lead
+2. `## Basic Usage` — minimum working markup
+3. Additional examples — 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
 
-- Add confirmed doc to `scripts/jtb-nav.json`.
-- Update the relevant row in `docs/jtb-status.md`.
+**Rules:**
 
-## Documentation Locations
+- 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 the SCSS Variables table directly after the class examples, 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.
 
-- **All documentation** → `docs/`
+### Utility Documentation
 
-## Workflow
+Use for class-based APIs such as spacing, sizing, border, position, transforms,
+and typography helpers.
 
-- 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.
+**Structure:**
 
-## Showcases
+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
 
-Showcases are quick visual references — not comprehensive docs. Three files:
+**Rules:**
 
-- `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
+- 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.
 
-Two reasons something belongs in a showcase:
+## Code Block Attributes
 
-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
+- `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
 
-Format depends on content type:
+For layout/responsive docs, use:
 
-- **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
+```md
++demo-folded class="resizable-container with-docs-only-overrides"
+```
 
-Group by component family under `##` headings. Variants sit under `###` within that group.
+## Examples Files
 
-Do not create a new showcase file for a single component — if it doesn't fit the three above, discuss with the user.
+Quick visual references — not comprehensive docs. Two files:
 
-## Documentation Types
+- `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.
 
-### Utility Documentation
+Two reasons something belongs in an examples file:
 
-Use for class-based APIs such as spacing, sizing, border, position, transforms, and typography helpers.
+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
 
-Structure:
+Format depends on content type:
 
-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
+- **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
 
-Rules:
+Group by component family under `##` headings. Variants sit under `###` within that group.
 
-- 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`.
+Do not create a new examples file for a single component. If it does not fit the two above, discuss with the user.
 
-### Component Documentation
+When a section of a component or utility doc is complete, ask:
 
-Use for named structural classes such as `navbar`, `menu`, `bx`, or form controls.
+> Do you want this added to an examples file?
 
-Every component doc must cover:
+Do not ask this for skill, reference, or API docs.
 
-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
+## Nav & Completion
 
-Rules:
+Nav lives in `scripts/jtb-nav.json`. Route names follow `docs.jtb.{path}`:
 
-- 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.
+- `docs/components/list.md` → `docs.jtb.components.list`
+- `docs/variable-system.md` → `docs.jtb.variable-system`
 
-## Code Block Attributes
+All documentation lives in `docs/`. Create new documentation directly in `docs/`.
 
-- `class="..."` → outer demo wrapper class
-- `preview-class="..."` → class applied to the preview container
-- `+demo` / `+demo-folded` → render preview and code together
+When a doc is confirmed complete:
 
-For layout/responsive docs, use `class="resizable-container with-docs-only-overrides"`.
+- Add it to `scripts/jtb-nav.json`.
+- Update the relevant row in `docs/jtb-status.md`.
 
 ## Links
 

package/dev.html

@@ -11,9 +11,64 @@
     <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
 </head>
 
-<body class="container py-5 bg-gray-200">
+<body class="bg-stone-100 pxy-075">
 
+    <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>