@rcarls/rc-theme-material 0.5.0 → 0.7.0

package/README.md

@@ -34,6 +34,30 @@ Selective component styles are also exported:
 @import '@rcarls/rc-theme-material/components/menu.css';
 ```
 
+Native HTML can opt into the same presentation without registering an RC
+element. Import the defaults and bridge when needed, then opt into the native
+layer and the CSS-only recipes independently:
+
+```css
+@import '@rcarls/rc-theme-material/defaults.css';
+@import '@rcarls/rc-theme-material/bridge.css';
+@import '@rcarls/rc-theme-material/native.css';
+@import '@rcarls/rc-theme-material/css-components.css';
+```
+
+`native.css` is an optional convenience layer for giving ordinary buttons, text
+fields, selects, textareas, checkboxes, radios, ranges, and progress controls a
+Material treatment throughout `.rc-theme-material`. Component recipes style
+native children when their presentation belongs to a themed menu, toolbar, or
+other component context. Add `data-rc-native="off"` to an element to opt it and
+its descendants out of the native layer. The
+opt-in `css-components.css` recipes cover `.rc-button`, `.rc-chip`,
+`.rc-chip-group`, `.rc-select`, `.rc-textarea`, `.rc-card`, `.rc-list`, and
+`details.rc-disclosure`; each recipe is also available under
+`css-components/<name>.css`. These styles provide appearance and CSS-visible
+states only: they do not add behavior, events, popup replacement, or measured
+overflow.
+
 The state-layer utility is included by `components.css` and `theme.css`, and is
 also exported separately for selective imports:
 
@@ -52,6 +76,30 @@ Theme styles are scoped under a `.rc-theme-material` class.
 </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
@@ -61,6 +109,23 @@ bridge and component style layers:
 @import '@rcarls/rc-theme-material/theme.css';
 ```
 
+## Designing with the theme
+
+[`DESIGN.md`](./DESIGN.md) is a Material 3 composition guide written for AI
+coding agents. It covers which component fills which Material role, adaptive
+layouts by window size class, dialogs, sheets, lists, navigation and
+feedback, with the baseline token values in machine-readable front matter. It
+ships in the package and is exported as `@rcarls/rc-theme-material/DESIGN.md`,
+so agents in a consuming app can read it from `node_modules`, or under Yarn
+Plug'n'Play with:
+
+```sh
+yarn node -e "process.stdout.write(require('fs').readFileSync(require.resolve('@rcarls/rc-theme-material/DESIGN.md'), 'utf8'))"
+```
+
+App design documents should reference it for Material 3 composition and keep
+only their own overrides, branding and product patterns.
+
 ## Theming scope
 
 The full style layer styles native controls when their intent is established by
@@ -70,11 +135,79 @@ 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.
-Tag general icon-font markup with `data-rc-icon`; component-specific markers
-such as `data-rc-button-icon` and `data-rc-navigation-icon` opt in
-automatically. 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.
+
+### Scoped type scale
+
+Mark a region with `data-rc-type-scale` and set `--rc-type-scale` to enlarge or
+shrink its text, such as a reading view used at arm's length. Every Material type
+size and line height beneath the marked element, and the RC text tokens built on
+them, are multiplied by the factor. Text outside the region is unchanged.
+
+```html
+<main data-rc-type-scale style="--rc-type-scale: 1.25">…</main>
+```
+
+Marking the theme root itself scales the whole page, for an app-wide text size
+setting. A nested marked region uses its own `--rc-type-scale`; to compound it
+with a page-wide factor, keep that factor in a separate custom property and
+multiply, since a property can't refer to its own inherited value:
+
+```html
+<html
+  class="rc-theme-material"
+  data-rc-type-scale
+  style="--app-scale: 0.75; --rc-type-scale: var(--app-scale)"
+>
+  …
+  <p data-rc-type-scale style="--rc-type-scale: calc(var(--app-scale) * 1.25)">…</p>
+</html>
+```
+
+With `theme.css`, the Material type tokens and RC text tokens scale from the
+bundled `defaults.css` values. With `bridge.css` alone, RC text tokens scale from
+the application's Material type tokens; the application's own
+`--md-sys-typescale-*` tokens remain unchanged. Supply both size and line-height
+tokens for the roles used by RC components when customizing the bridge. If your
+Material token environment also defines matching `*-size-value` or
+`*-line-height-value` source tokens, those are the scale baseline; update them
+alongside branded final values.
+
+### 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, a marker
+renders its literal text, so a navigation toggle shows the word `menu`. See
+[Fonts and icons](./DESIGN.md#fonts-and-icons) in the design guide for the
+one rule that wires every marker.
+
+### 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

package/bridge.css

@@ -1,4 +1,5 @@
-@layer rc-theme-material.defaults, rc-theme-material.bridge, rc-theme-material.components;
+@layer rc-base, rc-theme-material.defaults, rc-theme-material.bridge, rc-theme-material.native, rc-theme-material.components, rc-theme-material.css-components,
+  rc-theme-material.overrides;
 
 @layer rc-theme-material.bridge {
   /*
@@ -34,6 +35,31 @@
       calc(var(--md-sys-elevation-level4, 8px) * 2)
       color-mix(in srgb, var(--md-sys-color-shadow, #000) 24%, transparent);
     --rc-shadow: var(--rc-shadow-level2);
+    /*
+     * Menus, select and combobox listboxes, and adaptive-menu popups share the
+     * MD3 menu container. Set here rather than per element so the values also
+     * inherit into popups rendered inside other shadow roots.
+     */
+    --rc-popup-background: var(
+      --md-menu-container-color,
+      var(--md-sys-color-surface-container, Canvas)
+    );
+    --rc-popup-color: var(--md-sys-color-on-surface, CanvasText);
+    --rc-popup-border: 0;
+    --rc-popup-radius: var(
+      --md-menu-container-shape,
+      var(--md-sys-shape-corner-extra-small, 0.25rem)
+    );
+    --rc-popup-shadow: var(--rc-shadow);
+    --rc-adaptive-menu-popup-shadow: 0 1px 2px rgb(0 0 0 / 30%), 0 2px 6px 2px rgb(0 0 0 / 15%);
+    --rc-popup-padding-block: 0.5rem;
+    /* Menu, listbox, and adaptive-menu items use the MD3 body-large scale. */
+    --rc-item-font-family: var(--md-sys-typescale-body-large-font, inherit);
+    --rc-item-font-size: var(--md-sys-typescale-body-large-size, 1rem);
+    --rc-item-font-weight: var(--md-sys-typescale-body-large-weight, 400);
+    --rc-item-line-height: var(--md-sys-typescale-body-large-line-height, 1.5rem);
+    --rc-item-letter-spacing: var(--md-sys-typescale-body-large-tracking, 0.03125rem);
+    --rc-item-icon-size: 1.5rem;
     --rc-font-family: var(--md-sys-typescale-body-medium-font, inherit);
     --rc-font-size: var(--md-sys-typescale-body-medium-size, 0.875rem);
     --rc-line-height: var(--md-sys-typescale-body-medium-line-height, 1.25rem);
@@ -51,7 +77,14 @@
     --rc-list-item-selected-bg: var(--md-sys-color-secondary-container, Highlight);
     --rc-list-item-selected-color: var(--md-sys-color-on-secondary-container, HighlightText);
     --rc-button-bg: var(--md-sys-color-primary, ButtonFace);
-    --rc-button-color: var(--md-sys-color-on-primary, ButtonText);
+    /*
+     * Both of these sit on --rc-button-bg, so both take the on-primary color.
+     * rc-select, rc-combobox, and rc-menu-button read --rc-button-text directly
+     * for their trigger and chip text; leaving it unset dropped them onto the
+     * ButtonText system color over the primary fill.
+     */
+    --rc-button-text: var(--md-sys-color-on-primary, ButtonText);
+    --rc-button-color: var(--rc-button-text, ButtonText);
     --rc-button-block-size: var(--rc-control-block-size);
     --rc-button-radius: var(--rc-control-radius);
     --rc-button-border: 0;
@@ -122,27 +155,38 @@
     --rc-focus-ring-offset: 2px;
     --rc-disabled-opacity: var(--md-sys-state-disabled-state-layer-opacity, 0.38);
     --rc-motion-effects-duration-fast: var(--md-sys-motion-duration-150, 150ms);
-    --rc-motion-effects-easing-fast: cubic-bezier(
-      var(--md-sys-motion-easing-standard-x0, 0.2),
-      var(--md-sys-motion-easing-standard-y0, 0),
-      var(--md-sys-motion-easing-standard-x1, 0),
-      var(--md-sys-motion-easing-standard-y1, 1)
-    );
+    --rc-motion-effects-easing-fast: var(--md-sys-motion-easing-standard, ease-out);
     --rc-motion-effects-duration-default: var(--md-sys-motion-duration-200, 200ms);
     --rc-motion-effects-easing-default: var(--rc-motion-effects-easing-fast);
     --rc-motion-effects-duration-slow: var(--md-sys-motion-duration-300, 300ms);
     --rc-motion-effects-easing-slow: var(--rc-motion-effects-easing-fast);
-    --rc-motion-spatial-duration-fast: var(--md-sys-motion-duration-350, 350ms);
-    --rc-motion-spatial-easing-fast: cubic-bezier(
-      var(--md-sys-motion-easing-emphasized-x0, 0.2),
-      var(--md-sys-motion-easing-emphasized-y0, 0),
-      var(--md-sys-motion-easing-emphasized-x1, 0),
-      var(--md-sys-motion-easing-emphasized-y1, 1)
-    );
-    --rc-motion-spatial-duration-default: var(--md-sys-motion-duration-500, 500ms);
+    /*
+     * Spec spatial durations are 350/500/700ms. This project's own motion
+     * guide finds anything past ~400ms reads as waiting rather than
+     * feedback, so the scale is compressed to 300/400/500ms — a deliberate
+     * departure recorded here rather than a silent guess. The curve shape
+     * (emphasized) is unchanged from spec.
+     */
+    --rc-motion-spatial-duration-fast: var(--md-sys-motion-duration-medium2, 300ms);
+    --rc-motion-spatial-easing-fast: var(
+      --md-sys-motion-easing-emphasized,
+      cubic-bezier(0.2, 0, 0, 1)
+    );
+    --rc-motion-spatial-duration-default: var(--md-sys-motion-duration-medium4, 400ms);
     --rc-motion-spatial-easing-default: var(--rc-motion-spatial-easing-fast);
-    --rc-motion-spatial-duration-slow: var(--md-sys-motion-duration-700, 700ms);
+    --rc-motion-spatial-duration-slow: var(--md-sys-motion-duration-long2, 500ms);
     --rc-motion-spatial-easing-slow: var(--rc-motion-spatial-easing-fast);
+    /* Decelerate for arriving, accelerate for leaving; family matches above. */
+    --rc-motion-effects-easing-enter: var(--md-sys-motion-easing-standard-decelerate, ease-out);
+    --rc-motion-effects-easing-exit: var(--md-sys-motion-easing-standard-accelerate, ease-in);
+    --rc-motion-spatial-easing-enter: var(
+      --md-sys-motion-easing-emphasized-decelerate,
+      cubic-bezier(0, 0, 0, 1)
+    );
+    --rc-motion-spatial-easing-exit: var(
+      --md-sys-motion-easing-emphasized-accelerate,
+      cubic-bezier(0.3, 0, 1, 1)
+    );
     --rc-motion-duration: var(--rc-motion-effects-duration-default);
     --rc-dialog-scrim: color-mix(in srgb, var(--md-sys-color-scrim, #000) 32%, transparent);
   }
@@ -157,16 +201,9 @@
     );
     --rc-select-border: 1px solid
       var(--md-outlined-select-text-field-outline-color, var(--md-sys-color-outline, ButtonBorder));
-    --rc-select-listbox-radius: var(
-      --md-menu-container-shape,
-      var(--md-sys-shape-corner-extra-small, 0.25rem)
-    );
-    --rc-select-listbox-border: 0;
-    --rc-select-listbox-padding-block: 0.5rem;
-    --rc-select-shadow: var(--rc-shadow);
     --rc-select-chip-radius: var(--md-sys-shape-corner-small, 0.5rem);
-    --rc-select-chip-padding-block: 0.375rem;
-    --rc-select-chip-padding-inline: 0.75rem;
+    --rc-select-chip-padding-block: 0;
+    --rc-select-chip-padding-inline-start: 0.75rem;
     --rc-field: var(
       --md-outlined-select-text-field-container-color,
       var(--md-sys-color-surface, Field)
@@ -215,16 +252,9 @@
     );
     --rc-combobox-border: 1px solid
       var(--md-outlined-text-field-outline-color, var(--md-sys-color-outline, ButtonBorder));
-    --rc-combobox-listbox-radius: var(
-      --md-menu-container-shape,
-      var(--md-sys-shape-corner-extra-small, 0.25rem)
-    );
-    --rc-combobox-listbox-border: 0;
-    --rc-combobox-listbox-padding-block: 0.5rem;
-    --rc-combobox-shadow: var(--rc-shadow);
     --rc-combobox-chip-radius: var(--md-sys-shape-corner-small, 0.5rem);
-    --rc-combobox-chip-padding-block: 0.375rem;
-    --rc-combobox-chip-padding-inline: 0.75rem;
+    --rc-combobox-chip-padding-block: 0;
+    --rc-combobox-chip-padding-inline-start: 0.75rem;
     --rc-field: var(--md-outlined-text-field-container-color, var(--md-sys-color-surface, Field));
     --rc-field-text: var(
       --md-outlined-text-field-input-text-color,
@@ -259,6 +289,24 @@
     --rc-thumb-radius: calc(var(--md-slider-handle-width, 1.25rem) / 2);
   }
 
+  .rc-theme-material rc-progress,
+  :host(.rc-theme-material) rc-progress {
+    --rc-progress-track-background: var(
+      --md-linear-progress-track-color,
+      var(--md-sys-color-surface-container-highest, CanvasText)
+    );
+    --rc-progress-track-opacity: 1;
+    --rc-progress-track-radius: var(
+      --md-linear-progress-track-shape,
+      var(--md-sys-shape-corner-full, 999px)
+    );
+    --rc-progress-fill-background: var(
+      --md-linear-progress-active-indicator-color,
+      var(--md-sys-color-primary, Highlight)
+    );
+    --rc-progress-value-color: var(--md-sys-color-on-surface-variant, GrayText);
+  }
+
   .rc-theme-material rc-range-slider,
   :host(.rc-theme-material) rc-range-slider {
     --rc-range-slider-accent: var(
@@ -390,19 +438,9 @@
     );
   }
 
-  .rc-theme-material rc-menu,
-  :host(.rc-theme-material) rc-menu {
-    --rc-menu-padding-block: 0.5rem;
-    --rc-menu-background: var(
-      --md-menu-container-color,
-      var(--md-sys-color-surface-container, Canvas)
-    );
-    --rc-menu-border: 0;
-    --rc-menu-radius: var(
-      --md-menu-container-shape,
-      var(--md-sys-shape-corner-extra-small, 0.25rem)
-    );
-    --rc-menu-shadow: var(--rc-shadow);
+  /* Declared on the theme root so menus inside other shadow roots inherit it. */
+  .rc-theme-material,
+  :host(.rc-theme-material) {
     --rc-menu-color: var(
       --md-menu-item-label-text-color,
       var(--md-sys-color-on-surface, CanvasText)
@@ -511,10 +549,10 @@
 
   .rc-theme-material rc-markdown-editor,
   :host(.rc-theme-material) rc-markdown-editor {
-    --rme-background: var(--md-sys-color-surface, Canvas);
-    --rme-color: var(--md-sys-color-on-surface, CanvasText);
-    --rme-border: 1px solid var(--md-sys-color-outline, ButtonBorder);
-    --rme-focus-outline: 2px solid var(--md-sys-color-primary, Highlight);
+    --rc-markdown-editor-background: var(--md-sys-color-surface, Canvas);
+    --rc-markdown-editor-color: var(--md-sys-color-on-surface, CanvasText);
+    --rc-markdown-editor-border: 1px solid var(--md-sys-color-outline, ButtonBorder);
+    --rc-markdown-editor-focus-outline: 2px solid var(--md-sys-color-primary, Highlight);
   }
 
   .rc-theme-material rc-transfer-list,
@@ -540,9 +578,6 @@
     --rc-navigation-rail-item-text-decoration: none;
     --rc-navigation-rail-indicator-bg: var(--md-sys-color-secondary-container, Highlight);
     --rc-navigation-rail-indicator-border: 0;
-    --rc-navigation-rail-toggle-padding: 0;
-    --rc-navigation-rail-toggle-border: 0;
-    --rc-navigation-rail-toggle-font: inherit;
   }
   .rc-theme-material rc-navigation-rail > rc-fab[slot='header'],
   :host(.rc-theme-material) rc-navigation-rail > rc-fab[slot='header'] {
@@ -615,6 +650,65 @@
     );
   }
 
+  /*
+   * Scale RC text from the unscaled Material values. The bundled defaults
+   * expose *-value tokens; bridge-only consumers can supply Material type
+   * tokens, which the bridge leaves unchanged.
+   */
+  /* A marked theme root itself must outrank its own token rule above. */
+  :where(.rc-theme-material [data-rc-type-scale], :host(.rc-theme-material) [data-rc-type-scale]),
+  .rc-theme-material[data-rc-type-scale],
+  :host(.rc-theme-material[data-rc-type-scale]) {
+    --rc-item-font-size: calc(
+      var(--md-sys-typescale-body-large-size-value, var(--md-sys-typescale-body-large-size, 1rem)) *
+        var(--rc-type-scale, 1)
+    );
+    --rc-item-line-height: calc(
+      var(
+          --md-sys-typescale-body-large-line-height-value,
+          var(--md-sys-typescale-body-large-line-height, 1.5rem)
+        ) *
+        var(--rc-type-scale, 1)
+    );
+    --rc-font-size: calc(
+      var(
+          --md-sys-typescale-body-medium-size-value,
+          var(--md-sys-typescale-body-medium-size, 0.875rem)
+        ) *
+        var(--rc-type-scale, 1)
+    );
+    --rc-line-height: calc(
+      var(
+          --md-sys-typescale-body-medium-line-height-value,
+          var(--md-sys-typescale-body-medium-line-height, 1.25rem)
+        ) *
+        var(--rc-type-scale, 1)
+    );
+    --rc-button-font: 500
+      calc(
+        var(
+            --md-sys-typescale-label-large-size-value,
+            var(--md-sys-typescale-label-large-size, 0.875rem)
+          ) *
+          var(--rc-type-scale, 1)
+      ) /
+      calc(
+        var(
+            --md-sys-typescale-label-large-line-height-value,
+            var(--md-sys-typescale-label-large-line-height, 1.25rem)
+          ) *
+          var(--rc-type-scale, 1)
+      )
+      var(--rc-font-family);
+    --rc-menu-shortcut-size: calc(
+      var(
+          --md-sys-typescale-label-large-size-value,
+          var(--md-sys-typescale-label-large-size, 0.875rem)
+        ) *
+        var(--rc-type-scale, 1)
+    );
+  }
+
   @media (forced-colors: active) {
     .rc-theme-material,
     :host(.rc-theme-material) {
@@ -623,6 +717,7 @@
       --rc-shadow-level2: none;
       --rc-shadow-level3: none;
       --rc-shadow: none;
+      --rc-popup-border: 1px solid ButtonBorder;
       --rc-disabled-opacity: 1;
     }