@incursa/ui-kit 1.0.0 → 1.2.0

package/AI-AGENT-INSTRUCTIONS.md

@@ -2,64 +2,77 @@
 
 Use this package as a reusable data-heavy UI baseline.
 
-Repository brand assets live under `assets/brand/`. Prefer those local files when adding logos, favicons, or README imagery.
+Repository brand assets live under [`assets/brand/`](assets/brand). Prefer those local files when adding logos, favicons, or README imagery.
 
 ## Fast path
 
-- Prefer `dist/inc-design-language.css` if the target app already has working HTML and only needs the look.
-- Prefer `src/inc-design-language.scss` if you need to tune tokens, density, or Bootstrap defaults.
-- Prefer `dist/inc-design-language.js` only for stateful UI primitives such as menus, tabs, or collapsible sections.
-- Prefer `reference.html` when you need copy/paste starter markup for a supported control before composing a full page.
-- Prefer `states.html`, `forms-and-validation.html`, and `data-grid-advanced.html` when the target screen is workflow-heavy and you need realistic composition patterns, not isolated snippets.
+- Prefer [`dist/inc-design-language.css`](dist/inc-design-language.css) if the target app already has working HTML and only needs the look.
+- Prefer [`src/inc-design-language.scss`](src/inc-design-language.scss) if you need to tune tokens, density, or Bootstrap defaults.
+- Prefer [`dist/inc-design-language.js`](dist/inc-design-language.js) only for stateful UI primitives such as menus, tabs, collapsible sections, modal/offcanvas shells, native dialog launch hooks, and auto-refresh widgets.
+- Prefer the optional [`web-components.html`](web-components.html) landing page and the same-package `./web-components` entrypoint when you need browser-native custom elements for the approved v1 families and want declarative slots, attributes, and DOM events from plain HTML.
+- Prefer [`reference.html`](reference.html) when you need copy/paste starter markup for a supported control or page-frame primitive before composing a full page.
+- Prefer [`states.html`](states.html), [`forms-and-validation.html`](forms-and-validation.html), and [`data-grid-advanced.html`](data-grid-advanced.html) when the target screen is workflow-heavy and you need realistic composition patterns, not isolated snippets.
+
+## Markdown links
+
+- Use relative links for repo-local references in markdown, and keep the visible label code-formatted, for example [`README.md`](README.md), [`SPEC-UIK-CNV`](specs/requirements/ui-kit/SPEC-UIK-CNV.md), or [`src/inc-design-language.scss`](src/inc-design-language.scss).
+- Use absolute URLs only for external documentation, hosted examples, package registry pages, or other non-repo targets.
+- When a reference has a clear local target, prefer linking it instead of leaving it as a plain code span.
+- Run `node scripts/linkify-markdown-docs.mjs --check` after markdown edits to confirm the repo-local reference policy still holds.
 
 ## Naming rules
 
-- Use the `inc-` prefix for all public classes.
+- Use the [`inc-`](reference.html) prefix for all public classes.
 - Keep the existing BEM pattern:
-  `inc-block`, `inc-block__element`, `inc-block--modifier`.
+  [`inc-block`](reference.html), [`inc-block__element`](reference.html), [`inc-block--modifier`](reference.html).
 
 ## Core primitives
 
 - Tables:
-  Start with `inc-table` and add cell modifiers such as `inc-table__cell--numeric`, `inc-table__cell--action`, `inc-table__cell--min`, and `inc-table__cell--expand`.
+  Start with [`inc-table`](reference.html) and add cell modifiers such as [`inc-table__cell--numeric`](reference.html), [`inc-table__cell--action`](reference.html), [`inc-table__cell--min`](reference.html), and [`inc-table__cell--expand`](reference.html).
 - Buttons:
-  Use `inc-btn` plus a semantic modifier such as `inc-btn--primary`, `inc-btn--secondary`, or `inc-btn--danger`.
-  Use `inc-btn--micro` for in-row or in-cell actions.
+  Use [`inc-btn`](reference.html) plus a semantic modifier such as [`inc-btn--primary`](reference.html), [`inc-btn--secondary`](reference.html), or [`inc-btn--danger`](reference.html).
+  Use [`inc-btn--micro`](reference.html) for in-row or in-cell actions.
 - Forms:
-  Use `inc-form--inline` for toolbar/filter layouts, wrap each label/control pair in `inc-form__field` or `inc-form__group`, and use `inc-input-group` for composed inputs.
-  Use `inc-form__hint`, `inc-form__feedback--error`, `inc-form__feedback--success`, and `inc-form__error-summary` for validation.
+  Use [`inc-form--inline`](reference.html) for toolbar/filter layouts, wrap each label/control pair in [`inc-form__field`](reference.html) or [`inc-form__group`](reference.html), and use [`inc-input-group`](reference.html) for composed inputs.
+  Use [`inc-form__hint`](reference.html), [`inc-form__feedback--error`](reference.html), [`inc-form__feedback--success`](reference.html), and [`inc-form__error-summary`](reference.html) for validation.
 - Filter bars:
-  Use `inc-filter-bar`, `inc-filter-chip`, and `inc-bulk-bar` for search-heavy or multi-select operator screens.
+  Use [`inc-filter-bar`](reference.html), [`inc-filter-chip`](reference.html), and [`inc-bulk-bar`](reference.html) for search-heavy or multi-select operator screens.
 - Cards and shells:
-  Use `inc-card` for plain cards and `inc-header-body inc-header-body--card` for titled sections with actions.
-  Use `inc-header-body--table-body` when the body contains a table and should keep section padding without adding extra bottom table margin.
+  Use [`inc-card`](reference.html) for plain cards and [`inc-header-body inc-header-body--card`](reference.html) for titled sections with actions.
+  Use [`inc-header-body--table-body`](reference.html) when the body contains a table and should keep section padding without adding extra bottom table margin.
 - App layout:
-  Use `inc-app-shell`, `inc-footer-bar`, `inc-navbar`, `inc-breadcrumb`, `inc-nav-triad`, and `inc-sidebar-menu` when you need an opinionated application frame instead of isolated components.
+  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) when you need an opinionated application frame instead of isolated components.
 - States and workflow:
-  Use `inc-state-panel`, `inc-permission-banner`, `inc-toast-card`, `inc-timeline`, `inc-file-dropzone`, `inc-file-row`, and `inc-key-value` for non-happy-path and detail-heavy B2B flows.
+  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) for non-happy-path and detail-heavy B2B flows.
 - Interaction:
-  Use `data-inc-toggle="menu"`, `data-inc-toggle="tab"`, and `data-inc-toggle="collapse"` with `data-inc-target="#target-id"` when you want the optional vanilla-JS helper to wire behavior.
+  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 optional vanilla-JS helper to wire behavior. Use [`data-inc-toggle="modal"`](src/inc-design-language.js), [`data-inc-toggle="offcanvas"`](src/inc-design-language.js), [`data-inc-dismiss="modal"`](src/inc-design-language.js), [`data-inc-dismiss="offcanvas"`](src/inc-design-language.js), and [`data-inc-native-dialog-open`](src/inc-design-language.js) only when the helper-managed or launch-hook contract is the intended path.
 - Native interaction:
-  Use `details.inc-disclosure` for section stacks, `details.inc-native-menu` for lightweight menus, and `dialog.inc-native-dialog` for native modal surfaces.
+  Use [`details.inc-disclosure`](reference.html) for section stacks, [`details.inc-native-menu`](reference.html) for lightweight menus, and [`dialog.inc-native-dialog`](reference.html) for native modal surfaces.
+- Web Components:
+  Keep the CSS class surface canonical, use the optional layered entrypoint for the approved v1 component families, and prefer native HTML primitives when they already satisfy the semantic and interaction contract.
 - Status:
-  Use `inc-badge--success|warning|danger|info` for compact status signals.
+  Use [`inc-badge--success|warning|danger|info`](reference.html) for compact status signals.
 - Metrics:
-  Use `inc-summary-overview` and `inc-summary-block` for dashboard and header metrics.
+  Use [`inc-summary-overview`](reference.html) and [`inc-summary-block`](reference.html) for dashboard and header metrics.
 
 ## Customization order
 
-1. Change fonts and colors in `src/_inc-theme.scss`.
-2. Use `src/_inc-tokens.scss` only for deeper token or Bootstrap-level tuning.
+1. Change fonts and colors in [`src/_inc-theme.scss`](src/_inc-theme.scss).
+2. Use [`src/_inc-tokens.scss`](src/_inc-tokens.scss) only for deeper token or Bootstrap-level tuning.
 3. Rebuild the CSS.
-4. Only add new component rules after checking whether an existing `inc-*` block already fits.
+4. Only add new component rules after checking whether an existing [`inc-*`](reference.html) block already fits.
 
 ## Packaging
 
+- Use `npm run verify` before versioning when you want to rebuild, smoke-test, and dry-run the package.
 - Use `npm run build` to rebuild distributables.
 - Use `npm pack` or `npm run package` to produce a local installable tarball.
 - The repository is licensed under Apache 2.0.
-- The compiled `dist/inc-design-language.css` already includes the Bootstrap layer it was built from, so consumers do not need Bootstrap CSS at runtime when they use the compiled assets.
-- The source `src/inc-design-language.scss` does require Bootstrap Sass at build time because it imports `bootstrap/scss/bootstrap`.
+- The compiled [`dist/inc-design-language.css`](dist/inc-design-language.css) already includes the Bootstrap layer it was built from, so consumers do not need Bootstrap CSS at runtime when they use the compiled assets.
+- The source [`src/inc-design-language.scss`](src/inc-design-language.scss) does require Bootstrap Sass at build time because it imports `bootstrap/scss/bootstrap`.
+- The optional Web Component layer lives in the same package as a layered entrypoint so the CSS-first surface and browser-native surface stay aligned.
+- The Web Component source tree lives under [`src/web-components/`](src/web-components); keep consumer-facing guidance in [`web-components.html`](web-components.html) and maintainer notes alongside the runtime source tree.
 
 ## Guardrails
 
@@ -68,9 +81,10 @@ Repository brand assets live under `assets/brand/`. Prefer those local files whe
 - Preserve explicit alignment classes for numeric table data.
 - Avoid adding product-specific shell/background styles to this package.
 - Keep new components generic enough to drop into another admin/data app.
-- If you add a new block, prefer names like `inc-filter-bar`, `inc-stat-card`, or `inc-data-toolbar` over feature-specific names.
+- If you add a new block, prefer names like [`inc-filter-bar`](reference.html), [`inc-stat-card`](reference.html), or [`inc-data-toolbar`](reference.html) over feature-specific names.
 - Keep border radius consistent across panels, tabs, tables, and cards unless there is a deliberate reason to differentiate them.
 - Prefer native browser behavior first for disclosures and dialogs when it fits the product; use the helper only when the Bootstrap-like component contract needs custom state handling.
+- Keep the CSS-first class API canonical and treat the Web Component layer as additive, not a replacement.
 
 ## Build
 

package/LLMS.txt

@@ -1,7 +1,7 @@
 Incursa UI Kit
 
 Short description:
-Reusable UI kit for data-heavy business applications. The public surface uses `inc-*` classes and ships compiled CSS, optional vanilla-JS helpers, and SCSS source entrypoints.
+Reusable UI kit for data-heavy business applications. The public surface stays CSS-first through [`inc-*`](reference.html) classes, with optional vanilla-JS helpers, SCSS source entrypoints, and a layered `./web-components` entrypoint for browser-native components.
 
 Package identity:
 - npm package: `@incursa/ui-kit`
@@ -9,62 +9,77 @@ Package identity:
 - repository: https://github.com/incursa/ui-kit
 
 Fast path:
-- Use `dist/inc-design-language.css` if the target app already has working HTML and mainly needs the visual language.
-- Use `dist/inc-design-language.js` only for stateful primitives such as menus, tabs, collapsible sections, auto-refresh widgets, the native dialog launch hook, and legacy modal/offcanvas shells.
-- Use `src/inc-design-language.scss` if the consumer needs to tune tokens, theme variables, density, or Bootstrap defaults.
+- Use [`dist/inc-design-language.css`](dist/inc-design-language.css) if the target app already has working HTML and mainly needs the visual language.
+- Use [`dist/inc-design-language.js`](dist/inc-design-language.js) only for stateful primitives such as menus, tabs, collapsible sections, auto-refresh widgets, the native dialog launch hook, and legacy modal/offcanvas shells.
+- Use [`web-components.html`](web-components.html) and the same-package `./web-components` entrypoint when you want declarative custom elements for the approved v1 component families.
+- Use [`src/inc-design-language.scss`](src/inc-design-language.scss) if the consumer needs to tune tokens, theme variables, density, or Bootstrap defaults.
 
 Primary files:
-- `dist/inc-design-language.css`: compiled standalone CSS output.
-- `dist/inc-design-language.js`: optional dependency-free helper for menus, tabs, collapsible sections, auto-refresh widgets, the native dialog launch hook, and legacy modal/offcanvas shells.
-- `src/inc-design-language.scss`: main SCSS entrypoint.
-- `src/_inc-theme.scss`: brand-facing fonts, palette, semantic surfaces, and text colors.
-- `src/_inc-tokens.scss`: deeper token and Bootstrap-facing overrides.
-- `reference.html`: copy/paste catalog for standard controls and markup patterns.
-- `specs/requirements/ui-kit/_index.md`: first-pass Spec Trace suite for the UI kit.
-- `specs/requirements/ui-kit/REQUIREMENT-GAPS.md`: unresolved requirement gaps and follow-up questions.
-- `specs/requirements/ui-kit/SPEC-UIK-STD.md`: public surface standards for `inc-` naming and accessible interactive behavior.
-- `specs/requirements/ui-kit/SPEC-UIK-CNV.md`: shared control conventions for base-plus-modifier surfaces, density suffixes, and state hooks.
-- `specs/verification/ui-kit/_index.md`: auditable source-review verification baseline for the UI kit surface.
-- `states.html`, `forms-and-validation.html`, `data-grid-advanced.html`, `overlay-workflows.html`: workflow-heavy composition patterns.
-- `demo.html`, `work-queue.html`, `record-detail.html`, `native-patterns.html`: fuller page examples.
+- [`dist/inc-design-language.css`](dist/inc-design-language.css): compiled standalone CSS output.
+- [`dist/inc-design-language.js`](dist/inc-design-language.js): optional dependency-free helper for menus, tabs, collapsible sections, auto-refresh widgets, the native dialog launch hook, and legacy modal/offcanvas shells.
+- [`dist/web-components/index.js`](dist/web-components/index.js): optional custom-element entrypoint for the same-package Web Component layer.
+- [`src/inc-design-language.scss`](src/inc-design-language.scss): main SCSS entrypoint.
+- [`src/_inc-theme.scss`](src/_inc-theme.scss): brand-facing fonts, palette, semantic surfaces, and text colors.
+- [`src/_inc-tokens.scss`](src/_inc-tokens.scss): deeper token and Bootstrap-facing overrides.
+- [`web-components.html`](web-components.html): public landing page for the optional Web Component entrypoint and the CSS-first versus Web Component usage split.
+- [`reference.html`](reference.html): copy/paste catalog for standard controls, page-frame primitives, metric variants, and overlay shells.
+- [`specs/architecture/_index.md`](specs/architecture/_index.md): design-rationale layer for token boundaries, helper scope, and package intent.
+- [`specs/requirements/ui-kit/_index.md`](specs/requirements/ui-kit/_index.md): first-pass Spec Trace suite for the UI kit.
+- [`specs/requirements/ui-kit/REQUIREMENT-GAPS.md`](specs/requirements/ui-kit/REQUIREMENT-GAPS.md): unresolved requirement gaps and follow-up questions.
+- [`specs/requirements/ui-kit/SPEC-UIK-STD.md`](specs/requirements/ui-kit/SPEC-UIK-STD.md): public surface standards for [`inc-`](reference.html) naming and accessible interactive behavior.
+- [`specs/requirements/ui-kit/SPEC-UIK-CNV.md`](specs/requirements/ui-kit/SPEC-UIK-CNV.md): shared control conventions for base-plus-modifier surfaces, density suffixes, and state hooks.
+- [`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.
+- Tables, utilities, filter/bulk/file workflows, permission banners, toasts, and compatibility overlay shells stay CSS-only or deferred in v1.
+
+Markdown links:
+- Use relative links for repo-local references in markdown, and keep the visible label code-formatted.
+- Use absolute URLs only for external documentation, hosted examples, package registry pages, or other non-repo targets.
+- When a reference has a clear local target, link it instead of leaving it as a bare code span.
 
 Public naming rules:
-- Use the `inc-` prefix for public classes.
-- Keep the existing BEM structure: `inc-block`, `inc-block__element`, `inc-block--modifier`.
+- Use the [`inc-`](reference.html) prefix for public classes.
+- Keep the existing BEM structure: [`inc-block`](reference.html), [`inc-block__element`](reference.html), [`inc-block--modifier`](reference.html).
 - Use the shared control modifier grammar for density, expansion, and state hooks instead of inventing one-off suffixes.
-- Avoid nested element names such as `inc-form__check__input`; keep public element names one level deep.
+- Avoid nested element names such as [`inc-form__check__input`](reference.html); keep public element names one level deep.
 - Preserve native semantics and accessible focus/disabled/hidden states for interactive surfaces.
 - Treat light and dark as global theme concerns activated through `data-bs-theme` on the root scope, not public component-class modifiers.
 
 Core primitives:
-- Typography: use `inc-text`, `inc-heading`, `inc-data`, `inc-button-text`, `inc-form-text`, and `inc-table-text` for public text helpers.
-- Tables: start with `inc-table`; use modifiers such as `inc-table__cell--numeric`, `inc-table__cell--action`, `inc-table__cell--min`, and `inc-table__cell--expand`.
-- Buttons: use `inc-btn` with semantic modifiers such as `inc-btn--primary`, `inc-btn--secondary`, and `inc-btn--danger`. Keep the visual treatment identical on `<button>` and `<a>` markup, use `<button>` for in-place actions, use `<a>` for navigation, and use `inc-btn--micro` for in-row actions.
-- Forms: use `inc-form--inline`, `inc-form__field`, `inc-form__fieldset`, `inc-form__legend`, `inc-form__control`, `inc-form__select`, `inc-input-group`, `inc-readonly-field`, `inc-form-text`, `inc-form__feedback--error`, `inc-form__feedback--success`, and `inc-form__error-summary`.
-- Form choices: use `inc-form__check`, `inc-form__check-input`, `inc-form__check-label`, `inc-form__switch`, and `inc-form__choices` for checkbox and radio groups.
+- Typography: use [`inc-text`](reference.html), [`inc-heading`](reference.html), [`inc-data`](reference.html), [`inc-button-text`](reference.html), [`inc-form-text`](reference.html), and [`inc-table-text`](reference.html) for public text helpers.
+- Tables: start with [`inc-table`](reference.html); use modifiers such as [`inc-table__cell--numeric`](reference.html), [`inc-table__cell--action`](reference.html), [`inc-table__cell--min`](reference.html), and [`inc-table__cell--expand`](reference.html).
+- Buttons: use [`inc-btn`](reference.html) with semantic modifiers such as [`inc-btn--primary`](reference.html), [`inc-btn--secondary`](reference.html), and [`inc-btn--danger`](reference.html). Keep the visual treatment identical on `<button>` and `<a>` markup, use `<button>` for in-place actions, use `<a>` for navigation, and use [`inc-btn--micro`](reference.html) for in-row actions.
+- Forms: use [`inc-form--inline`](reference.html), [`inc-form__field`](reference.html), [`inc-form__fieldset`](reference.html), [`inc-form__legend`](reference.html), [`inc-form__control`](reference.html), [`inc-form__select`](reference.html), [`inc-input-group`](reference.html), [`inc-readonly-field`](reference.html), [`inc-form-text`](reference.html), [`inc-form__feedback--error`](reference.html), [`inc-form__feedback--success`](reference.html), and [`inc-form__error-summary`](reference.html).
+- Form choices: use [`inc-form__check`](reference.html), [`inc-form__check-input`](reference.html), [`inc-form__check-label`](reference.html), [`inc-form__switch`](reference.html), and [`inc-form__choices`](reference.html) for checkbox and radio groups.
 - Control conventions: use the shared base-plus-modifier patterns from `SPEC-UIK-CNV.md` for density, expansion, and state hooks.
-- Control density: use the shared `inc-control-density-micro-*` tokens for compact buttons, inputs, selects, and input groups instead of hard-coded micro values.
-- Filter bars: use `inc-filter-bar`, `inc-filter-chip`, and `inc-bulk-bar`.
-- Cards and shells: use `inc-card` for plain cards. Use `inc-header-body` for titled sections with actions. Use `inc-header-body--table-body` when the body contains a table and should keep body padding without extra bottom table margin.
-- App layout: use `inc-app-shell`, `inc-footer-bar`, `inc-navbar`, `inc-breadcrumb`, `inc-nav-triad`, and `inc-sidebar-menu`.
-- Utilities: use `inc-u-stack-*`, `inc-u-gap-*`, `inc-grid`, `inc-row`, `inc-col`, `inc-stack`, and `inc-flex-*` when composition needs a public helper class.
-- States and workflow: use `inc-state-panel`, `inc-permission-banner`, `inc-toast-card`, `inc-timeline`, `inc-file-dropzone`, `inc-file-row`, and `inc-key-value`.
-- Interaction: use `data-inc-toggle="menu"`, `data-inc-toggle="tab"`, and `data-inc-toggle="collapse"` with `data-inc-target="#target-id"` when you want the helper to wire behavior. Use `data-inc-dismiss="modal"` / `data-inc-dismiss="offcanvas"`, `data-inc-accordion`, `data-inc-backdrop-for`, `data-inc-initial-focus`, `data-inc-auto-refresh`, and the `data-inc-refresh-seconds`, `data-inc-refresh-label`, `data-inc-refresh-loading-label`, `data-inc-refresh-paused-label`, `data-inc-refresh-pause-action-label`, and `data-inc-refresh-resume-action-label` hooks when you need the rest of the helper contract. Use `data-inc-native-dialog-open="dialog-id"` when you want the helper to open a native `<dialog>`.
-- Native interaction: use `details.inc-disclosure`, `details.inc-native-menu`, and `dialog.inc-native-dialog`.
-- Status: use `inc-badge--success|warning|danger|info`.
-- Metrics: use `inc-summary-overview` and `inc-summary-block`.
+- Control density: use the shared [`inc-control-density-micro-*`](reference.html) tokens for compact buttons, inputs, selects, and input groups instead of hard-coded micro values.
+- Filter bars: use [`inc-filter-bar`](reference.html), [`inc-filter-chip`](reference.html), and [`inc-bulk-bar`](reference.html).
+- 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).
+- 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.
+- 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).
+- Metrics: use [`inc-summary-overview`](reference.html) and [`inc-summary-block`](reference.html).
 
 Customization order:
-1. Change fonts and colors in `src/_inc-theme.scss`.
-2. Use `src/_inc-tokens.scss` only for deeper token or Bootstrap-level tuning.
+1. Change fonts and colors in [`src/_inc-theme.scss`](src/_inc-theme.scss).
+2. Use [`src/_inc-tokens.scss`](src/_inc-tokens.scss) only for deeper token or Bootstrap-level tuning.
 3. Rebuild the CSS.
-4. Only add new component rules after checking whether an existing `inc-*` block already fits.
+4. Only add new component rules after checking whether an existing [`inc-*`](reference.html) block already fits.
 
 Packaging and build:
+- `npm run verify` rebuilds distributables, runs the smoke gate, and dry-runs the package.
+- `npm run test:browser` runs the Playwright browser suite for tabs, overlays, native dialogs, and auto-refresh; use `npm run test:browser:install` once if Chromium is not already installed.
 - `npm run build` rebuilds distributables.
 - `npm pack` or `npm run package` produces a local installable tarball.
 - The compiled CSS already includes the Bootstrap layer it was built from, so consumers do not need Bootstrap CSS at runtime when using compiled assets.
 - The SCSS source path does require Bootstrap Sass at build time because it imports `bootstrap/scss/bootstrap`.
+- The Web Component layer ships as a layered entrypoint in the same package, not as a second package or separate design system.
 
 Guardrails:
 - Keep typography split: sans for UI text, mono for data.
@@ -72,7 +87,8 @@ Guardrails:
 - Avoid product-specific shell or background styles in this package.
 - Keep new components generic enough to reuse across admin/data apps.
 - Prefer native browser behavior first for disclosures and dialogs when it fits the product.
+- Keep the CSS-first class API canonical and treat the Web Component layer as additive, not a replacement.
 
 See also:
-- `README.md` for package usage, release flow, and repository structure.
-- `AI-AGENT-INSTRUCTIONS.md` for the same guidance in markdown form.
+- [`README.md`](README.md) for package usage, release flow, and repository structure.
+- [`AI-AGENT-INSTRUCTIONS.md`](AI-AGENT-INSTRUCTIONS.md) for the same guidance in markdown form.