@malva-ui/core 0.1.12 → 0.1.14

package/AGENTS.md

@@ -52,6 +52,7 @@ import { MlvInput } from '@malva-ui/core/input';
 | filter | `@malva-ui/core/filter` | `@malva-ui/core/filter` provides a compact field filter and a metadata-driven Smart Filter Bar. [Details](docs/ai/filter.md) |
 | form | `@malva-ui/core/form` | `@malva-ui/core/form` is the **layout** layer for forms. [Details](docs/ai/form.md) |
 | form-utils | `@malva-ui/core/form-utils` | The Form Utils library provides foundational building blocks for accessible, state-aware forms. [Details](docs/ai/form-utils.md) |
+| icon-toggle | `@malva-ui/core/icon-toggle` | `@malva-ui/core/icon-toggle` provides a **chromeless, glyph-only** WAI-ARIA. [Details](docs/ai/icon-toggle.md) |
 | input | `@malva-ui/core/input` | The Input library provides a fully accessible, state-aware text input component that integrates with Angular signal, reactive, and template-driven forms. [Details](docs/ai/input.md) |
 | kbd | `@malva-ui/core/kbd` | The Kbd library provides a purely presentational `mlv-kbd` component that renders keyboard shortcuts as styled `<kbd>` HTML elements. [Details](docs/ai/kbd.md) |
 | layout | `@malva-ui/core/layout` | The Layout library provides a responsive application. [Details](docs/ai/layout.md) |
@@ -79,9 +80,10 @@ import { MlvInput } from '@malva-ui/core/input';
 | status-indicator | `@malva-ui/core/status-indicator` | `@malva-ui/core/status-indicator` provides a small circular **status dot**. [Details](docs/ai/status-indicator.md) |
 | stepper | `@malva-ui/core/stepper` | `@malva-ui/core/stepper` provides a multi-step workflow UI with a stepper header and managed content panels. [Details](docs/ai/stepper.md) |
 | switch | `@malva-ui/core/switch` | The Switch library provides accessible toggle switch components implementing the WAI-ARIA switch pattern. [Details](docs/ai/switch.md) |
+| table | `@malva-ui/core/table` | @malva-ui/core/table [Details](docs/ai/table.md) |
 | tabs | `@malva-ui/core/tabs` | `@malva-ui/core/tabs` provides a full-featured, accessible tab group component for the Malva UI design system. [Details](docs/ai/tabs.md) |
 | textarea | `@malva-ui/core/textarea` | `@malva-ui/core/textarea` provides a multi-line text input form control. [Details](docs/ai/textarea.md) |
-| tile | `@malva-ui/core/tile` | The Tile library provides a card-like container component for displaying information in a structured, elevated panel. [Details](docs/ai/tile.md) |
+| tile | `@malva-ui/core/tile` | The Tile library provides a compact outlined surface for standalone status and summary content plus a compound, immutable tree for nested drag-and-drop layouts. [Details](docs/ai/tile.md) |
 | time-picker | `@malva-ui/core/time-picker` | The Time Picker library provides a popup-based drum-roll style time selection component. [Details](docs/ai/time-picker.md) |
 | timeline | `@malva-ui/core/timeline` | `@malva-ui/core/timeline` provides a vertical timeline component for visualising ordered sequences of events. [Details](docs/ai/timeline.md) |
 | title | `@malva-ui/core/title` | The Title library provides an inline heading-typography component that decorates the host element itself through the `[mlvTitle]` selector. [Details](docs/ai/title.md) |
@@ -90,3 +92,4 @@ import { MlvInput } from '@malva-ui/core/input';
 | toolbar | `@malva-ui/core/toolbar` | The Toolbar library provides simple, composable components for building horizontal toolbars and action bars. [Details](docs/ai/toolbar.md) |
 | tooltip | `@malva-ui/core/tooltip` | The Tooltip library provides a lightweight, accessible tooltip that appears on hover and focus. [Details](docs/ai/tooltip.md) |
 | tree | `@malva-ui/core/tree` | The Tree library provides a hierarchical data tree component for displaying nested data. [Details](docs/ai/tree.md) |
+| view-variant | `@malva-ui/core/view-variant` | `@malva-ui/core/view-variant` provides controlled, generic saved-view. [Details](docs/ai/view-variant.md) |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Malva UI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,12 @@
 # @malva-ui/core
 
-Malva UI's grouped Angular component package. Components are available from
-secondary entry points such as `@malva-ui/core/button`,
-`@malva-ui/core/dialog`, and `@malva-ui/core/data-table`.
+A production-grade Angular component library — 68 components, light/dark theming, five density levels, 14 locales, and WCAG 2.1 AA accessibility verified with axe.
+
+Every component is standalone, `OnPush`, and signal-based throughout, styled with BEM against `--mlv-*` design tokens you can override.
+
+```html
+<button mlvButton>Save</button>
+```
 
 ## Install
 
@@ -52,10 +56,72 @@ If styles or providers are managed elsewhere, disable those steps with
 
 ## Use a component
 
+Each component has its own entry point, so you only bundle what you import:
+
 ```ts
 import { MlvButton } from '@malva-ui/core/button';
+import { MlvDialogService } from '@malva-ui/core/dialog';
+import { MlvInput } from '@malva-ui/core/input';
 ```
 
 ```html
 <button mlvButton>Save</button>
 ```
+
+## Components
+
+**Forms** — `button` · `input` · `textarea` · `select` · `combobox` · `autocomplete` · `checkbox` · `radio` · `switch` · `slider` · `rating` · `number-input` · `pin-input` · `file-upload` · `color-picker` · `tokenizer` · `search-field` · `segmented` · `form` · `form-utils`
+
+**Dates** — `calendar` · `day-picker` · `date-range-picker` · `time-picker`
+
+**Data** — `data-table` · `tree` · `pagination` · `filter` · `list` · `timeline`
+
+**Overlays** — `dialog` · `drawer` · `popup` · `menu` · `tooltip` · `toast` · `notification` · `dropdown`
+
+**Navigation** — `sidebar` · `tabs` · `breadcrumb` · `stepper` · `bottom-nav` · `action-bar` · `link` · `page`
+
+**Layout** — `layout` · `card` · `tile` · `accordion` · `expand` · `split-pane` · `divider` · `toolbar` · `scrollbar`
+
+**Display** — `avatar` · `avatar-group` · `badge` · `chip` · `alert` · `progress` · `loader` · `skeleton` · `empty-state` · `status-indicator` · `kbd` · `title` · `chat` · `copy-to-clipboard`
+
+## Theming
+
+Components read `--mlv-*` custom properties, so a theme is a stylesheet override — no build step, no SCSS fork:
+
+```css
+:root {
+  --mlv-background-accent-1: #6d28d9;
+  --mlv-radius-button: 0.75rem;
+}
+```
+
+Light and dark ship out of the box via `provideDefaultTheme()`; density (`tight` → `airy`) is switched per-tree with `mlvDensity` or globally with `provideMlvDensity()`.
+
+## Zoneless and SSR
+
+Every component is `OnPush` and signal-based, so the library runs under
+`provideZonelessChangeDetection()` with `zone.js` removed:
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideZonelessChangeDetection(), provideDefaultTheme()],
+});
+```
+
+Components are also safe to server-render — measurement, observers and
+document-level listeners stay behind platform guards, and overlays are never
+constructed during SSR. Both are covered by tests, not just intent.
+
+## Peer dependencies
+
+`@angular/aria`, `@angular/cdk`, `@angular/common`, `@angular/core`, `@angular/forms`, `@lucide/angular`, `rxjs`, plus the companion packages `@malva-ui/cdk` and `@malva-ui/i18n` (both added by `ng add`).
+
+## Related packages
+
+- [`@malva-ui/cdk`](https://www.npmjs.com/package/@malva-ui/cdk) — headless primitives (overlay, density, data-source)
+- [`@malva-ui/i18n`](https://www.npmjs.com/package/@malva-ui/i18n) — localisation, 14 locales
+- [`@malva-ui/editor`](https://www.npmjs.com/package/@malva-ui/editor) — Tiptap-based rich-text editor
+
+## License
+
+MIT

package/docs/ai/avatar.md

@@ -100,6 +100,8 @@ host: {
 
 Converts a string to a deterministic `hsl(...)` CSS color by hashing the characters into a hue value (0–360). Saturation ~60% and lightness ~80% are fixed for pleasant, accessible results.
 
+Hue is the only thing the name controls; the pale-tint band is deliberate (AB-R6 of the 2026-08 visual language spec) because `avatar.scss` renders the initials in the dark `--mlv-palette-neutral-800`. Empty / `null` / `undefined` input returns `'hsl(210,60%,80%)'` — inside the same band, so a nameless avatar keeps AA-legible initials.
+
 ```html
 <mlv-avatar [name]="user.name" [color]="user.name | mlvColorFromText" />
 ```

package/docs/ai/breadcrumb.md

@@ -48,19 +48,21 @@ There is **no `separator` input**. The separator is a projected template:
 
 #### Inputs
 
-| Name         | Type                         | Default | Description                                                                           |
-| ------------ | ---------------------------- | ------- | ------------------------------------------------------------------------------------- |
-| `routerLink` | `string \| string[] \| null` | `null`  | Angular router link for navigation.                                                   |
-| `href`       | `string \| null`             | `null`  | Raw href for anchor navigation.                                                       |
-| `current`    | `BooleanInput`               | `false` | Marks item as current page; renders as `<span>` with `aria-current="page"`.           |
-| `disabled`   | `BooleanInput`               | `false` | Disables navigation; renders as plain `<span>` with `mlv-breadcrumb__link--disabled`. |
+| Name         | Type                         | Default | Description                                                                                                                                                                                           |
+| ------------ | ---------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `routerLink` | `string \| string[] \| null` | `null`  | Angular router link for navigation.                                                                                                                                                                   |
+| `href`       | `string \| null`             | `null`  | Raw href for anchor navigation.                                                                                                                                                                       |
+| `current`    | `BooleanInput`               | `false` | Marks item as current page; renders as `<span>` with `aria-current="page"`.                                                                                                                           |
+| `disabled`   | `BooleanInput`               | `false` | Marks a destination that exists but is **switched off** for this user; renders as a `<span>` with `mlv-breadcrumb__link--disabled`. Not for link-less ancestors — see _Non-interactive crumb states_. |
 
 #### Host
 
 | Attribute | Value                  |
 | --------- | ---------------------- |
 | `class`   | `mlv-breadcrumb__item` |
-| `role`    | `listitem`             |
+
+The host deliberately claims **no** `role` — see the _Known axe exception_ note
+under Accessibility.
 
 ---
 
@@ -75,6 +77,11 @@ interface MlvBreadcrumbEntry {
 }
 ```
 
+`disabled` means a destination that exists but is currently unavailable to this
+user. An ancestor step that simply has nowhere to navigate to is **not**
+disabled — omit `routerLink`, `href` and `disabled`, and it renders as a plain
+crumb. See _Non-interactive crumb states_.
+
 ---
 
 ## CSS Classes
@@ -86,12 +93,59 @@ interface MlvBreadcrumbEntry {
 | `.mlv-breadcrumb__item`           | Each `<li>` breadcrumb item                        |
 | `.mlv-breadcrumb__link`           | Link or span inside each item                      |
 | `.mlv-breadcrumb__link--current`  | Applied to the current/last item (non-interactive) |
+| `.mlv-breadcrumb__link--plain`    | Applied to a link-less, non-current ancestor crumb |
 | `.mlv-breadcrumb__link--disabled` | Applied to disabled items                          |
 | `.mlv-breadcrumb__separator`      | Separator between items                            |
 | `.mlv-breadcrumb__ellipsis`       | Ellipsis shown during overflow truncation          |
 
 ---
 
+## Non-interactive crumb states
+
+Three states render as text rather than a link, and they are **not**
+interchangeable:
+
+| State    | How to express it                                   | Class                             | Meaning                                                      |
+| -------- | --------------------------------------------------- | --------------------------------- | ------------------------------------------------------------ |
+| current  | last `items` entry, or `[current]="true"`           | `.mlv-breadcrumb__link--current`  | The page being viewed. Carries `aria-current="page"`.        |
+| plain    | omit `routerLink`, `href`, `current` and `disabled` | `.mlv-breadcrumb__link--plain`    | A grouping ancestor with nowhere to navigate to.             |
+| disabled | `disabled: true` / `[disabled]="true"`              | `.mlv-breadcrumb__link--disabled` | A destination that exists but is switched off for this user. |
+
+A plain crumb is deliberately **not** styled as a link: it reads
+`--mlv-text-secondary` with no hover underline and no accent colour, because an
+accent-coloured, underlining crumb promises a navigation that never happens.
+
+Reaching for `disabled` to express a plain ancestor is the common misuse — it
+tells assistive technology the step was switched off, and opts the crumb into
+the disabled colour ramp.
+
+---
+
+## Styling contract
+
+| Custom property                   | Default                     | Notes                                                                            |
+| --------------------------------- | --------------------------- | -------------------------------------------------------------------------------- |
+| `--mlv-breadcrumb-disabled-color` | `var(--mlv-text-secondary)` | Foreground of `--disabled` crumbs, in the trail and in the overflow popup alike. |
+
+Two colour choices are load-bearing for WCAG 2.1 AA and are guarded by
+
+- **The separator reads `--mlv-text-secondary`, not `--mlv-text-tertiary`.** It
+  is a non-text UI element and owes 3:1. Tertiary clears that only in dark
+  (3.78:1) and fails in light (2.42:1 on `--mlv-background-base`); secondary
+  clears it in both (7.49:1 light / 12.09:1 dark).
+- **Disabled crumbs do not read `--mlv-text-disabled`.** That global ramp sits
+  at 1.42:1 in light and 2.29:1 in dark against `--mlv-background-base` —
+  technically exempt from the contrast minimum as an inactive control, but
+  unreadable in a navigation trail. `--mlv-breadcrumb-disabled-color` is the
+  escape hatch for an application that deliberately wants the fainter ramp back.
+
+The overflow popup is portaled to the CDK overlay container, outside this
+block's DOM subtree, so `--mlv-breadcrumb-disabled-color` cannot cascade into
+it — `.mlv-breadcrumb__overflow-link--disabled` repeats the accessible default
+as a `var()` fallback.
+
+---
+
 ## Accessibility
 
 - `<nav>` host uses native landmark semantics
@@ -99,6 +153,8 @@ interface MlvBreadcrumbEntry {
 - Last/current item has `aria-current="page"`
 - Separators are `aria-hidden="true"` by default
 - Disabled items are non-interactive `<span>` elements
+- Link-less ancestor crumbs render as plain `<span>` elements with no link affordance — see _Non-interactive crumb states_
+- Every crumb part clears WCAG 2.1 AA in both themes — see _Styling contract_
 - All interactive links have `:focus-visible` outline using `--mlv-border-focus`
 - Uses semantic `<ol>` + `<li>` list structure in **data-driven** mode
 - Overflow popover focuses the first hidden link when opened
@@ -140,6 +196,10 @@ interface MlvBreadcrumbEntry {
   <mlv-breadcrumb-item [current]="true">Widget Pro</mlv-breadcrumb-item>
 </nav>
 
+<!-- Grouping ancestors with nowhere to navigate to: omit href/routerLink,
+     do NOT use `disabled` -->
+<nav mlvBreadcrumb [items]="[{ label: 'Settings' }, { label: 'Personal' }, { label: 'Profile' }]"></nav>
+
 <!-- Projected items with href -->
 <nav mlvBreadcrumb separator="→">
   <mlv-breadcrumb-item href="/">Home</mlv-breadcrumb-item>

package/docs/ai/button.md

@@ -46,6 +46,7 @@ Exported from `@malva-ui/core/button`:
 | `shape`    | `MlvButtonShape`                | `'default'` | Shape variant; `pill` keeps content width with a fully rounded stadium radius (`--mlv-radius-full`), matching the pill action bar and pill form controls |
 | `disabled` | `BooleanInput`                  | `false`     | Disables the button; coerced to boolean                                                                                                                  |
 | `loading`  | `BooleanInput`                  | `false`     | Shows a spinner, exposes busy state, and prevents duplicate activation                                                                                   |
+| `selected` | `BooleanInput`                  | `false`     | Paints the pressed surface with no ARIA of its own — for a menu button reflecting an active state (see **Pressed state** below)                          |
 
 #### Content Children (protected)
 
@@ -69,10 +70,18 @@ host: {
 }
 ```
 
-> **Outlined / transparent label colour** — these two variants set
-> `--mlv-btn-text-color: var(--mlv-text-action)` (theme-aware: primary-600 in
-> light, primary-400 in dark). A previously hardcoded `primary-500` was not
-> theme-aware and failed WCAG AA contrast (3.59:1) on dark surfaces.
+> **Outlined vs. transparent label colour (AB-R1)** — `outlined` keeps the
+> accent label (`--mlv-btn-text-color: var(--mlv-text-action)`): a bordered
+> button is a call to action, not a routine per-row glyph. `transparent`
+> instead resolves `--mlv-text-secondary` at rest, stepping to
+> `--mlv-text-primary` on hover — a bare glyph (the row's configure/add/
+> remove/reorder cluster, and per AB-R3 its destructive members too) is
+> neutral chrome, never an accent mark, so a repeated unit never spends more
+> than one accent-carrying mark. Both variants keep
+> `--mlv-btn-bg-hover: var(--mlv-background-neutral-1-hover)` /
+> `-active: var(--mlv-background-neutral-1-active)` on `transparent`, and
+> `--mlv-background-accent-1-pale` / `--mlv-background-neutral-1-active` on
+> `outlined`.
 
 #### Template Structure (`button.html`)
 
@@ -97,7 +106,7 @@ for changing the action label when a more specific in-progress label is useful.
 
 - Base: `display: inline-flex; align-items: center; gap: 0.25rem`
 - `appearance: none; cursor: pointer; transition: 0.2s`
-- Focus: 2px outline via `--mlv-focus-ring-color`
+- Focus: Form A — `outline: var(--mlv-stroke-width-medium) solid transparent;` at rest, coloured `var(--mlv-border-focus)` (or a variant's own `focus-outline`) on `:focus-visible`, offset `var(--mlv-focus-ring-offset)` (SF-R3)
 - Size presets (padding, height, font scale):
   - `xs`: xs padding, xs height, body-xs font
   - `s`: s padding, s height, body-s font
@@ -108,28 +117,73 @@ for changing the action label when a more specific in-progress label is useful.
   - `primary`: `accent-1` background
   - `secondary`: `neutral-1` background
   - `accent`: `accent-2` background
-  - `transparent`: no background, neutral hover
-  - `outlined`: transparent with border
+  - `transparent`: no background, neutral `--mlv-text-secondary` label, neutral hover (AB-R1)
+  - `outlined`: transparent with border, accent label kept
 - Shape styles:
   - `default`: standard rectangular with radius
   - `square`: `padding: 0.25rem; width = height`
-  - `circle`: `border-radius: 100%`
-- Disabled: `opacity` reduced, `cursor: not-allowed`, `pointer-events: none`
+  - `circle`: `border-radius: var(--mlv-radius-full)`
+- Disabled (SF-R4): a declared surface, not an opacity multiply — `--mlv-background-disabled` fill (transparent for `transparent`/`outlined`) + `--mlv-text-disabled` label; `cursor: not-allowed`, `pointer-events: none`
 - Loading: current-colour `MlvLoader`, wait cursor, blocked pointer interaction, and inherited reduced-motion support
-- Pressed: `[aria-pressed='true']` fills with `--mlv-btn-bg-active` and adds a `--mlv-stroke-width` inset `--mlv-border-normal` ring
+- Pressed (SF-R1): `[aria-pressed='true']` fills with `--mlv-background-selected` / `-hover` + `--mlv-text-on-selected` label, plus a `--mlv-stroke-width` inset `--mlv-border-normal` ring — never the pressed/`-active` fill, which means "the pointer is down right now"
+
+**Canonical emission order (AB-R3).** The filled-variant loop and
+`--variant-transparent`/`--variant-outlined` are plain single-class
+selectors — specificity `(0,1,0)` — so both state selectors below always
+outrank them regardless of source order. `[aria-pressed='true']` is
+class+attribute (`(0,2,0)`). `--disabled` is deliberately emitted as a
+doubled class (`&#{&}--disabled`, i.e. `.mlv-button.mlv-button--disabled`)
+to match that same `(0,2,0)` specificity — a plain `&--disabled` is only
+`(0,1,0)` and silently loses the specificity contest to `[aria-pressed]`
+regardless of source order, which is exactly the bug this doubling fixes (a
+disabled+pressed control — e.g. a disabled time-picker AM/PM button or
+calendar month/year button — previously rendered as enabled-and-selected).
+With both at `(0,2,0)`, source order decides, so disabled must stay
+emitted **after** pressed. Emitted in this order, after the density blocks
+and `&__*` parts: 1) base `:hover`/`:active`, 2) the filled-variant `@each`
+loop, 3) `--variant-transparent`/`--variant-outlined` (AB-R1), 4)
+`[aria-pressed='true']` (SF-R1 — outranks variant), 5) `--disabled` + its
+two variant qualifiers (SF-R4 — outranks everything, including pressed, via
+both the specificity tie and source order), 6) `--loading`, then the shape
+modifiers.
 
 > **Pressed state** — any `button[mlvButton]` carrying `aria-pressed="true"`
-> gets the visible treatment, not just `mlv-button-toggle`. Toggles that render
+> **or the `selected` input** gets the visible treatment, not just
+> `mlv-button-toggle`. The two share one rule: `selected` renders
+> `.mlv-button--selected` (doubled to `(0,2,0)` so it matches the attribute
+> half's specificity and cannot lose to `--variant-transparent:hover`) and adds
+> no ARIA. It exists for a **menu** button that reflects an active state — the
+> editor's heading trigger while the caret sits in an H2 — which must not claim
+> the toggle-button pattern on top of `aria-haspopup`/`aria-expanded`; its state
+> reaches assistive technology through the level-bearing accessible name
+> instead. A real toggle sets `aria-pressed` and paints identically. Toggles that render
 > the attribute on a plain `mlvButton` — every editor toolbar command button —
 > previously announced their state to assistive technology while looking
-> identical to an inactive control. The rule pins `--mlv-btn-bg-hover` as well,
-> because `.mlv-button:hover` has the same specificity and would otherwise
-> decide the background by Sass emission order. It writes
-> `--mlv-btn-box-shadow` rather than `box-shadow`, keeping the base
-> `box-shadow: var(--mlv-btn-box-shadow, none)` the single place the property
-> is set. `--mlv-background-neutral-1-active` backs it in both themes, so a
-> pressed control reads against light and dark toolbar surfaces alike.
-> targeting and all three declarations.
+> identical to an inactive control. The rule pins `--mlv-btn-bg-hover` **and**
+> `--mlv-btn-text-color` as well, because `.mlv-button:hover` and
+> `.mlv-button--variant-transparent:hover` carry the same `(0,2,0)`
+> specificity and would otherwise decide the background/label by Sass
+> emission order. It writes `--mlv-btn-box-shadow` rather than `box-shadow`,
+> keeping the base `box-shadow: var(--mlv-btn-box-shadow, none)` the single
+> place the property is set. `--mlv-background-selected` / `-hover` back it
+> in both themes (SF-R1), so a pressed control reads as a persistent
+> selection, not a mouse-down affordance, against light and dark toolbar
+> pins the selector's targeting and all three declarations.
+>
+> **Disabled state (SF-R4)** — `&#{&}--disabled` (doubled class,
+> `.mlv-button.mlv-button--disabled`, specificity `(0,2,0)`) sits **last** in
+> the canonical emission order (after `[aria-pressed='true']`), so a disabled
+> control never shows a pressed fill. The doubling matters: a plain
+> `&--disabled` is only `(0,1,0)` and loses to `[aria-pressed='true']`'s
+> against real cascade resolution via `getComputedStyle`, not just rule
+> declarations in isolation. It sets `--mlv-btn-bg`/`-hover`/`-active` to the new
+> `--mlv-background-disabled` token and `--mlv-btn-text-color` to
+> `--mlv-text-disabled` — a declared pale surface with legible ink, not the
+> old `opacity: var(--mlv-disabled-opacity)` multiply, which produced white
+> text on a washed-out accent composite at ~1.9:1 contrast. Two qualifiers
+> keep `transparent`/`outlined` disabled buttons background-free
+> (`--variant-outlined.--disabled` also mutes its border to
+> `--mlv-border-subtle`).
 
 > **Icon-only inference & the shape-aware default variant** — see
 > [docs/migrations/2026-08-button-icon-only-default-variant.md](../../docs/migrations/2026-08-button-icon-only-default-variant.md).
@@ -158,6 +212,7 @@ The public `effectiveVariant` computed signal resolves the local `variant`, the
 - Applies `ariaLabel` to the inner native button; the role-less custom-element host is not an accessible-name target
 - For the transparent variant, uses `--mlv-text-secondary` at rest and `--mlv-text-primary` on hover/active, adapting automatically to light and dark themes
 - Retains regular button background, focus, active, and motion behavior
+- Glyph size uses a component-local `--mlv-button-close-icon-ratio: 0.6` (vs. the shared `--mlv-icon-in-container-ratio: 0.45` every other icon-only button uses), applied through a `.mlv-button--close.mlv-button--icon-only` override that outranks the base rule regardless of stylesheet order. `mlv-button-close` is most often seen at `compact` density or smaller (dialog/drawer headers, tile, inline clear affordances), where the shared 0.45 ratio rendered an illegibly small X (~12.6px at compact); 0.6 raises it to ~16.8px without touching the shared token or any other icon-only button
 - Pins its own `:focus-visible` ring (`.mlv-button--close.mlv-button:focus-visible { outline-color: var(--mlv-border-focus) }`). The base `.mlv-button` neutralises the UA outline and only the per-variant rules restore a colour, so the close button previously depended entirely on the variant it happened to render with; the qualified selector also outranks those equally specific variant rules regardless of stylesheet order. Width/offset stay on the shared base so the ring matches every other button.
 
 ### `MlvButtonGroup`

package/docs/ai/card.md

@@ -35,7 +35,7 @@ Exported from `@malva-ui/core/card`:
 
 | Name              | Type                | Default  | Description                                                                                                                |
 | ----------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `size`            | `MlvCardSize`       | `'m'`    | Size preset controlling padding, radius, typography                                                                        |
+| `size`            | `MlvCardSize`       | `'m'`    | Size preset controlling padding and typography (radius is fixed — see Size Presets below)                                  |
 | `elevated`        | `BooleanInput`      | `false`  | Larger shadow + hover lift effect                                                                                          |
 | `backgroundImage` | `string \| null`    | `null`   | URL for a background image; sets the `--mlv-card-bg-image` CSS variable                                                    |
 | `bodyLayout`      | `MlvCardBodyLayout` | `'none'` | `'stack'` turns `.mlv-card__body` into a vertical flex stack separated by `--mlv-card-body-gap`; `'none'` is a plain block |
@@ -81,11 +81,13 @@ host: {
 
 #### Size Presets
 
-| Size | Padding     | Radius       | Heading font    | Subheading     | Gap       |
-| ---- | ----------- | ------------ | --------------- | -------------- | --------- |
-| `s`  | `spacing-3` | `radius-xl`  | `font-size-xl`  | `font-size-s`  | Inherited |
-| `m`  | `spacing-5` | `radius-2xl` | `font-size-3xl` | `font-size-l`  | Inherited |
-| `l`  | `spacing-8` | `radius-3xl` | `font-size-4xl` | `font-size-xl` | Inherited |
+Radius is fixed at `--mlv-card-radius: var(--mlv-radius-card)` (→ `--mlv-radius-xl`, 12px) for every size — the per-size radius step (`s`→`xl`, `m`→`2xl`, `l`→`3xl`) was removed per RR-R2 (no per-density/per-size radius overrides; a card role has one radius).
+
+| Size | Padding     | Heading font    | Subheading     | Gap       |
+| ---- | ----------- | --------------- | -------------- | --------- |
+| `s`  | `spacing-3` | `font-size-xl`  | `font-size-s`  | Inherited |
+| `m`  | `spacing-5` | `font-size-3xl` | `font-size-l`  | Inherited |
+| `l`  | `spacing-8` | `font-size-4xl` | `font-size-xl` | Inherited |
 
 #### Styles Summary (`card.scss`)
 

package/docs/ai/chat.md

@@ -5,27 +5,27 @@
 
 Data-driven chat surface. `mlv-chat` renders an oldest→newest `messages` array as author groups with date separators, delivery ticks, embedded reply quotes, an image/gif/video grid, audio playback, a typing indicator, loading skeletons, appear/removal animations, and reverse infinite pagination. Grouping and date insertion are computed internally — consumers only supply flat data.
 
-**Naming:** the bubble component is `MlvChatMessage`; the message *data* interface is **`MlvChatMessageData`**. The `mlv-message` selector and `.mlv-message` BEM block are already owned by `MlvMessage` in `@malva-ui/core/form-utils`, which is why the lib is `chat` (not `message`) and every selector is `mlv-chat-*`.
+**Naming:** the bubble component is `MlvChatMessage`; the message _data_ interface is **`MlvChatMessageData`**. The `mlv-message` selector and `.mlv-message` BEM block are already owned by `MlvMessage` in `@malva-ui/core/form-utils`, which is why the lib is `chat` (not `message`) and every selector is `mlv-chat-*`.
 
 ---
 
 ## Public API
 
-| Export                                             | Kind                  | Description                                                          |
-| -------------------------------------------------- | --------------------- | -------------------------------------------------------------------- |
-| `MlvChat`                                          | Component             | `mlv-chat` — scroll container and renderer                           |
-| `MlvChatMessage`                                   | Component             | `mlv-chat-message` — one bubble; rendered internally, usable alone   |
-| `MlvChatMessageDef`                                | Structural directive  | `[mlvChatMessageDef]` — custom bubble body per message `type`        |
-| `MlvChatAuthorDef`                                 | Structural directive  | `[mlvChatAuthorDef]` — custom author slot above other-authored groups |
-| `MlvChatDateDef`                                   | Structural directive  | `[mlvChatDateDef]` — custom date separator                           |
-| `MlvChatMessageData<TData>`                        | Interface             | One message                                                          |
-| `MlvChatUser`, `MlvChatAttachment`                 | Interfaces            | Participant / attachment                                             |
-| `MlvChatMessageStatus`, `MlvChatGroupPosition`     | Types                 | `'sending' \| 'sent' \| 'delivered' \| 'read' \| 'failed'`; `'single' \| 'first' \| 'middle' \| 'last'` |
-| `MlvChatRenderItem`, `MlvChatRenderMessage`        | Types                 | Output of `buildChatRenderList`                                      |
-| `MlvChatMessageDefContext`, `MlvChatMessageDefRef` | Interfaces            | Template context / registered def                                    |
-| `MlvChatAuthorDefContext`, `MlvChatDateDefContext` | Interfaces            | Template contexts                                                    |
-| `MLV_CHAT_USERS`, `MLV_CHAT_MESSAGE_DEFS`          | Injection tokens      | Container→bubble wiring                                              |
-| `buildChatRenderList`, `toChatDate`, `isSameChatDay`, `formatChatDuration` | Functions | Pure helpers (also used by the internals)                  |
+| Export                                                                     | Kind                 | Description                                                                                             |
+| -------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------- |
+| `MlvChat`                                                                  | Component            | `mlv-chat` — scroll container and renderer                                                              |
+| `MlvChatMessage`                                                           | Component            | `mlv-chat-message` — one bubble; rendered internally, usable alone                                      |
+| `MlvChatMessageDef`                                                        | Structural directive | `[mlvChatMessageDef]` — custom bubble body per message `type`                                           |
+| `MlvChatAuthorDef`                                                         | Structural directive | `[mlvChatAuthorDef]` — custom author slot above other-authored groups                                   |
+| `MlvChatDateDef`                                                           | Structural directive | `[mlvChatDateDef]` — custom date separator                                                              |
+| `MlvChatMessageData<TData>`                                                | Interface            | One message                                                                                             |
+| `MlvChatUser`, `MlvChatAttachment`                                         | Interfaces           | Participant / attachment                                                                                |
+| `MlvChatMessageStatus`, `MlvChatGroupPosition`                             | Types                | `'sending' \| 'sent' \| 'delivered' \| 'read' \| 'failed'`; `'single' \| 'first' \| 'middle' \| 'last'` |
+| `MlvChatRenderItem`, `MlvChatRenderMessage`                                | Types                | Output of `buildChatRenderList`                                                                         |
+| `MlvChatMessageDefContext`, `MlvChatMessageDefRef`                         | Interfaces           | Template context / registered def                                                                       |
+| `MlvChatAuthorDefContext`, `MlvChatDateDefContext`                         | Interfaces           | Template contexts                                                                                       |
+| `MLV_CHAT_USERS`, `MLV_CHAT_MESSAGE_DEFS`                                  | Injection tokens     | Container→bubble wiring                                                                                 |
+| `buildChatRenderList`, `toChatDate`, `isSameChatDay`, `formatChatDuration` | Functions            | Pure helpers (also used by the internals)                                                               |
 
 **Internal, deliberately not exported:** `MlvChatMediaGrid`, `MlvChatAudio`, `MlvChatAudioService`, `MLV_CHAT_AUDIO_FACTORY`, `MlvChatDate`, `MlvChatTyping`.
 
@@ -38,29 +38,29 @@ Data-driven chat surface. `mlv-chat` renders an oldest→newest `messages` array
 
 ### Inputs
 
-| Input            | Type                    | Default  | Description                                                        |
-| ---------------- | ----------------------- | -------- | ------------------------------------------------------------------ |
-| `messages`       | `MlvChatMessageData[]`  | required | Ordered oldest → newest                                            |
-| `selfId`         | `string`                | required | Messages with this `authorId` render as own                        |
-| `users`          | `MlvChatUser[]`         | `[]`     | Avatars, author names, typing names                                |
-| `loading`        | `BooleanInput`          | `false`  | Skeleton bubbles instead of content                                |
-| `loadingOlder`   | `BooleanInput`          | `false`  | Top spinner; also suppresses further `loadOlder`                   |
-| `hasOlder`       | `BooleanInput`          | `false`  | Gates `loadOlder`                                                  |
-| `typingUsers`    | `string[]`              | `[]`     | Ids resolved against `users`; unknown ids are dropped              |
-| `groupWindow`    | `number`                | `5`      | Max gap in minutes inside one author group                         |
-| `showAuthors`    | `'auto' \| boolean`     | `'auto'` | `'auto'` shows the author slot once `users.length > 2`             |
-| `dateSeparators` | `BooleanInput`          | `true`   | Calendar-day separators                                            |
-| `windowSize`     | `number`                | `150`    | Newest messages kept in the DOM                                    |
-| `mlvDensity`     | `MlvDensity`            | ambient  | Via `MlvDensityDirective` host directive                           |
+| Input            | Type                   | Default  | Description                                            |
+| ---------------- | ---------------------- | -------- | ------------------------------------------------------ |
+| `messages`       | `MlvChatMessageData[]` | required | Ordered oldest → newest                                |
+| `selfId`         | `string`               | required | Messages with this `authorId` render as own            |
+| `users`          | `MlvChatUser[]`        | `[]`     | Avatars, author names, typing names                    |
+| `loading`        | `BooleanInput`         | `false`  | Skeleton bubbles instead of content                    |
+| `loadingOlder`   | `BooleanInput`         | `false`  | Top spinner; also suppresses further `loadOlder`       |
+| `hasOlder`       | `BooleanInput`         | `false`  | Gates `loadOlder`                                      |
+| `typingUsers`    | `string[]`             | `[]`     | Ids resolved against `users`; unknown ids are dropped  |
+| `groupWindow`    | `number`               | `5`      | Max gap in minutes inside one author group             |
+| `showAuthors`    | `'auto' \| boolean`    | `'auto'` | `'auto'` shows the author slot once `users.length > 2` |
+| `dateSeparators` | `BooleanInput`         | `true`   | Calendar-day separators                                |
+| `windowSize`     | `number`               | `150`    | Newest messages kept in the DOM                        |
+| `mlvDensity`     | `MlvDensity`           | ambient  | Via `MlvDensityDirective` host directive               |
 
 ### Outputs
 
-| Output       | Payload                                                       | When                                          |
-| ------------ | ------------------------------------------------------------- | --------------------------------------------- |
-| `loadOlder`  | `void`                                                        | Near the top, window exhausted, `hasOlder` set |
-| `retry`      | `MlvChatMessageData`                                          | Retry on a failed own message                 |
-| `mediaClick` | `{ message, attachment }`                                     | A media cell was activated                    |
-| `replyClick` | `{ message, replyTo }`                                        | A reply quote was activated                   |
+| Output       | Payload                   | When                                           |
+| ------------ | ------------------------- | ---------------------------------------------- |
+| `loadOlder`  | `void`                    | Near the top, window exhausted, `hasOlder` set |
+| `retry`      | `MlvChatMessageData`      | Retry on a failed own message                  |
+| `mediaClick` | `{ message, attachment }` | A media cell was activated                     |
+| `replyClick` | `{ message, replyTo }`    | A reply quote was activated                    |
 
 ### Providers / host directives
 
@@ -72,12 +72,12 @@ Data-driven chat surface. `mlv-chat` renders an oldest→newest `messages` array
 
 **Files:** *(internal)*
 
-| Input           | Type                    | Default    | Description                                             |
-| --------------- | ----------------------- | ---------- | ------------------------------------------------------- |
-| `message`       | `MlvChatMessageData`    | required   | The message                                             |
-| `own`           | `BooleanInput`          | `false`    | Right-aligned accent bubble; ticks render only when true |
-| `groupPosition` | `MlvChatGroupPosition`  | `'single'` | Corner-tail radii                                       |
-| `quote`         | `BooleanInput`          | `false`    | Condensed reply-quote rendering                         |
+| Input           | Type                   | Default    | Description                                              |
+| --------------- | ---------------------- | ---------- | -------------------------------------------------------- |
+| `message`       | `MlvChatMessageData`   | required   | The message                                              |
+| `own`           | `BooleanInput`         | `false`    | Right-aligned accent bubble; ticks render only when true |
+| `groupPosition` | `MlvChatGroupPosition` | `'single'` | Corner-tail radii                                        |
+| `quote`         | `BooleanInput`         | `false`    | Condensed reply-quote rendering                          |
 
 Outputs: `retry: void`, `mediaClick: MlvChatAttachment`, `replyClick: MlvChatMessageData`.
 
@@ -102,9 +102,23 @@ Native scroll plus `content-visibility: auto` on group rows (no view recycling,
 - Re-pinning trims the window back to `windowSize` and clears the pill.
 - `_evaluateScroll(scrollTop, scrollHeight, clientHeight)` holds the logic separately from DOM measurement so it is testable without layout.
 
-### Replies
+### Replies — the citation block
 
-`replyTo` carries a **full** `MlvChatMessageData`, not an id — so a quote renders correctly even when the original sits outside the loaded pages. The quote is the same bubble in `quote` mode (clamped text, thumbnail, audio chip, no meta). Recursion is one level deep: a quoted message with its own `replyTo` shows a `↩` marker instead of nesting.
+`replyTo` carries a **full** `MlvChatMessageData`, not an id — so a citation renders correctly even when the original sits outside the loaded pages. The citation is the same bubble in `quote` mode (clamped text, thumbnail, audio chip, no meta), wrapped in a `button.mlv-chat-message__reply` that emits `replyClick`. Recursion is one level deep: a quoted message with its own `replyTo` shows a `↩` marker (`__reply-marker`) instead of nesting.
+
+**Palette inheritance.** The citation is a _second_ `mlv-chat-message` host, so it redeclares every `--mlv-chat-message-*` variable and can never inherit the parent bubble's values through that prefix. The citation therefore reads a separate set declared on `.mlv-chat-message__reply` — an ancestor that does not redeclare them:
+
+| Variable                         | Default                                                | Purpose                            |
+| -------------------------------- | ------------------------------------------------------ | ---------------------------------- |
+| `--mlv-chat-quote-surface`       | `color-mix(--mlv-chat-message-color 8%, transparent)`  | Citation background                |
+| `--mlv-chat-quote-surface-hover` | `color-mix(--mlv-chat-message-color 14%, transparent)` | Hover state of the citation button |
+| `--mlv-chat-quote-accent`        | `--mlv-background-accent-1`                            | Leading bar                        |
+| `--mlv-chat-quote-author`        | `--mlv-text-action`                                    | Quoted author name                 |
+| `--mlv-chat-quote-fg`            | `--mlv-chat-message-color`                             | Quoted text and the audio chip     |
+
+Deriving the surface from the _parent bubble's own text colour_ is what makes one rule set cover the neutral other-bubble and the accent own-bubble in both themes — it is always a tint of something already legible on that bubble. `.mlv-chat-message--own .mlv-chat-message__reply` additionally remaps the accent, the author colour and `--mlv-border-focus` to `--mlv-text-primary-on-accent-1`, because the global action blue would otherwise sit blue-on-blue.
+
+The button carries its own background, border reset and focus ring: without them a bare `<button>` renders the UA `buttonface` surface, which is light in **both** themes.
 
 ### Media
 
@@ -136,7 +150,7 @@ Token `MLV_CHAT_I18N` (*(internal)*). Keys: `chatLabel`, `today`, `yesterday`, `
 
 ## Styling
 
-BEM blocks `.mlv-chat`, `.mlv-chat-message`, `.mlv-chat-media-grid`, `.mlv-chat-audio`, `.mlv-chat-date`, `.mlv-chat-typing`. The group avatar is `position: sticky; inset-block-end: 0`, so a tall run keeps its avatar in view. Because the global `[class*='mlv']` reset drops inherited colour, `__text`, `__meta`, `__time`, and `__status` each restate `--mlv-chat-message-color`; the read tick is the full-strength bubble colour (ticks only render on the accent own-bubble, where an info hue would sit blue-on-blue). State-driven custom properties only: `--mlv-chat-gap`, `--mlv-chat-padding`, `--mlv-chat-bubble-gap` (density), `--mlv-chat-message-bg/-color/-radius/-tail-radius` (own/other/failed). Density levels tight → airy via `density.scss` mixins, comfortable being the base.
+BEM blocks `.mlv-chat`, `.mlv-chat-message`, `.mlv-chat-media-grid`, `.mlv-chat-audio`, `.mlv-chat-date`, `.mlv-chat-typing`. The group avatar is `position: sticky; inset-block-end: 0`, so a tall run keeps its avatar in view. Because the global `[class*='mlv']` reset drops inherited colour, `__text`, `__meta`, `__time`, and `__status` each restate `--mlv-chat-message-color`; the read tick is the full-strength bubble colour (ticks only render on the accent own-bubble, where an info hue would sit blue-on-blue). State-driven custom properties only: `--mlv-chat-gap`, `--mlv-chat-padding`, `--mlv-chat-bubble-gap` (density), `--mlv-chat-message-bg/-color/-radius/-tail-radius` (own/other/failed), and the `--mlv-chat-quote-*` citation set declared on `__reply` (see **Replies**). Density levels tight → airy via `density.scss` mixins, comfortable being the base.
 
 ---
 

package/docs/ai/checkbox.md

@@ -191,3 +191,15 @@ A dev-mode `console.warn` fires once per instance when a checkbox has no project
 - `@angular/cdk/a11y` — `FocusableOption`, `FocusKeyManager`
 - `@lucide/angular` — `LucideCheck`, `LucideMinus` icons
 - `@malva-ui/core/form-utils` — `MlvLabel`
+
+## Label type scale (2026-08-26)
+
+`.mlv-checkbox` now carries the shared control-text ramp (CH-R3) via
+`density.density-*` mixins — `--mlv-font-size-s` (tight) / `-m` (compact,
+comfortable) / `-l` (spacious) / `-xl` (airy) — so the label reads at the
+same size as an input's text or a select's trigger text at every density.
+Previously it had none: the label's font-size fell back to whatever ambient
+context it sat in, which is what made it visibly mismatch other controls in
+the same form. See `.claude/projects/libs-form-utils.md` → _Control-text
+type & padding ramp_. The swatch geometry (`__visual`) is unaffected — it is
+sized in fixed `rem`, not `em`, and does not respond to density.