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

package/templates/new/.claude/commands/publish.md

@@ -0,0 +1,226 @@
+---
+description: Prepare {{PACKAGE_NAME}} for npm publish — bump version, finalize CHANGELOG/README, build, test, commit
+argument-hint: rc|release|patch|minor|major
+---
+
+# /publish — prepare an npm release of {{PACKAGE_NAME}}
+
+You are preparing this package for `npm publish`. **Do not run `npm publish`** — the user logs in and publishes manually.
+
+This command follows the canonical `/publish` structure defined in the BlissFramework component guidelines at
+`web-components/publish-command.md`. Sections marked **[canonical]** are byte-identical across every
+component's `/publish`; sections marked **[per-repo]** are customized for this repo's layout, build, and tests.
+
+## Argument [canonical]
+
+The release type: **$ARGUMENTS**
+
+Must be one of:
+
+- `rc` — ship the WIP rc as-is. The topmost CHANGELOG heading (e.g. `## [1.10.0-rc02] - 2026-06-18`) gets ` [PUBLISHED]` appended.
+- `release` — promote a WIP rc to a final release. `X.Y.Z-rcN` → `X.Y.Z`. CHANGELOG heading is renamed to match the new version.
+- `patch` — SemVer patch bump. Drops any `-rc` suffix.
+- `minor` — SemVer minor bump. Drops `-rc`. Resets patch.
+- `major` — SemVer major bump. Drops `-rc`. Resets minor and patch.
+
+If missing or invalid, stop and ask the user which one to use (don't guess).
+
+## Repo layout [per-repo]
+
+Single-package repo, everything at root:
+
+- **`./package.json`** — `version` field is the source of truth.
+- **`./CHANGELOG.md`** — at the root. Topmost `## [X.Y.Z] - YYYY-MM-DD` heading **without** the `[PUBLISHED]` marker is the WIP section.
+- **`./README.md`** — at the root. Carries `## What's New in vX.Y.Z` sections near the top (one per release, the **two most recent** retained).
+- **`./dist/`** — gitignored. Produced by `npm run build` (custom-elements-manifest analyze + Vite). Never staged.
+- **`./custom-elements.json`, `./web-types.json`, `./vscode.html-custom-data.json`, `./vscode.css-custom-data.json`** — generated by `npm run analyze` (part of the build) and **committed** (custom-elements-manifest D-CEM-2 = A).
+- **`./component-variables.manifest.json`** — published with the package. Edit if the variable surface changes; `npm run check:vars` validates it.
+- **`./docs/`** — usage / theming / examples / accessibility, published with the package.
+
+## CHANGELOG convention in this repo [canonical]
+
+There is **no `## [Unreleased]` section**. The WIP section is the topmost `## [X.Y.Z] - YYYY-MM-DD` heading without a `[PUBLISHED]` tag. Already-released sections carry `[PUBLISHED]` at the end of their heading:
+
+```
+## [1.10.0-rc02] - 2026-06-18                  ← WIP, the one you're shipping
+### Added
+- ...
+
+## [1.9.0] - 2026-06-09 [PUBLISHED]
+### Added
+- ...
+```
+
+Publishing the WIP section means **appending ` [PUBLISHED]`** to its heading — exact format: `## [X.Y.Z] - YYYY-MM-DD [PUBLISHED]`. The next development cycle creates a fresh `## [next-version] - <date>` heading on its first CHANGELOG edit.
+
+## Resolve versions [canonical]
+
+Read `./package.json` `version` as `CURRENT_VERSION`.
+Read the topmost `## [X.Y.Z...]` heading from `./CHANGELOG.md` as `WIP_VERSION` (the version the latest WIP section is tagged for).
+
+Compute `NEW_VERSION`:
+
+| Argument | Logic |
+|---|---|
+| `rc` | If `CURRENT_VERSION` matches `X.Y.Z-rcN`, `NEW_VERSION = CURRENT_VERSION` (no bump — we're shipping what's already in package.json). If `CURRENT_VERSION` is not an rc, stop and ask the user (they probably wanted `release`/`patch`/etc.). |
+| `release` | If `CURRENT_VERSION` matches `X.Y.Z-rcN`, `NEW_VERSION = X.Y.Z`. Otherwise stop. |
+| `patch` | Strip any `-rcN`, then bump patch. |
+| `minor` | Strip any `-rcN`, then bump minor, reset patch. |
+| `major` | Strip any `-rcN`, then bump major, reset minor and patch. |
+
+If `WIP_VERSION` ≠ `NEW_VERSION` (e.g. the WIP is `X.Y.Z-rcN` but the user asked for `release`), the CHANGELOG heading rename in step 3 also re-tags the section to `NEW_VERSION` — call this out in the report so the user notices.
+
+## Steps (in order)
+
+### 1. Sanity checks [canonical]
+
+- Run `git status`. The repo intentionally keeps `.claude/`, `test-results/`, `playwright-report/` and `dist-examples/` untracked — those are fine. If there are **other** uncommitted changes that aren't `CHANGELOG.md`, `README.md`, or `package.json`, list them and ask the user before continuing. (Typical case: substantive source changes belonging in this release that haven't been committed yet — confirm they're intended for this version before bumping.)
+- **Verify the new version isn't already on npm.** Run `npm view {{PACKAGE_NAME}}@<NEW_VERSION> version 2>/dev/null` — if it returns the version string, that version is already published and **stop**: bumping over it would fail at publish time and pollute the commit.
+- **Verify the registry hasn't drifted past you.** Run `npm view {{PACKAGE_NAME}} version` to fetch the latest published version on the `latest` tag; if it's higher than `NEW_VERSION` (e.g. someone shipped from another machine, or there's a registry-vs-local mismatch from before the [PUBLISHED] convention landed), warn the user and ask before continuing.
+- Confirm the WIP CHANGELOG section has at least one bullet of substantive content under `### Added`, `### Changed`, `### Removed`, `### Fixed`, or `### Internal`. If empty, stop — there's nothing meaningful to release.
+- Confirm `./README.md` has a `## What's New in vWIP_VERSION` section. If it's missing, draft one from the CHANGELOG and present it to the user for approval before continuing:
+  - Read the WIP CHANGELOG section, distill it to 5–8 scannable bullets covering the Added/Changed themes (paraphrase, don't copy CHANGELOG bullets verbatim — those are exhaustive; What's New is the highlight reel). Pure internal refactors and Fixed-only entries don't need coverage, though headline bug fixes worth advertising are worth a bullet.
+  - **Follow the canonical "What's New" format** defined in the BlissFramework component guidelines (`web-components/readme-structure.md` → "`## What's New in vX.Y.Z` — canonical format"). Auto-check **C-RS-16** in `readme-structure.checks.sh` enforces it. Concretely:
+    - **Heading:** `## What's New in vNEW_VERSION` — lowercase `v`, no backticks around the version, no date.
+    - **Each bullet:** `- **<area or component> — <one-line headline>** — <engineer-level prose, 3–8 sentences>`. Bold-wrapped lead phrase, then a true em-dash (` — `, U+2014 with surrounding spaces), then a prose body explaining *what changed*, *why* (regression history / motivation), *what surface is affected* (concrete component / prop / file names listed inline), and *the mechanism* (the technique used). Plain hyphens or en-dashes fail the check.
+    - **No `### ` sub-headings** inside a What's New section — no `### Added` / `### Fixed` lifted from the CHANGELOG. It's a flat bullet list.
+    - **Reference implementation:** the `## What's New in v1.3.3` / `v1.3.2` sections at the top of `svelte-fluentui/README.md` are the canonical shape — mirror that voice and structure.
+  - Show the user the proposed draft as plain markdown in your reply. Ask whether to (a) insert as-is, (b) edit, or (c) abort so they can write it themselves.
+  - Only proceed past step 1 once the user approves the draft (or supplies their own). On approval, insert the section directly above the current top `## What's New in vX.Y.Z` heading in `./README.md`, then continue.
+  - Do not silently insert the draft without confirmation — release highlights are a writing call and the user owns the voice.
+
+### 2. Bump version (if needed) [canonical]
+
+If `NEW_VERSION` ≠ `CURRENT_VERSION`, edit `./package.json` and change `"version": "CURRENT_VERSION"` to `"version": "NEW_VERSION"`.
+
+For `rc` arg this is normally a no-op — version was bumped earlier in the development cycle.
+
+### 3. Finalize CHANGELOG [canonical]
+
+In `./CHANGELOG.md`:
+
+- If `WIP_VERSION` ≠ `NEW_VERSION` (e.g. promoting `X.Y.Z-rcN` → `X.Y.Z`), rename the WIP heading from `## [WIP_VERSION] - <date>` to `## [NEW_VERSION] - <today>` (today's date from system context).
+- If `WIP_VERSION` == `NEW_VERSION`, leave the bracketed version alone but update the date to today **if** the existing date is stale (more than a few days old). The WIP date is usually whatever day the section was opened; refresh it so the changelog reflects the actual ship date.
+- In either case, **append ` [PUBLISHED]`** to the heading so it reads exactly: `## [NEW_VERSION] - YYYY-MM-DD [PUBLISHED]`.
+- Leave all bullet content untouched.
+- **Do not** create an empty new WIP section — the next dev cycle's first CHANGELOG edit will create one.
+
+### 4. Update README "What's New" — only if version changed [canonical]
+
+In `./README.md`:
+
+- If the existing `## What's New in vWIP_VERSION` section's version differs from `NEW_VERSION` (e.g. promoting `X.Y.Z-rcN` → `X.Y.Z`), rename its heading to `## What's New in vNEW_VERSION`. (No content rewrites — the text was already curated for this release.)
+- Then count the `## What's New in vX.Y.Z` headings. If there are more than **two**, delete the oldest ones so only the **two most recent** remain (the just-finalized one plus the one before it).
+
+For `rc` arg this is normally a no-op on the heading itself — only trims if someone left an extra-old section behind.
+
+### 5. Validate README reflects the release [canonical]
+
+Read both the finalized CHANGELOG section and the matching `What's New in vNEW_VERSION` section. Every **Added** or **Changed** bullet in the CHANGELOG that represents a user-facing feature or behavior change should have a corresponding hit in the What's New section (paraphrased, not verbatim). Pure internal refactors and `Fixed`-only entries don't need coverage, though headline bug fixes worth advertising (e.g. "X used to silently fail; now works") are worth a bullet.
+
+If you find a significant CHANGELOG entry that isn't reflected in What's New, add a bullet for it. If the section ends up with more than ~8 bullets after this pass, condense — What's New should be scannable, not exhaustive.
+
+### 6. Validate CHANGELOG entries match recent work [canonical]
+
+Find the previous `[PUBLISHED]` tag in CHANGELOG (the version just before NEW_VERSION) and locate the commit that bumped to it — usually a commit whose subject starts with `v<previous-version>` or `- v<previous-version>`. Run `git log --oneline <previous-publish-commit>..HEAD` to list commits since.
+
+Also check `git diff` (or `git status`) for any uncommitted source/test work outside the files you're editing in this command.
+
+For every substantive commit or uncommitted change, verify the WIP CHANGELOG section mentions it. If something significant is missing, **stop and ask the user** before finalizing — don't invent entries on their behalf. Pure example/doc tweaks and trivial typo fixes don't need entries.
+
+### 7. Run tests [per-repo]
+
+Run `npm run test:e2e` (or equivalently `make test-e2e`). e2e tests via Playwright. All specs must pass.
+
+If anything fails, **stop and report**. Do not proceed to build/commit. The user fixes the regression (or decides to fixme the spec) before the publish flow can continue.
+
+If Playwright complains that chromium isn't installed, suggest `make test-e2e-install` and stop.
+
+### 8. Build the package [per-repo]
+
+Run `npm run build` (or `make build`). This:
+- Runs `npm run analyze` — regenerates `custom-elements.json`, `web-types.json` and the VS Code custom-data files.
+- Runs Vite to emit `dist/{{FILE_NAME}}.js`, `dist/{{FILE_NAME}}.umd.js`, `dist/style.css`, and the type declarations.
+
+If the build errors, stop and report.
+
+After build, do a quick smoke check on the emitted artifacts:
+- `dist/{{FILE_NAME}}.js` and `dist/{{FILE_NAME}}.umd.js` both exist and are non-empty.
+- `dist/style.css` exists.
+- `dist/index.d.ts` (or whatever the `types` field points to) exists.
+- `git status` shows the regenerated CEM files only if the element API changed — stage them in step 10 if so.
+
+### 9. Verify the package contents [per-repo]
+
+Run `npm pack --dry-run` and confirm the file list includes:
+
+- `dist/` (built JS + d.ts files + style.css)
+- `custom-elements.json`, `web-types.json`, `vscode.html-custom-data.json`, `vscode.css-custom-data.json`
+- `component-variables.manifest.json`
+- `docs/`
+- `README.md`
+- `LICENSE`
+- `package.json`
+
+If anything user-facing is missing or anything private leaked in (e.g. `test/`, `e2e/`, `examples-*.html`, `*.spec.ts`, `tsconfig.json`, `vite.config.ts`), stop and report — the `files` field in `package.json` controls this and the leak needs fixing before publish.
+
+### 10. Commit [canonical]
+
+Stage:
+
+- `./CHANGELOG.md`
+- `./README.md`
+- `./package.json`
+- `./custom-elements.json`, `./web-types.json`, `./vscode.html-custom-data.json`, `./vscode.css-custom-data.json` (if the build regenerated them)
+
+Do **not** stage `dist/` — it's gitignored.
+
+Commit message format:
+
+```
+vNEW_VERSION - <one-line summary of the headline change>
+
+<grouped bullets paraphrased from the CHANGELOG section — split into the same
+groups the CHANGELOG used: Added, Fixed, Changed, Internal, etc. Keep bullets
+terse; full prose lives in the CHANGELOG.>
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+```
+
+### 11. Report [canonical]
+
+Report back with:
+
+- The new version number
+- The commit SHA
+- The exact commands to publish. **Pick the right one for the arg type:**
+  - For `rc` (publishing a pre-release):
+    ```
+    npm login          # if not already logged in
+    npm publish --tag rc
+    ```
+    The `--tag rc` is critical — without it npm assigns the `latest` dist-tag, which would make the pre-release the default install for everyone running `npm install {{PACKAGE_NAME}}`. With `--tag rc`, the `latest` tag stays put and consumers opt in via `@rc` or pinning the exact version.
+  - For `release` / `patch` / `minor` / `major` (publishing a stable release):
+    ```
+    npm login          # if not already logged in
+    npm publish
+    ```
+    Or `make publish`. No `--tag` needed — it correctly lands as `latest`.
+- A reminder that the CHANGELOG `[PUBLISHED]` tag is now in place — if `npm publish` fails, the user should revert both the tag (CHANGELOG heading) and the version bump (`package.json`) before retrying, since the registry will refuse to re-publish the same version.
+
+## Things not to do [canonical]
+
+- **Do not run `npm publish`.** The user publishes manually after `npm login`.
+- **Do not push to git remote.** The commit stays local until the user pushes.
+- **Do not create an empty `[Unreleased]` or new WIP heading** in CHANGELOG after finalizing — the next dev cycle's first edit creates the next heading.
+- **Do not retro-fix older CHANGELOG sections** that are missing the `[PUBLISHED]` tag or carry legacy markers — only finalize the section you're shipping.
+- **Do not silently insert a drafted What's New section.** If you draft one in Step 1 because it's missing, you must present it and wait for explicit approval (or edits) before inserting — the writing voice is the user's call, even when you're handing them a starting point.
+- **Do not keep more than two `## What's New in vX.Y.Z` sections in the README.** Step 4 trims older ones; if you see three or more after Step 4, you missed one.
+- **Do not skip the build step** — without it `dist/` is stale and the publish would ship outdated artifacts (or fail entirely if `dist/` was wiped by `make clean`).
+- **Do not skip the test gate** if the repo has one — the gate is what catches regressions before they ship.
+- **Do not invent CHANGELOG entries** to cover commits you find; ask the user if something's missing.
+- **Do not bump if there's nothing meaningful in the WIP section** — stop and explain.
+
+### Repo-specific don'ts
+
+- **Do not stage `test/`, `e2e/`, `test-results/`, `playwright-report/` or `dist-examples/`** — they're either ignored or test artifacts.

package/templates/new/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [{{VERSION}}] - {{TODAY}}
+
+### Added
+
+- Initial scaffold (`kmwc new`, `@keenmate/web-components-devkit`): `<{{TAG}}>` element (`{{ELEMENT_CLASS}}`) over the `{{LOGIC_CLASS}}` logic class, `label` / `active` inputs, `change` event with the `onChange` property twin.
+- Canonical CSS set (`src/css/`, prefix `{{PREFIX}}`) with `@layer variables, component, overrides`, `--base-*` fallback chains and Strategy-B dark mode.
+- Custom Elements Manifest (`custom-elements.json`, `web-types.json`, VS Code custom data) and `component-variables.manifest.json`.
+
+### Internal
+
+- Intake: technology web-component · package `{{PACKAGE_NAME}}` · tag `<{{TAG}}>` · CSS prefix `{{PREFIX}}` (reserve it in BlissFramework `guidelines/web-components/base-variables.md`) · dev port {{DEV_PORT}}.

package/templates/new/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) {{YEAR}} Keenmate s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/new/README.md

@@ -0,0 +1,71 @@
+# {{PACKAGE_NAME}}
+
+> {{TAGLINE}}
+
+## What is it
+
+`{{PACKAGE_NAME}}` is a custom element (`<{{TAG}}>`) built on
+[`@keenmate/web-components-core`](https://www.npmjs.com/package/@keenmate/web-components-core).
+It works in any HTML page or framework that can render a custom element —
+React, Vue, Svelte, Blazor, plain HTML.
+
+It reads `--base-*` variables from the page when `@keenmate/theme-designer`
+is present, falls back to sensible light/dark defaults otherwise, and supports
+per-instance dark mode via `data-theme`.
+
+## What's New in v{{VERSION}}
+
+- **`<{{TAG}}>` — initial release** — First version, scaffolded with `kmwc new` from `@keenmate/web-components-devkit`. Ships the Element / Logic / Side-layer split, the canonical eight-file CSS set with `@layer variables, component, overrides`, light/dark defaults through `light-dark()` fallbacks, a Custom Elements Manifest for editor tooling, and a `change` event with an `onChange` property twin. See [CHANGELOG.md](./CHANGELOG.md).
+
+## Demos & docs
+
+- 🚀 [Live demo](https://demos.keenmate.com/{{ID}})
+- 📘 [Usage / API reference](./docs/usage.md)
+- 🎨 [Theming contract](./docs/theming.md)
+- 📚 [Examples / cookbook](./docs/examples.md)
+- ♿ [Accessibility](./docs/accessibility.md)
+
+## Install
+
+```bash
+npm install {{PACKAGE_NAME}}
+```
+
+## Quick start
+
+```html
+<script type="module">
+  import '{{PACKAGE_NAME}}';
+</script>
+
+<{{TAG}} label="Hello"></{{TAG}}>
+```
+
+Clicking toggles the `active` state and dispatches a `change` event
+(`event.detail.isActive`). See [usage.md](./docs/usage.md) for the full API.
+
+## Browser support
+
+Modern evergreen browsers (Chrome, Edge, Firefox, Safari) — anything with
+native `customElements`, CSS `@layer` and `light-dark()` support. No polyfills
+shipped.
+
+## About
+
+Authored and maintained by [Keenmate s.r.o.](https://keenmate.com/).
+The component ships standalone with sensible light/dark defaults;
+when mounted inside [Pure Admin](https://pureadmin.io/) — or any
+host that publishes the `--base-*` taxonomy via
+[`@keenmate/theme-designer`](https://www.npmjs.com/package/@keenmate/theme-designer) — it adopts the host's colors,
+typography, and sizing automatically. There is no runtime
+dependency on Pure Admin; the integration is opt-in via CSS
+variables.
+
+## Built with BlissFramework
+
+Follows the [BlissFramework component guidelines](https://blissframework.dev/)
+for structure, theming, color-scheme, and accessibility.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/templates/new/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+dist-examples/
+test-results/
+playwright-report/
+*.tgz
+.makefile.env

package/templates/new/component-variables.manifest.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://raw.githubusercontent.com/keenmate/schemas/main/component-variables.schema.json",
+  "component": "{{PACKAGE_NAME}}",
+  "prefix": "{{PREFIX}}",
+  "baseVariables": [
+    { "name": "base-main-bg", "required": false, "usage": "Component surface" },
+    { "name": "base-text-color-1", "required": false, "usage": "Label text" },
+    { "name": "base-border-color", "required": false, "usage": "Button border" },
+    { "name": "base-primary-color", "required": false, "usage": "Active state fill, focus outline" },
+    { "name": "base-on-primary-text-color", "required": false, "usage": "Label text in the active state" },
+    { "name": "base-hover-bg", "required": false, "usage": "Hover background (falls back to the contract formula on --{{PREFIX}}-bg)" },
+    { "name": "base-font-family", "required": false, "usage": "Font family" },
+    { "name": "base-font-size-base", "required": false, "usage": "Font size (multiplier × --{{PREFIX}}-rem)" },
+    { "name": "base-border-radius-md", "required": false, "usage": "Corner radius (multiplier × --{{PREFIX}}-rem)" },
+    { "name": "base-input-size-md-height", "required": false, "usage": "Minimum height (multiplier × --{{PREFIX}}-rem)" }
+  ],
+  "componentVariables": [
+    { "name": "{{PREFIX}}-rem", "category": "spacing", "usage": "Base unit for every size (default 10px; 1rem follows the page font size)" },
+    { "name": "{{PREFIX}}-bg", "category": "surface", "usage": "Component surface" },
+    { "name": "{{PREFIX}}-text-color-1", "category": "text", "usage": "Label text" },
+    { "name": "{{PREFIX}}-border-color", "category": "border", "usage": "Button border" },
+    { "name": "{{PREFIX}}-accent-color", "category": "accent", "usage": "Active state fill, focus outline" },
+    { "name": "{{PREFIX}}-text-color-on-accent", "category": "text", "usage": "Label text in the active state" },
+    { "name": "{{PREFIX}}-hover-bg", "category": "state", "usage": "Hover background" },
+    { "name": "{{PREFIX}}-font-family", "category": "typography", "usage": "Font family" },
+    { "name": "{{PREFIX}}-font-size-base", "category": "typography", "usage": "Font size" },
+    { "name": "{{PREFIX}}-root-border-radius", "category": "radius", "usage": "Corner radius" },
+    { "name": "{{PREFIX}}-root-min-height", "category": "spacing", "usage": "Minimum height" },
+    { "name": "{{PREFIX}}-root-padding-block", "category": "spacing", "usage": "Vertical padding" },
+    { "name": "{{PREFIX}}-root-padding-inline", "category": "spacing", "usage": "Horizontal padding" }
+  ]
+}

package/templates/new/custom-elements-manifest.config.mjs

@@ -0,0 +1,23 @@
+import { blissAnalyzerConfig, cssVariablesFromManifestPlugin } from '@keenmate/web-components-core/cem';
+import { customElementVsCodePlugin } from 'custom-element-vs-code-integration';
+import { customElementJetBrainsPlugin } from 'custom-element-jet-brains-integration';
+
+/**
+ * Custom Elements Manifest (custom-elements-manifest.md). Core's
+ * blissAnalyzerConfig() reads the `static inputs` / `static events` tables
+ * (ATTRIBUTE_TABLE) straight from the AST, so attributes, properties and events
+ * in custom-elements.json come from the same table the runtime uses.
+ * cssVariablesFromManifestPlugin() adds the --{{PREFIX}}-* surface from
+ * component-variables.manifest.json; the editor plugins then emit
+ * vscode.html-custom-data.json / vscode.css-custom-data.json / web-types.json.
+ */
+export default blissAnalyzerConfig({
+  globs: ['src/**/*.ts'],
+  exclude: ['src/**/*.spec.ts', 'src/**/*.test.ts', 'src/**/*.d.ts', 'src/index.ts'],
+  outdir: '.',
+  plugins: [
+    cssVariablesFromManifestPlugin(),
+    customElementVsCodePlugin({ outdir: '.' }),
+    customElementJetBrainsPlugin({ outdir: '.', packageJson: false }),
+  ],
+});

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-primary-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-primary-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(30, 41, 59)');
+  });
+
+  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(30, 41, 59)');
+  });
+
+  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(30, 41, 59)');
+  });
+
+  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/);
+  });
+});