nk_jtb 0.23.0 → 0.24.0

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

@@ -0,0 +1,55 @@
+# NK JTB Framework
+
+NK JTB (NayKel Just the Basics) is a utility-based SCSS/CSS framework — a
+lightweight Tailwind-like alternative. Components provide structure; utilities
+add styling.
+
+> JTB follows similar principles to Tailwind but has different naming
+> conventions and uses logical properties. Always refer to JTB documentation for
+> correct scales, breakpoints, and class names. Tailwind values are intent
+> references only — never direct mappings.
+
+## Naming Conventions
+
+- **Numbers = rem** — `m-1` = 1rem, `p-2` = 2rem, `gap-05` = 0.5rem (sub-1
+  values drop the leading zero and decimal)
+- **Property = class name** — use `relative`, `sticky`, `flex` directly. Never
+  `position-relative` or `display-flex`
+- **Axis modifiers** — `-t`, `-b`, `-l`, `-r`, `-x`, `-y` map to logical
+  properties internally (e.g. `-t` → `block-start`, `-l` → `inline-start`)
+- **Context-aware modifiers** — `.primary`, `.xs`, `.rounded` adapt to their
+  component. Use `<button class="btn primary">` not `.btn-primary`
+- **Logical properties by default** — use logical properties
+  (`margin-inline-start`) not physical (`margin-left`). Physical properties only
+  in explicitly positioned contexts
+
+## Responsive Prefixes
+
+Three distinct prefix types — do not substitute one for another:
+
+- **`{bp}:`** (e.g. `md:flex`) — applies from breakpoint upward. Primary pattern
+  for progressive layout and styling
+- **`to-{bp}:`** (e.g. `to-md:hidden`) — applies below breakpoint. Use for
+  visibility windows
+- **`on-{bp}:`** (e.g. `on-md:hidden`) — applies only within that breakpoint
+  range, non-cascading. Use for exact-range targeting
+
+`on-` and `to-` are only generated for `display` and `visibility` utilities —
+this is intentional. Use mixins for custom responsive behavior on other
+properties.
+
+## Auto Spacing
+
+The framework automatically adds `margin-block-start` between content elements.
+Do not manually add top margins between standard content elements — the spacing
+system handles it. Elements inside flex or grid containers have margins reset;
+use `gap` instead.
+
+## Prohibited Patterns
+
+- `@import` — use `@use` / `@forward`
+- Component-specific modifiers like `.btn-primary` — use `<button class="btn
+  primary">`
+- Hardcoded values — use variables
+- Deep nesting — maximum 3 levels
+- `!important` — never use

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

@@ -0,0 +1,7 @@
+Create documentation for the `[component].scss` component, following the conventions and architecture rules defined in the JTB documentation.
+
+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`

package/{.opencode/prompt-code-review.md → .ai/prompts/jtb-code-review.md}

@@ -1,73 +1,65 @@
-# Code Review Prompt for NK JTB SCSS Framework
-
-Before reviewing, load and read these files in full:
-
-- `AGENTS.md`
-- `SKILL.md`
-- `scss-engineer.md`
-- `working-with-nathan.md`
--
-
-You are reviewing code for the NK JTB SCSS Framework. Please follow these
-guidelines:
-
-- **Framework Alignment:** Ensure all code strictly follows the JTB conventions,
-  naming, and architecture as described in the documentation. 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:** Check that only `@use` and `@forward` are used for imports.
-  `@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 the 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. Are all prohibited patterns (see AGENTS.md) avoided?
-5. Is documentation provided or updated as required?
-
-Provide clear, actionable feedback. If you suggest changes, reference the
-specific JTB documentation section or rule.
-
-## Skill & Agent File Review
-
-When any of the 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 PR documented?
-- Are deprecated patterns removed or flagged?
-
-**Internal Consistency**
-
-- Do the files agree with each other? Flag any contradictions between
-  `scss-engineer.md`, `SKILL.md`, `AGENTS.md`, and `working-with-nathan.md`
-- Does a change in one file require an update in another?
-
-**Scope Drift**
-
-- Do changes silently expand or restrict the agent/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/{.opencode/prompt-review-component-utility.md → .ai/prompts/jtb-review-component.md}

@@ -1,15 +1,11 @@
-# JTB Component/Utility Review
+Review the `[component]` component.
 
-Review the menu component.
-
-Before reviewing, load and read these files in full:
-
-- `AGENTS.md`
-- `docs/conventions-and-architecture-rules.md`
+Invoke the `jtb-documentation` skill before starting. Read
+`docs/conventions-and-architecture-rules.md` in full.
 
 ## Scope
 
-Review only the named target and its directly related docs/examples.
+Review only the named target and its directly related docs and examples.
 
 ## Review Questions
 
@@ -17,8 +13,8 @@ Review only the named target and its directly related docs/examples.
 2. Does the code follow JTB rules and conventions?
 3. Does it match the JTB philosophy and architecture rules?
 4. Are there any mismatches between docs and code?
-5. Are there any prohibited patterns from `AGENTS.md` in this target?
-6. Are there target-level bugs/regressions visible?
+5. Are there any prohibited patterns in this target?
+6. Are there target-level bugs or regressions visible?
 
 ## Priority Definitions
 
@@ -34,7 +30,7 @@ Review only the named target and its directly related docs/examples.
 - Suggest improvements with trade-offs.
 - If something is unclear or inconsistent, call it out explicitly.
 
-Write results to `review-[target].md` in the project root.
+Write results to `review-[component].md` in the project root.
 
 Use these sections in order:
 

package/{.opencode/prompt-review-documentation.md → .ai/prompts/jtb-review-documentation.md}

@@ -1,17 +1,11 @@
-# JTB Documentation Review
-
 Review the documentation for the JTB framework.
 
-Load and read these in full first. These define what is correct:
+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`
 
-Also load:
-
-- `AGENTS.md` — intended source of truth, but flag any contradictions with the
-  above.
-
 ## Goals
 
 1. Validate what exists — is documentation correct, consistent, and
@@ -27,8 +21,6 @@ This review runs in three passes:
 2. **Triage** — decide what's worth pursuing before any work happens.
 3. **Sweep** — act only on approved items.
 
----
-
 ## Scope
 
 Review only:
@@ -42,8 +34,6 @@ Do not review:
 - `src/functions/` — build system internals
 - `src/base/` — output layer
 
----
-
 ## Review Questions
 
 ### Validation
@@ -64,13 +54,8 @@ Do not review:
 2. Are there conventions described in the docs with no implementation in
    `src/maps_and_variables/`?
 
----
-
 ## Priority Definitions
 
-> Priorities are tentative in early passes — they guide triage, not final
-> decisions.
-
 - `critical` — contradicts a source of truth or produces incorrect guidance.
   Must fix.
 - `high` — likely causes confusion, inconsistency, or future breakage. Should
@@ -78,8 +63,6 @@ Do not review:
 - `low` — style, preference, or minor improvement. Fix if you want.
 - `missing` — expected content that isn't there.
 
----
-
 ## Output Requirements
 
 - Be direct and critical.

package/.ai/prompts/misc.md

@@ -0,0 +1,18 @@
+I have been working on the `jtb-documentation` skill at
+C:\Users\natha\sites\nk_jtb\.ai\skills\jtb-documentation\SKILL.md. Read it
+before we start.
+
+I want to continue refining skills, guidelines, and framework documentation.
+
+The next few threads I want to pull on:
+
+- Utility Documentation section in the skill — never discussed, needs review
+
+- Utility-based examples alongside class-based component docs — how to structure
+  and where they live. For example, the checklist component is a good candidate
+  for a utility-based example, but where does it go? Does it live in the
+  component doc, or do we create a separate utility-based example doc?
+
+- Variable system document. I think this is full of rubbish and hard to make
+  sense of. needs a rethink and rewrite. maybe it should be a living document
+  that we update as we go, rather than trying to get it right in one go?

package/{.opencode/skills/tailwind-to-jtb → .ai/skills/jtb-conversion}/SKILL.md

@@ -1,40 +1,39 @@
 ---
-name: tailwind-to-jtb
-description: Convert Tailwind-oriented HTML and class usage to NK JTB framework classes and documented patterns. Use when updating markup that currently uses Tailwind classes, arbitrary values, or Tailwind-style responsive/layout conventions and the goal is to express the same intent with JTB.
+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.
 ---
 
-Read `AGENTS.md` first. For responsive or layout conversion, read:
+For layout decisions during conversion, invoke the `jtb-layout` skill.
 
-- `docs/responsive-design.md`
-- `docs/conventions-and-architecture-rules.md`
-- `docs/layer-system.md`
+If the output file is not specified, ask before proceeding.
 
 ## Conversion Order (review)
 
-1. Replace Tailwind classes with documented JTB utilities or components.
+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 Tailwind value.
+   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 any imperfect token match or missing framework support in a root-level
-   notes file for review.
+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 (review)
 
-- Treat Tailwind classes as intent references, not direct mappings.
+- 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.
 - Prefer documented JTB scales, breakpoints, and logical-property utilities.
-- When replacing `max-w-* mx-auto px-*` wrappers, check whether a `container-*`
-  utility already expresses the same intent without extra horizontal padding.
-- For normal page sections, prefer `container` first.
-- Only step up to a `container-*` variant when the page type or reading width
-  clearly calls for it.
-- Keep padding ownership on the section or component where possible. Use the
-  container for width, not as the default home for reusable section spacing.
-- When a section uses a common responsive rhythm, prefer the documented magic
-  class pattern such as `py-4-3-2` or `py-5-3-2` instead of expanding the same
-  breakpoint sequence by hand.
 - Prefer framework components when the structure already matches what they
   provide. Common examples include `navbar`, `bx`, `bx-header`, `bx-content`,
   `bx-footer`, and `divide-y`.
@@ -49,22 +48,20 @@ Read `AGENTS.md` first. For responsive or layout conversion, read:
   styling.
 - Prefer semantic utility tokens such as `txt-muted` when they match the intent,
   instead of repeatedly assembling the same low-level token combination.
-- If JTB cannot express a requirement, prefer a small reusable local helper
-  class over repeating the same inline styles across multiple elements.
+- If 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.
 - 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.
-- Use `{bp}:` for progressive changes.
-- Use `to-` / `on-` for visibility windows.
-- Keep visibility logic consistent within the same layout shell.
 - Do not create new classes just to make a single conversion easier.
 
 ## Review Checklist (review)
 
-- Remove Tailwind-only syntax such as arbitrary value classes where a JTB
+- Remove source-only syntax such as arbitrary value classes where a JTB
   utility exists.
 - Check whether an existing component expresses the structure more cleanly than
   rebuilding it with low-level utilities.
@@ -74,6 +71,6 @@ Read `AGENTS.md` first. For responsive or layout conversion, read:
   local helper instead.
 - Remove classes that only restate the default behavior.
 - Check whether a nearby JTB token is acceptable before creating custom CSS.
-- Document missing utilities or unsupported patterns in a root-level notes file.
+- Document missing utilities or unsupported patterns in
+  `jtb-conversion-notes.md`.
 - Flag framework gaps that should become docs or utilities later.
-

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

@@ -0,0 +1,174 @@
+---
+name: jtb-documentation
+description: >-
+  Use this skill whenever creating or updating NK JTB framework documentation.
+  Do not wait for an explicit request — if documentation is being created or
+  updated, this skill applies.
+---
+
+## Documentation Locations
+
+- **All documentation** → `docs/`
+
+## Workflow
+
+- Create new documentation directly in `docs/`.
+- Mark every new heading with `(review)` until its content is confirmed.
+- When you update a section carrying `(review)`, ask: "[Section name] has been
+  updated. Is this section complete?"
+- On confirmation: remove the `(review)` tag. If the confirmed 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.
+- Leave `(review)` on any headings that are still unresolved.
+
+## Showcases
+
+Showcases are quick visual references — not comprehensive docs. There are three
+showcase files:
+
+- `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
+
+Two reasons something belongs in a showcase:
+
+1. **Syntax reminder** — enough variations exist that you forget the class names
+   (border, typography)
+2. **Existence reminder** — a single component worth flagging so it doesn't get
+   overlooked (checklist)
+
+Showcase entries have no explanation — just enough to jog memory. Format depends
+on content type:
+
+- **UI components** (`showcase-ui.md`) — use `+demo-folded` so markup is visible
+  and copyable
+- **Typography/syntax** (`showcase-typography.md`) — use raw HTML pairing
+  `<code>` class names with output
+- **Layouts** (`showcase-layouts.md`) — case by case
+
+Group entries by component family under `##` headings (e.g. `## Lists`, `##
+Buttons`). Individual variants sit under `###` within that group.
+
+Do not create a new showcase file for a single component — if it doesn't fit the
+three above, discuss with the user.
+
+## Documentation Types
+
+Choose the document shape based on what is being documented.
+
+### Utility Documentation
+
+Use for class-based APIs such as spacing, sizing, border, position, transforms,
+and typography helpers.
+
+Default structure:
+
+1. Title
+2. One-line lead
+3. Major utility groups as `##` headings when the page covers more than one
+   family
+4. Example groups within those sections as `###` headings when needed
+5. Optional compact table of available properties or value groups
+6. Available values at the end, when useful
+
+Rules:
+
+- Let the examples do most of the work.
+- Keep prose short.
+- Use `##` for major utility families such as `Border` and `Outline` when the
+  page covers multiple related groups.
+- Use `###` for example groups within those families such as `Width`, `Color`,
+  `Style`, or `Offset`.
+- Keep utility heading levels parallel. Do not mix levels unevenly when the
+  groups are peers.
+- Use a compact table near the top when it helps scan the utility API quickly.
+- Only add notes when behaviour is non-obvious.
+- 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 `class="..."` for the outer demo wrapper when the preview needs a
+  container such as `bx`.
+
+### Component Documentation
+
+Use for named structural classes such as `navbar`, `menu`, `bx`, or form
+controls.
+
+Every component doc must communicate four things — heading names can flex to
+suit the content:
+
+1. **What it is** — a one-line lead describing purpose, not implementation
+2. **How to use it** — minimum working markup shown early with `+code`
+3. **What it looks like** — examples moving from simple to fuller usage
+4. **How to customise it** — variables, modifiers, or overrides
+
+Rules:
+
+- Do not add a separate `## Introduction` heading — the lead is the
+  introduction.
+- The lead describes what the component is and does — not implementation
+  details. Do not mention specific CSS properties. Those may change; the
+  component's purpose does not.
+- Heading names should match the content. A single component might use `##
+  Structure` and `## Basic Usage`. A page covering base styles and variants
+  might use `## Base` and `## Variants`. Use whatever is clearest.
+- Show the minimum working structure early with `+code`.
+- Use prose where structure or context-aware behaviour needs explanation.
+- Move from simple usage to fuller examples.
+- Wrap all interactive examples in `class="bx"` on the demo block so they are
+  visually presented in context.
+- 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 to the
+  same pattern is viable. This lives in the component doc — not a separate
+  file. It shows the utility-built version alongside the component class.
+
+## Prose vs Code
+
+Default to code-first. Add prose only when:
+
+- Context-aware behaviour needs explanation
+- Non-obvious structure requires a note
+- Foundational patterns apply across multiple examples
+
+## Code Block Attributes
+
+- `class="..."` → outer demo wrapper class
+- `preview-class="..."` → class applied to the preview container
+- `+demo` / `+demo-folded` → render preview and code together
+
+Prefer `preview-class` when the layout is only for the preview. That keeps the
+example code cleaner when copied.
+
+For layout/responsive docs, use `class="resizable-container
+with-docs-only-overrides"` so the example preview can respond inside the docs
+without changing the copied markup.
+
+## Links
+
+Docs are served from a Laravel app. Always use app-rooted paths — never relative
+file paths:
+
+- `/docs/jtb/variable-system` ✅
+- `../variable-system.md` ❌
+
+The base path is `/docs/jtb/` followed by the directory and filename without
+extension — mirroring the `docs/` folder structure:
+
+- `docs/components/list.md` → `/docs/jtb/components/list`
+- `docs/api/helpers.md` → `/docs/jtb/api/helpers`
+- `docs/variable-system.md` → `/docs/jtb/variable-system`
+
+## Formatting Rules
+
+- **No horizontal rules (`---`)** — ever. Use headings and spacing
+- **Concise** — get to the point
+- **Show code** — examples over explanation
+- **Document the non-obvious** — skip what's clear from context
+- **Call out outstanding review tags** — when closing documentation work, say
+  which headings or docs still carry `(review)` tags