kempo-ui 0.4.2 → 0.4.4

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

@@ -1,17 +1,30 @@
 ---
 name: highlight-code
-description: Generates syntax-highlighted HTML for use in documentation code examples. USE THIS instead of creating temporary scripts.
+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 updating a `<pre><code class="hljs ...">` block in a `docs/components/*.html` file. **Do not create temporary `.mjs` scripts to do this.**
+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 / zsh:**
+```bash
+cat <<'EOF' | npx kempo-highlightcode <lang>
+<div class='container'>
+  <h1>Hello</h1>
+</div>
+EOF
+```
+
+**PowerShell:**
 ```powershell
 @"
 <div class='container'>
@@ -20,8 +33,8 @@ Pipe code via stdin (supports multi-line):
 "@ | npx kempo-highlightcode <lang>
 ```
 
-Or pass minified code as an argument:
-```powershell
+Or pass minified code as an argument (works in any shell):
+```bash
 npx kempo-highlightcode <lang> "<div class='container'><h1>Hello</h1></div>"
 ```
 
@@ -35,26 +48,44 @@ Input is automatically beautified before highlighting, so you can pass minified
 
 ## Workflow for Updating Doc Code Samples
 
-Pipe the code into the script, capture to `$hl`, then use PowerShell's `.Replace()` to patch the HTML file:
+1. Capture the highlighted block to a shell variable (or a temp file):
 
-```powershell
-$hl = @"
-<k-table id=myExample></k-table>
-<script type=module>
-  doSomething('foo');
-</script>
-"@ | npx kempo-highlightcode xml
-$html = [System.IO.File]::ReadAllText((Resolve-Path 'docs/components/my-component.html'))
-$old = [regex]::Match($html, '(?s)<pre><code class="hljs xml">.*?</code></pre>').Value
-[System.IO.File]::WriteAllText((Resolve-Path 'docs/components/my-component.html'), $html.Replace($old, $hl))
-```
+   **bash / zsh:**
+   ```bash
+   HL=$(cat <<'EOF' | npx kempo-highlightcode xml
+   <k-table id=myExample></k-table>
+   <script type=module>
+     doSomething('foo');
+   </script>
+   EOF
+   )
+   ```
+
+   **PowerShell:**
+   ```powershell
+   $hl = @"
+   <k-table id=myExample></k-table>
+   <script type=module>
+     doSomething('foo');
+   </script>
+   "@ | npx kempo-highlightcode xml
+   ```
+
+2. Replace the existing `<pre><code class="hljs xml">…</code></pre>` block in `docs-src/components/<name>.page.html` with the new value:
+   - **In an editor / Claude Edit tool / VS Code Copilot edit:** find the existing `<pre><code class="hljs xml">…</code></pre>` block and replace it. This handles escaping correctly.
+   - **In PowerShell scripts** (legacy): use `[System.IO.File]::ReadAllText` + `.Replace()` (not `-replace`) to avoid regex interpretation:
+     ```powershell
+     $path = Resolve-Path 'docs-src/components/my-component.page.html'
+     $html = [System.IO.File]::ReadAllText($path)
+     $old = [regex]::Match($html, '(?s)<pre><code class="hljs xml">.*?</code></pre>').Value
+     [System.IO.File]::WriteAllText($path, $html.Replace($old, $hl))
+     ```
 
 ## Important Notes
 
-- Use PowerShell **here-strings** (`@"…"@`) for multi-line code input via stdin.
 - Use **single-quotes** for JS string literals inside the code. This preserves all quoting correctly through to node.
-- HTML attribute values should be **unquoted** in the argument (`id=foo` not `id="foo"`) — the beautifier adds consistent formatting anyway.
-- Use `[System.IO.File]::ReadAllText` / `WriteAllText` + `.Replace()` (not `-replace`) to avoid regex interpretation of the replacement string.
-- If a page has multiple `<pre><code>` blocks, adjust the regex to match the specific one (e.g. match by a nearby unique string, or loop with an index).
+- 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 in bash/zsh, use a **quoted heredoc** (`<<'EOF'`) so the shell does not interpolate `$`, backticks, or backslashes inside the code. PowerShell here-strings (`@"…"@`) handle this without extra quoting.
+- If a page has multiple `<pre><code>` blocks, include enough surrounding context in your replace target to make the match unique (e.g. include the nearby `<h3>` or `<k-card label="HTML">` wrapper).
 - The beautifier handles indentation and formatting automatically.
 - Output uses `<br>` instead of `\n`, keeping the block on one line in the HTML source.

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

@@ -1,6 +1,6 @@
 ---
 name: new-component
-description: Creates a new Kempo UI web component — choosing the right base class, writing the source file, registering the custom element, and adding documentation.
+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
@@ -13,14 +13,14 @@ Use this skill any time you are asked to create a new component or add a new cus
 
 ## Overview
 
-Creating a component involves six steps:
+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/`
-3. **Register the custom element** at the bottom of the source file
-4. **Add documentation** in `docs/components/`
+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. **Update `llm.txt.md`** — add a row to the Components table
+6. **Verify in the browser** at `http://localhost:8083`
 
 ---
 
@@ -29,10 +29,10 @@ Creating a component involves six steps:
 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.
+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 } from '../lit-all.min.js';
+import { html, css } from '../lit-all.min.js';
 import ShadowComponent from './ShadowComponent.js';
 
 export default class MyComponent extends ShadowComponent {
@@ -43,50 +43,26 @@ export default class MyComponent extends ShadowComponent {
 ```
 
 ### `LightComponent`
-Use when the component renders to the light DOM (no encapsulation, inherits page styles).
-
-```javascript
-import { html } from '../lit-all.min.js';
-import LightComponent from './LightComponent.js';
-
-export default class MyComponent extends LightComponent {
-  renderLightDom() {
-    return html`<p>Light DOM content</p>`;
-  }
-}
-```
+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).
-
-```javascript
-import { html } from '../lit-all.min.js';
-import HybridComponent from './HybridComponent.js';
+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()`.
 
-export default class MyComponent extends HybridComponent {
-  render() {
-    return html`<p>Shadow DOM content</p>`;
-  }
-
-  renderLightDom() {
-    return html`<p>Light DOM content alongside natural children</p>`;
-  }
-}
-```
-
-**Important:** Always call `super.updated()` when overriding the `updated()` method in `LightComponent` or `HybridComponent`.
+**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:
+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 Functions`, `Rendering`, `Styles`.
+- 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)`.
-- Do not prefix private fields with underscores — use native JS private fields (`#field`) when true privacy is needed.
+- 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 `<select>` / `<input>` if you need to fully opt out, but most form controls render fine with kempo-css defaults.
 
 Example skeleton:
 
@@ -96,26 +72,28 @@ import ShadowComponent from './ShadowComponent.js';
 
 export default class MyComponent extends ShadowComponent {
   static properties = {
-    value: { type: String, reflect: true }
+    value: { type: String, reflect: true },
+    disabled: { type: Boolean, reflect: true }
   };
-  
+
   /*
-    Lifecycle Calblacks
+    Lifecycle Callbacks
   */
-  constructor(){
+  constructor() {
     super();
-    this.value = 'default value';
-  }
-  connectedCallback(){
-    super.connectedCallback();
-    // Do things
+    this.value = '';
+    this.disabled = false;
   }
 
   /*
     Event Handlers
   */
   handleClick = () => {
-    this.dispatchEvent(new CustomEvent('my-event', { bubbles: true, composed: true }));
+    if(this.disabled) return;
+    this.dispatchEvent(new CustomEvent('change', {
+      detail: { value: this.value },
+      bubbles: true
+    }));
   };
 
   /*
@@ -123,24 +101,29 @@ export default class MyComponent extends ShadowComponent {
   */
   render() {
     return html`
-      <button @click=${this.handleClick}>${this.value}</button>
+      <button class="no-btn btn" ?disabled=${this.disabled} @click=${this.handleClick}>
+        ${this.value}
+      </button>
     `;
   }
+
   /*
     Styles
   */
   static styles = css`
-    :host {
-      display: block;
+    :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;
     }
   `;
-  
-  /*
-    Static Methods
-  */
-  static staticMethod(){
-    // Do things
-  }
 }
 
 customElements.define('k-my-component', MyComponent);
@@ -153,138 +136,185 @@ customElements.define('k-my-component', MyComponent);
 
 ---
 
-## Step 3: Register in the Nav, Search, and Index (if it should appear in docs)
+## 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).
 
-There are **two** nav include files that must both be updated:
+### Conditionals and loops
 
-- `docs/nav.inc.html` — used on the homepage (paths start with `./`)
-- `docs/nav-1.inc.html` — used on sub-pages (paths start with `../`)
+The templating engine supports:
+- `<if condition="..."> … </if>` with `===`, `!==`, `>`, `<`, `>=`, `<=`, `&&`, `||`, `!`
+- `<foreach in="arrayName" as="item"> {{item.name}} </foreach>` with dot-path access
 
-In **each** file, add the component in **three** places, all in alphabetical order:
+### Dev server
 
-### 1. Search dropdown filter item
+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.**
 
-Inside the `<k-filter-list id="navSearchList">`, add a `<k-filter-item>` in alphabetical order among the other component entries:
+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
-<!-- nav.inc.html (homepage) -->
-<k-filter-item filter-keywords="my component mycomponent components"><a href="./components/my-component.html">My Component<br><small>Component</small></a></k-filter-item>
+<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. **Do not** add `<!DOCTYPE html>`, `<html>`, `<head>`, `<body>`, or a `<k-import>` for the nav — those come from the template.
+
+### Code Samples in the Docs
+
+For every `<pre><code class="hljs ...">` block, **use the [highlight-code skill](../highlight-code/SKILL.md)** to generate the markup. Do not hand-write the highlighted HTML — it is fragile and error-prone.
 
-<!-- nav-1.inc.html (sub-pages) -->
-<k-filter-item filter-keywords="my component mycomponent components"><a href="../components/my-component.html">My Component<br><small>Component</small></a></k-filter-item>
+```bash
+cat <<'EOF' | npx kempo-highlightcode xml
+<k-my-component value="hello"></k-my-component>
+EOF
 ```
 
-### 2. Sidebar menu link
+Then paste the result into the page.
 
-Inside the `<menu>` under the `Components` `<div>`, add an `<a>` tag in alphabetical order:
+### 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
-<!-- nav.inc.html -->
-<a href="./components/my-component.html">My Component</a>
+<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 inserting a new filter-item with a search-and-replace tool, do **not** truncate the `<a` of the surrounding filter-item. Always re-read the file after each edit to verify nothing was clipped.
 
-<!-- nav-1.inc.html -->
-<a href="../components/my-component.html">My Component</a>
+#### 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
+#### 3. Homepage card — [`docs-src/index.page.html`](../../../docs-src/index.page.html)
 
-Add a card in `docs/index.html` inside the `<div class="row -mx">` under the `<h2>Components</h2>` section, in alphabetical order:
+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="./components/my-component.html" class="card mb no-link d-b">
+  <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>
 ```
 
----
-
-## Step 4: Add Documentation
-
-Create `docs/components/my-component.html`. Use an existing docs page (e.g. `docs/components/spinner.html`) as a reference for structure and conventions.
+#### 4. LLM reference — [`llms.txt`](../../../llms.txt)
 
-Key requirements:
-- Consistent `<head>` with title, stylesheets, and `window.litDisableBundleWarning = true`.
-- `<k-import src="../nav-1.inc.html"></k-import>` at the top of `<body>`.
-- A Table of Contents accordion.
-- Sections for: examples/usage, and a JavaScript Reference covering constructor, attributes/properties, CSS variables, events, and public methods (as applicable).
-- Use the `highlight-code` skill for all code examples that need syntax highlighting.
-- At the bottom of the file, load the component and its dependencies as `<script type="module">` tags:
+Add a row to the **Components** table (alphabetical by element name):
 
-```html
-  <script type="module" src="../src/components/MyComponent.js"></script>
-  <script type="module" src="../src/components/Import.js"></script>
-  <script type="module" src="../src/components/Accordion.js"></script>
-  <script type="module" src="../src/components/Card.js"></script>
+```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
 
-Create `tests/components/MyComponent.browser-test.js`. Use an existing test file (e.g. `tests/components/Toggle.browser-test.js`) as a reference.
+**This step is required.** Skipping tests is a common mistake — AGENTS.md says "ALL tests must pass — ZERO failures are acceptable."
 
-Key conventions:
+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()` helper that builds the DOM, appends it to `document.body`, awaits `el.updateComplete`, and returns `{ container, el }`.
+- 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 (e.g. `/* Element Creation */`, `/* Properties */`).
+- 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
+- Element has a shadow root (when applicable)
 - Default property values are correct
-- Attribute reflection works (if applicable)
+- Attribute reflection works (when `reflect: true`)
 - Public methods behave correctly
-- Events are dispatched correctly (if applicable)
+- Events are dispatched correctly with the right `detail` shape
+- For form-associated components: form submission produces the expected value
 
-Example skeleton:
+Run the tests after writing them:
 
-```javascript
-import MyComponent from '../../src/components/MyComponent.js';
-
-const createMyComponent = async () => {
-  const container = document.createElement('div');
-  container.innerHTML = `<k-my-component></k-my-component>`;
-  document.body.appendChild(container);
-  const el = container.querySelector('k-my-component');
-  await el.updateComplete;
-  return { container, el };
-};
-
-const cleanup = (container) => {
-  if(container && container.parentNode){
-    container.parentNode.removeChild(container);
-  }
-};
-
-export default {
-  /*
-    Element Creation
-  */
-  'should create my-component element': async ({pass, fail}) => {
-    const { container, el } = await createMyComponent();
-    if(!(el instanceof MyComponent)){
-      cleanup(container);
-      return fail('Element should be instance of MyComponent');
-    }
-    cleanup(container);
-    pass('MyComponent element created correctly');
-  },
-};
+```bash
+npm run test -- MyComponent
 ```
 
-After writing the tests, run them to confirm they all pass:
+The partial string `MyComponent` matches any test file path containing it. Fix any failures before considering the component complete. Zero failures.
 
-```
-npm run test -- MyComponent
-```
+---
+
+## Step 6: Verify in the Browser
+
+The dev server is running on `http://localhost:8083` (don't start another).
+
+- Navigate to `http://localhost:8083/components/my-component.html`
+- Interact with the rendered output — golden path AND edge cases
+- Confirm form-associated behavior by submitting an actual `<form>`
+- Watch for console errors that aren't pre-existing
 
-The partial string `MyComponent` will match any test file whose path contains that string. Fix any failures before considering the component complete.
+If you cannot test the UI for some reason, say so explicitly rather than claiming success.
 
 ---
 
@@ -307,7 +337,7 @@ Any component using `position: fixed` must follow the kempo-css elevation system
 | 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|
+| 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 |
 
@@ -321,12 +351,13 @@ When deciding a new component's elevation:
 
 ---
 
-## Step 6: Update `llm.txt.md`
-
-Add a row for the new component to the **Components** table in `llm.txt.md` at the root of the repository. Keep the table in alphabetical order by element name.
-
-```markdown
-| `<k-my-component>` | `MyComponent.js` | One-sentence description | [my-component.html](https://dustinpoissant.github.io/kempo-ui/components/my-component.html) |
-```
+## Common Mistakes To Avoid
 
-If the component registers multiple elements (e.g. a parent + child pair), list all element names in the first column separated by spaces.
+- **Hand-writing the syntax-highlighted HTML** in code samples — use the [highlight-code skill](../highlight-code/SKILL.md) 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/`.
+- **Adding `<!DOCTYPE>` / `<html>` / `<head>` / `<body>` / `<k-import>` to a page file** — the template provides the document shell. Pages contain only `<page>` and `<content>` blocks.
+- **Using a relative path like `../src/components/...`** in a page — use `{{pathToRoot}}src/components/...` so it resolves correctly at any depth.
+- **Forgetting `class="no-btn"` on shadow-DOM `<button>` elements** — kempo-css aggressively styles native buttons; opt out and re-center with flex.
+- **Updating only one of the four wiring locations** (search filter, sidebar menu, homepage card, llms.txt) — all four must be updated for a new component.
+- **Truncating adjacent elements when editing `nav.fragment.html`** — search-and-replace boundaries must include whole lines; always re-read the file after editing to verify nothing was clipped.

package/AGENTS.md

@@ -7,7 +7,7 @@
  - All utility function module files should be in the `src/utils/` directory.
  - All documnentation should be in the `docs/` directory. This directory is used by GitHub as the "GitHub Pages", so all links need to be relative, and there will be a build script which copies all code to the `docs/` directory.
  - Documentation source files (templates, fragments, page files) are in the `docs-src/` directory. These use the kempo-server v3 templating system and are pre-rendered to `docs/` during build.
- - `llm.txt.md` in the root is the consumer-facing LLM reference for this library. **Keep it up to date**: when adding a new component or utility, add a row to the relevant table in `llm.txt.md`.
+ - `llms.txt` in the root is the consumer-facing LLM reference for this library. **Keep it up to date**: when adding a new component or utility, add a row to the relevant table in `llms.txt`.
  
 ## Dependencies
 
@@ -102,7 +102,7 @@ Do not prefix identifiers with underscores.
 - **DO NOT** start a development server - one is already running
 - Default port: **8083**
 - Base URL: `http://localhost:8083`
-- Documentation URLs follow the directory/file structure in `docs/` (e.g., `docs/components/color-picker.html` → `http://localhost:8083/components/color-picker.html`)
+- Documentation URLs follow the directory/file structure in `docs-src/` (e.g., source `docs-src/components/color-picker.page.html` → URL `http://localhost:8083/components/color-picker.html`). Edit the `*.page.html` source — never the generated `docs/` output.
 - Use this server for all testing and verification
 
 ### Testing and Verification