@kerfjs/ui 5.0.0-beta.21 → 5.0.0-beta.23

package/README.md

@@ -146,6 +146,13 @@ as a `New` marker.
 | `PanelHeader`                                                       | `@kerfjs/ui/panel-header`               | `@kerfjs/ui/panel-header.css`          |
 | `ValueTable`, `ValueTableRow`                                       | `@kerfjs/ui/value-table`                | `@kerfjs/ui/value-table.css`           |
 
+Opt-in application layouts keep JavaScript and CSS explicit. For the
+desktop-class multi-panel shell, import `Workbench` from
+`@kerfjs/ui/workbench` and load `@kerfjs/ui/workbench.css`; its supported
+classes and size tokens are cataloged under the `workbench` entry. See
+[`docs/workbench.md`](./docs/workbench.md) for panel ownership and responsive
+replacement guidance.
+
 `PanelHeader` is a plain `Toolbar` used as a panel, dialog, or page heading: an
 optional icon control group (given a brand fill with a matching border), the
 title as extra-large `ToolbarText`, the app's trailing action controls, and an
@@ -331,9 +338,10 @@ that convenience import, also import `@kerfjs/ui/styles.css`, which deliberately
 contains the complete layer. Non-browser/SSR tools resolve the pure `import`
 condition automatically; `@kerfjs/ui/unstyled` is the explicit CSS-free root
 entry for a browser build with a custom styling pipeline. The exported
-`foundation.css` and component CSS paths remain available for fully manual
-delivery. Load application overrides after package styles, or scope `--kui-*`
-variables directly on a component instance.
+`@kerfjs/ui/foundation.css` and component CSS paths remain available for fully
+manual delivery. Its complete supported `--kui-*` token surface is cataloged
+under the `foundation` entry. Load application overrides after package styles,
+or scope variables directly on a component instance.
 
 ## Pane and content geometry
 

package/ai/component-catalog-v2.json

@@ -141,6 +141,157 @@
         "composition": "generated-permissive-default"
       }
     },
+    {
+      "key": "@kerfjs/ui:foundation",
+      "package": "@kerfjs/ui",
+      "id": "foundation",
+      "name": "Foundation tokens",
+      "kind": "composition",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "application theme overrides",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "responsive policy at the cataloged device-class breakpoints",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": { "required": false, "helpers": [], "obligations": [] },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["foundation"],
+        "geometry": { "margin": "none", "border": "none", "padding": "none" }
+      },
+      "accessibility": {
+        "obligations": [
+          "Preserve semantic contrast relationships and the visible focus ring when overriding foundation colors."
+        ]
+      },
+      "boundaries": {
+        "rootClass": null,
+        "publicClasses": [],
+        "publicTokens": [
+          "--kui-font-sans",
+          "--kui-font-mono",
+          "--kui-font-2xs",
+          "--kui-font-xs",
+          "--kui-font-s",
+          "--kui-font-m",
+          "--kui-font-l",
+          "--kui-font-2xl",
+          "--kui-font-weight-semibold",
+          "--kui-space-none",
+          "--kui-space-2xs",
+          "--kui-space-xs",
+          "--kui-space-s",
+          "--kui-space-m",
+          "--kui-space-l",
+          "--kui-space-xl",
+          "--kui-bp-mobile",
+          "--kui-bp-tablet",
+          "--kui-bp-desktop",
+          "--kui-bp-xl-desktop",
+          "--kui-layout-inline-margin",
+          "--kui-layout-item-border-width",
+          "--kui-layout-item-padding",
+          "--kui-layout-item-gap",
+          "--kui-layout-content-gap",
+          "--kui-layout-control-gap",
+          "--kui-layout-metadata-gap",
+          "--kui-layout-rounded-radius",
+          "--kui-layout-pill-radius",
+          "--kui-toolbar-group-inner-size",
+          "--kui-toolbar-group-size",
+          "--kui-toolbar-gap",
+          "--kui-radius-s",
+          "--kui-radius-m",
+          "--kui-radius-l",
+          "--kui-radius-circle",
+          "--kui-radius-pill",
+          "--kui-disclosure-icon-scale",
+          "--kui-color-surface",
+          "--kui-color-surface-raised",
+          "--kui-color-surface-lowered",
+          "--kui-color-text",
+          "--kui-color-text-quiet",
+          "--kui-color-text-link",
+          "--kui-color-neutral-fill-quiet",
+          "--kui-color-neutral-fill-normal",
+          "--kui-color-neutral-fill-loud",
+          "--kui-color-neutral-border-quiet",
+          "--kui-color-neutral-border-normal",
+          "--kui-color-neutral-border-loud",
+          "--kui-color-neutral-on-quiet",
+          "--kui-color-neutral-on-normal",
+          "--kui-color-neutral-on-loud",
+          "--kui-color-brand-fill-loud",
+          "--kui-color-brand-fill-quiet",
+          "--kui-color-brand-fill-normal",
+          "--kui-color-brand-border-quiet",
+          "--kui-color-brand-border-normal",
+          "--kui-color-brand-border-loud",
+          "--kui-color-brand-on-quiet",
+          "--kui-color-brand-on-normal",
+          "--kui-color-brand-on-loud",
+          "--kui-color-brand-on-fill",
+          "--kui-color-success-fill-loud",
+          "--kui-color-success-fill-quiet",
+          "--kui-color-success-fill-normal",
+          "--kui-color-success-border-quiet",
+          "--kui-color-success-border-normal",
+          "--kui-color-success-border-loud",
+          "--kui-color-success-on-quiet",
+          "--kui-color-success-on-normal",
+          "--kui-color-success-on-loud",
+          "--kui-color-success-on-fill",
+          "--kui-color-warning-fill-loud",
+          "--kui-color-warning-fill-quiet",
+          "--kui-color-warning-fill-normal",
+          "--kui-color-warning-border-quiet",
+          "--kui-color-warning-border-normal",
+          "--kui-color-warning-border-loud",
+          "--kui-color-warning-on-quiet",
+          "--kui-color-warning-on-normal",
+          "--kui-color-warning-on-loud",
+          "--kui-color-warning-on-fill",
+          "--kui-color-danger-fill-loud",
+          "--kui-color-danger-fill-quiet",
+          "--kui-color-danger-fill-normal",
+          "--kui-color-danger-border-quiet",
+          "--kui-color-danger-border-normal",
+          "--kui-color-danger-border-loud",
+          "--kui-color-danger-on-quiet",
+          "--kui-color-danger-on-normal",
+          "--kui-color-danger-on-loud",
+          "--kui-color-border",
+          "--kui-color-border-quiet",
+          "--kui-color-accent",
+          "--kui-color-accent-text",
+          "--kui-color-success",
+          "--kui-color-success-text",
+          "--kui-color-warning",
+          "--kui-color-warning-text",
+          "--kui-color-danger",
+          "--kui-color-danger-text",
+          "--kui-focus-ring",
+          "--kui-shadow-s",
+          "--kui-shadow-l"
+        ]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:layout",
       "package": "@kerfjs/ui",
@@ -282,6 +433,78 @@
         "composition": "generated-permissive-default"
       }
     },
+    {
+      "key": "@kerfjs/ui:workbench",
+      "package": "@kerfjs/ui",
+      "id": "workbench",
+      "name": "Workbench",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "panel presence and content",
+          "owner": "application",
+          "required": false
+        },
+        { "id": "collapsed state", "owner": "application", "required": false },
+        { "id": "panel sizes", "owner": "application", "required": false },
+        {
+          "id": "responsive replacement below desktop",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "collapse controls and focus policy",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": { "required": false, "helpers": [], "obligations": [] },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["structure"],
+        "geometry": {
+          "margin": "none",
+          "border": "self",
+          "padding": "child",
+          "notes": [
+            "Workbench owns the rail and drawer separators; each region's content owns its internal padding and scroll behavior."
+          ]
+        }
+      },
+      "accessibility": {
+        "obligations": [
+          "Give the Workbench and each meaningful rail or drawer an accessible label.",
+          "Keep collapse controls outside the disappearing region and move focus when a controlled rerender replaces a collapse control with its restore control."
+        ]
+      },
+      "boundaries": {
+        "rootClass": "kui-workbench",
+        "publicClasses": [
+          "kui-workbench",
+          "kui-workbench__rail",
+          "kui-workbench__rail--left",
+          "kui-workbench__rail--right",
+          "kui-workbench__center",
+          "kui-workbench__main",
+          "kui-workbench__drawer",
+          "kui-workbench__panel-content"
+        ],
+        "publicTokens": [
+          "--kui-workbench-rail-width",
+          "--kui-workbench-drawer-height"
+        ]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:sunken-panel",
       "package": "@kerfjs/ui",

package/ai/component-catalog.json

@@ -248,6 +248,160 @@
         "recipe": "docs/webawesome-theme.md#component-selection-guidance"
       }
     },
+    {
+      "id": "foundation",
+      "name": "Foundation tokens",
+      "category": "Foundation",
+      "kind": "composition",
+      "source": "kerf",
+      "description": "The complete public typography, spacing, breakpoint, geometry, radius, color, focus, and shadow token surface shipped by foundation.css.",
+      "uses": [],
+      "purpose": "Provide the shared semantic token foundation for application themes and every styled Kerf UI component.",
+      "publicExports": [],
+      "useWhen": [
+        "Theme a Kerf application globally or reuse the shipped semantic typography, spacing, geometry, color, focus, and shadow values in application-owned composition CSS."
+      ],
+      "avoidWhen": [
+        "Do not replace a component-specific prop or token with a broad foundation override when only one component instance should change."
+      ],
+      "alternatives": [],
+      "appOwns": [
+        "application theme overrides",
+        "responsive policy at the cataloged device-class breakpoints"
+      ],
+      "variants": [
+        "light",
+        "dark"
+      ],
+      "accessibility": [
+        "Preserve semantic contrast relationships and the visible focus ring when overriding foundation colors."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
+      "delivery": {
+        "manualCssImport": "@kerfjs/ui/foundation.css",
+        "sideEffects": [
+          "css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [],
+      "publicTokens": [
+        "--kui-font-sans",
+        "--kui-font-mono",
+        "--kui-font-2xs",
+        "--kui-font-xs",
+        "--kui-font-s",
+        "--kui-font-m",
+        "--kui-font-l",
+        "--kui-font-2xl",
+        "--kui-font-weight-semibold",
+        "--kui-space-none",
+        "--kui-space-2xs",
+        "--kui-space-xs",
+        "--kui-space-s",
+        "--kui-space-m",
+        "--kui-space-l",
+        "--kui-space-xl",
+        "--kui-bp-mobile",
+        "--kui-bp-tablet",
+        "--kui-bp-desktop",
+        "--kui-bp-xl-desktop",
+        "--kui-layout-inline-margin",
+        "--kui-layout-item-border-width",
+        "--kui-layout-item-padding",
+        "--kui-layout-item-gap",
+        "--kui-layout-content-gap",
+        "--kui-layout-control-gap",
+        "--kui-layout-metadata-gap",
+        "--kui-layout-rounded-radius",
+        "--kui-layout-pill-radius",
+        "--kui-toolbar-group-inner-size",
+        "--kui-toolbar-group-size",
+        "--kui-toolbar-gap",
+        "--kui-radius-s",
+        "--kui-radius-m",
+        "--kui-radius-l",
+        "--kui-radius-circle",
+        "--kui-radius-pill",
+        "--kui-disclosure-icon-scale",
+        "--kui-color-surface",
+        "--kui-color-surface-raised",
+        "--kui-color-surface-lowered",
+        "--kui-color-text",
+        "--kui-color-text-quiet",
+        "--kui-color-text-link",
+        "--kui-color-neutral-fill-quiet",
+        "--kui-color-neutral-fill-normal",
+        "--kui-color-neutral-fill-loud",
+        "--kui-color-neutral-border-quiet",
+        "--kui-color-neutral-border-normal",
+        "--kui-color-neutral-border-loud",
+        "--kui-color-neutral-on-quiet",
+        "--kui-color-neutral-on-normal",
+        "--kui-color-neutral-on-loud",
+        "--kui-color-brand-fill-loud",
+        "--kui-color-brand-fill-quiet",
+        "--kui-color-brand-fill-normal",
+        "--kui-color-brand-border-quiet",
+        "--kui-color-brand-border-normal",
+        "--kui-color-brand-border-loud",
+        "--kui-color-brand-on-quiet",
+        "--kui-color-brand-on-normal",
+        "--kui-color-brand-on-loud",
+        "--kui-color-brand-on-fill",
+        "--kui-color-success-fill-loud",
+        "--kui-color-success-fill-quiet",
+        "--kui-color-success-fill-normal",
+        "--kui-color-success-border-quiet",
+        "--kui-color-success-border-normal",
+        "--kui-color-success-border-loud",
+        "--kui-color-success-on-quiet",
+        "--kui-color-success-on-normal",
+        "--kui-color-success-on-loud",
+        "--kui-color-success-on-fill",
+        "--kui-color-warning-fill-loud",
+        "--kui-color-warning-fill-quiet",
+        "--kui-color-warning-fill-normal",
+        "--kui-color-warning-border-quiet",
+        "--kui-color-warning-border-normal",
+        "--kui-color-warning-border-loud",
+        "--kui-color-warning-on-quiet",
+        "--kui-color-warning-on-normal",
+        "--kui-color-warning-on-loud",
+        "--kui-color-warning-on-fill",
+        "--kui-color-danger-fill-loud",
+        "--kui-color-danger-fill-quiet",
+        "--kui-color-danger-fill-normal",
+        "--kui-color-danger-border-quiet",
+        "--kui-color-danger-border-normal",
+        "--kui-color-danger-border-loud",
+        "--kui-color-danger-on-quiet",
+        "--kui-color-danger-on-normal",
+        "--kui-color-danger-on-loud",
+        "--kui-color-border",
+        "--kui-color-border-quiet",
+        "--kui-color-accent",
+        "--kui-color-accent-text",
+        "--kui-color-success",
+        "--kui-color-success-text",
+        "--kui-color-warning",
+        "--kui-color-warning-text",
+        "--kui-color-danger",
+        "--kui-color-danger-text",
+        "--kui-focus-ring",
+        "--kui-shadow-s",
+        "--kui-shadow-l"
+      ],
+      "links": {
+        "catalogRoute": "?component=foundation",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/component-selection.md#foundation-tokens"
+      }
+    },
     {
       "id": "layout",
       "name": "Application layout",
@@ -401,6 +555,89 @@
         "recipe": "docs/layout.md#anatomy"
       }
     },
+    {
+      "id": "workbench",
+      "name": "Workbench",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A desktop-class multi-panel workspace with independently collapsible left and right rails and a bottom drawer around one central work area.",
+      "uses": [],
+      "purpose": "Arrange a complex tool or editor as a stable central work area with optional peripheral rails and a bottom drawer.",
+      "publicExports": [
+        "Workbench",
+        "WorkbenchPanel",
+        "WorkbenchProps"
+      ],
+      "useWhen": [
+        "A desktop-class tool needs a central work area plus independently collapsible navigator, inspector, or console regions."
+      ],
+      "avoidWhen": [
+        "Do not shrink the full multi-panel shell onto compact devices; present peripheral content through NavStack or overlay drawers instead.",
+        "Do not use Workbench for one standalone collapsible rail or drawer; use CollapsiblePanel."
+      ],
+      "alternatives": [
+        {
+          "id": "pane",
+          "relationship": "composes-with",
+          "when": "Use Pane inside Workbench regions when fixed header/footer chrome must surround one scroll owner."
+        }
+      ],
+      "appOwns": [
+        "panel presence and content",
+        "collapsed state",
+        "panel sizes",
+        "responsive replacement below desktop",
+        "collapse controls and focus policy"
+      ],
+      "variants": [
+        "main only",
+        "left rail",
+        "right rail",
+        "bottom drawer",
+        "all panels",
+        "independently collapsed panels"
+      ],
+      "accessibility": [
+        "Give the Workbench and each meaningful rail or drawer an accessible label.",
+        "Keep collapse controls outside the disappearing region and move focus when a controlled rerender replaces a collapse control with its restore control."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "child",
+        "notes": [
+          "Workbench owns the rail and drawer separators; each region's content owns its internal padding and scroll behavior."
+        ]
+      },
+      "delivery": {
+        "moduleImport": "@kerfjs/ui/workbench",
+        "manualCssImport": "@kerfjs/ui/workbench.css",
+        "sideEffects": [
+          "manual-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-workbench",
+        "kui-workbench__rail",
+        "kui-workbench__rail--left",
+        "kui-workbench__rail--right",
+        "kui-workbench__center",
+        "kui-workbench__main",
+        "kui-workbench__drawer",
+        "kui-workbench__panel-content"
+      ],
+      "publicTokens": [
+        "--kui-workbench-rail-width",
+        "--kui-workbench-drawer-height"
+      ],
+      "links": {
+        "catalogRoute": "?component=workbench",
+        "documentation": "docs/workbench.md",
+        "recipe": "docs/workbench.md#state-lives-in-the-app"
+      }
+    },
     {
       "id": "sunken-panel",
       "name": "SunkenPanel",

package/ai/component-catalog.schema.json

@@ -76,6 +76,7 @@
       "type": "object",
       "required": ["sideEffects"],
       "properties": {
+        "moduleImport": { "type": "string" },
         "browserImport": { "type": "string" },
         "manualCssImport": { "type": "string" },
         "registrationImport": { "type": "string" },

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.21` and `kerfjs@5.0.0-beta.21`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.23` and `kerfjs@5.0.0-beta.23`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/disclosure-arrow`
 

package/ai/webawesome-jsx-signatures-v1.md

@@ -1,6 +1,6 @@
 # Web Awesome JSX signatures for the UI authoring corpus
 
-Generated from the emitted `@kerfjs/ui@5.0.0-beta.21` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.23` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
 
 ```ts
 import { KerfCustomElement } from 'kerfjs/jsx-runtime';

package/analyzer/index.mjs

@@ -13,6 +13,7 @@ import postcss from 'postcss';
 import ts from 'typescript';
 
 import { loadApplicationUiProfile } from '../ai/application-ui-profile.mjs';
+import { isUiTraversalExcluded } from '../traversal-exclusions.mjs';
 
 export const UI_ANALYSIS_SCHEMA_VERSION = 1;
 
@@ -36,16 +37,10 @@ const spacingProperties = /^(?:margin|padding|gap|inset)(?:-|$)/;
 const dimensionProperties =
   /^(?:width|height|min-width|max-width|min-height|max-height)$/;
 const approvedSpacing = new Set([0, 4, 8, 16, 24]);
-const ignoredDirectories = new Set([
-  '.git',
-  'coverage',
-  'dist',
-  'node_modules',
-]);
-
 async function collectFiles(root, paths) {
   const files = [];
   const visit = async (path) => {
+    if (isUiTraversalExcluded(root, path)) return;
     const details = await stat(path);
     if (details.isFile()) {
       if (sourceExtensions.has(extname(path)) || path.endsWith('.css'))
@@ -54,7 +49,6 @@ async function collectFiles(root, paths) {
     }
     const entries = await readdir(path, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isDirectory() && ignoredDirectories.has(entry.name)) continue;
       const child = resolve(path, entry.name);
       if (entry.isDirectory()) await visit(child);
       else if (