@keenmate/web-components-devkit 0.0.0-stage → 1.0.0-rc01

package/templates/new/docs/accessibility.md

@@ -0,0 +1,24 @@
+# Accessibility — `<{{TAG}}>`
+
+## Keyboard
+
+| Key | Action |
+|---|---|
+| `Tab` / `Shift+Tab` | Move focus to / from the toggle button. |
+| `Enter` / `Space` | Toggle the active state (native `<button>` behaviour). |
+
+## ARIA
+
+The toggle is a native `<button>` with `aria-pressed` reflecting the active
+state, so screen readers announce it as a toggle button. The label text is the
+accessible name.
+
+## Focus
+
+A visible `:focus-visible` outline uses `--{{PREFIX}}-accent-color`.
+
+## Contrast
+
+Default colours meet WCAG AA in both light and dark schemes. When overriding
+`--{{PREFIX}}-accent-color`, keep `--{{PREFIX}}-text-color-on-accent` legible
+on it (4.5:1).

package/templates/new/docs/examples.md

@@ -0,0 +1,33 @@
+# Examples — `<{{TAG}}>`
+
+Live examples: run `make dev` and open http://localhost:{{DEV_PORT}}.
+
+## Common patterns
+
+### React to the active state
+
+Shows the event API and the `active` attribute reflecting the state.
+
+```html
+<{{TAG}} id="toggle" label="Notifications"></{{TAG}}>
+<script type="module">
+  import '{{PACKAGE_NAME}}';
+  const toggle = document.getElementById('toggle');
+  toggle.addEventListener('change', (event) => {
+    console.log('notifications', event.detail.isActive ? 'on' : 'off');
+    // the element also reflects the state: toggle.hasAttribute('active')
+  });
+</script>
+```
+
+### A themed instance
+
+Combines a `--base-*` override (all components) with a `--{{PREFIX}}-*` one
+(this instance only), forced dark.
+
+```html
+<style>
+  :root { --base-accent-color: #10b981; }
+</style>
+<{{TAG}} label="Dark" data-theme="dark" style="--{{PREFIX}}-root-border-radius: 999px"></{{TAG}}>
+```

package/templates/new/docs/theming.md

@@ -0,0 +1,54 @@
+# Theming — `<{{TAG}}>`
+
+## Container contract
+
+The theme container is `:host` — the `<{{TAG}}>` element itself. It paints
+its own surface (`--{{PREFIX}}-bg`), so it is visible standalone. Attach
+`data-theme="dark|light"` to the element (per instance) or to any ancestor; the
+framework conventions `[data-bs-theme]` (Bootstrap) and `.dark` / `.light`
+(Tailwind and friends) are honoured too.
+
+## Variable contract
+
+Two layers, never three: `--base-*` is the cross-component hook (set by
+`@keenmate/theme-designer` or by you on `:root`), `--{{PREFIX}}-*` is the
+component-local override. The full list, with categories, is in
+[`component-variables.manifest.json`](../component-variables.manifest.json)
+(exported as `{{PACKAGE_NAME}}/manifest`).
+
+All sizes multiply through `--{{PREFIX}}-rem` (default `10px`; set `1rem` to
+follow the page font size).
+
+```css
+/* every Keenmate component on the page */
+:root { --base-accent-color: #10b981; }
+
+/* this component only */
+{{TAG}} { --{{PREFIX}}-accent-color: #8b5cf6; }
+```
+
+## Color-scheme strategy
+
+Strategy B (color-scheme.md): every colour falls back through
+`light-dark(<light>, <dark>)`, and the component sets `color-scheme` on the
+host only when you signal a theme (`data-theme`, `data-bs-theme`, `.dark`).
+Without a signal it inherits the page's `color-scheme` — declare
+`color-scheme: light dark` on your page to follow the OS.
+
+## Cascade-layer contract
+
+```css
+@layer variables, component, overrides;
+```
+
+Any unlayered rule of yours beats every rule of the component; any `--base-*`
+on `:root` beats the `variables` layer. If your page ships a universal reset
+(`* { margin: 0; padding: 0 }`), wrap it in a layer — an unlayered reset beats
+the component's layered defaults.
+
+## BEM hooks
+
+| Part | Class | `::part()` |
+|---|---|---|
+| The toggle button | `.{{PREFIX}}__root` (`.{{PREFIX}}__root--active` when active) | `::part(root)` |
+| The label | `.{{PREFIX}}__label` | `::part(label)` |

package/templates/new/docs/usage.md

@@ -0,0 +1,51 @@
+# Usage — `<{{TAG}}>`
+
+## Attributes / properties
+
+Every input works as an HTML attribute **and** a JS property (core input
+table, `ATTRIBUTE_TABLE` in `src/web-component.ts`).
+
+| Attribute | Property | Type | Default | Description |
+|---|---|---|---|---|
+| `label` | `label` | `string` | `"Hello from {{TAG}}"` | Text shown inside the component. |
+| `active` | `isActive` | `boolean` (`bool-default-false`: present = true, `"false"` = false) | `false` | Whether the component is in its active (pressed) state. |
+
+## Events
+
+| Event | `detail` (`{{EVENT_DETAIL_TYPE}}`) | Property twin | When |
+|---|---|---|---|
+| `change` | `{ isActive: boolean }` | `onChange` | The active state was toggled by the user. Bubbles, composed, not cancelable. |
+
+```js
+const el = document.querySelector('{{TAG}}');
+el.addEventListener('change', (event) => console.log(event.detail.isActive));
+el.onChange = (event) => console.log(event.detail.isActive); // same event, property form
+```
+
+## Slots / children
+
+None.
+
+## Methods
+
+None beyond the core `BlissElement` API (`setAttributes()`, `batch()`, `whenSettled()`).
+
+## Lifecycle notes
+
+The element builds its shadow DOM on first connect; attribute and property
+changes are batched into one update per microtask (`await el.whenSettled()`
+before reading rendered state in tests).
+
+## Editor integration
+
+The package ships a Custom Elements Manifest plus VS Code custom data. Add to
+`.vscode/settings.json` for attribute autocomplete in HTML:
+
+```json
+{
+  "html.customData": ["./node_modules/{{PACKAGE_NAME}}/vscode.html-custom-data.json"],
+  "css.customData": ["./node_modules/{{PACKAGE_NAME}}/vscode.css-custom-data.json"]
+}
+```
+
+JetBrains IDEs pick up `web-types.json` automatically.

package/templates/new/e2e/dark-mode.spec.ts

@@ -0,0 +1,30 @@
+import { test, expect, type Page } from '@playwright/test';
+
+// Dark-mode signals (rulebook color-scheme.md): page color-scheme, framework
+// class on an ancestor, and the per-instance data-theme attribute.
+const getHostBackground = (page: Page, selector: string) =>
+  page.locator(selector).evaluate((element) => getComputedStyle(element).backgroundColor);
+
+test.describe('<{{TAG}}> dark mode', () => {
+  test('defaults to light, per-instance data-theme="dark" goes dark', async ({ page }) => {
+    await page.goto('/test/dark-mode.html');
+    expect(await getHostBackground(page, '#light-default')).toBe('rgb(255, 255, 255)');
+    expect(await getHostBackground(page, '#dark-instance')).toBe('rgb(26, 26, 26)');
+  });
+
+  test('an ancestor data-theme="dark" reaches the component', async ({ page }) => {
+    await page.goto('/test/dark-mode.html');
+    expect(await getHostBackground(page, '#dark-ancestor')).toBe('rgb(26, 26, 26)');
+  });
+
+  test('a page color-scheme of dark is inherited', async ({ page }) => {
+    await page.goto('/test/dark-mode.html');
+    await page.evaluate(() => (document.documentElement.style.colorScheme = 'dark'));
+    expect(await getHostBackground(page, '#light-default')).toBe('rgb(26, 26, 26)');
+  });
+
+  test('--base-* themes the component', async ({ page }) => {
+    await page.goto('/test/dark-mode.html');
+    expect(await getHostBackground(page, '#base-themed')).toBe('rgb(255, 0, 0)');
+  });
+});

package/templates/new/e2e/smoke.spec.ts

@@ -0,0 +1,26 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('<{{TAG}}>', () => {
+  test('renders the label and reacts to attribute changes', async ({ page }) => {
+    await page.goto('/test/fixture.html');
+    const label = page.locator('#subject .{{PREFIX}}__label');
+    await expect(label).toHaveText('fixture');
+
+    await page.evaluate(() => document.getElementById('subject')!.setAttribute('label', 'changed'));
+    await expect(label).toHaveText('changed');
+  });
+
+  test('click toggles the active state, reflects it and fires change', async ({ page }) => {
+    await page.goto('/test/fixture.html');
+    const changeDetails = page.evaluate(
+      () =>
+        new Promise<unknown>((resolve) =>
+          document.getElementById('subject')!.addEventListener('change', (event) => resolve((event as CustomEvent).detail), { once: true })
+        )
+    );
+    await page.locator('#subject .{{PREFIX}}__root').click();
+    expect(await changeDetails).toEqual({ isActive: true });
+    await expect(page.locator('#subject')).toHaveAttribute('active', '');
+    await expect(page.locator('#subject .{{PREFIX}}__root')).toHaveClass(/{{PREFIX}}__root--active/);
+  });
+});

package/templates/new/examples-basic.html

@@ -0,0 +1,57 @@
+<meta name="kmwc:title" content="Basic Usage">
+<meta name="kmwc:subtitle" content="The essentials of &lt;{{TAG}}&gt;.">
+
+<!-- A fragment page: the devkit layout adds <head>, the header (back link,
+     title, subtitle), the container and the component entry script; the kit
+     adds the shared styles, chapter nav, copy-links and theme switch.
+     Each <kmwc-demo> renders its markup live AND as a code block. -->
+
+<div class="card">
+    <h2>BU01 · Label &amp; active state</h2>
+    <p>Every input is reactive through attribute and property alike. Click the component to toggle it — it fires <code>change</code>.</p>
+    <div class="controls">
+        <label>label <input type="text" id="bu-label" value="Hello from {{TAG}}"></label>
+        <label><input type="checkbox" id="bu-active"> <code>active</code></label>
+    </div>
+    <kmwc-demo>
+        <{{TAG}} id="ex-basic"></{{TAG}}>
+    </kmwc-demo>
+    <div class="log-panel" id="bu-log">Click the component…</div>
+</div>
+
+<div class="card">
+    <h2>BU02 · Declarative markup</h2>
+    <p>No JavaScript needed — attributes only.</p>
+    <kmwc-demo>
+        <{{TAG}} label="Pre-activated" active></{{TAG}}>
+    </kmwc-demo>
+</div>
+
+<div class="card">
+    <h2>BU03 · Listening for changes</h2>
+    <p>The <code>change</code> event carries <code>detail.isActive</code>; the script below runs on this page and is shown verbatim.</p>
+    <kmwc-demo>
+        <{{TAG}} id="ex-events" label="Off"></{{TAG}}>
+        <script type="module" data-kmwc-show>
+            const toggle = document.getElementById('ex-events');
+            toggle.addEventListener('change', (event) => {
+                toggle.setAttribute('label', event.detail.isActive ? 'On' : 'Off');
+            });
+        </script>
+    </kmwc-demo>
+</div>
+
+<script type="module">
+    import { attachControlsPersistence } from '@keenmate/web-components-devkit/examples';
+
+    const example = document.getElementById('ex-basic');
+    const log = document.getElementById('bu-log');
+    document.getElementById('bu-label').addEventListener('input', (event) => example.setAttribute('label', event.target.value));
+    document.getElementById('bu-active').addEventListener('change', (event) => example.toggleAttribute('active', event.target.checked));
+    example.addEventListener('change', (event) => {
+        log.textContent = `change → isActive: ${event.detail.isActive}`;
+        document.getElementById('bu-active').checked = event.detail.isActive;
+    });
+
+    attachControlsPersistence('basic');
+</script>

package/templates/new/examples-theming.html

@@ -0,0 +1,28 @@
+<meta name="kmwc:title" content="Theming">
+<meta name="kmwc:subtitle" content="--base-* / --{{PREFIX}}-* overrides and the dark-mode signals.">
+
+<kmwc-include src="partials/note.html" title="Theme signals">
+    The ☀/☾ switch (top right) sets <code>data-theme</code> on the page — the
+    same signal a host app sends. <code>data-theme</code> on one instance wins.
+</kmwc-include>
+
+<div class="card">
+    <h2>TH01 · Dark-mode signals</h2>
+    <p>Page theme reaches every instance; <code>data-theme</code> on one instance overrides it.</p>
+    <kmwc-demo>
+        <{{TAG}} id="th-follow" label="Follows the page" active></{{TAG}}>
+        <{{TAG}} id="th-dark" label="data-theme=dark" data-theme="dark" active></{{TAG}}>
+        <{{TAG}} id="th-light" label="data-theme=light" data-theme="light" active></{{TAG}}>
+    </kmwc-demo>
+</div>
+
+<div class="card">
+    <h2>TH02 · Variable overrides</h2>
+    <p><code>--base-accent-color</code> themes every Keenmate component in a subtree; <code>--{{PREFIX}}-accent-color</code> one instance.</p>
+    <kmwc-demo>
+        <div style="--base-accent-color: #10b981">
+            <{{TAG}} id="th-base" label="--base-accent-color" active></{{TAG}}>
+            <{{TAG}} id="th-local" label="--{{PREFIX}}-accent-color" active style="--{{PREFIX}}-accent-color: #8b5cf6"></{{TAG}}>
+        </div>
+    </kmwc-demo>
+</div>

package/templates/new/index.html

@@ -0,0 +1,16 @@
+<meta name="kmwc:layout" content="bare">
+<meta name="kmwc:entry" content="none">
+
+<!-- Header, cards, footer, version badge and the cross-page nav are all
+     rendered by the devkit from this registry + package.json#kmwc. -->
+<script type="module">
+    import { renderExamplesIndex } from '@keenmate/web-components-devkit/examples';
+
+    renderExamplesIndex({
+        pages: [
+            { href: 'examples-basic.html', icon: '🧩', title: 'Basic Usage', description: 'The essentials, as one live component driven by control switches.' },
+            { href: 'examples-theming.html', icon: '🎨', title: 'Theming', description: 'Dark-mode signals, --base-* and --{{PREFIX}}-* overrides.' },
+        ],
+        links: [{ label: 'API Docs', href: 'https://github.com/keenmate/{{ID}}/blob/main/docs/usage.md' }],
+    });
+</script>

package/templates/new/partials/note.html

@@ -0,0 +1,5 @@
+<!-- Shared callout: <kmwc-include src="partials/note.html" title="…">body</kmwc-include> -->
+<div class="note info">
+    <div class="note-title">{{title}}</div>
+    {{content}}
+</div>

package/templates/new/playwright.config.ts

@@ -0,0 +1,4 @@
+import { definePlaywrightConfig } from '@keenmate/web-components-devkit/playwright';
+
+// Specs in e2e/ target fixture pages under test/*.html on kmwc.ports.dev.
+export default definePlaywrightConfig();

package/templates/new/src/__FEATURE__.ts

@@ -0,0 +1,55 @@
+/**
+ * Logic class: framework-agnostic state + rendering for {{PACKAGE_NAME}}.
+ * Knows nothing about custom elements — it renders into the container it is
+ * given and reports back through the `on*` events in its config. The Element
+ * layer (web-component.ts) owns attribute parsing and DOM events.
+ */
+import type { {{CONFIG_TYPE}} } from './types.js';
+
+const CSS_CLASSES = {
+  root: '{{PREFIX}}__root',
+  rootActive: '{{PREFIX}}__root--active',
+  label: '{{PREFIX}}__label',
+} as const;
+
+export class {{LOGIC_CLASS}} {
+  #container: HTMLElement;
+  #config: {{CONFIG_TYPE}};
+  #rootElement: HTMLButtonElement | null = null;
+  #labelElement: HTMLSpanElement | null = null;
+
+  constructor(container: HTMLElement, config: {{CONFIG_TYPE}}) {
+    this.#container = container;
+    this.#config = { ...config };
+    this.render();
+  }
+
+  /** Build the markup once. */
+  render(): void {
+    this.#container.innerHTML = `<button type="button" class="${CSS_CLASSES.root}" part="root"><span class="${CSS_CLASSES.label}" part="label"></span></button>`;
+    this.#rootElement = this.#container.querySelector(`.${CSS_CLASSES.root}`);
+    this.#labelElement = this.#container.querySelector(`.${CSS_CLASSES.label}`);
+    this.#rootElement?.addEventListener('click', this.handleRootClick);
+    this.update(this.#config);
+  }
+
+  /** Patch the rendered DOM to a (partial) new config. */
+  update(partialConfig: Partial<{{CONFIG_TYPE}}>): void {
+    this.#config = { ...this.#config, ...partialConfig };
+    if (this.#labelElement) this.#labelElement.textContent = this.#config.label;
+    this.#rootElement?.classList.toggle(CSS_CLASSES.rootActive, this.#config.isActive);
+    this.#rootElement?.setAttribute('aria-pressed', String(this.#config.isActive));
+  }
+
+  toggle(): void {
+    this.update({ isActive: !this.#config.isActive });
+    this.#config.onChange?.({ isActive: this.#config.isActive });
+  }
+
+  destroy(): void {
+    this.#rootElement?.removeEventListener('click', this.handleRootClick);
+    this.#container.innerHTML = '';
+  }
+
+  private handleRootClick = (): void => this.toggle();
+}

package/templates/new/src/css/animations.css

@@ -0,0 +1 @@
+/* animations.css — no keyframe animations in this component. */

package/templates/new/src/css/base.css

@@ -0,0 +1,43 @@
+/* ==============================================================================
+   BASE STYLES
+   ==============================================================================
+   FOUC prevention and the theme container (:host). */
+
+/* ==============================================================================
+   FOUC PREVENTION
+   ==============================================================================
+   Light-DOM rule (reaches the page via index.ts's side-effect CSS import):
+   reserve the post-upgrade footprint and hide child text until the element is
+   defined. The tag MUST equal the customElements.define() tag. */
+{{TAG}}:not(:defined) {
+    display: inline-block;
+    min-height: calc(3.5 * 10px);
+    color: transparent !important;
+    background: transparent;
+}
+
+/* ==============================================================================
+   THEME CONTAINER
+   ==============================================================================
+   :host is the container: layout sanity, the default surface, text colour and
+   font. Self-painted host (D-TC-3 case 1). */
+:host {
+    display: inline-block;
+    position: relative;
+    box-sizing: border-box;
+    background: var(--{{PREFIX}}-bg);
+    color: var(--{{PREFIX}}-text-color-1);
+    font-family: var(--{{PREFIX}}-font-family);
+    font-size: var(--{{PREFIX}}-font-size-base);
+    border-radius: var(--{{PREFIX}}-root-border-radius);
+}
+
+:host([hidden]) {
+    display: none;
+}
+
+*,
+*::before,
+*::after {
+    box-sizing: inherit;
+}

package/templates/new/src/css/controls.css

@@ -0,0 +1,20 @@
+/* ==============================================================================
+   CONTROLS
+   ==============================================================================
+   The root toggle button. */
+.{{PREFIX}}__root {
+    display: inline-flex;
+    align-items: center;
+    min-height: var(--{{PREFIX}}-root-min-height);
+    padding: var(--{{PREFIX}}-root-padding-block) var(--{{PREFIX}}-root-padding-inline);
+    border: 1px solid var(--{{PREFIX}}-border-color);
+    border-radius: var(--{{PREFIX}}-root-border-radius);
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    cursor: pointer;
+}
+
+.{{PREFIX}}__label {
+    white-space: nowrap;
+}

package/templates/new/src/css/dark-mode.css

@@ -0,0 +1,36 @@
+/* ==============================================================================
+   DARK MODE — framework class + per-instance signal handling (Strategy B)
+   ==============================================================================
+   Every --{{PREFIX}}-* colour in variables.css resolves through light-dark(),
+   so flipping `color-scheme` on the host picks the right branch without
+   touching any --base-* value — the consumer's themed --base-* stays the
+   source of truth. Declared ONLY when the consumer signals intent, never bare
+   on :host (that would shadow the page's inherited color-scheme).
+
+   Signals handled (color-scheme.md):
+     #1-#3 OS / forced / page color-scheme — inherited, light-dark() resolves.
+     #4 Framework class on an ancestor — [data-theme], [data-bs-theme], .dark / .light
+     #5 Per-instance attribute — <{{TAG}} data-theme="dark|light">, wins over #4. */
+
+/* DARK — framework class on an ancestor (signal #4) */
+:host-context([data-theme="dark"]),
+:host-context([data-bs-theme="dark"]),
+:host-context(.dark) {
+    color-scheme: dark;
+}
+
+/* LIGHT — framework class on an ancestor (signal #4) */
+:host-context([data-theme="light"]),
+:host-context([data-bs-theme="light"]),
+:host-context(.light) {
+    color-scheme: light;
+}
+
+/* Per-instance attribute on the host (signal #5) */
+:host([data-theme="dark"]) {
+    color-scheme: dark;
+}
+
+:host([data-theme="light"]) {
+    color-scheme: light;
+}

package/templates/new/src/css/floating.css

@@ -0,0 +1 @@
+/* floating.css — no floating elements in this component. */

package/templates/new/src/css/main.css

@@ -0,0 +1,27 @@
+/* ==============================================================================
+   {{TITLE_UPPER}} — MAIN ENTRY POINT
+   ==============================================================================
+   Cascade layer order (later = higher priority):
+     variables  — :host { --{{PREFIX}}-* } declarations
+     component  — base + feature rules
+     overrides  — dark mode, framework themes, per-instance overrides
+
+   Consumer override contract:
+   - Any unlayered consumer rule beats every rule in these layers.
+   - Any :root --base-* declaration beats the variables layer trivially.
+*/
+
+@layer variables, component, overrides;
+
+/* === SKELETON + CANONICAL CONCERNS (Tier 1 + Tier 2) === */
+@import url('./variables.css')      layer(variables);
+@import url('./base.css')           layer(component);
+@import url('./controls.css')       layer(component);
+@import url('./floating.css')       layer(component);
+@import url('./states.css')         layer(component);
+@import url('./animations.css')     layer(component);
+
+/* === COMPONENT-SPECIFIC FEATURES (Tier 3 — alphabetized) === */
+
+/* === OVERRIDES === */
+@import url('./dark-mode.css')      layer(overrides);

package/templates/new/src/css/states.css

@@ -0,0 +1,22 @@
+/* ==============================================================================
+   STATES
+   ==============================================================================
+   Hover, focus and the active (pressed) modifier. */
+.{{PREFIX}}__root:hover {
+    background: var(--{{PREFIX}}-hover-bg);
+}
+
+.{{PREFIX}}__root:focus-visible {
+    outline: 2px solid var(--{{PREFIX}}-accent-color);
+    outline-offset: 2px;
+}
+
+.{{PREFIX}}__root--active {
+    background: var(--{{PREFIX}}-accent-color);
+    border-color: var(--{{PREFIX}}-accent-color);
+    color: var(--{{PREFIX}}-text-color-on-accent);
+}
+
+.{{PREFIX}}__root--active:hover {
+    background: var(--{{PREFIX}}-accent-color);
+}

package/templates/new/src/css/variables.css

@@ -0,0 +1,40 @@
+/* ==============================================================================
+   CSS CUSTOM PROPERTIES (:host level)
+   ==============================================================================
+   Every --{{PREFIX}}-* variable reads through the cross-component --base-* hook
+   with a standalone fallback; colours fall back to light-dark(), so the
+   component follows the page's color-scheme. `color-scheme` is deliberately
+   NOT declared here (it would shadow the page's) — see dark-mode.css.
+
+   Override from outside the shadow DOM:
+     {{TAG}} { --{{PREFIX}}-accent-color: #10b981; }
+   ============================================================================== */
+
+:host {
+    /* ==========================================================================
+       SCALE
+       ==========================================================================
+       Unitless --base-* sizes multiply through --{{PREFIX}}-rem. Set it to 1rem
+       to follow the host page's font size (Pure Admin integration). */
+    --{{PREFIX}}-rem: 10px;
+
+    /* ==========================================================================
+       COLORS
+       ========================================================================== */
+    --{{PREFIX}}-bg: var(--base-main-bg, light-dark(#ffffff, #1a1a1a));
+    --{{PREFIX}}-text-color-1: var(--base-text-color-1, light-dark(#242424, #f5f5f5));
+    --{{PREFIX}}-border-color: var(--base-border-color, light-dark(#e0e0e0, #3d3d3d));
+    --{{PREFIX}}-accent-color: var(--base-accent-color, light-dark(#0078d4, #3a96dd));
+    --{{PREFIX}}-text-color-on-accent: var(--base-text-color-on-accent, light-dark(#ffffff, #ffffff));
+    --{{PREFIX}}-hover-bg: var(--base-hover-bg, color-mix(in srgb, var(--{{PREFIX}}-text-color-1) 8%, var(--{{PREFIX}}-bg)));
+
+    /* ==========================================================================
+       TYPOGRAPHY & SHAPE
+       ========================================================================== */
+    --{{PREFIX}}-font-family: var(--base-font-family, inherit);
+    --{{PREFIX}}-font-size-base: calc(var(--base-font-size-base, 1.6) * var(--{{PREFIX}}-rem));
+    --{{PREFIX}}-root-border-radius: calc(var(--base-border-radius-md, 0.6) * var(--{{PREFIX}}-rem));
+    --{{PREFIX}}-root-min-height: calc(var(--base-input-size-md-height, 3.5) * var(--{{PREFIX}}-rem));
+    --{{PREFIX}}-root-padding-block: calc(0.6 * var(--{{PREFIX}}-rem));
+    --{{PREFIX}}-root-padding-inline: calc(1.2 * var(--{{PREFIX}}-rem));
+}

package/templates/new/src/env.d.ts

@@ -0,0 +1,7 @@
+// Build-time constants defined by the devkit Vite preset (from package.json).
+declare const __VERSION__: string;
+declare const __PACKAGE_NAME__: string;
+declare const __AUTHOR__: string;
+declare const __LICENSE__: string;
+declare const __REPOSITORY__: string;
+declare const __HOMEPAGE__: string;

package/templates/new/src/index.ts

@@ -0,0 +1,17 @@
+// Light-DOM stylesheet (dist/style.css) — carries the :not(:defined) FOUC rule
+// from base.css. The shadow root gets the same CSS via ?inline in web-component.ts.
+import './css/main.css';
+
+import { registerComponent } from '@keenmate/web-components-core';
+import { {{ELEMENT_CLASS}} } from './web-component.js';
+import { logging } from './logger.js';
+
+export { {{ELEMENT_CLASS}} };
+export { {{LOGIC_CLASS}} } from './{{FEATURE}}.js';
+export type { {{CONFIG_TYPE}}, {{EVENT_DETAIL_TYPE}} } from './types.js';
+export { logging };
+
+registerComponent('{{TAG}}', {{ELEMENT_CLASS}} as unknown as CustomElementConstructor, {
+  config: { name: __PACKAGE_NAME__, version: __VERSION__, author: __AUTHOR__ },
+  logging,
+});

package/templates/new/src/logger.ts

@@ -0,0 +1,11 @@
+/**
+ * Side layer: categorized loggers for {{PACKAGE_NAME}}, built on the core
+ * logging module. Enable from the console:
+ *
+ *     window.components['{{TAG}}'].logging.enableLogging();
+ */
+import { createLoggers } from '@keenmate/web-components-core';
+
+export const LOGGING_CATEGORIES = ['INIT', 'UI', 'INTERACTION'] as const;
+
+export const logging = createLoggers('{{LOG_NAME}}', LOGGING_CATEGORIES);