@rcarls/rc-theme-material 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. package/README.md +34 -82
  2. package/bridge.css +446 -298
  3. package/components/accordion.css +173 -6
  4. package/components/app-bar.css +8 -4
  5. package/components/combobox.css +63 -0
  6. package/components/dialog.css +5 -2
  7. package/components/disclosure.css +102 -7
  8. package/components/fab.css +17 -0
  9. package/components/listbox.css +31 -22
  10. package/components/menu-button.css +13 -13
  11. package/components/menu.css +96 -12
  12. package/components/menubar.css +18 -3
  13. package/components/search-bar.css +16 -6
  14. package/components/select.css +62 -0
  15. package/components/splitter.css +26 -12
  16. package/components/transfer-list.css +40 -1
  17. package/components.css +1 -0
  18. package/defaults.css +858 -87
  19. package/package.json +6 -7
package/README.md CHANGED
@@ -1,11 +1,15 @@
1
1
  # `@rcarls/rc-theme-material`
2
2
 
3
- Optional Material 3 design-token bridge and full CSS style layer for
4
- `rc-webcomponents`.
3
+ [Material 3](https://m3.material.io/) CSS theme and token bridge for `rc-webcomponents`.
5
4
 
6
- The package maps Material system and component CSS custom properties into RC's
7
- public `--rc-*` styling contracts. It changes presentation only; it does not
8
- claim behavioral or structural conformance with Material components.
5
+ Docs: [https://richardcarls.github.io/rc-webcomponents/guide/theme-previews](https://richardcarls.github.io/rc-webcomponents/guide/theme-previews).
6
+
7
+ Maps Material Design system and component CSS custom properties onto the
8
+ public `--rc-*` styling contract. It changes presentation only and is an
9
+ entirely optional theme package.
10
+
11
+ Material 3 tokens and defaults vendored from the archived
12
+ [material-foundation/material-tokens](https://github.com/material-foundation/material-tokens)
9
13
 
10
14
  ## Installation
11
15
 
@@ -13,31 +17,15 @@ claim behavioral or structural conformance with Material components.
13
17
  yarn add @rcarls/rc-theme-material
14
18
  ```
15
19
 
16
- Use an application's existing Material token environment:
17
-
18
- ```css
19
- @import '@rcarls/rc-theme-material/bridge.css';
20
- ```
20
+ ### Bridge your existing Material 3 theme
21
21
 
22
- ```html
23
- <main class="rc-theme-material">
24
- <!-- rc components -->
25
- </main>
26
- ```
27
-
28
- For a standalone baseline that includes representative light and dark Material
29
- system tokens and the full component style layer:
22
+ Import the design-token bridge and `rc-webcomponents` styles.
30
23
 
31
24
  ```css
32
- @import '@rcarls/rc-theme-material/theme.css';
25
+ @import '@rcarls/rc-theme-material/bridge.css';
26
+ @import '@rcarls/rc-theme-material/components.css';
33
27
  ```
34
28
 
35
- Import `defaults.css` separately when only the baseline Material system tokens
36
- are needed. Import `components.css` with `bridge.css` when an application
37
- provides its own Material system tokens but wants the full RC component styling.
38
- `bridge.css` never defines `--md-sys-*`, so branded or dynamically generated
39
- application tokens remain authoritative.
40
-
41
29
  Selective component styles are also exported:
42
30
 
43
31
  ```css
@@ -46,69 +34,33 @@ Selective component styles are also exported:
46
34
  @import '@rcarls/rc-theme-material/components/menu.css';
47
35
  ```
48
36
 
49
- Package rules use ordered cascade layers:
37
+ Theme styles are scoped under a `.rc-theme-material` class.
50
38
 
51
- ```css
52
- @layer rc-theme-material.defaults, rc-theme-material.bridge, rc-theme-material.components;
39
+ ```html
40
+ <body class="rc-theme-material">
41
+ <!-- rc-webcomponents -->
42
+ </body>
53
43
  ```
54
44
 
55
- Unlayered application CSS and application layers declared after these layers
56
- can override the theme normally.
57
-
58
- ## Supported mappings
45
+ ### Full standalone Material 3 theme
59
46
 
60
- The initial bridge and style layer cover:
47
+ Includes bundled light and dark Material 3 token defaults and the full
48
+ bridge and component style layers:
61
49
 
62
- - `rc-select` and `rc-combobox`
63
- - `rc-slider` and `rc-range-slider`
64
- - `rc-search-bar`
65
- - `rc-app-bar`
66
- - `rc-menu`, `rc-menu-button`, and `rc-menubar`
67
- - `rc-toolbar`
68
- - `rc-listbox`, `rc-textarea`, `rc-markdown-editor`, and `rc-transfer-list`
69
- - `rc-dialog`, `rc-disclosure`, and `rc-accordion`
70
- - `rc-splitter` and `rc-virtual-canvas`
71
-
72
- Material Web token names are used where a corresponding component exists.
73
- Search bar and top app bar mappings follow Material 3 token terminology and
74
- fall back through Material system roles.
75
-
76
- The initial mapping targets Material Web's `v0_192` component-token generation
77
- and the public token names documented at material-web.dev. Material Web token
78
- changes are not adopted silently; mapping updates are versioned package API.
79
-
80
- Consumer-provided native controls remain consumer-owned. The bridge does not
81
- style arbitrary buttons or infer filled, tonal, text, or icon-button intent.
82
- Menu-button mappings provide trigger geometry only; applications choose trigger
83
- colors and button variants.
84
-
85
- The full style layer does style native controls when their intent is established
86
- by an RC composition, including menu items, menu triggers, toolbar controls,
87
- app-bar actions, transfer-list actions, disclosure summaries, and dialog
88
- actions. It never styles unrelated application controls.
89
-
90
- ## Fidelity
91
-
92
- | Surface | Fidelity | Notes |
93
- | --- | --- | --- |
94
- | Select, combobox, listbox, menus, search, app bar, sliders | Strong | Existing parts and states support recognizable M3 treatments. |
95
- | Toolbar, transfer list, textarea, splitter, dialog, disclosure | Approximate | Material styling is applied to RC's existing structure. |
96
- | Markdown editor and virtual canvas | Foundational | Surface, state, and contextual-control styling only. |
50
+ ```css
51
+ @import '@rcarls/rc-theme-material/theme.css';
52
+ ```
97
53
 
98
- Floating labels, supporting/error text structures, ripples, Material button
99
- variants, and richer component-specific compositions require future styling
100
- hooks or structural variants. Fonts and icons are not bundled; applications may
101
- provide Roboto and Material Symbols through their normal asset pipeline.
54
+ ## Theming scope
102
55
 
103
- ## Token precedence
56
+ The full style layer will style native controls when their intent is established
57
+ by composition (e.g., menu items, button triggers, etc.). Otherwise, It never styles
58
+ unrelated application controls and tries to follow design token conventions.
104
59
 
105
- Component tokens override system tokens, which override RC's platform fallback:
60
+ Fonts and icons are not bundled; websites and applications may provide
61
+ [Roboto](https://fonts.google.com/specimen/Roboto) and
62
+ [Material Symbols](https://fonts.google.com/icons) through other means.
106
63
 
107
- ```css
108
- --rc-slider-progress-background:
109
- var(--md-slider-active-track-color, var(--md-sys-color-primary, Highlight));
110
- ```
111
-
112
- The bridge's Material token mapping is a versioned public contract. Review
113
- release notes before upgrading when an application overrides Material component
114
- tokens directly.
64
+ [Material Web](material-web.dev) token names are used where a corresponding component
65
+ exists. Search bar and top app bar mappings follow Material 3 token terminology and
66
+ fall back through Material system roles.