nk_jtb 0.25.1 → 0.27.0

package/.ai/prompts/create-documentation.md

@@ -1,7 +1,20 @@
-Create documentation for the `[component].scss` component, following the conventions and architecture rules defined in the JTB documentation.
+Create documentation for `[component]`.
 
-Invoke the `jtb-documentation` skill before starting. Read these in full first
-— these define what is correct:
+Invoke the `jtb-documentation` skill before starting.
 
-- `introduction.md`
-- `docs/conventions-and-architecture-rules.md`
+## Type
+
+[Component / Utility]
+
+## What it does
+
+[One or two sentences describing purpose — not implementation.]
+
+## Cover
+
+[List specific sections or aspects to document, e.g. basic usage, modifiers,
+SCSS variables, utility examples.]
+
+## Notes
+
+[Optional: existing markup, decisions already made, related components.]

package/.ai/prompts/jtb-code-review.md

@@ -1,6 +1,6 @@
 Review the code changes for the NK JTB SCSS framework.
 
-Invoke the `jtb-documentation` skill before starting.
+Invoke the `scss-engineer` and `jtb-documentation` skills before starting.
 
 ## Guidelines
 

package/.ai/prompts/jtb-review-documentation.md

@@ -1,23 +1,20 @@
 Review the documentation for the JTB framework.
 
-Invoke the `jtb-documentation` skill before starting. Read these in full first
-— these define what is correct:
+Invoke the `jtb-documentation` skill before starting. Read these in full first — they define what is correct:
 
 - `introduction.md`
 - `docs/conventions-and-architecture-rules.md`
 
 ## Goals
 
-1. Validate what exists — is documentation correct, consistent, and
-   rule-compliant?
-2. Identify what's missing — what is absent but expected?
+1. Validate what exists — correct, consistent, and rule-compliant?
+2. Identify what's missing — absent but expected?
 
 ## Process
 
-This review runs in three passes:
+Three passes:
 
-1. **Identify** — surface contradictions and gaps. Incomplete docs are expected;
-   flag them without treating incompleteness as a failure.
+1. **Identify** — surface contradictions and gaps. Flag incompleteness without treating it as failure.
 2. **Triage** — decide what's worth pursuing before any work happens.
 3. **Sweep** — act only on approved items.
 
@@ -30,64 +27,40 @@ Review only:
 
 Do not review:
 
-- `src/mixins/` — build system internals
-- `src/functions/` — build system internals
-- `src/base/` — output layer
+- `src/mixins/`, `src/functions/`, `src/base/` — build system internals and output layer
 
 ## Review Questions
 
 ### Validation
 
-1. Do the variable files in `src/maps_and_variables/` match what the
-   conventions doc describes?
+1. Do variable files in `src/maps_and_variables/` match what the conventions doc describes?
 2. Do all final maps follow the `-map` suffix rule?
-3. Is the three-map pattern applied consistently across all variable files?
+3. Is the three-map pattern applied consistently?
 4. Is `smart-merge` order correct — variants first, values second?
-5. Are `!default` flags present where the conventions require them?
-6. Do the breakpoint values in `_base.scss` match what `responsive-design.md`
-   describes?
+5. Are `!default` flags present where required?
+6. Do breakpoint values in `_base.scss` match `responsive-design.md`?
 7. Does `index.scss` forward all expected files?
 
-### Gap Identification
+### Gaps
 
 1. Are there variable files with no corresponding documentation?
-2. Are there conventions described in the docs with no implementation in
-   `src/maps_and_variables/`?
+2. Are there conventions with no implementation in `src/maps_and_variables/`?
 
-## Priority Definitions
+## Priorities
 
-- `critical` — contradicts a source of truth or produces incorrect guidance.
-  Must fix.
-- `high` — likely causes confusion, inconsistency, or future breakage. Should
-  fix.
-- `low` — style, preference, or minor improvement. Fix if you want.
+- `critical` — contradicts a source of truth. Must fix.
+- `high` — likely causes confusion or future breakage. Should fix.
+- `low` — minor improvement. Fix if you want.
 - `missing` — expected content that isn't there.
 
-## Output Requirements
+## Output
 
-- Be direct and critical.
-- Do not praise unnecessarily.
-- Separate findings by type clearly.
-- Suggest improvements with trade-offs.
-- If something is unclear or inconsistent, call it out explicitly.
+Be direct. Do not praise. Call out anything unclear or inconsistent.
 
-Write results to `review-docs-run1.md` in the project root.
-
-Use these sections in order:
-
-- **Confirmed Issues** — rule violations, bugs, mismatches
-- **Gaps** — missing docs, tests, examples, or conventions
-- **Findings** — observations that don't rise to issues
-- **Pass** — if no confirmed issues: `No blocking issues found.`
-
-For every confirmed issue use this format:
+Write results to `review-docs.md` in the project root using these sections:
 
+**Confirmed Issues** — rule violations, bugs, mismatches
 **Issue title** · `critical/high/low`
 `file:line`
 Rule: brief quote
-Fix: one line
-
-For every gap use this format:
-
-**Gap title** · `missing`
-What's absent and where it's expected.
+Fix: on

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>
+```