@capillaryjs/capillary-ui 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -6,8 +6,92 @@ Versioning.
 
 ## Unreleased
 
+### Fixed
+
+- Set the default GroupBox content gap independently from island spacing, using
+  a compact 2px rhythm for controls inside a GroupBox.
+
+- Render unfilled required controls with a transparent negative ✲ marker:
+  inside native input surfaces and beside a pseudo-element checkable outline
+  extension that does not change the label's layout width.
+- Place checkbox and radio validation halos around the complete labelled
+  choice while retaining the error border on the painted shell.
+- Keep busy buttons visually normal and layer only the working animation over
+  their ordinary chrome. Gate ProgressBar's busy animation on an emitter-backed
+  `FetchState.Loading` state, applying the working texture to both determinate
+  and indeterminate bars so literal indeterminate values remain static.
+- Make ProgressBar fill its available inline width while remaining shrinkable
+  inside constrained layouts.
+- Omit island content padding on direct app-root headers, letting their navbar
+  and toolbar own spacing. Preserve nested headers, other islands, outer
+  gutters, borders, and shadows across themes and managed/legacy layouts.
+- Keep island borders and shadows visible through nested scrollports by using
+  existing gutter space inside the clipping boundary. Preserve surface
+  alignment, shared gaps, and split resizing without theme clearance tokens.
+  Add browser pixel checks for painted borders/shadows and clipping regressions.
+- Publish only the maintained Capillary, Shiny, Soft, White, and Minimal themes.
+  The former Glossy, Original, Java, Dark, and Sci-fi assets and picker entries
+  are removed from the package and applications.
+- Make named-theme surfaces, text, borders, and fills palette-derived. In
+  particular, Shiny progress chrome now follows the muted surface and primary
+  ramps instead of fixed Ice blue stops. Neutral black/white gloss and shadow
+  overlays remain intentionally literal.
+- Replace hue-named palette status primitives with semantic negative, positive,
+  and neutral status colors. Error and success aliases follow the negative and
+  positive colors; multi-state checkbox deny, require, and prefer chrome uses
+  negative, positive, and neutral respectively.
+- Derive shared chrome backgrounds from muted primary palette tones, so panels,
+  table headers, button gradients, and disabled surfaces follow palette changes.
+  Ice blue preserves exactly `#f5f7f8`, `#ebeff3`, and `#d7dee3`. The derivation
+  uses relative HSL colors and sRGB mixing; existing UI aliases remain overridable.
+- Add palette-level `--palette-primary-surface-saturation`: `0` removes primary
+  hue from the three chrome surfaces, `1` retains their calibrated default.
+- Keep unchanged DataTable headers out of row-update renders and avoid redundant
+  renderer marker, attribute, dataset, and style writes.
+- Preserve table-part names after minification and identify header cells by column.
+- Preserve table/header/body identities when loading/error messages or captions change.
+
+- `DataTable` filterable columns no longer keep a permanent document-level
+  click listener: the outside-click listener that closes the filter panel is
+  now attached only while the panel is open. Previously every click in the
+  document fired it, which also flooded event traces with a
+  "Table header cell: click" interaction per click. The listener uses the new
+  `Component.listenWhile`, so it stays on the normal traced native-event path
+  and coalesces with other listeners observing the same click.
+
 ### Added
 
+- Add a live `readOnly` state to Dropdown, checkbox variants, RadioButton,
+  RadioGroup, Toggle, and stylesheet pickers. Read-only value controls stay
+  focusable and readable, expose native `readonly` or `aria-readonly` as
+  appropriate, and reject attempted user changes without becoming disabled.
+- Add palette-derived base read-only chrome tokens for inputs, dropdowns,
+  checkables, and toggles. Themes can override the tokens but no longer need to
+  reproduce disabled styling to represent a fixed value.
+- Add inherited `islands` layout mode to `CapillaryUiApp` and `Layout`, with
+  native `cap-island-layout` / `cap-island-layout-off` traits. One outer inset
+  and shared gutters replace accumulated island margins inside opt-in scopes;
+  ordinary island content and legacy layouts keep their existing spacing.
+  The `--island-gap` and `--island-inset` tokens support theme/application
+  overrides, RouteOutlet carries the mode, and SplitView puts its accessible
+  separator in one gutter, including zero-gap and RTL resizing.
+- Add the light `capillary` theme: bright rounded cards, restrained neutral
+  elevation, compact controls, and palette-primary selected states.
+- Add an overridable instance diagnostic label and a named table-body consumer.
+  Consumer facts report render triggers/passes and own renderer DOM-write counts,
+  distinguishing execution from DOM work without changing update scheduling.
+- Add `Component.listenWhile(target, type, listener, options)`: like
+  `listen`, but returns a function that detaches the listener, for listeners
+  that are only active some of the time. It runs through the same traced
+  native-event coalescing as `listen` and is removed on destroy if still
+  attached.
+- Add a `filterable` column flag to `DataTable`: a column marked
+  `filterable` derives its header filter options from the field's distinct
+  values across the source's unfiltered rows, so options stay stable while
+  a filter is applied. Explicit `filterOptions` still take precedence.
+  Local and caller-query data sources expose their pre-filter rows through
+  the new `TableDataSource.sourceRows`; remote sources fall back to the
+  displayed rows.
 - Add diagnostic ownership scopes and stable diagnostic labels, automatic
   native interaction roots, component/read/watch and function-consumer facts,
   and reactive child, live-property, and native-binding endpoints. Synchronous
@@ -16,6 +100,29 @@ Versioning.
 
 ### Changed
 
+- Use flexbox for single-axis component stacks and simple centered chrome,
+  retaining grid only where its track model is needed. This does not change the
+  public DOM or layout contract.
+- Give all single-line controls the same minimum row footprint with symmetric
+  breathing room, including checkbox/radio variants, temporal inputs, and
+  ProgressBar. Add `--control-row-min-height` and `--control-row-padding-block`
+  without changing painted control shapes or Capillary's `6px 5px` padding.
+  Only OptionsBox retains compact rows and owns a fixed 2px vertical option
+  rhythm across themes; RadioGroup no longer adds a default gap on top of the
+  common row spacing elsewhere.
+- Empty required text, temporal, and dropdown controls now have a subtle
+  themeable dashed required-value outline. The same outline appears on an
+  unchecked two-state `Checkbox`; tri- and quad-state checkboxes intentionally
+  do not use native required validity because no single semantic state is the
+  required value.
+- Retained `Loading` results in `DataTable`, `ListView`, and `TreeView` now
+  show a non-blocking translucent animated working texture while their existing
+  rows remain visible.
+
+## 1.2.0 - 2026-09-15
+
+### Changed
+
 - Make DataTable, ListView, and TreeView shrink and own overflow before a
   bounded flex layout container must scroll. DataTable header cells now remain
   sticky within the table's scrollport.
@@ -42,8 +149,8 @@ Versioning.
   `cap-header:has(+ cap-toolbar)` shadow override together with its
   `--section-header-with-toolbar-shadow` variable.
 - Normalize line-control sizing and text centering in structural CSS: 24px
-  default textbox, dropdown, toggle, and button bodies at 12px UI text, with
-  compact checkbox/radio rows. Remove Shiny's label/select text offsets and
+  default textbox, dropdown, toggle, and button bodies at 12px UI text.
+  Remove Shiny's label/select text offsets and
   prevent toggle border/selection changes from shifting segment text.
 - Refine Shiny's input depth, toolbar/table-header chrome, navigation-to-toolbar
   seam, and loading BlockGraph treatment without moving structural layout

package/README.md

@@ -149,6 +149,14 @@ A class component has explicit phases:
 `onCleanup()` registers listeners or other cleanup functions that Capillary UI invokes
 on destruction.
 
+Diagnostic labels default to static `diagnosticLabel`, `hostName`, then the class
+name. Override the instance `diagnosticLabel` getter when instances need distinct
+names; identity labels are captured at first observation. Table diagnostics expose
+`Table header`, column-specific header cells, and `Table body`. Unchanged header
+props skip parent-driven rendering, while sort/filter subscriptions remain active.
+Consumer events distinguish render passes from own renderer DOM writes; see the
+[diagnostics guide](../../docs/diagnostics.md) for the exact counting boundary.
+
 ```tsx
 class Counter extends Component {
     readonly count = new Emitter(0)
@@ -197,7 +205,7 @@ class Badge extends Component<BadgeProps> {
     static override hostName = 'badge'
     static override css = css`
         & { display: inline-flex; }
-        &[data-tone="positive"] { color: var(--palette-green); }
+        &[data-tone="positive"] { color: var(--palette-status-positive); }
     `
 }
 ```
@@ -313,11 +321,11 @@ the tables below denotes that TypeScript type parameter.
 | `Toolbar` | Named action group | `label`, `orientation` |
 | `Label` | Native label for rich or live text | `text`, `htmlFor`; live: `text` |
 | `Textbox` | Labelled native text input with validation | `label`, `valueEmitter`, `defaultValue`, `type`, `name`, `placeholder`, `disabled`, `required`, `readOnly`, `busy`, `error`, native text constraints, `inputRef`, `onInput`, `onChange`; live: availability, `busy`, and `error` |
-| `Dropdown<T>` | Labelled native select | `options`, `label`, `valueEmitter`, `defaultValue`, `placeholder`, `disabled`, `required`, `busy`, `error`, `onChange`; `options` may be static or a readable emitter whose fetch state supplies loading/error feedback |
-| `RadioButton` | Standalone native radio and label | `label`, `name`, `value`, `checked`, `disabled`, `required`, `busy`, `error`, `onChange`; live: state, availability, `busy`, `error` |
-| `RadioGroup<T>` | Named native-radio fieldset owning one value | `options` as `[value, label]` tuples, `label`, `valueEmitter`, `defaultValue`, `disabled`, `required`, `busy`, `error`, `onChange`; options are ordinary render data |
-| `Toggle<T>` | ARIA radio group rendered as toggle buttons | `options` as `[value, label]` tuples, `label`, `valueEmitter`, `defaultValue`, `disabled`, `required`, `busy`, `error`, `onChange` |
-| `Checkbox<T>` | Configurable keyboard-operable semantic state cycle | `symbols` as `[content, value]` tuples, `label`/`ariaLabel`, `valueEmitter`, `defaultValue`, `disabled`, `required`, `busy`, `error`, `onChange` |
+| `Dropdown<T>` | Labelled native select | `options`, `label`, `valueEmitter`, `defaultValue`, `placeholder`, `disabled`, `required`, `readOnly`, `busy`, `error`, `onChange`; `readOnly` retains focusability and restores the selected value after attempted changes; `options` may be static or a readable emitter whose fetch state supplies loading/error feedback |
+| `RadioButton` | Standalone native radio and label | `label`, `name`, `value`, `checked`, `disabled`, `required`, `readOnly`, `busy`, `error`, `onChange`; live: state, availability, `busy`, `error` |
+| `RadioGroup<T>` | Named native-radio fieldset owning one value | `options` as `[value, label]` tuples, `label`, `valueEmitter`, `defaultValue`, `disabled`, `required`, `readOnly`, `busy`, `error`, `onChange`; options are ordinary render data |
+| `Toggle<T>` | ARIA radio group rendered as toggle buttons | `options` as `[value, label]` tuples, `label`, `valueEmitter`, `defaultValue`, `disabled`, `required`, `readOnly`, `busy`, `error`, `onChange` |
+| `Checkbox<T>` | Configurable keyboard-operable semantic state cycle | `symbols` as `[content, value]` tuples, `label`/`ariaLabel`, `valueEmitter`, `defaultValue`, `disabled`, `required`, `readOnly`, `busy`, `error`, `onChange` |
 | `TriCheckbox` | Neutral/prefer/deny `FilterMode` cycle | Same public props as `Checkbox`, except fixed symbols |
 | `QuadCheckbox` | Neutral/prefer/require/deny `FilterMode` cycle | Same public props as `Checkbox`, except fixed symbols |
 | `DatePicker` (experimental) | Native `<input type="date">` | `CivilDate` value props, `label`/`ariaLabel`, `name`, `autoComplete`, `disabled`, `required`, `readOnly`, `busy`, `error`, `min`/`max`/`step`, `inputRef`, input/change callbacks |
@@ -330,7 +338,12 @@ the native forward cycle.
 
 `busy` is presentational state: it sets native/ARIA busy semantics and paints
 the theme's moving working texture without disabling an input or choice.
-`Button` remains the exception: a busy action is unavailable until it settles.
+`Button` remains the exception: a busy action is unavailable until it settles,
+but keeps its normal button colors, border, and elevation with the working
+texture layered on top. `ProgressBar` only paints that working texture when it
+has a `valueEmitter` whose fetch state is `Loading`; this applies to both
+determinate and indeterminate bars. A literal `value={null}` is simply an
+unfilled indeterminate bar.
 When `error` is also present, error presentation wins over the animation.
 Every error-bearing control describes its native surface with a focusable
 `role="alert"` overlay. Its icon and initially hidden message are absolutely
@@ -355,12 +368,12 @@ const view = new Emitter<'list' | 'grid'>('list')
 
 | Component | Purpose | Key props and state |
 | --- | --- | --- |
-| `CapillaryUiApp` | Fixed `cap-app` application shell and theme-text boundary | `sizing`: `embedded`/viewport axes; `layout`: `horizontal`/`vertical`; `landmark`: `main`/`none`; content or overridden `renderContent()` |
+| `CapillaryUiApp` | Fixed `cap-app` application shell and theme-text boundary | `sizing`: `embedded`/viewport axes; `layout`: `horizontal`/`vertical`; `islands`: inherited surface spacing; `landmark`: `main`/`none`; content or overridden `renderContent()` |
 | `Header` | Styled native heading surface | `level` (1–6), `headingId`, content |
-| `GroupBox` | Labelled group; defaults to a bordered vertical-header group and may be a section or column | required `header`, content; optional `variant`: `section` or `column` |
-| `OptionGroup` | Labelled native fieldset for related controls | `label`/`ariaLabel`, `OptionGroupHeaderEnd` and ordinary content children, `disabled`, `required`, `busy`, `error`; state props are live |
-| `OptionsBox` | GroupBox specialization arranging option groups | required `header`, `OptionGroup` content |
-| `Layout` | Presentation-only arrangement of arbitrary children | exactly one of `horizontal`/`vertical`; `allocation`, `scroll`, optional accessible-region configuration |
+| `GroupBox` | Labelled group; defaults to a bordered vertical-header group and may be a section or column | required `header`, direct content arranged vertically (`section` arranges direct content horizontally); optional `variant`: `section` or `column` |
+| `OptionGroup` | Labelled native fieldset for related controls | `label`/`ariaLabel`, `OptionGroupHeaderEnd` and ordinary content children, `disabled`, `required`, `busy`, `error`; state props are live. Use for related direct checkboxes or multiple distinct controls. |
+| `OptionsBox` | GroupBox specialization arranging compact choice groups | required `header`, direct `OptionGroup` and/or `RadioGroup` content |
+| `Layout` | Presentation-only arrangement of arbitrary children | exactly one of `horizontal`/`vertical`; `allocation`, `scroll`, inherited `islands` spacing, optional accessible-region configuration |
 | `Panel` | Optional labelled, themed region composed over a Layout body | `header`, `horizontal`/`vertical`, `allocation`, `scroll`, `disabled`; `PanelToolbar` and ordinary content children; live: `disabled` |
 | `Sidebar` | Labelled complementary region with fixed header/toolbar and scrolling content | `header`, `ariaLabel`; `SidebarToolbar` and ordinary content children |
 | `SplitView` | Resizable two-pane layout | required `SplitPrimary` and `SplitSecondary` Layout panes; `horizontal`/`vertical`, `allocation`, initial/minimum sizes, separator label, `onResize` |
@@ -475,12 +488,13 @@ range while retaining selections outside that range.
 On an initial snapshot, or a loading snapshot with no result, all three
 collection views render deterministic, `aria-hidden` placeholder rows;
 `placeholderCount` selects their count. A loading snapshot with retained rows
-keeps those rows in place and marks the collection busy, avoiding flicker during
-sort and filter refinements. Application renderers never receive dummy values,
-and refreshes preserve valid keyed selections and expansions. Error snapshots
-retain any available rows, add an error edge and overlay detail icon, and stop
-the loading animation. A `DataTable` data source with `retry` also renders its
-localized retry action.
+keeps those rows in place, marks the collection busy, and displays a thin
+animated translucent working texture, avoiding flicker during sort and filter
+refinements.
+Application renderers never receive dummy values, and refreshes preserve valid
+keyed selections and expansions. Error snapshots retain any available rows,
+add an error edge and overlay detail icon, and stop the loading animation. A
+`DataTable` data source with `retry` also renders its localized retry action.
 
 Advanced compositions may use `BaseSelectionHandler`,
 `SingleSelectionHandler`, `MultiSelectionHandler`, and
@@ -503,13 +517,21 @@ expander needs a reusable presentation trait such as `colored`.
 For reusable sources, use `createLocalTableDataSource`,
 `createQueryTableDataSource`, `createHandlerTableDataSource`, or
 `createRestTableDataSource`. Sources expose `query`, `sortEmitter`,
-`filtersEmitter`, optional `retry`, and `dispose()`. Both direct data and
-query-shaped sources pass their rows through an emitter-derived local table
-view, so their sort and filter state always changes the rendered rows.
+`filtersEmitter`, optional `retry`, optional `sourceRows`, and `dispose()`.
+Both direct data and query-shaped sources pass their rows through an
+emitter-derived local table view, so their sort and filter state always
+changes the rendered rows. `sourceRows` exposes the rows before local
+sort/filter when the source can provide them — local and caller-query
+sources do; remote sources leave it absent because filtering is
+server-side.
 
 `TableColumn` definitions own display and local comparison/filter functions.
 When a column's visible `label` is rich content, supply its textual
 `ariaLabel` for Capillary UI-generated sort and filter control names.
+Set a column's `filterable` flag to derive its header filter options from
+the field's distinct values across `sourceRows` (or the displayed rows when
+the source cannot expose them), so the options stay stable while a filter
+is applied. Explicit `filterOptions` take precedence over `filterable`.
 The pure `applyLocalTableState`, `serializeTableQuery`, and related table-query
 helpers keep local behavior and remote encoding explicit. Pagination,
 virtualization, and server-specific wire policy remain application concerns.
@@ -519,7 +541,7 @@ virtualization, and server-specific wire policy remain application concerns.
 | Component | Purpose | Key props and state |
 | --- | --- | --- |
 | `Dialog` | Controlled native modal with focus containment and restoration | `title`, `description`, `DialogActions` and ordinary content children, `valueEmitter`/`defaultValue`, `closeLabel`, `showCloseButton`, `initialFocusRef`, `onClose` |
-| `ProgressBar` | Labelled native progress with visual track | required `label`, `value` or `valueEmitter`, `max`, `valueText`; `null` is indeterminate |
+| `ProgressBar` | Labelled native progress with visual track | required `label`, `value` or `valueEmitter`, `max`, `valueText`; fills its available width; `null` is indeterminate; emitter-backed busy chrome (including determinate bars) requires `FetchState.Loading` |
 | `ThemePicker` | Select and replace a Capillary UI theme link | value props, `options`, `label`/`ariaLabel`, `disabled`, `targetDocument`, `onChange` |
 | `ColorPicker` | Select and replace a Capillary UI color link | same contract as `ThemePicker` |
 
@@ -738,6 +760,14 @@ component selectors. Color files provide anchors and endpoints. Component
 `static css` owns selectors, layout, pseudo-elements, native states, and
 interaction mechanics.
 
+The three chrome backgrounds (`--ui-primary-bg-color`, `--ui-medium-bg-color`,
+and `--ui-dark-bg-color`) alias muted primary surface tones derived from the
+palette's primary anchor and light endpoint. Ice blue retains the exact legacy
+colors `#f5f7f8`, `#ebeff3`, and `#d7dee3`; other palettes recolor these surfaces.
+See the [palette contract](colors/README.md#muted-primary-surfaces) for the
+relative-HSL/sRGB calibration, including the `0`–`1`
+`--palette-primary-surface-saturation` palette control and override points.
+
 Theme files provide intentional overrides. Custom properties are the primary
 instrument and belong on `:root` inside `@layer theme`, with `color-scheme` as
 the only ordinary property in that block. A theme may also write ordinary CSS
@@ -746,6 +776,11 @@ be placed after the `@layer theme` block: component CSS is injected as an
 unlayered `<style>` element prepended to `<head>`, so unlayered theme rules win
 by document order while layered ones would always lose.
 
+The built-in theme options are Capillary, Shiny, Soft, White, and Minimal.
+Capillary is a bright, compact card treatment with restrained elevation and
+palette-primary selections. Minimal is adaptive; the other options are fixed
+light treatments.
+
 `capillaryUiThemeVariableCatalog` describes the supported palette and semantic
 variable hierarchy. `findCapillaryUiStylesheetOption`, `replaceCapillaryUiStylesheet`,
 `setCapillaryUiAppearance`, and `getCapillaryUiAppearance` support application-controlled
@@ -753,10 +788,23 @@ runtime selection.
 
 ### Line-control sizing
 
-Textbox, Dropdown, Toggle, and Button use `--control-min-height: 2em` by
-default: a 24px border-box minimum at the default 12px `--ui-font-size`.
-This minimum is independent of general UI padding and the text line height.
-Their labels and native controls inherit the font family and share a unitless
+All single-line controls reserve the same vertical row space: Textbox,
+Dropdown (including theme/color pickers), Toggle, Button, checkbox variants,
+RadioButton, date/time controls, and ProgressBar. Their existing painted
+bodies remain centered within that row; small checkbox/radio shapes do not
+grow to look like text fields.
+
+`--control-min-height: 2em` sets the body minimum (24px at the default 12px
+`--ui-font-size`). The row uses the greater of that minimum and
+`--control-row-min-height` (default `0px`), plus
+`--control-row-padding-block: .25em` on each side. Default rows are therefore
+30px with 3px above and below the body. Capillary supplies a `2.75em` row
+floor (39px including padding) to accommodate its roomier chrome and native
+temporal inputs while retaining its `6px 5px` control padding. Additional
+layout `gap` is optional and adds to this built-in breathing room.
+
+These are minimum sizes: multiline/rich content can grow without clipping.
+Labels and native controls inherit the font family and share a unitless
 1.2 authored text line height. Native single-line inputs may clamp the used
 line-height to platform font metrics (notably Firefox on Linux); their bodies
 and text remain centered. Larger content can increase the minimum-sized body.
@@ -765,6 +813,29 @@ minimum-width/shrinking behavior. Field and button inline padding is 5px;
 toggle segments use 6px. General `--space-xs`/`--space-sm` no longer determine
 these line controls' padding.
 
+`OptionsBox` deliberately keeps compact descendants, including through nested
+`OptionGroup` and `Layout` wrappers: it removes the shared row floor and
+block padding while retaining each control's natural body size. Its checkbox
+and radio rows are normally 1.2em, or the theme's larger painted-shell size.
+OptionsBox owns a fixed 2px vertical option rhythm—between nested groups,
+checkboxes, and radio options—regardless of theme. Ordinary GroupBox and
+Toolbar do not opt into compact spacing. RadioGroup elsewhere adds no
+inter-option gap by default, so the same number of radio and checkbox rows
+occupies the same height (excluding any group legend). Set
+`--radio-group-gap` to add spacing explicitly outside OptionsBox.
+
+An `OptionGroup` and a labelled `RadioGroup` both produce a native
+`fieldset`/`legend`. For one mutually exclusive choice, put the `RadioGroup`
+directly in an `OptionsBox` and give it the one visible label. Use an
+`OptionGroup` for a collection of direct checkboxes (or when its legend adds a
+separate, meaningful concept around several controls). Do not wrap a single
+labelled `RadioGroup` in an `OptionGroup` merely for layout; that creates
+redundant legends and nested fieldsets.
+
+Maintained themes add chrome without text offsets. Shadows do not participate
+in centering. Toggle borders and selected overlap are painted independently
+of segment layout, so selection does not move text.
+
 Horizontal form `GroupBox` children use their natural content size: GroupBox
 does not contribute a synthetic preferred width or an artificial size floor.
 Intrinsic label/body tracks distinguish preferred field widths from the
@@ -794,14 +865,6 @@ their normal inset. In this composition, omit a `DataTable` `caption`: the
 labelled Panel header supplies the surrounding data-region name. Application
 data-surface components can opt in by declaring the same static trait.
 
-Checkbox variants and RadioButton retain compact 1.2em label rows with 1em
-squares/circles. They center within stretched horizontal hosts without making
-vertical lists as tall as text fields. Date/time controls consume the same
-shared sizing rules. Themes may deliberately override the minimum (Java does),
-but Shiny uses the structural defaults and adds chrome without text offsets.
-Shadows do not participate in centering. Toggle borders and selected overlap
-are painted independently of segment layout, so selection does not move text.
-
 ### Root sizing and typography
 
 `CapillaryUiApp` is block-level and always applies `--application-background`,
@@ -837,7 +900,7 @@ semantics.
 Applications may explicitly opt native elements into Capillary UI presentation and
 layout contracts by applying public Capillary UI traits such as `island`,
 `cap-layout-horizontal`, `cap-layout-vertical`, `cap-size-natural`,
-`cap-size-flexible`, and `cap-scroll`. These traits are intentionally
+`cap-size-flexible`, `cap-scroll`, and `cap-island-layout`. These traits are intentionally
 element-agnostic and may style application-owned native markup as well as
 Capillary UI-owned hosts.
 
@@ -893,6 +956,85 @@ provide breakpoint variants.
 native markup. Capillary UI rejects nested component islands; application markup must
 preserve the same one-layer invariant.
 
+### Composing islands without margin doubling
+
+Enable `islands` once on the app or the Layout that contains the composition:
+
+```tsx
+<CapillaryUiApp sizing="viewport" islands>
+    <Header island>Application header</Header>
+    <Layout horizontal allocation="flexible">
+        <Sidebar island header="Navigation">...</Sidebar>
+        <Layout vertical allocation="flexible">
+            <Panel island header="Overview">...</Panel>
+            <Panel island header="Results" allocation="flexible">...</Panel>
+        </Layout>
+    </Layout>
+    <footer className="island cap-size-natural">Status</footer>
+</CapillaryUiApp>
+```
+
+`islands` is a **layout mode**; `island` still marks each **surface**. The
+outermost enabled container gets one perimeter inset. Participating layouts
+then place a single shared gutter between their children, with no island
+margins to add up. Nested Layouts inherit the mode automatically, including
+through ordinary wrappers and `RouteOutlet`. Repeating `islands` on an already
+enabled nested Layout does not add another inset. An app with `islands` and no
+explicit `layout` defaults to vertical; Layout still requires an axis.
+
+The public `CapillaryUiIslandLayoutProps` contract is static `islands?: boolean`:
+
+- `true` enables managed composition;
+- omitted or `undefined` inherits the surrounding mode;
+- `false` stops inheritance and restores legacy spacing in that subtree.
+
+Surface boundaries stop managed layout gaps from reaching controls inside
+them. Panel padding, toolbar gaps, and other internal spacing keep their own
+contracts. A later explicit enabled scope below an opt-out starts a fresh
+perimeter inset. Neither this mode nor nested layouts permit nested islands.
+
+Use `--island-gap` for gutters and `--island-inset` for the outer inset. Base
+defaults both to `1rem`; White uses zero. Override these on the composition,
+and optionally `--island-gap` on a nested Layout for a local gutter.
+`--island-padding` remains the padding **inside** each surface, except a direct
+app-root header: `cap-app > header.island` and `cap-app > cap-header.island`
+have zero padding. These shell headers delegate internal spacing to their
+navbar, toolbar, and branding rows. Their border, shadow, outer inset, and
+gutter remain unchanged. Nested headers and non-island headings are unaffected;
+this rule also applies outside managed island mode. Use a native `<header
+className="island">` for a shell containing navigation/toolbars; `Header`
+remains the component for a native heading.
+
+`SplitView`
+inherits the mode and places its separator in one shared gutter; a zero gutter
+retains an overlapping drag target and keyboard resizing.
+
+Scrolling layouts automatically include surrounding gutter space in their
+scrollport, so an island's border and shadow can paint there. Equal padding
+and negative margin extend the clip by half a gutter without moving the
+surfaces or increasing their separation. Nested scrollports reuse this space;
+RouteOutlet and SplitView leave clipping to their content/panes. Themes only
+declare their ordinary borders and shadows: no clearance token is required.
+Surface contents and opt-outs retain ordinary scrolling behavior. A zero
+gutter deliberately leaves no paint space between adjacent surfaces.
+
+Native markup can use `cap-island-layout` and `cap-island-layout-off`. Combine
+them with a direction trait, or with your own `display: grid` rules. A wrapper
+around one region needs no new trait. A native wrapper arranging multiple
+regions must opt into a layout: inheritance does not turn arbitrary elements
+into flex/grid containers. Axes, dimensions, responsive wrapping, allocation,
+and scroll ownership remain explicit application choices.
+
+Migration is opt-in. Existing layouts outside managed scopes keep
+`--island-margin` and their former behavior. When enabling a scope, remove
+margin-cancellation selectors and redundant gap rules, and move any intended
+spacing override to `--island-gap`/`--island-inset` on the layout. A direct CSS
+`margin` or `gap` override still wins through the normal cascade; the framework
+does not measure or rewrite application styles. `islands={false}` can isolate
+a legacy region during incremental migration.
+
+### Semantic category color
+
 `colored` consumes an explicit `--c1`, `--c2`, `--c3` triplet for the shared
 gradient and `--colored-shadow` treatment. It does not choose semantic colors
 for the application.

package/colors/README.md

@@ -14,9 +14,13 @@ A palette supplies:
 
 - `--palette-light` and `--palette-dark` endpoints;
 - `--palette-contrast-light` and `--palette-contrast-dark` foregrounds;
-- `--palette-red` and `--palette-green` status primitives;
+- `--palette-status-negative`, `--palette-status-positive`, and
+  `--palette-status-neutral` status primitives. The last is deliberately
+  distinct from the `--palette-neutral-*` tonal ramp;
 - `--palette-primary-500`, `--palette-secondary-500`, and
   `--palette-neutral-500` anchors.
+- palette-primary-surface-saturation, a 0–1 multiplier for the three muted
+  primary chrome surfaces.
 
 `themes/base.css` derives the remaining numeric ramp stops, ordinary
 `primary`/`light`/`dark` aliases, and transparent light variants with
@@ -31,9 +35,11 @@ ramp intentionally changes hue.
     --palette-dark: #111827;
     --palette-contrast-light: #fff;
     --palette-contrast-dark: #111827;
-    --palette-red: #c62828;
-    --palette-green: #2e7d32;
+    --palette-status-negative: #c62828;
+    --palette-status-positive: #2e7d32;
+    --palette-status-neutral: #64748b;
     --palette-primary-500: #2989d8;
+    --palette-primary-surface-saturation: 1;
     --palette-secondary-500: #7137a8;
     --palette-neutral-500: #7892aa;
   }
@@ -44,6 +50,50 @@ Color files must not declare semantic roles such as `--button-*`,
 `--input-*`, or `--panel-*`. The base and active theme map derived palette
 values to those roles.
 
+## Muted primary surfaces
+
+The base also derives `--palette-primary-surface-light`,
+`--palette-primary-surface-medium`, and `--palette-primary-surface-dark` from
+`--palette-primary-500` and `--palette-light`. These are pale, desaturated
+surface tones, separate from the accent ramp: Ice blue's cyan
+`--palette-primary-light-mix` intentionally does not tint these surfaces.
+The existing `--ui-primary-bg-color`, `--ui-medium-bg-color`, and
+`--ui-dark-bg-color` variables alias them, respectively. Shiny panels, table
+headers, button gradients, and other consumers retain their existing wiring.
+
+The derivation uses relative HSL to reduce primary saturation and apply a small
+hue offset, followed by `color-mix(in srgb, ..., var(--palette-light))`. Its
+rational coefficients preserve the historical Ice blue colors exactly:
+
+| Surface | Ice blue sRGB | Hue offset | Saturation multiplier | Primary tint weight |
+| --- | --- | --- | --- | --- |
+| light | `#f5f7f8` | `-248/35` degrees | `759/2975` | `17/253` |
+| medium | `#ebeff3` | `102/35` degrees | `253/700` | `32/253` |
+| dark | `#d7dee3` | `-73/35` degrees | `759/2975` | `68/253` |
+
+These are calibration ratios, not arbitrary rounded percentages: the reference
+primary `#2989d8` has HSL hue `7248/35`, saturation `17500/253` percent, and
+lightness `12850/255` percent. The three legacy targets have different hues
+and saturations, so one white/primary ramp cannot reproduce all three. The
+same calibrated recipe runs for every palette; there is no Ice blue override.
+Changing the primary anchor or light endpoint recomputes all three surfaces.
+Applications may still override the surface tokens or existing UI aliases.
+
+`--palette-primary-surface-saturation` controls how much primary hue the three
+surfaces retain. It is a palette number from `0` through `1`: `1` is the
+calibrated default (and preserves Ice blue exactly), `0.5` halves the primary
+saturation, and `0` makes all three surfaces completely neutral. It affects
+only these muted surfaces, never the primary accent ramp or component semantic
+roles that use it.
+
+Shiny's chrome and progress-track gradients explicitly interpolate in sRGB,
+preserving their legacy appearance when stops become derived `color()` values.
+Custom gradients that need the same legacy interpolation should likewise declare
+`in srgb` instead of relying on the browser's choice of interpolation space.
+
+This derivation requires relative HSL colors and `color-mix()`, verified in
+the package's Chromium, Firefox, and WebKit browser matrix.
+
 ## Loading and replacement
 
 Load one palette after Capillary UI's base and structural CSS and before the active

package/colors/gray/colors.css

@@ -6,10 +6,12 @@
       --palette-dark: #111827;
       --palette-contrast-light: var(--palette-light);
       --palette-contrast-dark: var(--palette-dark);
-      --palette-red: #b3261e;
-      --palette-green: #287a3c;
+      --palette-status-negative: #b3261e;
+      --palette-status-positive: #287a3c;
+      --palette-status-neutral: #64748b;
 
       --palette-primary-500: #5d6873;
+      --palette-primary-surface-saturation: 1;
       --palette-secondary-500: #1769aa;
       --palette-neutral-500: #858d95;
   }

package/colors/green/colors.css

@@ -6,10 +6,12 @@
       --palette-dark: #111827;
       --palette-contrast-light: var(--palette-light);
       --palette-contrast-dark: var(--palette-dark);
-      --palette-red: #b3261e;
-      --palette-green: #287a3c;
+      --palette-status-negative: #b3261e;
+      --palette-status-positive: #287a3c;
+      --palette-status-neutral: #64748b;
 
       --palette-primary-500: #287a3c;
+      --palette-primary-surface-saturation: 1;
       --palette-secondary-500: #087f78;
       --palette-neutral-500: #75947a;
   }

package/colors/iceblue/colors.css

@@ -6,13 +6,15 @@
       --palette-dark: #111827;
       --palette-contrast-light: var(--palette-light);
       --palette-contrast-dark: var(--palette-dark);
-      --palette-red: #b3261e;
-      --palette-green: #287a3c;
+      --palette-status-negative: #b3261e;
+      --palette-status-positive: #287a3c;
+      --palette-status-neutral: #64748b;
 
       /* Preserve the legacy Shiny movement from navy through blue to cyan. */
       --palette-primary-light-mix: #00b9e8;
       --palette-primary-dark-mix: #00193f;
       --palette-primary-500: #2989d8;
+      --palette-primary-surface-saturation: 1;
       --palette-secondary-500: #7137a8;
       --palette-neutral-500: #7892aa;
   }

package/colors/ocean/colors.css

@@ -6,10 +6,12 @@
       --palette-dark: #111827;
       --palette-contrast-light: var(--palette-light);
       --palette-contrast-dark: var(--palette-dark);
-      --palette-red: #b3261e;
-      --palette-green: #287a3c;
+      --palette-status-negative: #b3261e;
+      --palette-status-positive: #287a3c;
+      --palette-status-neutral: #64748b;
 
       --palette-primary-500: #087f78;
+      --palette-primary-surface-saturation: 1;
       --palette-secondary-500: #1769aa;
       --palette-neutral-500: #668f8a;
   }

package/colors/orange/colors.css

@@ -6,10 +6,12 @@
       --palette-dark: #111827;
       --palette-contrast-light: var(--palette-light);
       --palette-contrast-dark: var(--palette-dark);
-      --palette-red: #b3261e;
-      --palette-green: #287a3c;
+      --palette-status-negative: #b3261e;
+      --palette-status-positive: #287a3c;
+      --palette-status-neutral: #64748b;
 
       --palette-primary-500: #a94b00;
+      --palette-primary-surface-saturation: 1;
       --palette-secondary-500: #7137a8;
       --palette-neutral-500: #a87a56;
   }

package/colors/purple/colors.css

@@ -6,10 +6,12 @@
       --palette-dark: #111827;
       --palette-contrast-light: var(--palette-light);
       --palette-contrast-dark: var(--palette-dark);
-      --palette-red: #b3261e;
-      --palette-green: #287a3c;
+      --palette-status-negative: #b3261e;
+      --palette-status-positive: #287a3c;
+      --palette-status-neutral: #64748b;
 
       --palette-primary-500: #7137a8;
+      --palette-primary-surface-saturation: 1;
       --palette-secondary-500: #1769aa;
       --palette-neutral-500: #9273a2;
   }