@kerfjs/ui 5.0.0-beta.75 → 5.0.0-beta.76

package/README.md

@@ -9,6 +9,31 @@ When adding a first-party public component, follow the
 entry drives one validator across package, build, barrel, CSS, demo, route, and
 AI signature projections, with a non-mutating dry-run report.
 
+### Shared semantic tones
+
+`SemanticTone` is the shared color-role type for `Badge`, `Chip`, `StateBanner`,
+and semantic `ContentItem` appearances: `neutral`, `info`, `pop`, `success`,
+`warning`, and `danger`. Import it as a type from `@kerfjs/ui`,
+`@kerfjs/ui/badge`, `@kerfjs/ui/state-banner`, or `@kerfjs/ui/content-item`.
+Use `info` for the role backed by the existing `--kui-color-brand-*` tokens.
+Migrate Badge/Chip `tone="brand"` to `tone="info"`; `BadgeTone` and
+`StateBannerTone` remain deprecated aliases of `SemanticTone`.
+
+## Source organization
+
+The flat files directly under `src/` are stable package entry facades. Keep
+component implementation and CSS together under
+`src/components/<family>/<component>/`. Put support code used by one component
+in its `internal/`, `model/`, `register/`, or `wiring/` folder. Shared types and
+utilities live under `src/shared/`; wiring that spans several components lives
+under `src/wiring/`; Web Awesome integration code lives under
+`src/integrations/`. Catalog-only implementation remains under `src/catalog/`.
+
+Choose an existing family by the component role, and add a family only when no
+current one fits. Public JavaScript and CSS subpaths remain flat through their
+root facades. `npm run check:source-organization` rejects implementation added
+back to the root or component-local support code placed in the wrong folder.
+
 Browser verification always builds current source: both `npm run test:e2e`
 and direct focused Playwright commands run the catalog/conformance preflights
 and production build before preview. See the [UX catalog contract](./docs/ux-demo.md).
@@ -497,7 +522,8 @@ or scope variables directly on a component instance.
 
 Applications can separately opt into `@kerfjs/ui/document.css` for border-box
 sizing, token-backed body typography/colors, zero body margin, plain-link color,
-and a definite full-height chain. Add `class="kui-app-root"` to the one direct
+inherited native table-cell and form-control font metrics, and a definite
+full-height chain. Add `class="kui-app-root"` to the one direct
 mount container when a percentage-height application shell must fill the
 viewport. This global baseline is deliberately absent from `styles.css` and
 component browser imports. See [Document baseline](./docs/document-baseline.md).
@@ -766,3 +792,5 @@ For dimensions that should scale with the root font size, author pixels with
 baseline. Keep intentional 1px borders in pixels and contextual `em` values
 explicit. `npm run build` emits standard CSS to `dist/styles`; `npm run dev`
 applies the same transform directly to source styles and hot-reloads edits.
+
+Lowered surfaces and decorative neutral fills/borders use translucent shared theme colors. Nested surfaces compound naturally; demos compose public components without per-depth overrides. See [contextual transparency](docs/webawesome-theme.md#contextual-transparency).

package/ai/component-catalog.json

@@ -37,7 +37,7 @@
         "accessible label for abbreviated content"
       ],
       "variants": [
-        "neutral, brand, pop, success, warning, or danger tone",
+        "neutral, info, pop, success, warning, or danger tone",
         "quiet, solid, or outline appearance",
         "pill or rounded shape",
         "compact or default size, or a text-free dot (size: 'dot')",
@@ -96,7 +96,7 @@
         "disabled policy"
       ],
       "variants": [
-        "neutral, brand, pop, success, warning, or danger tone",
+        "neutral, info, pop, success, warning, or danger tone",
         "quiet, solid, or outline appearance",
         "pill or rounded shape",
         "compact or default size",
@@ -161,6 +161,7 @@
       "variants": [
         "decorative",
         "labeled",
+        "inline text flow",
         "outline (default appearance)",
         "solid (appearance=solid)"
       ],
@@ -174,6 +175,11 @@
           "title": "Semantic icon color",
           "description": "Set an icon foreground with a semantic color token; omit color to inherit from surrounding text. Use foregroundColor() for a custom CSS color or foregroundColorVar() for an app variable.",
           "code": "<LucideIcon icon={Bell} name=\"alert\" color={uiColor('warning-on-quiet')} />"
+        },
+        {
+          "title": "Inline with text",
+          "description": "Let a decorative icon flow inside Text or other prose while preserving its inherited 1em size.",
+          "code": "<Text>Ready <LucideIcon icon={Bell} name=\"notification\" inline /> now.</Text>"
         }
       ],
       "accessibility": [
@@ -466,12 +472,12 @@
       "category": "Foundation",
       "kind": "composition",
       "source": "kerf",
-      "description": "Opt-in document-level defaults: border-box sizing, body margin/font/surface, link color, and the html → body → .kui-app-root full-height chain.",
+      "description": "Opt-in document-level defaults: border-box sizing, body margin/font/surface, native table-cell and form-control font metrics, link color, and the html → body → .kui-app-root full-height chain.",
       "uses": [],
       "purpose": "Let an application opt into Kerf UI-owned document defaults and a definite full-height chain for a percentage-height application shell.",
       "publicExports": [],
       "useWhen": [
-        "An application wants Kerf UI to own document-level box sizing, body typography, surface, and link color.",
+        "An application wants Kerf UI to own document-level box sizing, body typography, native table-cell and form-control font metrics, surface, and link color.",
         "A full-height shell (Workbench, SplitView, NavStack, or TabScaffold) mounts into one direct container: put .kui-app-root on that container."
       ],
       "avoidWhen": [
@@ -2354,7 +2360,7 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Equal-width columns with a fixed count or a minimum-width responsive mode, typed gaps, and optional flex participation.",
+      "description": "Equal-width columns with a fixed count or a minimum-width responsive mode, typed gaps, physical-side text/control insets, and optional flex participation.",
       "uses": [],
       "purpose": "Arrange related siblings in equal-width columns with either a fixed count or automatic container-width collapse.",
       "publicExports": [
@@ -2483,7 +2489,7 @@
       "appOwns": [
         "child semantics and content",
         "fixed column count or responsive minimum width",
-        "typed gap and flex choices"
+        "typed gap, flex, and physical-side inset choices"
       ],
       "variants": [
         "any positive safe-integer equal-track count",
@@ -2491,6 +2497,7 @@
         "named none/2xs/xs/s/m/l/xl token gap",
         "typed CssLength gap",
         "boolean, finite-keyword, or typed CssFlex flex",
+        "top/right/bottom/left text and control inset combinations",
         "fill: the layout root fills a definite-height parent",
         "rootAttributes: safe data-* metadata on the root",
         "selectionMode=multiple: labeled multi-select grid for ContentItem tiles"
@@ -2503,8 +2510,9 @@
       "geometry": {
         "margin": "none",
         "border": "none",
-        "padding": "none",
+        "padding": "conditional",
         "notes": [
+          "textInsets adds 17px and controlInsets adds 8px on selected physical sides; text wins on overlap.",
           "Fixed tracks use minmax(0, 1fr); responsive tracks use auto-fit with a minimum width capped at 100%, preserving equal distribution without narrow overflow."
         ]
       },
@@ -3373,22 +3381,23 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "One self-contained content child with the shared 8px margin + 1px border + 8px padding geometry, a typed frame, and a rounded or pill shape.",
+      "description": "One self-contained content child with shared geometry plus typed transparent, surface, or semantic appearance, frame, and shape choices.",
       "uses": [],
-      "purpose": "Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, and radius, with framing and shape chosen by typed props instead of hand-written modifier classes.",
+      "purpose": "Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, radius, and optional coordinated surface colors.",
       "publicExports": [
         "ContentItem"
       ],
       "useWhen": [
         "An ordinary surface-like child of a Pane or .kui-content stack needs the shared content-item geometry so its content edge lands at the standard 17px inset.",
         "A content item marks a real distinction and must read as visibly bounded: pass frame=\"framed\" (the border is always reserved, so geometry does not change).",
+        "A content item needs the base surface or a coordinated semantic status treatment: pass appearance=\"surface\" or a semantic appearance such as success or danger.",
         "A content item should follow a pill control's 22px radius: pass shape=\"pill\".",
         "A selectable rich card needs nested controls: use selectionMode=\"multiple\" inside a labeled List multi-select grid."
       ],
       "avoidWhen": [
         "Do not wrap a component that already owns content-item geometry (ListItem, ListHeader, StateBanner, Toolbar, ValueTable) or pad around a ContentItem; either double-insets.",
         "Do not frame an item only to make it look contained; hierarchy comes from alignment, spacing, and type first.",
-        "Do not use it as a filled or lowered card; use SunkenPanel for a lowered surface.",
+        "Do not use its surface appearance for a lowered inset panel around a stack; use SunkenPanel for that structure.",
         "Do not use it for bare text alone; use ListInsetText, which adds the same inset without claiming a surface."
       ],
       "alternatives": [
@@ -3411,6 +3420,7 @@
       "appOwns": [
         "the item content",
         "whether the item marks a real distinction that warrants a visible frame",
+        "whether the item needs a surface or semantic appearance",
         "corner shape",
         "region semantics and accessible name",
         "whether the item is a programmatic focus target",
@@ -3421,6 +3431,8 @@
         "framed rounded item",
         "pill item",
         "framed pill item",
+        "base surface item",
+        "neutral, info, pop, success, warning, or danger semantic item",
         "named focus-target region",
         "multi-select rich grid row"
       ],
@@ -3435,7 +3447,7 @@
         "border": "self",
         "padding": "self",
         "notes": [
-          "The 1px border is always reserved and transparent unless frame=\"framed\", so framed and unframed items share the same geometry."
+          "The 1px border is always reserved; transparent items paint it only when frame=\"framed\", while surface and semantic appearances coordinate its color with their background and foreground."
         ]
       },
       "delivery": {

package/ai/component-composition.json

@@ -2107,7 +2107,7 @@
           "required": false
         },
         {
-          "id": "typed gap and flex choices",
+          "id": "typed gap, flex, and physical-side inset choices",
           "owner": "application",
           "required": false
         }
@@ -2124,8 +2124,9 @@
         "geometry": {
           "margin": "none",
           "border": "none",
-          "padding": "none",
+          "padding": "conditional",
           "notes": [
+            "textInsets adds 17px and controlInsets adds 8px on selected physical sides; text wins on overlap.",
             "Fixed tracks use minmax(0, 1fr); responsive tracks use auto-fit with a minimum width capped at 100%, preserving equal distribution without narrow overflow."
           ]
         }
@@ -2786,6 +2787,11 @@
           "owner": "application",
           "required": false
         },
+        {
+          "id": "whether the item needs a surface or semantic appearance",
+          "owner": "application",
+          "required": false
+        },
         { "id": "corner shape", "owner": "application", "required": false },
         {
           "id": "region semantics and accessible name",
@@ -2817,7 +2823,7 @@
           "border": "self",
           "padding": "self",
           "notes": [
-            "The 1px border is always reserved and transparent unless frame=\"framed\", so framed and unframed items share the same geometry."
+            "The 1px border is always reserved; transparent items paint it only when frame=\"framed\", while surface and semantic appearances coordinate its color with their background and foreground."
           ]
         }
       },

package/ai/components/README.md

@@ -38,7 +38,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [Spacer](./spacer.md) — Express an intentional empty dimension or consume remaining flex space without application-owned spacer markup or raw CSS lengths.
 - [ListInsetControl](./list-inset-control.md) — Apply the standard 8px outer margin to all physical sides of a self-bordered control by default, or only the sides selected with the canonical Sides contract.
 - [ListInsetText](./list-inset-text.md) — Apply the full 8px margin + 1px transparent border + 8px padding to all physical sides of bare text by default, or only the sides selected with the canonical Sides contract.
-- [ContentItem](./content-item.md) — Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, and radius, with framing and shape chosen by typed props instead of hand-written modifier classes.
+- [ContentItem](./content-item.md) — Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, radius, and optional coordinated surface colors.
 
 ## Kerf UI — Navigation
 

package/ai/components/badge.md

@@ -29,7 +29,7 @@ Exact prop names and types: [`@kerfjs/ui/badge`](../public-api-signatures-v1.md#
 
 **Variants (configure, do not restyle):**
 
-- neutral, brand, pop, success, warning, or danger tone
+- neutral, info, pop, success, warning, or danger tone
 - quiet, solid, or outline appearance
 - pill or rounded shape
 - compact or default size, or a text-free dot (size: 'dot')

package/ai/components/chip.md

@@ -29,7 +29,7 @@ Exact prop names and types: [`@kerfjs/ui/chip`](../public-api-signatures-v1.md#k
 
 **Variants (configure, do not restyle):**
 
-- neutral, brand, pop, success, warning, or danger tone
+- neutral, info, pop, success, warning, or danger tone
 - quiet, solid, or outline appearance
 - pill or rounded shape
 - compact or default size

package/ai/components/content-item.md

@@ -4,14 +4,15 @@
 
 `@kerfjs/ui:content-item` · Kerf UI · component · Structure
 
-One self-contained content child with the shared 8px margin + 1px border + 8px padding geometry, a typed frame, and a rounded or pill shape.
+One self-contained content child with shared geometry plus typed transparent, surface, or semantic appearance, frame, and shape choices.
 
 ## When to use
 
-Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, and radius, with framing and shape chosen by typed props instead of hand-written modifier classes.
+Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, radius, and optional coordinated surface colors.
 
 - An ordinary surface-like child of a Pane or .kui-content stack needs the shared content-item geometry so its content edge lands at the standard 17px inset.
 - A content item marks a real distinction and must read as visibly bounded: pass frame="framed" (the border is always reserved, so geometry does not change).
+- A content item needs the base surface or a coordinated semantic status treatment: pass appearance="surface" or a semantic appearance such as success or danger.
 - A content item should follow a pill control's 22px radius: pass shape="pill".
 - A selectable rich card needs nested controls: use selectionMode="multiple" inside a labeled List multi-select grid.
 
@@ -19,7 +20,7 @@ Render one self-contained .kui-content child that owns its 8px inline margin, re
 
 - Do not wrap a component that already owns content-item geometry (ListItem, ListHeader, StateBanner, Toolbar, ValueTable) or pad around a ContentItem; either double-insets.
 - Do not frame an item only to make it look contained; hierarchy comes from alignment, spacing, and type first.
-- Do not use it as a filled or lowered card; use SunkenPanel for a lowered surface.
+- Do not use its surface appearance for a lowered inset panel around a stack; use SunkenPanel for that structure.
 - Do not use it for bare text alone; use ListInsetText, which adds the same inset without claiming a surface.
 
 **Alternatives:**
@@ -44,6 +45,8 @@ Exact prop names and types: [`@kerfjs/ui/content-item`](../public-api-signatures
 - framed rounded item
 - pill item
 - framed pill item
+- base surface item
+- neutral, info, pop, success, warning, or danger semantic item
 - named focus-target region
 - multi-select rich grid row
 
@@ -55,7 +58,7 @@ Exact prop names and types: [`@kerfjs/ui/content-item`](../public-api-signatures
 
 ## State and wiring
 
-**The app owns:** the item content; whether the item marks a real distinction that warrants a visible frame; corner shape; region semantics and accessible name; whether the item is a programmatic focus target; the selection set and Shift/Cmd extension for multi-select rich cards.
+**The app owns:** the item content; whether the item marks a real distinction that warrants a visible frame; whether the item needs a surface or semantic appearance; corner shape; region semantics and accessible name; whether the item is a programmatic focus target; the selection set and Shift/Cmd extension for multi-select rich cards.
 
 No wiring helper.
 
@@ -63,7 +66,7 @@ No wiring helper.
 
 Margin: self · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
-- The 1px border is always reserved and transparent unless frame="framed", so framed and unframed items share the same geometry.
+- The 1px border is always reserved; transparent items paint it only when frame="framed", while surface and semantic appearances coordinate its color with their background and foreground.
 
 ## Accessibility
 

package/ai/components/document-baseline.md

@@ -4,13 +4,13 @@
 
 `@kerfjs/ui:document-baseline` · Kerf UI · CSS composition · Foundation
 
-Opt-in document-level defaults: border-box sizing, body margin/font/surface, link color, and the html → body → .kui-app-root full-height chain.
+Opt-in document-level defaults: border-box sizing, body margin/font/surface, native table-cell and form-control font metrics, link color, and the html → body → .kui-app-root full-height chain.
 
 ## When to use
 
 Let an application opt into Kerf UI-owned document defaults and a definite full-height chain for a percentage-height application shell.
 
-- An application wants Kerf UI to own document-level box sizing, body typography, surface, and link color.
+- An application wants Kerf UI to own document-level box sizing, body typography, native table-cell and form-control font metrics, surface, and link color.
 - A full-height shell (Workbench, SplitView, NavStack, or TabScaffold) mounts into one direct container: put .kui-app-root on that container.
 
 **Not when:**

package/ai/components/grid.md

@@ -4,7 +4,7 @@
 
 `@kerfjs/ui:grid` · Kerf UI · component · Structure
 
-Equal-width columns with a fixed count or a minimum-width responsive mode, typed gaps, and optional flex participation.
+Equal-width columns with a fixed count or a minimum-width responsive mode, typed gaps, physical-side text/control insets, and optional flex participation.
 
 ## When to use
 
@@ -45,6 +45,7 @@ Exact prop names and types: [`@kerfjs/ui/grid`](../public-api-signatures-v1.md#k
 - named none/2xs/xs/s/m/l/xl token gap
 - typed CssLength gap
 - boolean, finite-keyword, or typed CssFlex flex
+- top/right/bottom/left text and control inset combinations
 - fill: the layout root fills a definite-height parent
 - rootAttributes: safe data-\* metadata on the root
 - selectionMode=multiple: labeled multi-select grid for ContentItem tiles
@@ -63,14 +64,15 @@ Exact prop names and types: [`@kerfjs/ui/grid`](../public-api-signatures-v1.md#k
 
 ## State and wiring
 
-**The app owns:** child semantics and content; fixed column count or responsive minimum width; typed gap and flex choices.
+**The app owns:** child semantics and content; fixed column count or responsive minimum width; typed gap, flex, and physical-side inset choices.
 
 No wiring helper.
 
 ## Geometry
 
-Margin: none · border: none · padding: none (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+Margin: none · border: none · padding: conditional (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
+- textInsets adds 17px and controlInsets adds 8px on selected physical sides; text wins on overlap.
 - Fixed tracks use minmax(0, 1fr); responsive tracks use auto-fit with a minimum width capped at 100%, preserving equal distribution without narrow overflow.
 
 ## Accessibility

package/ai/components/lucide-icon.md

@@ -32,6 +32,7 @@ Exact prop names and types: [`@kerfjs/ui/lucide-icon`](../public-api-signatures-
 
 - decorative
 - labeled
+- inline text flow
 - outline (default appearance)
 - solid (appearance=solid)
 
@@ -73,6 +74,16 @@ Set an icon foreground with a semantic color token; omit color to inherit from s
 <LucideIcon icon={Bell} name="alert" color={uiColor('warning-on-quiet')} />
 ```
 
+### Inline with text
+
+Let a decorative icon flow inside Text or other prose while preserving its inherited 1em size.
+
+```tsx
+<Text>
+  Ready <LucideIcon icon={Bell} name="notification" inline /> now.
+</Text>
+```
+
 ## Styling boundary
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.