@incursa/ui-kit 1.5.0 → 1.7.0

package/LLMS.txt

@@ -32,7 +32,7 @@ Primary files:
 - [`specs/verification/ui-kit/_index.md`](specs/verification/ui-kit/_index.md): auditable source-review, smoke-validation, and Playwright browser-automation baseline for the UI kit surface.
 - [`states.html`](states.html), [`forms-and-validation.html`](forms-and-validation.html), [`data-grid-advanced.html`](data-grid-advanced.html), [`overlay-workflows.html`](overlay-workflows.html): workflow-heavy composition patterns.
 - [`demo.html`](demo.html), [`work-queue.html`](work-queue.html), [`record-detail.html`](record-detail.html), [`native-patterns.html`](native-patterns.html): fuller page examples.
-- The v1 Web Component families are layouts and shells, navbar/tabs/user-menu, field/input-group/choice-group/readonly-field/validation-summary, state-panel/live-region/auto-refresh/theme-switcher, and disclosure/dialog/drawer.
+- The v1 Web Component families are layouts and shells, navbar/tabs/user-menu, field/input-group/choice-group/readonly-field/validation-summary, state-panel/live-region/auto-refresh/theme-switcher, badge/spinner atoms, button/button-group/button-toolbar/close-button hosts, alert/empty-state/list-group/key-value hosts, and disclosure/dialog/drawer.
 - Prefer those browser-native components for supported v1 surfaces when the consumer wants declarative markup from plain HTML/JS; keep CSS-first HTML for surfaces that are intentionally outside the WC layer.
 - Tables, utilities, filter/bulk/file workflows, permission banners, toasts, and compatibility overlay shells stay CSS-only or deferred in v1.
 
@@ -61,11 +61,11 @@ Core primitives:
 - Cards and shells: use [`inc-card`](reference.html) for plain cards. Use [`inc-header-body`](reference.html) for titled sections with actions. Use [`inc-header-body--table-body`](reference.html) when the body contains a table and should keep body padding without extra bottom table margin.
 - App layout: use [`inc-app-shell`](reference.html), [`inc-page`](reference.html), [`inc-breadcrumb-body`](reference.html), [`inc-footer-bar`](reference.html), [`inc-footer-bar__menu`](reference.html), [`inc-footer-bar__meta`](reference.html), [`inc-navbar`](reference.html), [`inc-breadcrumb`](reference.html), [`inc-nav-triad`](reference.html), and [`inc-sidebar-menu`](reference.html).
 - Utilities: use [`inc-u-stack-*`](reference.html), [`inc-u-gap-*`](reference.html), [`inc-grid`](reference.html), [`inc-row`](reference.html), [`inc-col`](reference.html), [`inc-stack`](reference.html), and [`inc-flex-*`](reference.html) when composition needs a public helper class.
-- States and workflow: use [`inc-state-panel`](reference.html), [`inc-permission-banner`](reference.html), [`inc-toast-card`](reference.html), [`inc-timeline`](reference.html), [`inc-file-dropzone`](reference.html), [`inc-file-row`](reference.html), and [`inc-key-value`](reference.html).
+- States and workflow: use [`inc-state-panel`](reference.html), [`inc-permission-banner`](reference.html), [`inc-toast-card`](reference.html), [`inc-empty-state`](reference.html), [`inc-list-group`](reference.html), [`inc-key-value`](reference.html), [`inc-timeline`](reference.html), [`inc-file-dropzone`](reference.html), and [`inc-file-row`](reference.html).
 - Interaction: use [`data-inc-toggle="menu"`](src/inc-design-language.js), [`data-inc-toggle="tab"`](src/inc-design-language.js), and [`data-inc-toggle="collapse"`](src/inc-design-language.js) with [`data-inc-target="#target-id"`](src/inc-design-language.js) when you want the helper to wire behavior. Use [`data-inc-dismiss="modal"`](src/inc-design-language.js) / [`data-inc-dismiss="offcanvas"`](src/inc-design-language.js), [`data-inc-accordion`](src/inc-design-language.js), [`data-inc-backdrop-for`](src/inc-design-language.js), [`data-inc-initial-focus`](src/inc-design-language.js), [`data-inc-auto-refresh`](src/inc-design-language.js), and the [`data-inc-refresh-seconds`](src/inc-design-language.js), [`data-inc-refresh-label`](src/inc-design-language.js), [`data-inc-refresh-loading-label`](src/inc-design-language.js), [`data-inc-refresh-paused-label`](src/inc-design-language.js), [`data-inc-refresh-pause-action-label`](src/inc-design-language.js), and [`data-inc-refresh-resume-action-label`](src/inc-design-language.js) hooks when you need the rest of the helper contract. Use [`data-inc-native-dialog-open="dialog-id"`](src/inc-design-language.js) when you want the helper to open a native `<dialog>`.
-- Web Components: prefer the same-package entrypoint for layouts, navbar/tabs/user-menu, field/input wrappers, state/live-region/auto-refresh/theme switcher, and disclosure/dialog/drawer shells. Keep tables, utilities, filter/bulk/file workflows, and presentation-only atoms CSS-first in v1.
+- Web Components: prefer the same-package entrypoint for layouts, navbar/tabs/user-menu, field/input wrappers, badge/spinner atoms, button/action/detail/collection hosts, state/live-region/auto-refresh/theme switcher, and disclosure/dialog/drawer shells. Keep tables, utilities, filter/bulk/file workflows, and the remaining presentation-only atoms CSS-first in v1.
 - Native interaction: use [`details.inc-disclosure`](reference.html), [`details.inc-native-menu`](reference.html), and [`dialog.inc-native-dialog`](reference.html).
-- Status: use [`inc-badge--success|warning|danger|info`](reference.html).
+- Status: use [`inc-badge`](reference.html) with tone values such as `success`, `warning`, `danger`, or `info`; use [`inc-spinner`](reference.html) with `variant="border|grow"`, optional tone, `size="sm"`, and a `label` for accessible loading state.
 - Metrics: use [`inc-summary-overview`](reference.html) and [`inc-summary-block`](reference.html).
 
 Customization order:

package/README.md

@@ -36,10 +36,11 @@ The v1 Web Component scope covers:
 - layouts and shells: [`inc-app-shell`](reference.html), [`inc-page`](reference.html), [`inc-page-header`](reference.html), [`inc-section`](reference.html), [`inc-card`](reference.html), [`inc-summary-overview`](reference.html), [`inc-summary-block`](reference.html), [`inc-footer-bar`](reference.html)
 - navigation: [`inc-navbar`](reference.html), [`inc-tabs`](reference.html), [`inc-user-menu`](reference.html)
 - forms and inputs: [`inc-field`](reference.html), [`inc-input-group`](reference.html), [`inc-choice-group`](reference.html), [`inc-readonly-field`](reference.html), [`inc-validation-summary`](reference.html)
-- feedback and status: [`inc-state-panel`](reference.html), [`inc-live-region`](reference.html), [`inc-auto-refresh`](reference.html), [`inc-theme-switcher`](reference.html)
+- feedback and status: [`inc-state-panel`](reference.html), [`inc-live-region`](reference.html), [`inc-auto-refresh`](reference.html), [`inc-theme-switcher`](reference.html), [`inc-badge`](reference.html), [`inc-spinner`](reference.html)
+- actions and detail shells: [`inc-button`](reference.html), [`inc-button-group`](reference.html), [`inc-button-toolbar`](reference.html), [`inc-close-button`](reference.html), [`inc-alert`](reference.html), [`inc-empty-state`](reference.html), [`inc-list-group`](reference.html), [`inc-key-value-grid`](reference.html), [`inc-key-value`](reference.html)
 - overlays and disclosures: [`inc-disclosure`](reference.html), [`inc-dialog`](reference.html), [`inc-drawer`](reference.html)
 
-The intentionally deferred surfaces stay CSS-first in v1, including tables and data presentation, filter and bulk toolbars, file workflows, permission banners, toasts, utility helpers, and the remaining compatibility overlay shells.
+The intentionally deferred surfaces stay CSS-first in v1, including tables and the remaining data presentation surfaces, filter and bulk toolbars, file workflows, permission banners, toasts, utility helpers, and the remaining compatibility overlay shells.
 
 For maintainers, treat the Web Component layer as an additive wrapper over the same design language: one package, one token system, one naming vocabulary, and the same helper behavior where it already exists.
 
@@ -159,10 +160,10 @@ For titled sections that wrap tables, use [`inc-header-body--table-body`](refere
 
 ## CSS-only vs JS-assisted
 
-- CSS-only/native behavior is enough for layout, cards, tables, buttons, alerts, form fields, badges, breadcrumbs, sticky footer, and most surface styling.
+- CSS-only/native behavior is enough for layout, cards, tables, breadcrumbs, sticky footer, and most surface styling.
 - Stateful controls still need behavior:
   tabs, collapsible sections, menus/dropdowns, modal and offcanvas shells, and auto-refresh countdowns with pause/resume behavior.
-- Alert and toast surfaces stay CSS/HTML-first unless the consuming app adds its own dismissal or lifecycle logic.
+- Alert and toast surfaces can stay CSS/HTML-first when the app only needs static messaging; use the Web Component host when you want standardized tone or optional dismissal behavior.
 - This package now includes an optional dependency-free helper at [`dist/inc-design-language.js`](dist/inc-design-language.js) for:
   user-menu dropdowns, tab switching, collapse/accordion toggles, legacy modal/offcanvas shells, native dialog launching, page auto-refresh countdown widgets, and theme switching controls.
 - The helper also exposes `window.IncTheme` and listens for [`data-inc-theme-mode`](src/inc-design-language.js), [`data-inc-theme-toggle`](src/inc-design-language.js), and [`data-inc-theme-select`](src/inc-design-language.js) controls.
@@ -176,7 +177,7 @@ For titled sections that wrap tables, use [`inc-header-body--table-body`](refere
 - Use the CSS class surface when you already have the HTML structure and only need the design language.
 - Use the Web Component entrypoint when you want declarative slots, attributes, and DOM events around the approved v1 component families.
 - Use native HTML primitives when they already solve the interaction cleanly and keep the semantics simpler.
-- Keep tables, utilities, and other low-level atoms class-based until there is a clear component contract worth adding.
+- Keep tables, utilities, and the remaining low-value atoms class-based until there is a clear component contract worth adding.
 - Treat the Web Component layer as a layered entrypoint in the same package, not as a separate design system.
 
 ## Use it quickly
@@ -323,7 +324,7 @@ There are three supported ways to use it.
 
 - Import the same-package `./web-components` entrypoint when you want browser-native custom elements for the supported v1 families.
 - Keep the CSS bundle in place because the custom elements are designed to sit on top of the same class and token vocabulary.
-- Prefer this layer for declarative shell components, and keep static atoms and tables on the CSS surface.
+- Prefer this layer for declarative shell components, standardized atomic controls, and repeated action/detail or collection hosts, and keep static tables plus the remaining low-value atoms on the CSS surface.
 
 Practical recommendation for a .NET Razor Pages or MVC app:
 
@@ -339,6 +340,7 @@ This repository is set up for:
 
 - CI on pushes and pull requests via [`.github/workflows/ci.yml`](.github/workflows/ci.yml)
 - GitHub Pages showcase deployment from `main` via [`.github/workflows/pages.yml`](.github/workflows/pages.yml)
+- Cloudflare Worker MCP deployment from `main` via [`.github/workflows/mcp-worker.yml`](.github/workflows/mcp-worker.yml)
 - npm Trusted Publishing on `v*` tag pushes via [`.github/workflows/npm-publish.yml`](.github/workflows/npm-publish.yml)
 - Public release hygiene through `LICENSE`, [`CHANGELOG.md`](CHANGELOG.md), [`CONTRIBUTING.md`](CONTRIBUTING.md), and [`RELEASING.md`](RELEASING.md)
 - Brand assets in [`assets/brand/`](assets/brand) so README and future docs do not depend on external image hosting
@@ -378,3 +380,41 @@ $inc-font-family-sans: "Aptos", "Segoe UI", sans-serif;
 
 @import "./src/inc-design-language";
 ```
+
+## MCP Worker
+
+The repository also ships a deterministic Cloudflare Worker that exposes the UI kit content through Model Context Protocol. The Worker is intentionally read-only and stateless:
+
+- `POST /mcp` serves the MCP JSON-RPC endpoint.
+- `GET /mcp` serves a small HTML index for browsing the generated manifest.
+- `GET /mcp/resource/*` serves a human-readable resource page for inspection.
+- The Worker also tolerates a leading path prefix from a load balancer and keeps the rendered links under the configured `MCP_PATH_PREFIX` value.
+- Build-time manifests live under `dist/mcp/` and are regenerated from the repo docs, examples, specs, and package metadata.
+- The Worker does not call an LLM, crawl the web, or depend on a database.
+
+The local workflow is:
+
+```bash
+npm run build
+npm run test:mcp
+```
+
+`npm run build` regenerates the MCP manifests and bundles the Worker. `npm run verify` runs the full repo gate, including the MCP transport tests and the manifest smoke check.
+
+For local Worker development, use Wrangler against the generated bundle:
+
+```bash
+npm run build:mcp
+npx wrangler dev --config wrangler.toml
+```
+
+To refresh the generated manifests after changing docs or examples, rerun `npm run build:mcp` or the full `npm run build` pipeline.
+If you only need to refresh the JSON manifests before bundling, run `npm run build:mcp:manifests`.
+
+To deploy the Worker:
+
+```bash
+npm run deploy:mcp
+```
+
+The Cloudflare deploy workflow uses `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` secrets and deploys the bundled Worker from `dist/mcp/worker.mjs`.