@rcarls/rc-theme-material 0.0.0-next-20260921045401

package/CHANGELOG.md

@@ -0,0 +1,423 @@
+# @rcarls/rc-theme-material
+
+## 0.0.0-next-20260921045401
+
+### Minor Changes
+
+- 079e025: Standardize component styling contracts for the breaking 0.7 release.
+
+  BREAKING CHANGE: Rename the Markdown editor's `--rme-*` properties to
+  `--rc-markdown-editor-*`, `--rc-app-bar-background` to `--rc-app-bar-bg`,
+  `--rc-textarea-radius` to `--rc-textarea-border-radius`, the transfer-list
+  `--rc-transfer-list-panel-*` properties to `--rc-transfer-list-listbox-*`,
+  `--rc-chip-group-webkit-scrollbar-display` to
+  `--rc-chip-group-scrollbar-display`, and `--rc-text` to `--rc-field-text`.
+  Compatibility aliases are intentionally not provided.
+
+  BREAKING CHANGE: Replace `--rc-select-chip-padding-inline` and
+  `--rc-combobox-chip-padding-inline` with explicit `*-padding-inline-start` and
+  `*-padding-inline-end` tokens. Generated removable chips now reserve the full
+  remove target and its edge offset, so their indicator cannot overlap label text.
+
+  Add canonical app-bar elevation, transfer-list listbox radius, and textarea
+  line-action tokens. Add logical `rc-chip` inline-padding properties so themes
+  can implement Material's icon-aware spacing without overriding authored child
+  styles. Make `rc-field` consume the shared semantic token layer,
+  and place the `rc-chip` and `rc-search-bar` light-DOM structural styles in the
+  `rc-base` cascade layer so normal consumer rules override them.
+
+  Prevent decorative, `aria-hidden` trailing list content from intercepting a
+  whole-row action target, and keep segmented-list item geometry from leaking
+  into nested standard lists.
+
+  Remove unused Material navigation-rail toggle tokens and obsolete list-item
+  theme tokens. Register the segmented-button private theme seam and enforce
+  token ownership, documentation, removed-name, selector-budget, and cascade
+  layer contracts through the component architecture audit.
+
+- 4341311: Add reusable fullscreen dialogs and declarative dialog popup mode to `rc-select` and
+  `rc-combobox`. Dialog selection and creation are staged until Done, while close and Escape
+  discard the draft. Fullscreen surfaces follow the visual viewport under browser zoom and
+  software keyboards, and anchored popups now clamp to the visual viewport.
+- 2c7c80a: Give `rc-dialog` a surface styling contract.
+
+  It exposed only `--rc-dialog-scrim`, so both themes drew the surface by selecting the native
+  `<dialog>` directly. It now installs a light-DOM base stylesheet, the same pattern as `rc-button`
+  and `rc-disclosure`, and exposes minimum and maximum inline and block bounds, padding, border, radius, background,
+  foreground, and shadow, plus fullscreen-specific padding and background for the two values that
+  variant genuinely needs of its own.
+
+  Fullscreen geometry, meaning position, size, margin, radius, and shadow, stays structural rather
+  than something a theme sets: filling the visual viewport is what keeps the surface correct under browser zoom
+  and a software keyboard.
+
+  Material's explicit block bound with `overflow: hidden` moved into the base layer rather than
+  staying a theme value. It exists because Chromium does not reliably clip a scrolling element's
+  own border radius at the scroll boundary, which is a correctness fix every theme needs.
+
+  `--rc-dialog-visual-viewport-left`, `-top`, `-width`, and `-height` are no longer documented as
+  theme properties. They are geometry the component writes while a fullscreen dialog is open:
+  readable if something inside the dialog needs the same measurements, but setting them does not
+  move the dialog. They are candidates for private `--_rc-dialog-*` names in a future revision.
+
+- 4b9bfe6: Give `rc-disclosure` and `rc-accordion` a public styling contract.
+
+  Both were styled by targeting the native `<details>` element directly, so neither exposed a
+  single `--rc-*` property and no theme could change them without rewriting theme CSS. They now
+  follow the light-DOM base pattern `rc-button` and `rc-listbox` already use: `rc-disclosure`
+  installs one structural stylesheet per containing `Document` or `ShadowRoot`, in `@layer rc-base`
+  behind a `data-rc-light-dom-base` sentinel, reading documented properties with UA-like defaults.
+
+  One recipe covers both supported child forms, a bare `<details>` inside `rc-accordion` and one
+  wrapped in `rc-disclosure`, so neither theme repeats the panel rules. `rc-accordion` owns only
+  `--rc-accordion-gap`.
+
+  Motion is opt-in. `--rc-disclosure-duration` defaults to `0ms`, so a disclosure with no theme keeps
+  the platform's snap-open behavior, and the height animation runs on `::details-content` behind a
+  `@supports selector()` check. This replaces Material's `60rem` `max-block-size` ceiling, which
+  clipped content taller than the guess and made every non-summary child its own animation unit.
+
+  **Fixes a missing expand affordance in the Material theme.** It set `display: grid` on the
+  `<summary>` and then styled `summary::marker`. Any `display` other than `list-item` drops the
+  marker box, so that rule styled nothing and the theme drew no replacement: a Material disclosure
+  had no disclosure triangle at all. The base layer never sets `display` on a summary, so the
+  marker survives. A theme may still change it, as Substrate does, but only alongside a
+  replacement affordance.
+
+- 873592e: Add four directional motion tokens to the shared base contract:
+  `--rc-motion-effects-easing-enter`/`-exit` and
+  `--rc-motion-spatial-easing-enter`/`-exit`. An opening element decelerates
+  into place; a closing one accelerates out. There are no matching enter/exit
+  duration tokens; pair `-easing-exit` with an existing `-duration-fast` token
+  instead.
+
+  All three themes map the new tokens: Material pairs them with its
+  standard/emphasized decelerate and accelerate curves, Substrate keeps its one
+  curve as the enter curve and adds a generic accelerate shape for exit
+  (refined further once Substrate gets its own full spatial/effects scale), and
+  `rc-theme-win31` declares all four as `step-end`, matching its zero-motion
+  contract, so an application that loads the shared base tokens alongside
+  `rc-theme-win31` does not inherit the base defaults' real easing curves for
+  these two directions.
+
+- 7c952e2: `rc-theme-material` and `rc-theme-substrate` refine `prefers-reduced-motion:
+reduce` from removing every transition and animation to removing only
+  spatial motion; effects motion (color and opacity) is kept, shortened.
+  Vestibular harm, the reason for the preference, comes from movement across
+  the visual field; a color or opacity change doesn't trigger it, and removing
+  it too was also removing motion that aids comprehension.
+
+  Material's effects duration shortens to 50/70/100&nbsp;ms (from its full
+  150/200/300&nbsp;ms scale); Substrate's to 40/55/70&nbsp;ms, scaled down from
+  its own faster 100/160/240&nbsp;ms base. `rc-theme-win31` needs no change: it
+  already declares every duration at zero unconditionally.
+
+  Several component recipes that bypassed the shared motion scale entirely,
+  referencing a raw duration primitive directly, are rewired to the
+  appropriate effects or spatial token so this refinement actually reaches
+  them: Material's `rc-disclosure`, `rc-list-item`, `rc-bottom-sheet`'s snap
+  duration, `rc-button`'s ripple, and its shared state-layer opacity fade;
+  Substrate's `rc-listbox`, `rc-splitter`, and `rc-disclosure`. Most land on
+  their existing value exactly; `rc-button`'s ripple duration normalizes from
+  450&nbsp;ms to 500&nbsp;ms, the nearest real spatial tier.
+
+- e23a39c: Add an accessible native input and textarea field wrapper with Material 3 filled and outlined
+  theme treatments, including an explicit provider contract for enhanced native controls.
+- f5c1a8c: `rc-theme-material` now routes its component motion through the shared
+  spatial/effects token scale consistently. Previously, roughly thirty
+  `transition`/property declarations across combobox, listbox, menu, menu
+  button, menubar, select, range slider, search bar, app bar, textarea,
+  transfer list, toolbar, and splitter carried hardcoded `150ms ease` or
+  `200ms ease` literals instead of the theme's own motion tokens, and the
+  navigation bar/rail's active-item indicator (which resizes to the selected
+  item's box, a spatial change) was themed with a raw Material duration/easing
+  pair outside either scale. Every color/background-color/border-color/
+  box-shadow/opacity transition now uses `--rc-motion-effects-*`, and every
+  transform/scale/translate/inline-size/block-size transition uses
+  `--rc-motion-spatial-*`, splitting any declaration that mixed both kinds of
+  property. `rc-field`'s floating label transition moves its position/size
+  properties (`inset-block-start`, `font-size`) from the effects scale to the
+  spatial scale they actually belong to.
+
+  Five component motion tokens the theme previously left unset are now themed:
+  `--rc-switch-easing`, `--rc-button-state-layer-duration`,
+  `--rc-card-state-layer-duration`, `--rc-card-state-layer-easing`, and
+  `--rc-splitter-snap-duration`. `rc-switch`'s single duration/easing pair (it
+  has no separate spatial/effects knobs) now takes the spatial scale, since its
+  dominant motion, the thumb sliding and resizing, is spatial; this changes its
+  default transition speed under this theme from 150&nbsp;ms to 300&nbsp;ms.
+  `rc-splitter`'s snap-to-point animation moves from its 200&nbsp;ms component
+  default to the same 300&nbsp;ms spatial-fast tier for the same reason.
+
+  The spatial easing curves are now sourced from the semantic aliases added in
+  the last release rather than composed inline from raw control points four
+  times over. Material 3's spec spatial durations are
+  350/500/700&nbsp;ms; this theme's own motion guide finds durations past
+  roughly 400&nbsp;ms read as waiting rather than feedback, so the spatial
+  scale is compressed to 300/400/500&nbsp;ms: a deliberate, recorded departure
+  from the spec numbers, not the spec's `emphasized` curve shape, which is
+  unchanged.
+
+- 40f132d: `rc-theme-material` now declares the Material 3 motion system's seven named
+  easing curves (`--md-sys-motion-easing-standard`, `-emphasized`, and their
+  decelerate/accelerate variants, plus `-linear`) and sixteen named duration
+  bands (`--md-sys-motion-duration-short1` through `-extra-long4`), composed
+  from the control points and millisecond primitives already vendored. Several
+  component recipes were already reaching for these names with an inline
+  fallback (`var(--md-sys-motion-easing-standard, cubic-bezier(0.2, 0, 0, 1))`)
+  that silently won every time because nothing declared the token; those
+  references now resolve for real, and the fallback silently carrying a
+  Material 2 curve (`cubic-bezier(0.4, 0, 0.2, 1)`, in `rc-state-layer`'s
+  transition) is fixed to the correct Material 3 curve. Two more vendored-token
+  gaps of the same shape are fixed alongside: Material's disabled state-layer
+  and container opacity tokens, referenced across a dozen component recipes
+  with no local declaration, and two Substrate token names
+  (`--substrate-border`, `--substrate-radius-medium`) that never matched their
+  real declarations (`--substrate-border-color`, `--substrate-radius-md`) and
+  so always fell back to a hardcoded literal instead of the theme's actual
+  values; `rc-fab-menu`'s Substrate shadow tokens are corrected the same way.
+- 11b8cb9: Theme `rc-select` and `rc-combobox` as `rc-field` control providers: resting, hover, and
+  focus/open chrome resets mirroring the existing `rc-textarea` treatment, so `rc-field`'s own
+  `#field` surface owns the visible border, background, and focus ring instead of the wrapped
+  control rendering its own on top. Standalone (non-wrapped) usage is unaffected; every new rule
+  is scoped to `[data-rc-field-control]`.
+
+### Patch Changes
+
+- 011f3c6: Keep combobox chips clear of their trailing toggle, reset native selects inside
+  `rc-field`, keep controlled carousel accessibility state synchronized, and align
+  Material chips, menus, lists, disclosures, nested editors, and bottom-sheet
+  motion with their MD3 defaults.
+- 114e38a: `rc-progress`'s determinate fill transition is now themeable through two new
+  CSS custom properties, `--rc-progress-fill-transition-duration` (default
+  `150ms`) and `--rc-progress-fill-transition-easing` (default `ease-out`),
+  replacing a hardcoded `0.15s ease-out` no theme could reach.
+
+  The indeterminate loop's easing changes from `ease-in-out` to `linear`. A
+  loop has no beginning or end to decelerate into or accelerate out of, so an
+  eased loop visibly pulses at each cycle boundary; Material 3 specifies linear
+  easing for indeterminate loops for the same reason.
+
+  `rc-theme-material` and `rc-theme-substrate` map the new duration/easing
+  properties to their effects-fast motion tokens; `rc-theme-win31` already sets
+  `transition: none` on the fill part directly and needs no change.
+
+- fef89dc: Move the segmented appearance into the component behind one switch.
+
+  Turning the native fieldset into a segmented control took 27 `--_rc-*`
+  declarations that every theme had to restate, 23 of them byte-identical. Two of
+  those blocks were accessibility recipes rather than taste: the visually hidden
+  legend that keeps the group's accessible name, and the hidden but focusable
+  radio. A theme that got either wrong removed the accessible name or made the
+  control unreachable by keyboard.
+
+  The component now owns the recipe and a theme sets
+  `--rc-segmented-button-appearance: segmented`. Four genuine theme choices become
+  public properties: `--rc-segmented-button-cursor`,
+  `--rc-segmented-button-disabled-cursor`,
+  `--rc-segmented-button-vertical-divider`, and
+  `--rc-segmented-button-selected-icon-display`.
+
+  Unset, the fieldset, legend, and radios keep their browser appearance, as
+  before. The switch is read with a style container query (Chrome 111, Safari 18,
+  Firefox 128); where that is unsupported the recipe does not apply and the
+  control falls back to the same native appearance.
+
+  To migrate a theme, replace its `--_rc-segmented-button-*` block with the single
+  `--rc-segmented-button-appearance: segmented` declaration, plus any of the four
+  public properties whose value differs from the default.
+
+- 77f9c63: Fix three theme gaps where a token fell through to a system color.
+
+  **Substrate had no error color.** `--rc-field-error-color` fell through to `rc-field`'s own
+  default of `Mark`, the system color for the background of highlighted text, which renders as
+  pure yellow and measured 1.07:1 against the field. Validation worked, the message was in the
+  accessibility tree, and it could not be read. Substrate now ships `--substrate-error`, held
+  at hue 25 so it reads as red rather than as a darker shade of the orange primary at hue 48,
+  and the bridge maps it. Both modes clear 7:1.
+
+  Every remaining error fallback of `Mark`, in `rc-field` and in the Material field styles, now
+  falls back to the validation red a user agent uses for an invalid control. The `Mark` usages
+  inside `forced-colors` blocks are unchanged, where a system color is correct.
+
+  **Material never set `--rc-button-text`.** `rc-select`, `rc-combobox`, and `rc-menu-button`
+  read it directly for text drawn over `--rc-button-bg`, which Material sets to the primary
+  fill, so the `ButtonText` fallback gave 3.26:1 in light and 1.70:1 in dark. It now follows
+  `--md-sys-color-on-primary` alongside `--rc-button-color`, giving 6.44:1 and 7.71:1.
+
+  **Substrate referenced three tokens it never declared.** `--substrate-inverse-surface`,
+  `--substrate-inverse-on-surface`, and `--substrate-radius-pill` were used by the bridge and
+  component styles but missing from `defaults.css`, leaving `rc-snackbar` on system colors and
+  the bottom sheet handle on a literal. All three are declared, and a `defaults` test now
+  asserts that every referenced token exists.
+
+- 1aff823: Document icon font wiring as one copy-pasteable rule.
+
+  The theme sizes icon markers but sets no `font-family`, so a marker without one
+  renders as its literal text. That was documented per component, which meant
+  adopting a component could reintroduce the problem one marker at a time. The
+  README now lists every marker in the catalog in a single rule, and names the
+  three that carry no sizing from the theme either.
+
+- 3a5d979: Restore a multiline control-provider field's top spacing so its label sits as
+  far below the field's top edge as a single-line field's label does. A
+  single-line field gets that space for free from centering content within a
+  taller field surface; a multiline control-provider's content fills the
+  surface's whole height instead, so the label sat flush against the top edge
+  with no room above it.
+- 4457e71: Fix two token generator defects that produced plausible but wrong output.
+
+  A font shorthand read as a single number. `var(--weight, 500) var(--size, 1rem) / var(--lh)
+var(--family)` both starts and ends with `var(`, and the anchored pattern's fallback group is
+  greedy, so it matched as one `var(--weight)` whose fallback was the rest of the declaration and
+  resolved to `500`. The export carried `card/title-font` and `card/subtitle-font` as floats that
+  were really a collapsed shorthand. A value now counts as an alias only when its opening `var(`
+  closes at the end of the string.
+
+  A mix weight written as a `calc` only worked by accident. Material writes its state layers as
+  `color-mix(in srgb, var(--color) calc(var(--opacity, 0.08) * 100%), transparent)`. The old code
+  pattern-matched a trailing percentage off the operand, leaving a malformed remainder that
+  happened to resolve through the greedy match above. Mix operands are now split at parenthesis
+  depth zero and the weight resolves through the same resolver.
+
+## 0.6.0
+
+### Minor Changes
+
+- ffcbf11: Add adaptive chip-group layouts, native-backed filter chips, and shared
+  input-chip rendering. Native-backed chips preserve controlled host state,
+  follow form resets when uncontrolled, and accept native link actions. Groups
+  restore author-owned chip variants when coordination ends. Keep search input
+  chrome inside the search surface and align contextual icon sizes with Material 3.
+- 40f9776: Add an APG carousel built on native CSS scroll snap, with optional navigation,
+  pagination, mouse dragging, looping, and consumer-controlled slide sizing.
+  Preserve controlled active-index behavior after rejected swipes, keep visual
+  loop clones inert and out of forms, and degrade safely without intersection
+  observation.
+- a108336: Add shared-column `rc-list` and `rc-list-item` elements with standard and
+  segmented appearances, default content truncation, and native-backed single or
+  multiple selection coordination. Restore author-owned item state when native
+  selection coordination ends.
+- 509ee64: Add `rc-progress`, a native `<progress>` enhancer with a formatted value
+  display, a track and fill you can restyle with CSS custom properties, and a
+  built-in fix for the indeterminate/undefined-binding footgun.
+
+  Keep the native element as the uncontrolled source of truth, support releasing
+  a controlled value, and react to live native `value`/`max` changes. Preserve a
+  native determinate value while `indeterminate` temporarily removes its
+  attribute.
+
+  The bar renders at its intended height with no `display` attribute set,
+  matching its own documented default: previously the track/fill/native
+  `<progress>` are all absolutely positioned, contributing nothing to the
+  control's normal-flow height, so with no value-display text sharing its grid
+  row to give it one, the whole bar collapsed to 0px.
+
+- d67efde: Add a native-host scroll region with optional centered content and fullbleed
+  layout tracks, aggregate framework typings, RTL-aware boundary state, and
+  Material layout defaults.
+- 6d3b478: Add Material button emphasis, danger-tone, icon sizing, and adaptive-menu
+  contracts. Complete the bundled surface-role palette and forced-colors mappings.
+- 30eb232: Add icon-only activation-area sizing and Material icon-button variants. Align menu
+  selection and submenu affordances, and keep anchored popups within the viewport
+  across native and fallback positioning.
+- 6d3b478: Default the new touch-target overlap tokens for MD3's own dense/narrow
+  icon-button and overflow-trigger conventions: `rc-button`'s and
+  `rc-menu-button`'s narrow variant (where the icon is smaller than the
+  default 3rem touch target) now reclaim the trailing edge automatically,
+  and `rc-adaptive-menu`'s overflow trigger, always the trailing-most
+  control in its toolbar by design, does the same unconditionally. Only the
+  trailing edge defaults, matching each component's own documented
+  "trailing overflow trigger" use case; the leading edge stays an explicit
+  opt-in.
+
+### Patch Changes
+
+- 6d3b478: Keep generic dialog button styles out of custom control wrappers, support nested
+  bottom-sheet handles, and expose the Material disabled-button opacity token.
+
+## 0.5.0
+
+## 0.4.2
+
+## 0.4.1
+
+## 0.4.0
+
+### Minor Changes
+
+- e57277f: Add Material 3 search-view, fixed-pane splitter, dialog scrim, and resize enhancements.
+
+  `rc-search-bar` now supports `variant="view"`, controlled/default open state, search-view methods, a rich `suggestions` slot, and datalist-derived text suggestions. `rc-splitter` adds `mode="fixed"` for clampable pixel primary panes. `rc-common` now honors CSS max-size constraints during resize gestures, and `rc-dialog` exposes a scrim token plus resize handle/origin hooks used by themed surfaces.
+
+- c40a1be: Add theme-neutral fast, default, and slow effects and spatial motion token
+  pairs. Expose bottom-sheet settle easing through
+  `--rc-bottom-sheet-snap-easing` and map sheet settling to the Material spatial
+  motion scheme.
+
+  Give direct-child bottom-sheet handles a full-width 48px interaction target
+  while preserving the 32 by 4 pixel visual indicator. Replace rectangular
+  mobile browser tap highlights on chips with themeable, shape-clipped state
+  layers. Keep bottom-sheet snap targets docked to the block-end edge when CSS
+  minimum or maximum sizing constrains their requested heights.
+
+  Mount declaratively assigned textarea plugins at connection time and remount
+  them after reconnection, preserving plugin effects and adopted styles in
+  framework render lifecycles.
+
+### Patch Changes
+
+- 9c7476d: Add theme-specific rc-button progress treatments, including compact Material spinners and
+  Substrate percentage indicators.
+- 3efe74a: Center navigation rail header content on the inline axis and remove Material
+  elevation from FABs placed in the header slot.
+- ebec800: Dock bottom sheets without a theme to the viewport block-end by default and
+  support absolute positioning for non-modal sheets contained by a positioned ancestor.
+  Center authored drag handles with a splitter-aligned pill treatment. Align the
+  Material theme with its surface, elevation, scrim, drag-handle, and contextual
+  button treatment.
+- e88eff8: Refine semantic card-title typography and icon-button alignment across both
+  themes. Simplify Substrate navigation selection, match its bottom-sheet handle
+  to the splitter grip, improve inverse notification action contrast, and theme the
+  Markdown editor's composed controls.
+- 6f91e7a: Fix collapsed `rc-navigation-rail` items so the whole item's box wraps icon and
+  label, not just the icon. The shared component pulled the label out of flow
+  (`position: absolute`), so a theme's whole-item background or focus ring only
+  covered the icon; Material's detached-pill layout now lives in its own theme
+  stylesheet instead of the shared base. Substrate's collapsed rail also grows
+  from `5rem` to `6rem` so single-word labels like "Settings" stop wrapping.
+- dce5749: Replace the navigation rail's shadow-DOM fallback toggle with a consumer-authored light-DOM
+  button, and align collapsed and expanded item layouts across the default and reference themes.
+- 55e8ab5: Preserve UA-like control and surface styling until an optional theme supplies decorative tokens.
+  Restore themed button hover and pressed state layers, including a pointer-origin Material ripple.
+- 4d118ff: Share icon-font size and line-height tokens across themed component icon markers.
+- 3e89095: Replace rc-menu's generated submenu glyph with an author-supplied `indicator`
+  slot on rc-menu-button. Keep the decorative indicator inside the trigger bounds,
+  reserve label space for it, and expose theme-neutral size, color, and inset
+  tokens for Material, Substrate, and application themes.
+- 0dd9ff5: Prevent Material switches from collapsing below their 52 by 32 pixel track geometry in constrained flex and grid layouts.
+- 979b989: Use a zero default gap for tighter chip content layout and a smaller default
+  font size for slotted remove icons. Derive removable content padding from the
+  remove target width and chip gap so the label and trailing icon stay aligned.
+
+## 0.3.2
+
+## 0.3.1
+
+## 0.3.0
+
+### Added
+
+- Add full Material 3 token support.
+- Add Material styling for the FAB back-to-top pattern.
+- Add Material styling for the splitter collapse handle.
+
+### Changed
+
+- Normalize listbox, menu, menu-button, and menubar styling through inherited component tokens.
+- Update search-bar elevation, hover, and keyboard-focus styling.
+- Update rc-select selectors for the default native select slot.
+- Update transfer-list listbox backgrounds and action button corner radius.
+- Update package metadata, README intro, and docs links.
+
+## 0.2.0

package/README.md

@@ -0,0 +1,164 @@
+# `@rcarls/rc-theme-material`
+
+[Material 3](https://m3.material.io/) CSS theme and token bridge for `rc-webcomponents`.
+
+Docs: [https://richardcarls.github.io/rc-webcomponents/guide/theme-previews](https://richardcarls.github.io/rc-webcomponents/guide/theme-previews).
+
+Maps Material Design system and component CSS custom properties onto the
+public `--rc-*` styling contract. It changes presentation only and is an
+entirely optional theme package.
+
+Material 3 tokens and defaults vendored from the archived
+[material-foundation/material-tokens](https://github.com/material-foundation/material-tokens)
+
+## Installation
+
+```sh
+yarn add @rcarls/rc-theme-material
+```
+
+### Bridge your existing Material 3 theme
+
+Import the design-token bridge and `rc-webcomponents` styles.
+
+```css
+@import '@rcarls/rc-theme-material/bridge.css';
+@import '@rcarls/rc-theme-material/components.css';
+```
+
+Selective component styles are also exported:
+
+```css
+@import '@rcarls/rc-theme-material/bridge.css';
+@import '@rcarls/rc-theme-material/components/select.css';
+@import '@rcarls/rc-theme-material/components/menu.css';
+```
+
+The state-layer utility is included by `components.css` and `theme.css`, and is
+also exported separately for selective imports:
+
+```css
+@import '@rcarls/rc-theme-material/state-layer.css';
+```
+
+Apply `.rc-state-layer` to interactive elements that already define their own
+border radius when you want a CSS-only Material state layer.
+
+Theme styles are scoped under a `.rc-theme-material` class.
+
+```html
+<body class="rc-theme-material">
+  <!-- rc-webcomponents -->
+</body>
+```
+
+### Button variants and tones
+
+The default `rc-button` treatment is filled. Use `rc-button--tonal`,
+`rc-button--outlined`, or `rc-button--text` for the other Material emphasis
+levels. Icon-only buttons use `rc-icon-button--standard`,
+`rc-icon-button--tonal`, or `rc-icon-button--outlined`.
+
+`rc-field` uses the Material 3 filled text-field treatment by default. Add
+`rc-field--outlined` for the outlined variant.
+
+Add `data-tone="danger"` to any of those variants for the corresponding error
+or error-container color roles. These classes and data attributes are theme
+hooks; they do not change the component's native-button behavior or public API.
+
+```html
+<rc-button class="rc-button--tonal">
+  <button type="button">Save draft</button>
+</rc-button>
+
+<rc-button class="rc-button--outlined" data-tone="danger">
+  <button type="button">Delete</button>
+</rc-button>
+```
+
+### Full standalone Material 3 theme
+
+Includes bundled light and dark Material 3 token defaults and the full
+bridge and component style layers:
+
+```css
+@import '@rcarls/rc-theme-material/theme.css';
+```
+
+## Theming scope
+
+The full style layer styles native controls when their intent is established by
+composition, for example menu items and button triggers. Otherwise, it does not style
+unrelated application controls and follows design-token conventions.
+
+Fonts and icons are not bundled; websites and applications may provide
+[Roboto](https://fonts.google.com/specimen/Roboto) and
+[Material Symbols](https://fonts.google.com/icons) through other means.
+
+### Icon font wiring
+
+The theme sizes and centers icon markers but never sets `font-family` on them,
+because no font ships with it. Until the application supplies one, an icon
+marker renders as its literal text, so a navigation toggle shows the word
+`menu` rather than a glyph.
+
+Every marker in the catalog needs that one declaration. Wire them all at once
+rather than adding each as you adopt the component it belongs to:
+
+```css
+:is(
+  [data-rc-icon],
+  [data-rc-button-icon],
+  [data-rc-button-selected-icon],
+  [data-rc-chip-icon],
+  [data-rc-menu-icon],
+  [data-rc-navigation-icon],
+  [data-rc-navigation-collapse-icon],
+  [data-rc-navigation-expand-icon],
+  [data-rc-segmented-button-selected-icon]
+) {
+  font-family: 'Material Symbols Outlined';
+}
+```
+
+Three of those carry no sizing from the theme, so give them a `font-size`
+alongside the font where an application uses them:
+`data-rc-navigation-collapse-icon`, `data-rc-navigation-expand-icon`, and
+`data-rc-segmented-button-selected-icon`.
+
+For the rest, the shared `--rc-icon-font-size` and `--rc-icon-font-line-height`
+tokens keep glyph geometry consistent and can be overridden at the theme
+boundary or on one component.
+
+### Icon-button modifiers
+
+Apply these classes to `rc-button[icon-only]` to use the Material 3 expressive
+container and icon sizes. The default, unmodified size is small: a `2.5rem`
+container with a `1.5rem` icon.
+
+| Class                    | Container |      Icon |
+| ------------------------ | --------: | --------: |
+| `rc-button--extra-small` |    `2rem` | `1.25rem` |
+| `rc-button--medium`      |  `3.5rem` |  `1.5rem` |
+| `rc-button--large`       |    `6rem` |    `2rem` |
+| `rc-button--extra-large` |  `8.5rem` |  `2.5rem` |
+
+Combine a size class with `rc-button--narrow` or `rc-button--wide` to select
+that size's narrower or wider container width without changing its height or
+icon size. `rc-menu-button[icon-only]` supports `rc-menu-button--narrow` for a
+`2rem`-wide small trigger. The component packages continue to reserve a `3rem`
+activation area around visual containers smaller than that target.
+
+`rc-adaptive-menu` uses the same Material small narrow geometry for its
+overflow trigger: a `2rem × 2.5rem` visible container centered in the
+component-owned `3rem × 3rem` activation area. The theme also aligns overflow
+rows with Material menu geometry while leaving the component's controlled or
+uncontrolled `open` contract unchanged.
+
+Direct native buttons in an `rc-app-bar`'s `leading` and `trailing` slots also
+receive the Material small icon-button geometry. Controls nested in an
+`rc-button` or `rc-menu-button` keep their component-owned sizing.
+
+[Material Web](material-web.dev) token names are used where a corresponding component
+exists. Search bar and top app bar mappings follow Material 3 token terminology and
+fall back through Material system roles.