nk_jtb 0.24.1 → 0.25.1

package/.ai/guidelines/jtb-framework.md

@@ -53,3 +53,10 @@ use `gap` instead.
 - Hardcoded values — use variables
 - Deep nesting — maximum 3 levels
 - `!important` — never use
+
+## Common Pitfalls
+
+- Use JTB class names only.
+- Positional spacing utilities use `pxy` / `mxy`, not `p` / `m`.
+- If a class name is not confirmed in JTB docs or source, stop and check
+  before using it.

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

@@ -0,0 +1,39 @@
+Build `[component]` using JTB utilities.
+
+Invoke the `jtb-layouts-and-structures` skill before starting.
+
+## Output
+
+Check `index.html`.
+
+- If it contains no meaningful content, write there.
+- If it already has content, ask whether to add to it or create a new file.
+
+## Design Reference
+
+[Attach image or describe the component.]
+
+## Responsive Behaviour
+
+[Describe how this should adapt, or leave blank for ai to ask.]
+
+## Target Markup
+
+[Optional: if you have a specific markup structure in mind.]
+
+## Post-Build Report
+
+After building, report only actionable items:
+
+- **Issues** — anything that could not be expressed cleanly in JTB. State the
+  problem and what workaround was used.
+- **Framework Gaps** — utilities, tokens, patterns, or primitives that seem
+  missing, weak, or awkward.
+- **Guideline Gaps** — places where the component-creation guidance or JTB docs
+  were unclear or insufficient.
+- **Skill Gaps** — places where the invoked skill was unclear, insufficient,
+  misleading, or failed to help with a relevant decision.
+- **Recommendations** — concrete, minimal changes worth considering.
+
+Do not report clean decisions or resolved choices unless they expose a real
+problem.

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

@@ -0,0 +1,16 @@
+Add `[utility name]` to the JTB framework.
+
+Invoke the `scss-engineer` and `jtb-documentation` skills before starting.
+
+## What It Does
+
+[Describe the utility and the problem it solves.]
+
+## API
+
+[List the expected class names if known. Leave blank if the API shape needs to
+be worked out.]
+
+## Notes
+
+[Optional constraints, related utilities, or implementation notes.]

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

@@ -1,65 +1,65 @@
-Review the code changes for the NK JTB SCSS framework.
-
-Invoke the `jtb-documentation` skill before starting.
-
-## Guidelines
-
-- **Framework Alignment:** Ensure all code strictly follows JTB conventions,
-  naming, and architecture. Do not use Tailwind or other frameworks as reference
-  for implementation details.
-- **Directory Structure:** Verify files are placed in the correct directories
-  (`base`, `components`, `forms`, `utilities`, `mixins`, `functions`,
-  `maps_and_variables`).
-- **Import Rules:** Only `@use` and `@forward` are permitted. `@import` is
-  prohibited.
-- **Component Structure:** Components should provide structure only, not
-  decoration. Styling must be handled by utilities.
-- **Modifiers:** Only use context-aware modifiers (e.g., `.primary`), never
-  component-specific ones (e.g., `.btn-primary`).
-- **Variables:** All values must use variables or maps — no hardcoded values.
-- **Nesting:** No selector nesting deeper than 3 levels.
-- **Override Order:** Confirm the import order: base → components → forms →
-  utilities.
-- **Documentation:** All new or changed code must be documented using JTB
-  documentation conventions. Drafts go in `docs-for-review/`, finalized docs
-  in `docs/`.
-
-## Review Checklist
-
-1. Does the code follow JTB naming, structure, and logical property conventions?
-2. Are all values variable-driven and override-friendly?
-3. Is the code placed in the correct directory and imported in the right order?
-4. Is documentation provided or updated as required?
-
-Provide clear, actionable feedback. If you suggest changes, reference the
-specific JTB documentation section or rule.
-
-## Skill File Review
-
-When any source-of-truth files are included in the changeset, review them for
-accuracy against the actual codebase.
-
-**Accuracy**
-
-- Do the documented conventions match how the SCSS actually works?
-- Are examples valid and runnable — not invented or outdated?
-- Do file paths, class names, and patterns reflect the real codebase?
-
-**Completeness**
-
-- Are new patterns or workflows introduced in this changeset documented?
-- Are deprecated patterns removed or flagged?
-
-**Internal Consistency**
-
-- Do the files agree with each other? Flag contradictions between skill files
-  and documentation.
-- Does a change in one file require an update in another?
-
-**Scope Drift**
-
-- Do changes silently expand or restrict the skill scope without clear intent?
-
-**Output Format:**
-List issues grouped by file. For each issue: severity (blocking/suggestion),
-the violated rule, and a suggested fix.
+Review the code changes for the NK JTB SCSS framework.
+
+Invoke the `jtb-documentation` skill before starting.
+
+## Guidelines
+
+- **Framework Alignment:** Ensure all code strictly follows JTB conventions,
+  naming, and architecture. Do not use Tailwind or other frameworks as reference
+  for implementation details.
+- **Directory Structure:** Verify files are placed in the correct directories
+  (`base`, `components`, `forms`, `utilities`, `mixins`, `functions`,
+  `maps_and_variables`).
+- **Import Rules:** Only `@use` and `@forward` are permitted. `@import` is
+  prohibited.
+- **Component Structure:** Components should provide structure only, not
+  decoration. Styling must be handled by utilities.
+- **Modifiers:** Only use context-aware modifiers (e.g., `.primary`), never
+  component-specific ones (e.g., `.btn-primary`).
+- **Variables:** All values must use variables or maps — no hardcoded values.
+- **Nesting:** No selector nesting deeper than 3 levels.
+- **Override Order:** Confirm the import order: base → components → forms →
+  utilities.
+- **Documentation:** All new or changed code must be documented using JTB
+  documentation conventions. Drafts go in `docs-for-review/`, finalized docs
+  in `docs/`.
+
+## Review Checklist
+
+1. Does the code follow JTB naming, structure, and logical property conventions?
+2. Are all values variable-driven and override-friendly?
+3. Is the code placed in the correct directory and imported in the right order?
+4. Is documentation provided or updated as required?
+
+Provide clear, actionable feedback. If you suggest changes, reference the
+specific JTB documentation section or rule.
+
+## Skill File Review
+
+When any source-of-truth files are included in the changeset, review them for
+accuracy against the actual codebase.
+
+**Accuracy**
+
+- Do the documented conventions match how the SCSS actually works?
+- Are examples valid and runnable — not invented or outdated?
+- Do file paths, class names, and patterns reflect the real codebase?
+
+**Completeness**
+
+- Are new patterns or workflows introduced in this changeset documented?
+- Are deprecated patterns removed or flagged?
+
+**Internal Consistency**
+
+- Do the files agree with each other? Flag contradictions between skill files
+  and documentation.
+- Does a change in one file require an update in another?
+
+**Scope Drift**
+
+- Do changes silently expand or restrict the skill scope without clear intent?
+
+**Output Format:**
+List issues grouped by file. For each issue: severity (blocking/suggestion),
+the violated rule, and a suggested fix.

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

@@ -1,93 +1,93 @@
-Review the documentation for the JTB framework.
-
-Invoke the `jtb-documentation` skill before starting. Read these in full first
-— these 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?
-
-## Process
-
-This review runs in three passes:
-
-1. **Identify** — surface contradictions and gaps. Incomplete docs are expected;
-   flag them without treating incompleteness as a failure.
-2. **Triage** — decide what's worth pursuing before any work happens.
-3. **Sweep** — act only on approved items.
-
-## Scope
-
-Review only:
-
-- `docs/` — all foundational documentation
-- `src/maps_and_variables/` — all variable and configuration files
-
-Do not review:
-
-- `src/mixins/` — build system internals
-- `src/functions/` — build system internals
-- `src/base/` — output layer
-
-## Review Questions
-
-### Validation
-
-1. Do the 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?
-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?
-7. Does `index.scss` forward all expected files?
-
-### Gap Identification
-
-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/`?
-
-## Priority Definitions
-
-- `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.
-- `missing` — expected content that isn't there.
-
-## Output Requirements
-
-- 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.
-
-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:
-
-**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.
+Review the documentation for the JTB framework.
+
+Invoke the `jtb-documentation` skill before starting. Read these in full first
+— these 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?
+
+## Process
+
+This review runs in three passes:
+
+1. **Identify** — surface contradictions and gaps. Incomplete docs are expected;
+   flag them without treating incompleteness as a failure.
+2. **Triage** — decide what's worth pursuing before any work happens.
+3. **Sweep** — act only on approved items.
+
+## Scope
+
+Review only:
+
+- `docs/` — all foundational documentation
+- `src/maps_and_variables/` — all variable and configuration files
+
+Do not review:
+
+- `src/mixins/` — build system internals
+- `src/functions/` — build system internals
+- `src/base/` — output layer
+
+## Review Questions
+
+### Validation
+
+1. Do the 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?
+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?
+7. Does `index.scss` forward all expected files?
+
+### Gap Identification
+
+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/`?
+
+## Priority Definitions
+
+- `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.
+- `missing` — expected content that isn't there.
+
+## Output Requirements
+
+- 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.
+
+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:
+
+**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.

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

@@ -1,13 +1,18 @@
 ---
 name: jtb-conversion
 description: >-
-  Use this skill whenever applying or converting to NK JTB classes and
-  components, regardless of the source — Tailwind, custom CSS, plain HTML,
-  PHP, JS, or any other context. Do not wait for an explicit request — if JTB
-  classes or components are being applied or converted, this skill applies.
+  Use this skill whenever translating an existing implementation into NK JTB
+  classes and components — for example from Tailwind, custom CSS, plain HTML,
+  PHP, JS, or another framework. Do not wait for an explicit request — if
+  there is a source implementation that needs to be converted into JTB, this
+  skill applies.
 ---
 
-For layout decisions during conversion, invoke the `jtb-layout` skill.
+Do not use this skill for greenfield JTB component builds, design-to-code work
+from screenshots/mockups, or general component composition from scratch.
+
+For layout decisions during conversion, invoke the
+`jtb-layouts-and-structures` skill.
 
 If the output file is not specified, ask before proceeding.
 

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

@@ -88,8 +88,8 @@ Rules:
 - Keep review notes, implementation commentary, and TODOs out of the main doc.
 - Group examples by usage, not by SCSS implementation detail.
 - Use `+demo-folded class="bx"` for interactive examples.
-- Use `preview-class="..."` for preview-only layout or styling so copied code
-  stays clean.
+- Use `preview-class="..."` for visual aids in the docs so they do not affect
+  the code being copied.
 - Use `class="..."` for the outer demo wrapper when the preview needs a
   container such as `bx`.
 

package/.ai/skills/jtb-layouts-and-structures/SKILL.md

@@ -0,0 +1,70 @@
+---
+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.
+
+## Decision Order
+
+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
+   - `container-*` for width and placement
+3. Check whether JTB already provides an approved magic or composite class that
+   reduces responsive noise for the pattern you need.
+4. Build mobile-first. Add explicit `{bp}:` responsive utilities only when no
+   documented higher-level pattern expresses the layout cleanly.
+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.
+- 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.
+- Do not split `container`, padding, and grid/flex across extra wrappers unless
+  one of those concerns genuinely needs its own box.
+- Put shared layout/presentation utilities on the highest valid parent. Only
+  repeat them on children when a child genuinely needs a different value.
+- Treat `container-*` as a layout primitive with built-in inline gutter. Do not
+  add extra horizontal padding on the same element.
+- Let the component own its internal padding. Use the container for width and
+  placement only.
+- Default section rhythm:
+  - `py-4-3-2` for standard sections
+  - `py-5-3-2` for more prominent sections
+- 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/scss-engineer/SKILL.md

@@ -9,8 +9,45 @@ description: >-
 
 Read `docs/conventions-and-architecture-rules.md` before starting.
 
+## General Rules
+
+- Check existing source, docs, and `framework-status.md` before adding a new
+  framework API so you extend or formalise instead of duplicating.
+- If formalising an existing helper requires a structural decision, stop and
+  discuss it before proceeding. Examples: doc home, utility family scope, and
+  what to do with related experimental variants.
+- Do not invent variants, scales, or an expanded utility family. If the work
+  suggests them, stop and discuss the API first. Default to the smallest useful
+  addition.
+- Extend an existing domain file in `src/utilities/` or `src/components/`
+  before creating a new partial.
+- Prefer the build system (`build-classes`, `build-composite-classes`,
+  `child-combinator`) over hand-written selectors when the pattern fits.
+- Add or extend variables/maps in `src/maps_and_variables/` only when the new
+  API needs reusable configuration or scale values.
+
 ## Component Workflow
 
-1. Add variables to `src/maps_and_variables/_components.scss`.
-2. Create the component file in `src/components/`.
-3. Export via `src/components/index.scss`.
+1. Add variables to `src/maps_and_variables/_components.scss` only if the
+   component needs framework-level configuration.
+2. Create or update the component file in `src/components/`.
+3. Export via `src/components/index.scss` if this is a new component file.
+4. Invoke `jtb-documentation` to document the component.
+5. Update `framework-status.md` when the component or its docs change status.
+
+## Utility Workflow
+
+1. Choose the correct existing utility partial in `src/utilities/`. Create a
+   new partial only when the utility introduces a new domain.
+2. If the utility fits the build system, implement it with `build-classes` or
+   `build-composite-classes` rather than ad hoc selectors.
+3. Use `child-combinator` for direct-child utilities such as spacing or
+   dividers instead of duplicating selector logic by hand.
+4. Add or extend variables/maps only when the utility exposes real framework
+   configuration. Fixed helpers can stay local to the utility partial.
+5. If the utility already exists as an informal helper, formalise or migrate it
+   instead of creating a duplicate implementation.
+6. Keep related variants together in the same domain partial. Do not formalise
+   one variant while leaving related variants behind in a different home.
+7. Invoke `jtb-documentation` to document the utility.
+8. Update `framework-status.md` when the utility or its docs change status.