kempo-ui 0.4.2 → 0.4.4

package/.claude/skills/get-icon/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: get-icon
+description: Fetches icons from the Google Material Design Icon set, saves them to this project, and formats them. Use any time an icon is needed (explicit or implicit) — buttons, controls, actions, etc. ALWAYS check the local icons/ directory first before downloading.
+---
+
+# Get Icon
+
+## When to Use
+
+Use this skill any time an icon is needed — whether the user explicitly asks for one or you determine that a UI element (button, control, action, etc.) would benefit from one. For example, if a user asks you to build a "bold" button for a WYSIWYG toolbar, you should proactively source an appropriate icon without being explicitly told to.
+
+## Overview
+
+Icons live in the `icons/` directory as SVG files. The project uses the **Material Symbols Outlined** style from Google's CDN. The workflow has three stages:
+
+1. **Check local icons first** — the icon may already exist
+2. **Find** the correct Material Symbols name if it doesn't
+3. **Fetch, format, and save** using the script (directional handling is automatic)
+
+---
+
+## Stage 1: Check Local Icons First
+
+Before going to the internet, list the contents of `icons/` and look for an existing icon that fits the need (use `ls icons/` via Bash, or search with Glob).
+
+- If a **clear match** exists (e.g. `icons/format_bold.svg` for a bold button), use it — no download needed.
+- If a **reasonable match** exists for a directional icon (e.g. `icons/arrow.svg` for a left-arrow), use it with the appropriate `direction` attribute — no download needed.
+- If **nothing fits**, proceed to Stage 2.
+
+---
+
+## Stage 2: Find the Icon Name
+
+If the user describes an icon but doesn't supply an exact name, search Google Material Symbols to find the right one.
+
+Run the search script, which fetches icon names and tags from GitHub and caches them locally in `node_modules/.cache/kempo-ui/`. On subsequent runs it only re-downloads if the icon list has changed (SHA check — ~1KB request vs ~500KB full list). Search matches both icon names **and tags**, so searching `chevron` will also surface `keyboard_arrow_right` because it has a `chevron` tag:
+
+```bash
+npm run listicons -- <search_term>
+```
+
+Example:
+```bash
+npm run listicons -- bold
+# → format_bold
+```
+
+```bash
+npm run listicons -- chevron
+# → chevron_right
+#   chevron_left
+#   keyboard_arrow_right
+#   keyboard_arrow_left
+#   ...
+```
+
+The results show **full icon names including direction suffixes** so you can see what variants are available. Pick the best match for the user's intent. If no results are returned, try different search terms (e.g. `type` instead of `font`, `text` instead of `word`).
+
+---
+
+## Stage 3: Fetch, Format, and Save
+
+Run the fetch script with the chosen icon name. The script automatically handles directional icons — if the name you pass is directional (has a `_left`, `_up`, `_down`, `_backward` suffix, or has no exact match but a `_right`/`_forward` variant exists), it will prompt:
+
+```
+"chevron_left" is a directional icon. kempo-ui uses right direction only and applies CSS rotation.
+Save right-facing variant as "chevron.svg"? (Y/n)
+```
+
+```bash
+npm run geticon -- <icon_name> [custom_name] [-y]
+```
+
+- `icon_name` — the Material Symbols name as returned by the search script
+- `custom_name` — optional rename (e.g. `keyboard_double_arrow_right double_chevron` saves as `double_chevron.svg`)
+- `-y` — auto-accept the directional prompt without user interaction
+
+Examples:
+```bash
+# Non-directional — downloads silently
+npm run geticon -- format_bold
+
+# Directional — prompts to confirm saving right-facing variant as "chevron"
+npm run geticon -- chevron_left
+
+# Directional with rename and auto-accept
+npm run geticon -- keyboard_double_arrow_up double_chevron -y
+```
+
+If the script exits with a non-zero code mentioning a 404, the icon name is wrong — return to Stage 2 and search for the correct name.
+
+The script produces minified output with only `xmlns` and `viewBox` on `<svg>`, and only `fill="currentColor"` and `d` on each `<path>`:
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path fill="currentColor" d="..."/></svg>
+```
+
+---
+
+## Directional Icons and `<k-icon>`
+
+When the script saves a right-facing icon (after a directional prompt), the `<k-icon>` component handles rotation via its `direction` attribute:
+
+| `direction` value | Rotation applied |
+|---|---|
+| *(omitted)* | 0° — points right |
+| `down` | 90° |
+| `left` | 180° |
+| `up` | 270° |
+
+**Example:** A user asking for a "left arrow" after downloading `arrow.svg`:
+```html
+<k-icon name="arrow" direction="left"></k-icon>
+```
+
+---
+
+## Complete Examples
+
+**User asks to "add a bold button" (implicit icon need)**
+
+1. **Local check:** `icons/format_bold.svg` exists → use it directly, no download needed
+2. **Use:** `<k-icon name="format_bold"></k-icon>`
+
+**User asks to "add a thumbs up icon" (explicit, not in local icons)**
+
+1. **Local check:** No match in `icons/`
+2. **Find:** `npm run listicons -- thumbs+up` → `thumb_up`
+3. **Directional check:** Not directional, proceed normally
+4. **Run:** `npm run geticon -- thumb_up`
+5. **Result:** `icons/thumb_up.svg` saved
+
+**User asks for a "left arrow icon"**
+
+1. **Local check:** `icons/arrow.svg` exists and is right-facing
+2. **Directional check:** Directional — right-facing variant already present
+3. **No download needed:** use `<k-icon name="arrow" direction="left"></k-icon>`
+
+**User asks for a "left arrow icon" (no arrow in local icons)**
+
+1. **Local check:** No arrow icon found
+2. **Find:** `npm run listicons -- arrow` → consider `arrow_forward` or `arrow_right`
+3. **Directional check:** Directional — download the right-facing variant with a generic name
+4. **Run:** `npm run geticon -- arrow_forward arrow`
+5. **Use:** `<k-icon name="arrow" direction="left"></k-icon>`

package/.claude/skills/highlight-code/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: highlight-code
+description: Generates syntax-highlighted HTML for documentation code samples. USE THIS instead of hand-writing <pre><code class="hljs ..."> blocks or creating temporary scripts. Run via `npx kempo-highlightcode <lang>` with code piped on stdin.
+---
+
+# Highlight Code
+
+## When to Use
+
+Use this skill whenever you need syntax-highlighted HTML to embed in a documentation page — for example, when adding or updating a `<pre><code class="hljs ...">` block in a `docs-src/components/*.page.html` file. **Do not hand-write the highlighted markup, and do not create temporary scripts to do this.**
+
+> Source files live in `docs-src/` and are pre-rendered to `docs/` by the kempo-server templating system. Always edit the `*.page.html` source — never the generated `docs/*.html`.
+
+## Usage
+
+Pipe code via stdin (supports multi-line):
+```bash
+cat <<'EOF' | npx kempo-highlightcode <lang>
+<div class='container'>
+  <h1>Hello</h1>
+</div>
+EOF
+```
+
+Or pass minified code as an argument:
+```bash
+npx kempo-highlightcode <lang> "<div class='container'><h1>Hello</h1></div>"
+```
+
+**Supported languages:** `html`, `css`, `js` / `javascript`, `ts` / `typescript`, `json`, `md` / `markdown`, `sh` / `bash`, `xml`
+
+## Output
+
+Prints a complete `<pre><code class="hljs {lang}">…</code></pre>` block to stdout, with `<br>` tags instead of newlines — a single line suitable for embedding directly in HTML.
+
+Input is automatically beautified before highlighting, so you can pass minified code.
+
+## Workflow for Updating Doc Code Samples
+
+1. Capture the highlighted block to a file or shell variable:
+
+   ```bash
+   HL=$(cat <<'EOF' | npx kempo-highlightcode xml
+   <k-table id=myExample></k-table>
+   <script type=module>
+     doSomething('foo');
+   </script>
+   EOF
+   )
+   ```
+
+2. Use the **Edit tool** to replace the existing `<pre><code class="hljs xml">…</code></pre>` block in the target page with `$HL`. Do not use `sed` or shell-based file editing — Edit handles escaping correctly.
+
+   - Read the file first to find the exact `old_string` to replace.
+   - If the page has multiple `<pre><code>` blocks, include enough surrounding context in `old_string` to make it unique.
+
+## Important Notes
+
+- Use **single-quotes** for JS string literals inside the code. This preserves all quoting correctly through to node.
+- HTML attribute values can be **unquoted** in the argument (`id=foo` not `id="foo"`) — the beautifier adds consistent formatting anyway.
+- When piping multi-line code, use a **quoted heredoc** (`<<'EOF'`) so the shell does not interpolate `$`, backticks, or backslashes inside the code.
+- Output uses `<br>` instead of `\n`, keeping the block on one line in the HTML source.

package/.claude/skills/new-component/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: new-component
+description: Creates a new Kempo UI web component end-to-end — choosing the right base class, writing the source file, registering the custom element, adding the docs page, wiring up the nav/index/llms.txt, AND writing tests. Use any time you are asked to create a new component or add a new custom element.
+---
+
+# New Component
+
+## When to Use
+
+Use this skill any time you are asked to create a new component or add a new custom element to the project.
+
+---
+
+## Overview
+
+Creating a component involves six steps. Do not skip steps — especially the tests.
+
+1. **Choose the base component** — pick the right rendering strategy
+2. **Write the source file** in `src/components/` (also registers the custom element)
+3. **Read the templating primer** so the docs page is structured correctly
+4. **Add the documentation page** in `docs-src/components/` and wire up nav/index/llms.txt
+5. **Write and run unit tests** in `tests/components/`
+6. **Verify in the browser** at `http://localhost:8083`
+
+---
+
+## Step 1: Choose the Base Component
+
+Three base classes are available. Pick based on rendering needs:
+
+### `ShadowComponent`
+Use when the component needs shadow DOM encapsulation. The base class automatically injects the kempo-css stylesheet into the shadow root. **This is the default for most components.**
+
+```javascript
+import { html, css } from '../lit-all.min.js';
+import ShadowComponent from './ShadowComponent.js';
+
+export default class MyComponent extends ShadowComponent {
+  render() {
+    return html`<p>Shadow DOM content with scoped styles</p>`;
+  }
+}
+```
+
+### `LightComponent`
+Use when the component renders to the light DOM (no encapsulation, inherits page styles). Override `renderLightDom()`.
+
+### `HybridComponent`
+Use when the component needs both a shadow DOM portion and a light DOM portion (e.g. slotted children that also need managed light DOM output). Override both `render()` and `renderLightDom()`.
+
+**Important:** Always call `super.updated(...)` when overriding `updated()` in any base class.
+
+---
+
+## Step 2: Write the Source File
+
+Create `src/components/MyComponent.js`. Follow these conventions (also see [AGENTS.md](../../AGENTS.md)):
+
+- Use multi-line comments to separate logical sections: `Lifecycle Callbacks`, `Event Handlers`, `Public Methods`, `Utility`, `Rendering`, `Styles`.
+- Declare reactive properties with `static properties = { ... }` and initialize defaults in the constructor.
+- Use `static styles = css\`...\`` for component-scoped CSS (shadow DOM only).
+- Use **arrow functions** for class methods to avoid `.bind(this)`.
+- For private fields use native JS private fields (`#field`) — never underscore-prefixed.
+- For form-associated components: set `static formAssociated = true`, call `this.attachInternals()` in the constructor, and use `internals.setFormValue(...)` / `internals.setValidity(...)`.
+- **Buttons inside the shadow DOM should have `class="no-btn"`** to opt out of kempo-css's default button styling. Add explicit `display: inline-flex; align-items: center; justify-content: center;` in the component CSS to keep content centered after stripping. The same applies to `class="no-style"` on selects/inputs if you need to fully opt out, but most form controls render fine with kempo-css defaults.
+
+Example skeleton:
+
+```javascript
+import { html, css } from '../lit-all.min.js';
+import ShadowComponent from './ShadowComponent.js';
+
+export default class MyComponent extends ShadowComponent {
+  static properties = {
+    value: { type: String, reflect: true },
+    disabled: { type: Boolean, reflect: true }
+  };
+
+  /*
+    Lifecycle Callbacks
+  */
+  constructor() {
+    super();
+    this.value = '';
+    this.disabled = false;
+  }
+
+  /*
+    Event Handlers
+  */
+  handleClick = () => {
+    if(this.disabled) return;
+    this.dispatchEvent(new CustomEvent('change', {
+      detail: { value: this.value },
+      bubbles: true
+    }));
+  };
+
+  /*
+    Rendering
+  */
+  render() {
+    return html`
+      <button class="no-btn btn" ?disabled=${this.disabled} @click=${this.handleClick}>
+        ${this.value}
+      </button>
+    `;
+  }
+
+  /*
+    Styles
+  */
+  static styles = css`
+    :host { display: inline-block; }
+    .btn {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      padding: var(--spacer_h) var(--spacer);
+      border: 1px solid var(--c_border);
+      border-radius: var(--radius);
+      background: var(--c_bg);
+      color: var(--tc);
+      cursor: pointer;
+    }
+  `;
+}
+
+customElements.define('k-my-component', MyComponent);
+```
+
+### Custom element naming
+- All elements use the `k-` prefix (e.g. `k-spinner`, `k-color-picker`).
+- Use kebab-case for multi-word names.
+- The `customElements.define(...)` call goes at the **bottom** of the file, after the class.
+
+---
+
+## Step 3: kempo-server Templating Primer
+
+The docs site is built with the **kempo-server v3 templating system**. Source files live in `docs-src/`; production pages are pre-rendered into `docs/` at build time. **Do not edit anything inside `docs/components/` directly — those files are generated.**
+
+### File types
+
+| Suffix | Purpose | Example |
+|---|---|---|
+| `*.page.html` | An individual page. Wraps content in `<page>` and fills template slots with `<content>` blocks. | `docs-src/components/slider.page.html` |
+| `*.template.html` | Shared layout. Defines named slots with `<location>` and pulls in fragments with `<fragment name="..." />`. | `docs-src/default.template.html` |
+| `*.fragment.html` | Reusable HTML partial. Included via `<fragment name="..." />` from templates or pages. | `docs-src/nav.fragment.html` |
+| `*.global.html` | Site-wide content auto-injected into matching `<location>` tags across every page. | (none currently) |
+
+### How a page renders
+
+1. The `<page>` tag chooses a template (defaults to `default`, looked up upward from the page directory). For component docs that's `docs-src/default.template.html`.
+2. Each `<content>` block in the page fills a `<location>` slot in the template:
+   - `<content>` (no `location`) fills `<location />` (the unnamed default slot — body content).
+   - `<content location="scripts">` fills `<location name="scripts" />` (`<script type="module">` tags at the end of `<body>`).
+   - `<content location="header">` fills `<location name="header">` (overrides the default `<h1>` heading).
+3. Page tag attributes become template variables: `<page pageName="Slider" title="...">` makes `{{pageName}}` and `{{title}}` available throughout the template.
+4. The `<fragment name="nav" />` call in the template pulls in `docs-src/nav.fragment.html`, which renders the navbar and side menu.
+5. Path variables: **`{{pathToRoot}}`** is the relative path back to `docs-src/` — use it for every asset reference. The renderer substitutes the correct number of `../` segments based on the page's depth. Other built-ins include `{{year}}`, `{{date}}`, `{{datetime}}`, `{{timestamp}}`, `{{version}}`, `{{env}}`.
+6. Templates and fragments resolve **upward** from the referencing page directory (nearest match wins). Pages and globals scan **downward** (recursively).
+
+### Conditionals and loops
+
+The templating engine supports:
+- `<if condition="..."> … </if>` with `===`, `!==`, `>`, `<`, `>=`, `<=`, `&&`, `||`, `!`
+- `<foreach in="arrayName" as="item"> {{item.name}} </foreach>` with dot-path access
+
+### Dev server
+
+A dev server is already running on `http://localhost:8083` (started via `npm run dev`). It uses SSR for `docs-src/`, so your changes appear on refresh without a build. Static assets in `docs/` (CSS, media, manifest) are served via customRoutes. **Do not start another server.**
+
+For production, `npm run build` minifies the JS, copies icons, and pre-renders all pages from `docs-src/` into `docs/`.
+
+---
+
+## Step 4: Add the Documentation Page
+
+Create `docs-src/components/my-component.page.html`. Use an existing page (e.g. [`slider.page.html`](../../docs-src/components/slider.page.html), [`time.page.html`](../../docs-src/components/time.page.html)) as a structural reference. Recommended sections:
+
+- A Table of Contents accordion at the top
+- Examples (Basic Usage, Default Value, mode-specific examples, etc.)
+- A `<h2 id="jsRef">JavaScript Reference</h2>` section covering: Constructor, Requirements, Properties, Methods, CSS Variables, Events
+- Module script tags inside `<content location="scripts">`
+
+```html
+<page pageName="My Component" title="My Component - Components - Kempo Docs - A Web Components Solution">
+  <content>
+    <k-accordion persistent-id="toc" class="b r mb">
+      <k-accordion-header for-panel="toc-panel">Table of Contents</k-accordion-header>
+      <k-accordion-panel name="toc-panel">
+        <!-- TOC links -->
+      </k-accordion-panel>
+    </k-accordion>
+
+    <h3 id="basicUsage"><a href="#basicUsage" class="no-link">Basic Usage</a></h3>
+    <!-- examples -->
+
+    <h2 id="jsRef"><a href="#jsRef" class="no-link">JavaScript Reference</a></h2>
+    <!-- properties / methods / events -->
+  </content>
+  <content location="scripts">
+    <script type="module" src="{{pathToRoot}}src/components/MyComponent.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/Accordion.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/Card.js"></script>
+  </content>
+</page>
+```
+
+Use `{{pathToRoot}}` for any relative path (the templating system substitutes the correct `../` count per page depth).
+
+### Code Samples in the Docs
+
+For every `<pre><code class="hljs ...">` block, **use the highlight-code skill** to generate the markup. Do not hand-write the highlighted HTML — it is fragile and error-prone.
+
+```bash
+cat <<'EOF' | npx kempo-highlightcode xml
+<k-my-component value="hello"></k-my-component>
+EOF
+```
+
+Then paste the result into the page (Edit tool).
+
+### Wire Up Nav, Index, and llms.txt
+
+After creating the page, add the component in **four** places, all in alphabetical order:
+
+#### 1. Search filter dropdown — [`docs-src/nav.fragment.html`](../../docs-src/nav.fragment.html)
+
+Inside `<k-filter-list id="navSearchList">`, add a `<k-filter-item>`:
+
+```html
+<k-filter-item filter-keywords="my component mycomponent keywords here components"><a
+    href="{{pathToRoot}}components/my-component.html"
+  >My Component<br><small>Component</small></a></k-filter-item>
+```
+
+**WATCH OUT:** When using the Edit tool to insert a new filter-item, do **not** truncate the `<a` of the surrounding filter-item. The Edit tool's `old_string`/`new_string` boundaries must end on whole lines. Verify with Read after each edit.
+
+#### 2. Sidebar menu link — same `nav.fragment.html`
+
+Inside the `<menu>` block under `<h3>Components</h3>`, add an `<a>` tag in alphabetical order:
+
+```html
+<a href="{{pathToRoot}}components/my-component.html">My Component</a>
+```
+
+#### 3. Homepage card — [`docs-src/index.page.html`](../../docs-src/index.page.html)
+
+Inside the `<div class="row -mx">` under `<h2>Components</h2>`, add a card in alphabetical order:
+
+```html
+<div class="span-12 t-span-6 d-span-4 px">
+  <a href="{{pathToRoot}}components/my-component.html" class="card mb no-link d-b">
+    <h3 class="tc-primary">My Component</h3>
+    <p class="tc-muted">One-sentence description of what the component does.</p>
+  </a>
+</div>
+```
+
+#### 4. LLM reference — [`llms.txt`](../../llms.txt)
+
+Add a row to the **Components** table (alphabetical by element name):
+
+```markdown
+| `<k-my-component>` | `MyComponent.js` | One-sentence description with key attributes and events | [my-component.html](https://dustinpoissant.github.io/kempo-ui/components/my-component.html) |
+```
+
+If the component registers multiple elements (e.g. parent + child), list all element names in the first column separated by spaces.
+
+---
+
+## Step 5: Write and Run Unit Tests
+
+**This step is required.** Skipping tests is a common mistake — the AGENTS.md says "ALL tests must pass — ZERO failures are acceptable."
+
+Create `tests/components/MyComponent.browser-test.js`. Use [Toggle.browser-test.js](../../tests/components/Toggle.browser-test.js) or [Slider.browser-test.js](../../tests/components/Slider.browser-test.js) as a reference.
+
+Conventions:
+- Import the component class at the top.
+- Define an async `createMyComponent(attrs = {})` helper that builds the DOM, appends to `document.body`, awaits `el.updateComplete`, and returns `{ container, el }`.
+- Define a `cleanup(container)` helper that removes the container from the DOM.
+- Export a default plain object where each key is a test description and each value is an `async ({pass, fail}) => {}` function.
+- Always call `cleanup(container)` before every `pass()` or `fail()` call.
+- Use multi-line comments to group related tests (`/* Element Creation */`, `/* Properties */`, etc.).
+
+Tests to include at minimum:
+
+- Element is created and is an instance of the component class
+- Element has a shadow root (when applicable)
+- Default property values are correct
+- Attribute reflection works (when `reflect: true`)
+- Public methods behave correctly
+- Events are dispatched correctly with the right `detail` shape
+- For form-associated components: form submission produces the expected value
+
+Run the tests after writing them:
+
+```bash
+npm run test -- MyComponent
+```
+
+The partial string `MyComponent` matches any test file path containing it. Fix any failures before considering the component complete. Zero failures.
+
+---
+
+## Step 6: Verify in the Browser
+
+A dev server is already running on `http://localhost:8083` — **do not start another**. Source pages render via SSR so changes appear on refresh without rebuilding.
+
+- Navigate to `http://localhost:8083/components/my-component.html`
+- Use chrome-devtools-mcp to interact with the rendered output
+- Test the golden path AND edge cases
+- Confirm form-associated behavior by submitting an actual `<form>`
+- Watch for console errors that aren't pre-existing
+
+If you cannot test the UI for some reason, say so explicitly rather than claiming success.
+
+---
+
+## Component Architecture and Communication
+
+- Use **methods** to trigger actions. Events notify that something already happened; they should not be used to trigger logic.
+  - Prefer `el.closest('k-parent')?.doSomething()` over dispatching an event and listening for it.
+- Child components should locate their parent via `closest('k-parent-element')` and call its methods directly.
+- Avoid `window` globals and global custom events for coordination. Scope events to the relevant element; reserve `window` events for global, non-visual concerns (e.g. settings changes).
+
+---
+
+## Elevation (Z-Index)
+
+Any component using `position: fixed` must follow the kempo-css elevation system where `z-index = level × 10`.
+
+| Level | z-index | Kempo UI Components | Notes |
+|-------|---------|---------------------|-------|
+| 2 | 20 | (page default) | No z-index needed for flow-position components |
+| 3 | 30 | Aside (push) | Fixed panels that sit **below** a fixed navbar |
+| 5 | 50 | *(navbar — user-defined)* | Reserved buffer for user-defined navbars |
+| 6 | 60 | Aside (overlay) | Overlay drawers that sit **above** a fixed navbar |
+| 7 | 70 | Dropdown | Floating menus; above navbar and overlay |
+| 8 | 80 | Dialog, PhotoViewer | Full-screen modals and lightboxes |
+| 9 | 90 | Toast | Notification toasts; always topmost |
+
+Levels 1, 4 are intentional buffer zones for user customization.
+
+When deciding a new component's elevation:
+- If it is a panel or drawer in `push` mode (shifts page content), use level 3.
+- If it is a panel or drawer in `overlay` mode (floats over content), use level 6.
+- If it covers the entire viewport (modal/dialog), use level 8.
+- If it is a temporary notification, use level 9.
+
+---
+
+## Common Mistakes To Avoid
+
+- **Hand-writing the syntax-highlighted HTML** in code samples — use the `highlight-code` skill instead.
+- **Skipping tests** — every component needs a `*.browser-test.js` file with the minimum coverage above.
+- **Editing `docs/`** — that directory is generated by the build. Edit `docs-src/`.
+- **Forgetting `class="no-btn"` on shadow-DOM `<button>` elements** — kempo-css aggressively styles native buttons; opt out and re-center with flex.
+- **Editing only the search filter and forgetting the sidebar menu, index page, or llms.txt** — all four locations must be updated for a new component.
+- **Truncating adjacent elements when editing `nav.fragment.html`** — Edit tool boundaries must include whole lines; always Read after editing to verify nothing was clipped.

package/.github/skills/get-icon/SKILL.md

@@ -124,9 +124,9 @@ When the script saves a right-facing icon (after a directional prompt), the `<k-
 **User asks to "add a thumbs up icon" (explicit, not in local icons)**
 
 1. **Local check:** No match in `icons/`
-2. **Find:** Search Material Symbols for `thumbs+up` → `thumb_up`
+2. **Find:** `npm run listicons -- thumbs+up` → `thumb_up`
 3. **Arrow check:** Not directional, proceed normally
-4. **Run:** `node .github/skills/get-icon/get_icon.js thumb_up`
+4. **Run:** `npm run geticon -- thumb_up`
 5. **Result:** `icons/thumb_up.svg` saved and build triggered
 
 **User asks for a "left arrow icon"**
@@ -138,7 +138,7 @@ When the script saves a right-facing icon (after a directional prompt), the `<k-
 **User asks for a "left arrow icon" (no arrow in local icons)**
 
 1. **Local check:** No arrow icon found
-2. **Find:** Search for `arrow_forward` or `arrow_right`
+2. **Find:** `npm run listicons -- arrow` → consider `arrow_forward` or `arrow_right`
 3. **Arrow check:** Directional — download the right-facing variant with a generic name
-4. **Run:** `node .github/skills/get-icon/get_icon.js arrow_forward arrow`
+4. **Run:** `npm run geticon -- arrow_forward arrow`
 5. **Use:** `<k-icon name="arrow" direction="left"></k-icon>`