@kerfjs/ui 5.0.0-beta.22 → 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.22` and `kerfjs@5.0.0-beta.22`. 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.22` 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 (

package/docs/component-selection.md

@@ -24,6 +24,18 @@ fix the surrounding layout instead of overriding a control. See
 [`design-philosophy.md`](./design-philosophy.md) "Reach for the primitive, not for
 CSS".
 
+## Foundation tokens
+
+Import `@kerfjs/ui/foundation.css` when application-owned composition CSS needs
+the same semantic typography, spacing, device breakpoints, geometry, radii,
+colors, focus ring, or shadows as Kerf components. Its complete supported
+`--kui-*` surface is cataloged by the `foundation` entry; tools may treat that
+entry as the public allowlist rather than inferring stability from CSS text.
+Override these tokens globally for an application theme or on the narrowest
+useful subtree. Prefer a component prop or component-specific token when the
+change belongs to one component or instance, and preserve the documented
+foreground/background contrast relationships and visible focus ring.
+
 ## Production recipes
 
 Use the [complete recipe guide](./recipes.md) when several primitives form one

package/docs/ui-analyzer.md

@@ -28,6 +28,11 @@ its reachable project-local styles into the report, including quoted or
 unquoted `url()` imports; external package styles remain outside the consumer
 boundary.
 
+Recursive discovery excludes generated and tool-owned trees, including any
+nested `.claude/worktrees` checkout. Those checkouts are separate repositories,
+not application source, and cannot contribute files, diagnostics, profile
+policy, or analysis inputs to the containing application.
+
 ## Diagnostics and exit behavior
 
 | Rule       | Kind   | Meaning                                                           |

package/docs/ui-doctor.md

@@ -15,7 +15,7 @@ The default terminal output is short and repair-oriented. `--format json` emits
 
 The catalog stage discovers the package-default application UI profile and workspace/root-to-leaf directory layers. It validates referenced selection/composition catalogs and, when a workspace declares `package.json#kerfComponentCatalog`, invokes the installed `create-kerf-component` catalog checker to validate metadata, source exports, schema conformance, and generated-output drift. This checker reads source text; it does not import application modules.
 
-TypeScript uses the compiler API with `noEmit`. ESLint loads the installed `eslint-plugin-kerfjs` `recommended-ui` preset (`--eslint strict-ui` opts into advisory rules as errors). Stable KUI identifiers come from the packaged `application-ui-diagnostic-ids-v1.json` registry; the doctor also reads installed ESLint message metadata for semantic conflict detection instead of duplicating rule definitions. The analyzer calls the public `@kerfjs/ui/analyzer` contract. None of these stages executes generated application code.
+TypeScript uses the compiler API with `noEmit`. ESLint loads the installed `eslint-plugin-kerfjs` `recommended-ui` preset (`--eslint strict-ui` opts into advisory rules as errors). This is deliberately an isolated Kerf lint pass rather than the consumer's complete ESLint configuration. Inline directives for consumer-owned plugins, such as `@typescript-eslint`, therefore do not produce false "rule definition not found" diagnostics; the consumer's normal ESLint command remains authoritative for those rules. Unknown `kerfjs/*` directives still fail the doctor pass. Stable KUI identifiers come from the packaged `application-ui-diagnostic-ids-v1.json` registry; the doctor also reads installed ESLint message metadata for semantic conflict detection instead of duplicating rule definitions. The analyzer calls the public `@kerfjs/ui/analyzer` contract. None of these stages executes generated application code.
 
 The browser evaluator is different: it runs the application and is disabled by default. It only runs when configuration supplies `browser.url` or the command receives `--browser-url`. Start and authorize the target application separately.
 
@@ -25,6 +25,11 @@ An unavailable or failed stage does not prevent independent stages from reportin
 
 `--full` is the default and analyzes the selected package. `--changed` reads tracked and untracked paths from Git unless one or more `--path` values are supplied. An empty changed set is a configuration error instead of a false-clean success. With `--package`, workspace-relative Git paths are converted to package-relative paths before TypeScript, ESLint, and analyzer selection; paths outside the selected package are ignored.
 
+Full traversal treats nested `.claude/worktrees` checkouts as tool-owned
+repositories rather than application source. Their files are excluded
+consistently from TypeScript, ESLint, analyzer discovery, and cache inputs, even
+when the nested checkout lives below another application directory.
+
 TypeScript constructs the selected package's program so compiler options retain their real meaning, while its root inputs are narrowed to changed source files. Use `--full` for release gates.
 
 ## Configuration and suppressions

package/docs/ux-demo.md

@@ -10,7 +10,7 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - The `ListActionRow` route demonstrates sibling primary/trailing native controls, independent disabled states, controlled selection, first-line leading-icon alignment for wrapped labels, and an application-owned native popover relationship without nesting controls. The `ListItem` route demonstrates the same multiline leading-icon anchor alongside its single-control navigation contract.
 - The `AppTab` route demonstrates a runtime-filtered domain metadata slot and a decorative replacement close icon without changing TabBar selection, close, reorder, or focus ownership. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
 - Every first-party visual component and every free Web Awesome 3.12 component has its own stable `?component=<id>` URL and focused demo. Composite header, menu, feedback, and theme scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component.
-- `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, recommendation, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Non-supported Web Awesome recommendations project to a visible `Discouraged` sidebar tag, with Popup as the deliberate conditional exception. Demo paths resolve to the matching `ui/ux-demo/demos/<id>.tsx` or `ui/ux-demo/recipes/*.tsx` file, or to `ui/ux-demo/webawesome-demos.tsx` for Web Awesome entries. `ui/ux-demo/main.tsx` owns only the catalog shell, shared state, routing, and interaction wiring. First-party component entries additionally derive `ui/src/<browser-subpath>.tsx` from their canonical `delivery.browserImport`.
+- `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, recommendation, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Non-supported Web Awesome recommendations project to a visible `Discouraged` sidebar tag, with Popup as the deliberate conditional exception. Demo paths resolve to the matching `ui/ux-demo/demos/<id>.tsx` or `ui/ux-demo/recipes/*.tsx` file, or to `ui/ux-demo/webawesome-demos.tsx` for Web Awesome entries. `ui/ux-demo/main.tsx` owns only the catalog shell, shared state, routing, and interaction wiring. First-party component entries additionally derive `ui/src/<public-subpath>.tsx` from their canonical `delivery.browserImport` or opt-in `delivery.moduleImport`.
 - Every detail footer groups compact `Demo source` and `Guidance` actions; first-party component details also expose `Component source`. Web Awesome details say `Integration guidance` to distinguish the local integration contract from the upstream component implementation. Each button retains its repository-relative path in the DOM for verification and uses a deploy-safe absolute GitHub blob URL with a contextual new-tab name; the demo does not depend on a local source server or add a package runtime export. At phone widths, the resource group and related-component selector stack as full-width rows, with any resource overflow contained locally so labels cannot overlap the selector or widen the document.
 - The master/detail shell groups first-party routes by category with production `ListHeader` and `ListItem` components. Catalog entries can supply short reusable trailing tags; the Web Awesome projection uses them to label exactly the 15 discouraged choices. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
 - The shell itself uses `@kerfjs/ui/layout.css`: sidebars, details, previews, dialogs, and resize specimens share unpadded panes plus self-contained content items. Its sidebar identity uses the Kerf logo beside a vertically centered title, with the subtitle in its own aligned row like `PanelHeader`; the current-view heading is also a toolbar. Collapsing the catalog removes the pane completely and moves its restore action to the main toolbar's leading edge instead of leaving an icon-only rail. The selected view description remains inset below the page toolbar. The checkerboard belongs to the complete scrollable preview region rather than a nested card. A lightly separated footer keeps live status above compact source, guidance, and relationship groups. The focused `ResizableRegion` specimen stretches its surface through the available stage height and reports committed width in that shared status footer; narrow layouts retain local horizontal access when the pane is resized wider than the stage, and the split remains readable at 200% root scaling. Geometry coverage checks wide, intermediate, narrow, and 200% zoom layouts.

package/docs/workbench.md

@@ -49,6 +49,19 @@ Each `WorkbenchPanel` takes `content`, an optional `collapsed`, an optional
 `--kui-workbench-rail-width` 280px, `--kui-workbench-drawer-height` 220px), and
 an optional `label`.
 
+## Public styling boundary
+
+Import `@kerfjs/ui/workbench.css` after the component subpath. Applications may
+set `--kui-workbench-rail-width` and `--kui-workbench-drawer-height` on a
+Workbench instance. The supported composition classes are `.kui-workbench`,
+`.kui-workbench__rail`, `.kui-workbench__rail--left`,
+`.kui-workbench__rail--right`, `.kui-workbench__center`,
+`.kui-workbench__main`, `.kui-workbench__drawer`, and
+`.kui-workbench__panel-content`; these exact hooks are cataloged for tools that
+must classify public application selectors. Prefer the component props and two
+size tokens before selecting internal anatomy, and do not target its data
+attributes or descendant tags as styling contracts.
+
 ## How the collapse animates
 
 Collapsing snaps the panel's flex track to zero in a single reflow (so the work

package/doctor/eslint-diagnostics.d.mts

@@ -0,0 +1,8 @@
+export interface EslintDiagnosticLike {
+  ruleId?: string | null;
+  message: string;
+}
+
+export function isForeignRuleDefinitionDiagnostic(
+  item: EslintDiagnosticLike,
+): boolean;

package/doctor/eslint-diagnostics.mjs

@@ -0,0 +1,7 @@
+export function isForeignRuleDefinitionDiagnostic(item) {
+  return (
+    typeof item.ruleId === 'string' &&
+    !item.ruleId.startsWith('kerfjs/') &&
+    item.message === `Definition for rule '${item.ruleId}' was not found.`
+  );
+}

package/doctor/index.mjs

@@ -23,6 +23,8 @@ import { createRequire } from 'node:module';
 import { loadApplicationUiProfile } from '../ai/application-ui-profile.mjs';
 import { analyzeUiProject, UI_ANALYSIS_RULES } from '../analyzer/index.mjs';
 import { evaluateUi, UI_EVALUATION_RULES } from '../evaluator/index.mjs';
+import { isForeignRuleDefinitionDiagnostic } from './eslint-diagnostics.mjs';
+import { isUiTraversalExcluded } from '../traversal-exclusions.mjs';
 
 export const UI_DOCTOR_SCHEMA_VERSION = 1;
 export const UI_DOCTOR_EXIT = Object.freeze({
@@ -54,14 +56,6 @@ const sourceExtensions = new Set([
   '.cts',
   '.css',
 ]);
-const ignoredDirectories = new Set([
-  '.git',
-  '.kerf-cache',
-  'coverage',
-  'dist',
-  'kerf-ui-evidence',
-  'node_modules',
-]);
 const defaultStages = Object.freeze({
   catalog: true,
   typescript: true,
@@ -361,6 +355,7 @@ export async function resolveUiDoctorPackage(root, selector) {
 async function collectInputs(root, paths) {
   const result = [];
   const visit = async (path) => {
+    if (isUiTraversalExcluded(root, path)) return;
     let details;
     try {
       details = await stat(path);
@@ -381,7 +376,6 @@ async function collectInputs(root, paths) {
       return;
     }
     for (const entry of await readdir(path, { withFileTypes: true })) {
-      if (entry.isDirectory() && ignoredDirectories.has(entry.name)) continue;
       await visit(resolve(path, entry.name));
     }
   };
@@ -777,6 +771,9 @@ async function runTypeScript({ packageRoot, paths }) {
     { ...ts.default.sys, onUnRecoverableConfigFileDiagnostic: () => {} },
   );
   if (!parsed) throw new Error('TypeScript could not parse tsconfig.json.');
+  parsed.fileNames = parsed.fileNames.filter(
+    (file) => !isUiTraversalExcluded(packageRoot, file),
+  );
   if (paths?.length) {
     const selected = new Set(paths.map((path) => resolve(packageRoot, path)));
     parsed.fileNames = parsed.fileNames.filter((file) => selected.has(file));
@@ -850,7 +847,7 @@ async function runEslint({
       },
     },
   };
-  const configs = [base];
+  const configs = [{ ignores: ['**/.claude/worktrees/**'] }, base];
   if (usesTypeScript) {
     const parserModule = await importFrom(
       packageRoot,
@@ -879,6 +876,7 @@ async function runEslint({
   const diagnostics = [];
   for (const result of results)
     for (const item of result.messages) {
+      if (isForeignRuleDefinitionDiagnostic(item)) continue;
       const code = item.message.match(/\bKUI-[A-Z]\d{3}\b/)?.[0];
       diagnostics.push(
         normalizedDiagnostic({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.22",
+  "version": "5.0.0-beta.23",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -301,6 +301,7 @@
     "analyzer",
     "doctor",
     "evaluator",
+    "traversal-exclusions.mjs",
     "docs",
     "ux-demo/recipes",
     "llms.txt",

package/traversal-exclusions.mjs

@@ -0,0 +1,21 @@
+import { relative, sep } from 'node:path';
+
+const ignoredDirectoryNames = new Set([
+  '.git',
+  '.kerf-cache',
+  'coverage',
+  'dist',
+  'kerf-ui-evidence',
+  'node_modules',
+]);
+
+export function isUiTraversalExcluded(root, candidate) {
+  const segments = relative(root, candidate).split(sep);
+  return (
+    segments.some((segment) => ignoredDirectoryNames.has(segment)) ||
+    segments.some(
+      (segment, index) =>
+        segment === '.claude' && segments[index + 1] === 'worktrees',
+    )
+  );
+}