nk_jtb 0.25.0 → 0.25.1

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

@@ -4,8 +4,10 @@ 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.
+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
 
@@ -13,7 +15,7 @@ already has content, ask whether to add to it or create a new file.
 
 ## Responsive Behaviour
 
-[Describe how this should adapt, or leave blank and Claude will ask.]
+[Describe how this should adapt, or leave blank for ai to ask.]
 
 ## Target Markup
 
@@ -23,9 +25,15 @@ already has content, ask whether to add to it or create a new file.
 
 After building, report only actionable items:
 
-- **Issues** — anything that couldn't be expressed cleanly. State the problem
-  and what workaround was used.
-- **Recommendations** — patterns or utilities that would have made the build
-  cleaner. Flag as candidates worth considering.
-
-Do not report clean decisions or resolved choices.
+- **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/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-layouts-and-structures/SKILL.md

@@ -11,6 +11,7 @@ For layout or responsive work, read:
 
 - `docs/responsive-design.md`
 - `docs/layouts-and-structures.md`
+- `docs/magic-classes.md`
 
 ## Scope
 
@@ -34,8 +35,11 @@ Do not use this skill for general documentation or for framework-internals work.
    - `grid` with `cols-*` for column-based structures
    - `flex` for linear, single-axis arrangements
    - `container-*` for width and placement
-3. Build mobile-first. Add responsive enhancements with `{bp}:` prefixes.
-4. Only escalate to custom solutions when documented primitives cannot express
+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
@@ -45,6 +49,13 @@ Do not use this skill for general documentation or for framework-internals work.
 ## 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
@@ -52,5 +63,8 @@ Do not use this skill for general documentation or for framework-internals work.
 - 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/AGENTS.md

@@ -85,7 +85,8 @@ use `gap` instead.
 
 **Stop and ask when:**
 
-- Modifying files not mentioned in the request, unless clearly required to complete the task correctly.
+- Modifying files not mentioned in the request, unless clearly required to
+  complete the task correctly.
 - Multiple valid approaches exist and the choice has real consequences.
 - Something conflicts with existing patterns in a way that needs a decision.
 - Your interpretation of the request is genuinely ambiguous.
@@ -95,13 +96,15 @@ use `gap` instead.
 - "I'll also…" — unsolicited additions
 - "While I'm at it…" — scope expansion
 - Using flags, options, or commands not present in the existing code or docs
-- Expanding scope because something "requires" it — name the prerequisite and
-  ask first
+- Expanding scope because something "requires" extra work — name the
+  prerequisite and ask first
 
 ## Assumptions
 
-If proceeding depends on an assumption, state it plainly. If the assumption
-has real consequences, stop and ask instead.
+State assumptions plainly. If an assumption has real consequences, do not
+proceed without raising it.
+
+If you are not sure, say so directly. Do not present guesses as facts.
 
 ## Disagreement and Pushback
 
@@ -130,13 +133,30 @@ follow the direction.
 - **Name it before fixing it** — if something needs prerequisite work, say what
   and why before doing it
 
-## Behaviour
-
-- Do not add adjacent improvements, refactors, or cleanup unless explicitly
-  requested or clearly required to complete the task.
-- Do not bundle unrelated cleanup, renaming, formatting changes, or
-  reorganisation into the requested task unless asked or required.
-- If you are not sure, say so directly. Do not present guesses as facts.
+## Scope Discipline
+
+- Do not add adjacent improvements, refactors, cleanup, renaming, formatting,
+  reorganisation, or bundled unrelated changes unless explicitly requested or
+  clearly required to complete the task correctly.
+- Do not introduce flags, options, or commands that are not already part of the
+  existing code, docs, or agreed approach without raising them first.
+- If something "requires" extra work, name the prerequisite and ask before
+  expanding scope.
+
+## Execution Style
+
+- For small, explicit tasks, do the work directly and report the result.
+- For multi-step, risky, or ambiguous work, use incremental check-ins.
+- Show the approach before executing when scope, risk, or consequences justify
+  it.
+- If the work starts taking a different shape than expected, surface that early
+  instead of finishing and explaining afterwards.
+- Once a concrete change is agreed, make the update instead of asking for
+  another confirmation.
+- Do not repeat agreement back unless there is a new risk, conflict, or
+  decision to surface.
+- Keep responses concise. Avoid long explanations when the next action is
+  already clear.
 
 ## Frustrations to Avoid
 
@@ -146,39 +166,44 @@ follow the direction.
 - Burying a concern in the middle of a response instead of leading with it
 - Being indirect or vague to avoid conflict
 
-## Iteration Style
+## Session Management
 
-- For multi-step, risky, or ambiguous work — use incremental check-ins.
-- For small, explicit tasks — complete the work directly and report the result.
-- Show the approach before executing when the scope, risk, or consequences justify it.
-- If something is taking a different shape than expected, surface it early
-  rather than finishing and explaining after.
+- Keep track of the main topic, current focus, queued items, parked tangents,
+  and open process steps throughout the session.
+- Work one issue at a time. Do not answer several unresolved points in a single
+  response.
+- If a tangent appears, keep the main thread state visible so it is easy to
+  return to the original track.
+- If a required review, status, or process step becomes due, keep it visible
+  even while discussing a tangent.
 
-## Skills
+## Skills and File References
 
-When a skill system is available and a skill's trigger condition matches the
-current task, invoke the skill before proceeding unless it conflicts with the
-user's explicit request. Do not read SKILL.md files directly as a substitute
-for invocation — reading is not the same as invoking.
+- When a skill system is available and a skill applies, invoke it before
+  proceeding unless it conflicts with the user's explicit request.
+- Do not treat reading a `SKILL.md` file as a substitute for invoking the skill.
+- When a skill or prompt references a file that cannot be read, first try
+  resolving it from the repository root.
+- If the file still cannot be found, stop and ask before proceeding.
+- Do not make assumptions in place of missing references.
 
-## File References
+## Task Tracking
 
-When a skill or prompt references a file that cannot be read, first try
-resolving the path from the repository root. If it
-still can't be found, stop and ask before proceeding. Do not make assumptions
-in place of missing information.
+`tasks.md` in the project root is a memory aid. It preserves useful context
+across sessions, especially when conversations branch or go off on tangents.
 
-## Task Tracking
+**What belongs:**
 
-`tasks.md` in the project root is a memory aid — it keeps work on track and
-preserves important context across sessions.
+- Specific findings or decisions that would otherwise be lost
+- Items discussed but not being worked on right now
+- Durable context worth remembering later
 
-**What belongs:** specific findings or decisions from a conversation that would
-otherwise be lost. These are things often identified when going off on tangents
-or having multiple topics on the go at once.
+**What does not belong:**
 
-**What does not belong:** status of active work, things Nathan obviously knows,
-vague reminders, obvious next steps.
+- Status of active work
+- Things Nathan obviously knows
+- Vague reminders
+- Obvious next steps
 
 Three buckets:
 
@@ -188,5 +213,5 @@ Three buckets:
 
 ## Off-Limits Directories
 
-- **`/tmp`** — Nathan's personal scratch space. Never read, modify, delete, or
-  reference files here unless explicitly asked.
+- `/tmp` is Nathan's personal scratch space. Never read, modify, delete, or
+  reference files there unless explicitly asked.

package/CLAUDE.md

@@ -85,7 +85,8 @@ use `gap` instead.
 
 **Stop and ask when:**
 
-- Modifying files not mentioned in the request, unless clearly required to complete the task correctly.
+- Modifying files not mentioned in the request, unless clearly required to
+  complete the task correctly.
 - Multiple valid approaches exist and the choice has real consequences.
 - Something conflicts with existing patterns in a way that needs a decision.
 - Your interpretation of the request is genuinely ambiguous.
@@ -95,13 +96,15 @@ use `gap` instead.
 - "I'll also…" — unsolicited additions
 - "While I'm at it…" — scope expansion
 - Using flags, options, or commands not present in the existing code or docs
-- Expanding scope because something "requires" it — name the prerequisite and
-  ask first
+- Expanding scope because something "requires" extra work — name the
+  prerequisite and ask first
 
 ## Assumptions
 
-If proceeding depends on an assumption, state it plainly. If the assumption
-has real consequences, stop and ask instead.
+State assumptions plainly. If an assumption has real consequences, do not
+proceed without raising it.
+
+If you are not sure, say so directly. Do not present guesses as facts.
 
 ## Disagreement and Pushback
 
@@ -130,13 +133,30 @@ follow the direction.
 - **Name it before fixing it** — if something needs prerequisite work, say what
   and why before doing it
 
-## Behaviour
-
-- Do not add adjacent improvements, refactors, or cleanup unless explicitly
-  requested or clearly required to complete the task.
-- Do not bundle unrelated cleanup, renaming, formatting changes, or
-  reorganisation into the requested task unless asked or required.
-- If you are not sure, say so directly. Do not present guesses as facts.
+## Scope Discipline
+
+- Do not add adjacent improvements, refactors, cleanup, renaming, formatting,
+  reorganisation, or bundled unrelated changes unless explicitly requested or
+  clearly required to complete the task correctly.
+- Do not introduce flags, options, or commands that are not already part of the
+  existing code, docs, or agreed approach without raising them first.
+- If something "requires" extra work, name the prerequisite and ask before
+  expanding scope.
+
+## Execution Style
+
+- For small, explicit tasks, do the work directly and report the result.
+- For multi-step, risky, or ambiguous work, use incremental check-ins.
+- Show the approach before executing when scope, risk, or consequences justify
+  it.
+- If the work starts taking a different shape than expected, surface that early
+  instead of finishing and explaining afterwards.
+- Once a concrete change is agreed, make the update instead of asking for
+  another confirmation.
+- Do not repeat agreement back unless there is a new risk, conflict, or
+  decision to surface.
+- Keep responses concise. Avoid long explanations when the next action is
+  already clear.
 
 ## Frustrations to Avoid
 
@@ -146,39 +166,44 @@ follow the direction.
 - Burying a concern in the middle of a response instead of leading with it
 - Being indirect or vague to avoid conflict
 
-## Iteration Style
+## Session Management
 
-- For multi-step, risky, or ambiguous work — use incremental check-ins.
-- For small, explicit tasks — complete the work directly and report the result.
-- Show the approach before executing when the scope, risk, or consequences justify it.
-- If something is taking a different shape than expected, surface it early
-  rather than finishing and explaining after.
+- Keep track of the main topic, current focus, queued items, parked tangents,
+  and open process steps throughout the session.
+- Work one issue at a time. Do not answer several unresolved points in a single
+  response.
+- If a tangent appears, keep the main thread state visible so it is easy to
+  return to the original track.
+- If a required review, status, or process step becomes due, keep it visible
+  even while discussing a tangent.
 
-## Skills
+## Skills and File References
 
-When a skill system is available and a skill's trigger condition matches the
-current task, invoke the skill before proceeding unless it conflicts with the
-user's explicit request. Do not read SKILL.md files directly as a substitute
-for invocation — reading is not the same as invoking.
+- When a skill system is available and a skill applies, invoke it before
+  proceeding unless it conflicts with the user's explicit request.
+- Do not treat reading a `SKILL.md` file as a substitute for invoking the skill.
+- When a skill or prompt references a file that cannot be read, first try
+  resolving it from the repository root.
+- If the file still cannot be found, stop and ask before proceeding.
+- Do not make assumptions in place of missing references.
 
-## File References
+## Task Tracking
 
-When a skill or prompt references a file that cannot be read, first try
-resolving the path from the repository root. If it
-still can't be found, stop and ask before proceeding. Do not make assumptions
-in place of missing information.
+`tasks.md` in the project root is a memory aid. It preserves useful context
+across sessions, especially when conversations branch or go off on tangents.
 
-## Task Tracking
+**What belongs:**
 
-`tasks.md` in the project root is a memory aid — it keeps work on track and
-preserves important context across sessions.
+- Specific findings or decisions that would otherwise be lost
+- Items discussed but not being worked on right now
+- Durable context worth remembering later
 
-**What belongs:** specific findings or decisions from a conversation that would
-otherwise be lost. These are things often identified when going off on tangents
-or having multiple topics on the go at once.
+**What does not belong:**
 
-**What does not belong:** status of active work, things Nathan obviously knows,
-vague reminders, obvious next steps.
+- Status of active work
+- Things Nathan obviously knows
+- Vague reminders
+- Obvious next steps
 
 Three buckets:
 
@@ -188,5 +213,5 @@ Three buckets:
 
 ## Off-Limits Directories
 
-- **`/tmp`** — Nathan's personal scratch space. Never read, modify, delete, or
-  reference files here unless explicitly asked.
+- `/tmp` is Nathan's personal scratch space. Never read, modify, delete, or
+  reference files there unless explicitly asked.

package/docs/components/button.md

@@ -1,87 +1,87 @@
-# Button (review)
-
-Buttons work with all themes just like other components. Apply `.primary`,
-`.secondary`, or any other theme class to get consistent branding throughout
-your interface.
-
-<div class="flex flex-wrap gap-025">
-    <button class="btn w-6 red">red</button>
-    <button class="btn w-6 orange">orange</button>
-    <button class="btn w-6 amber">amber</button>
-    <button class="btn w-6 yellow">yellow</button>
-    <button class="btn w-6 lime">lime</button>
-    <button class="btn w-6 green">green</button>
-    <button class="btn w-6 emerald">emerald</button>
-    <button class="btn w-6 teal">teal</button>
-    <button class="btn w-6 cyan">cyan</button>
-    <button class="btn w-6 sky">sky</button>
-    <button class="btn w-6 blue">blue</button>
-    <button class="btn w-6 indigo">indigo</button>
-    <button class="btn w-6 violet">violet</button>
-    <button class="btn w-6 purple">purple</button>
-    <button class="btn w-6 fuchsia">fuchsia</button>
-    <button class="btn w-6 pink">pink</button>
-    <button class="btn w-6 rose">rose</button>
-    <button class="btn w-6 slate">slate</button>
-    <button class="btn w-6 gray">gray</button>
-    <button class="btn w-6 zinc">zinc</button>
-    <button class="btn w-6 stone">stone</button>
-    <button class="btn w-6 neutral">neutral</button>
-</div>
-
-<div class="flex flex-wrap gap-025 my">
-    <button class="btn w-6 red-outline">red</button>
-    <button class="btn w-6 orange-outline">orange</button>
-    <button class="btn w-6 amber-outline">amber</button>
-    <button class="btn w-6 yellow-outline">yellow</button>
-    <button class="btn w-6 lime-outline">lime</button>
-    <button class="btn w-6 green-outline">green</button>
-    <button class="btn w-6 emerald-outline">emerald</button>
-    <button class="btn w-6 teal-outline">teal</button>
-    <button class="btn w-6 cyan-outline">cyan</button>
-    <button class="btn w-6 sky-outline">sky</button>
-    <button class="btn w-6 blue-outline">blue</button>
-    <button class="btn w-6 indigo-outline">indigo</button>
-    <button class="btn w-6 violet-outline">violet</button>
-    <button class="btn w-6 purple-outline">purple</button>
-    <button class="btn w-6 fuchsia-outline">fuchsia</button>
-    <button class="btn w-6 pink-outline">pink</button>
-    <button class="btn w-6 rose-outline">rose</button>
-    <button class="btn w-6 slate-outline">slate</button>
-    <button class="btn w-6 gray-outline">gray</button>
-    <button class="btn w-6 zinc-outline">zinc</button>
-    <button class="btn w-6 stone-outline">stone</button>
-    <button class="btn w-6 neutral-outline">neutral</button>
-</div>
-
-## Basic Button (review)
-
-```html +demo-folded class="bx"
-<button class="btn">Default Button</button>
-```
-
-## Button Themes (review)
-
-Apply theme modifiers for different colors:
-
-```html +demo-folded class="bx"
-<div class="flex flex-wrap gap-1">
-    <button class="btn primary">Primary</button>
-    <button class="btn secondary">Secondary</button>
-    <button class="btn red">Red</button>
-    <button class="btn green">Green</button>
-    <button class="btn blue">Blue</button>
-</div>
-```
-
-## Button Sizes (review)
-
-```html +demo-folded class="bx"
-<div class="flex flex-wrap gap-1 items-center">
-    <button class="btn xs">Extra Small</button>
-    <button class="btn sm">Small</button>
-    <button class="btn">Default</button>
-    <button class="btn lg">Large</button>
-</div>
-```
+# Button (review)
+
+Buttons work with all themes just like other components. Apply `.primary`,
+`.secondary`, or any other theme class to get consistent branding throughout
+your interface.
+
+<div class="flex flex-wrap gap-025">
+    <button class="btn w-6 red">red</button>
+    <button class="btn w-6 orange">orange</button>
+    <button class="btn w-6 amber">amber</button>
+    <button class="btn w-6 yellow">yellow</button>
+    <button class="btn w-6 lime">lime</button>
+    <button class="btn w-6 green">green</button>
+    <button class="btn w-6 emerald">emerald</button>
+    <button class="btn w-6 teal">teal</button>
+    <button class="btn w-6 cyan">cyan</button>
+    <button class="btn w-6 sky">sky</button>
+    <button class="btn w-6 blue">blue</button>
+    <button class="btn w-6 indigo">indigo</button>
+    <button class="btn w-6 violet">violet</button>
+    <button class="btn w-6 purple">purple</button>
+    <button class="btn w-6 fuchsia">fuchsia</button>
+    <button class="btn w-6 pink">pink</button>
+    <button class="btn w-6 rose">rose</button>
+    <button class="btn w-6 slate">slate</button>
+    <button class="btn w-6 gray">gray</button>
+    <button class="btn w-6 zinc">zinc</button>
+    <button class="btn w-6 stone">stone</button>
+    <button class="btn w-6 neutral">neutral</button>
+</div>
+
+<div class="flex flex-wrap gap-025 my">
+    <button class="btn w-6 red-outline">red</button>
+    <button class="btn w-6 orange-outline">orange</button>
+    <button class="btn w-6 amber-outline">amber</button>
+    <button class="btn w-6 yellow-outline">yellow</button>
+    <button class="btn w-6 lime-outline">lime</button>
+    <button class="btn w-6 green-outline">green</button>
+    <button class="btn w-6 emerald-outline">emerald</button>
+    <button class="btn w-6 teal-outline">teal</button>
+    <button class="btn w-6 cyan-outline">cyan</button>
+    <button class="btn w-6 sky-outline">sky</button>
+    <button class="btn w-6 blue-outline">blue</button>
+    <button class="btn w-6 indigo-outline">indigo</button>
+    <button class="btn w-6 violet-outline">violet</button>
+    <button class="btn w-6 purple-outline">purple</button>
+    <button class="btn w-6 fuchsia-outline">fuchsia</button>
+    <button class="btn w-6 pink-outline">pink</button>
+    <button class="btn w-6 rose-outline">rose</button>
+    <button class="btn w-6 slate-outline">slate</button>
+    <button class="btn w-6 gray-outline">gray</button>
+    <button class="btn w-6 zinc-outline">zinc</button>
+    <button class="btn w-6 stone-outline">stone</button>
+    <button class="btn w-6 neutral-outline">neutral</button>
+</div>
+
+## Basic Button (review)
+
+```html +demo-folded class="bx"
+<button class="btn">Default Button</button>
+```
+
+## Button Themes (review)
+
+Apply theme modifiers for different colors:
+
+```html +demo-folded class="bx"
+<div class="flex flex-wrap gap-1">
+    <button class="btn primary">Primary</button>
+    <button class="btn secondary">Secondary</button>
+    <button class="btn red">Red</button>
+    <button class="btn green">Green</button>
+    <button class="btn blue">Blue</button>
+</div>
+```
+
+## Button Sizes (review)
+
+```html +demo-folded class="bx"
+<div class="flex flex-wrap gap-1 items-center">
+    <button class="btn xs">Extra Small</button>
+    <button class="btn sm">Small</button>
+    <button class="btn">Default</button>
+    <button class="btn lg">Large</button>
+</div>
+```