Styling
Design-system neutral by default
Components ship without decorative visual opinions. The default appearance mirrors the UA stylesheet; buttons look like buttons, inputs look like inputs. This lets them blend into any design system without fighting existing styles.
What components always emit is structural: layout, geometry, and interaction state indicators. The decorative layer is entirely up to you.
Color scheme
Components consume CSS system colors (Canvas, CanvasText, ButtonFace,
Highlight, etc.), which the browser resolves differently in light and dark
schemes. Set color-scheme on a container and every component inside it
adapts automatically:
.my-app {
color-scheme: dark;
}
No class-based theming or JavaScript needed for basic color scheme support.
Global design tokens
The optional base.css export defines semantic tokens that all components
reference. Import it once at your application root to enable the token layer:
@import '@rcarls/rc-webcomponents/themes/base.css';
These tokens fall back to CSS system colors without the import; the file is optional. Override any token at your theme boundary to adjust all components at once:
:root {
--rc-accent: oklch(55% 0.2 250); /* primary action color */
--rc-border-color: oklch(75% 0 0); /* all component borders */
--rc-control-block-size: 2.5rem; /* input / button height */
--rc-control-radius: 0.5rem; /* border radius */
--rc-font-family: 'Inter', sans-serif;
}
The semantic layer is deliberately smaller than the sum of every component's styling API. Components consume these shared decisions and expose narrower component tokens where their structure needs an additional adaptation point.
| Role | Tokens and defaults |
|---|---|
| Surfaces | --rc-surface: Canvas; --rc-field: Field; --rc-button-bg: ButtonFace |
| Text | --rc-field-text: FieldText; --rc-button-text: ButtonText; --rc-highlight-text: HighlightText; --rc-text-disabled: GrayText |
| Accent and selection | --rc-accent: Highlight (AccentColor when supported); --rc-highlight: Highlight |
| Border and elevation | --rc-border-color: ButtonBorder; --rc-border-width: 1px; --rc-border-style: solid; --rc-border: var(--rc-border-width) var(--rc-border-style) var(--rc-border-color); --rc-shadow: 0 2px 8px rgba(0, 0, 0, 0.15) |
| Type | --rc-font-family: inherit; --rc-font-size: 1em; --rc-font-weight: 400; --rc-line-height: normal |
| Controls | --rc-control-block-size: 2.25em; --rc-control-padding-block: 0.25em; --rc-control-padding-inline: 0.5em; --rc-control-gap: 0.25em |
| Items | --rc-item-padding-block: 0.3em; --rc-item-padding-inline: 0.75em; --rc-item-gap: 0.4em |
| Item type | Unset by default, so items inherit their text style. --rc-item-font-family, --rc-item-font-size, --rc-item-font-weight, --rc-item-line-height, --rc-item-letter-spacing, and --rc-item-icon-size style menu, listbox, and adaptive-menu items. |
| Shape | --rc-radius-sm: 0.125em; --rc-radius-md: 0.25em; --rc-control-radius: var(--rc-radius-sm) |
| Popups | --rc-popup-background: var(--rc-surface); --rc-popup-color: var(--rc-field-text); --rc-popup-border: var(--rc-border); --rc-popup-radius: var(--rc-radius-sm); --rc-popup-shadow: var(--rc-shadow); --rc-popup-padding-block: var(--rc-control-padding-block). Menus, adaptive-menu popups, popovers, and select and combobox listboxes read these before their own fallbacks. |
| Focus and disabled | --rc-focus-ring: auto; --rc-focus-ring-offset: 0; --rc-disabled-opacity: 0.5 |
| Effects motion | --rc-motion-effects-duration-fast: 80ms; --rc-motion-effects-duration-default: 120ms; --rc-motion-effects-duration-slow: 200ms; matching --rc-motion-effects-easing-fast, --rc-motion-effects-easing-default, and --rc-motion-effects-easing-slow default to ease-out |
| Spatial motion | --rc-motion-spatial-duration-fast: 180ms; --rc-motion-spatial-duration-default: 300ms; --rc-motion-spatial-duration-slow: 450ms; matching --rc-motion-spatial-easing-fast, --rc-motion-spatial-easing-default, and --rc-motion-spatial-easing-slow default to cubic-bezier(0.2, 0, 0, 1) |
| Directional easing | --rc-motion-spatial-easing-enter: cubic-bezier(0, 0, 0, 1); --rc-motion-spatial-easing-exit: cubic-bezier(0.3, 0, 1, 1); --rc-motion-effects-easing-enter: ease-out; --rc-motion-effects-easing-exit: ease-in. No matching enter/exit duration tokens; pair -easing-exit with -duration-fast. |
| Compatibility motion | --rc-motion-duration: var(--rc-motion-effects-duration-default) |
Set the popup and item type tokens at the theme root rather than on individual
elements. The same applies to a theme's menu and adaptive-menu tokens.
Custom properties inherit into shadow roots, so a menu rendered inside another
component's shadow root, where element selectors such as .my-theme rc-menu
cannot reach, still gets the theme's popup surface.
Per-component tokens
Each component also exposes its own scoped tokens for fine-grained control. These are documented in the API table on each component page. Example:
/* Make the FAB match your brand */
rc-fab {
--rc-fab-bg: oklch(55% 0.2 250);
--rc-fab-color: white;
--rc-fab-radius: 0.75rem;
--rc-fab-shadow: 0 4px 12px oklch(55% 0.2 250 / 40%);
}
Some public tokens intentionally form a small family across related
components. --rc-thumb-radius aligns slider and range-slider thumbs;
--rc-fab-* tokens let rc-fab-menu reuse the FAB trigger contract. A few
composition tokens are deliberate pass-throughs: rc-bottom-sheet forwards
--rc-dialog-scrim, and rc-fab-menu forwards
--rc-menu-button-popup-z-index. These contracts are documented by every
component that consumes them and enforced by the architecture audit.
0.7 styling migration
Version 0.7 removes compatibility aliases and accepts the following breaking token replacements as the only supported names:
| Removed token or prefix | Replacement |
|---|---|
--rme-* | --rc-markdown-editor-* |
--rc-app-bar-background | --rc-app-bar-bg |
--rc-textarea-radius | --rc-textarea-border-radius |
--rc-transfer-list-panel-border | --rc-transfer-list-listbox-border |
--rc-transfer-list-panel-background | --rc-transfer-list-listbox-bg |
--rc-transfer-list-panel-radius | --rc-transfer-list-listbox-radius |
--rc-chip-group-webkit-scrollbar-display | --rc-chip-group-scrollbar-display |
--rc-text | --rc-field-text |
The Material navigation-rail toggle overrides and list-item background and supporting-color tokens were internal theme leftovers with no component consumer; they have been removed rather than replaced. Component-specific tokens still win over shared semantic fallbacks, so localized overrides remain straightforward after migrating.
Adaptive layout contracts
Choose the narrowest responsive mechanism that keeps a component's visual and behavioral state synchronized:
- Override one geometry token for a scalar change such as carousel slide size.
- Override a coordinated token set when unchanged regions need new grid
tracks or placement, as with
rc-cardandrc-list-item. - Write a property or attribute when a mode also changes ARIA, keyboard behavior, pointer calculations, focus, popup placement, rendered controls, or light-DOM slot assignment.
- Use a component's
automode only when it measures an objective layout failure it owns, such asrc-chip-groupexceedingmax-rows.
Container queries style descendants of the query container; they do not set custom-element properties or attributes. Keep the query container on a stable consumer-owned ancestor:
.card-region {
container-type: inline-size;
}
@container (max-width: 28rem) {
.card-region rc-card {
--rc-card-grid-template-columns: minmax(0, 2fr) minmax(0, 3fr);
--rc-card-media-grid-row: 1 / -1;
--rc-card-media-grid-column: 1;
--rc-card-title-grid-row: 1;
--rc-card-title-grid-column: 2;
}
}
Do not use a CSS custom property as a hidden behavioral input that component
JavaScript reads with getComputedStyle(). CSS changes have no reliable
property-change notification, and server rendering, accessibility state, and
interaction logic can fall out of sync.
Adapt behavior from application state
rc-splitter.orientation affects pane geometry, drag and measurement axes,
arrow-key handling, collapse icons, and aria-orientation. Set the property
from application code when the containing region changes size:
const $region = document.querySelector('.workspace-region');
const $splitter = $region.querySelector('rc-splitter');
const observer = new ResizeObserver(([entry]) => {
const inlineSize = entry.borderBoxSize[0]?.inlineSize ?? entry.contentRect.width;
$splitter.orientation = inlineSize < 600 ? 'vertical' : 'horizontal';
});
observer.observe($region);
Apply the same boundary to structural states:
- Keep
rc-app-bar variant="compact|expanded"declarative because expanded mode adds measured collapse behavior. - Set
rc-adaptive-menu.maxShownfrom application responsive state because it moves authored controls between toolbar and menu semantics. CSS-hiding actions would not place them in the overflow menu. - Keep
rc-transfer-list compact, toolbar/menu orientation, slider orientation, navigation-rail expansion, search view mode, and select display mode property-driven because their rendered controls or interaction semantics change. - Set
--rc-carousel-slide-size, card region tracks, list-item region placement, and toolbar wrapping in CSS because those alter geometry only.
CSS parts
Components expose named parts for styling elements that are inside shadow
DOM. Use the ::part() selector:
/* Style the trigger button inside rc-select */
rc-select::part(trigger) {
font-weight: 500;
letter-spacing: 0.01em;
}
/* Style the toggle indicator */
rc-select::part(toggle-indicator) {
color: var(--rc-accent);
}
Available parts are listed in the API table under the Parts section on each component's page.
Styling hooks and ownership
Use the narrowest public styling surface that expresses the change:
- Override a shared semantic token at a real theme ancestor when the decision should flow through nested light and shadow trees.
- Override a component token on one component when changing a documented adaptation point such as geometry, color, or typography.
- Use a CSS part when styling a shadow-owned element requires selectors or declarations that cannot be represented by one token.
- Use a documented
data-rc-*marker when consumer-authored light-DOM content must declare a structural or behavioral role. - Use a theme modifier class or theme-specific data attribute only for an optional visual recipe supplied by that theme.
The data-rc-* prefix identifies ownership, not visibility. Documented markers
such as data-rc-button-icon, data-rc-field-control, and
data-rc-bottom-sheet-handle are author-facing contracts. Other markers are
written by components or shared controllers for measurement, coordination, or
style deduplication and are not consumer APIs. Do not depend on a marker unless
the component or theme documentation explicitly exposes it.
Prefer native or ARIA state selectors such as [open], :checked,
[aria-selected], and [aria-current]. Components expose documented host
data-* state when the authoritative state cannot otherwise be selected by a
theme. Theme CSS may style that state, but it must not use CSS to create a
second behavioral source of truth.
Public tokens, parts, and documented markers are versioned API. The repository architecture audit tracks their usage along with private theme overrides and ID-selector complexity. Net growth requires a documented consumer need and an explicit budget rationale; prefer consolidating an existing hook over creating an overlapping one.
Cascade layers
Shadow-DOM component styles are scoped by the shadow tree and do not share the
document's layer order. Components that must install structural light-DOM CSS
place it in the rc-base layer and deduplicate it per document or shadow root.
Consumer rules outside a layer therefore override these structural defaults
without selector specificity contests.
Each packaged theme declares its ordered layers after rc-base:
@layer rc-base, rc-theme.defaults, rc-theme.bridge, rc-theme.native,
rc-theme.components, rc-theme.css-components, rc-theme.overrides;
Naming rc-base first keeps component structural CSS below the theme even though
components inject it at runtime, after the theme stylesheet has loaded. A layer is
ordered by its first declaration, so without this an injected rc-base would become
the last and strongest layer. An application that declares its own layer order should
also list rc-base before the theme layers.
The real names include the theme package, such as
rc-theme-material.components. Defaults own the theme's raw source tokens,
the bridge maps those tokens to shared and component RC tokens. The opt-in
native layer is a convenience for styling ordinary HTML controls throughout
an application without composing every control from RC elements. Component
recipes can style native children when their presentation belongs to a themed
menu, toolbar, or other component context. components holds element-specific
recipes, parts, contextual selectors, and visual variants for registered RC elements.
The separate opt-in css-components layer styles native elements carrying documented
classes such as .rc-button, .rc-chip, .rc-select, .rc-card, and .rc-list,
plus details.rc-disclosure. These recipes provide appearance and CSS-visible states
only; they do not add behavior, events, popup replacement, or measured overflow.
Overrides hold the few contextual rules that must beat every component
variant, such as rc-adaptive-menu overflow rows, which restyle a moved rc-button
or rc-menu-button as a menu row whatever its own variant. Normal application rules
outside a layer outrank all theme layers, which provides a straightforward
consumer override path. Avoid routine
!important: important declarations reverse layer precedence.
This is also why a packaged theme's class belongs on a container, as shown
below, not on <html>. The shared base.css declares no layer at all, so
its :root values act as normal application rules and outrank every theme
layer for that same reason. On a container, a theme's own value is a direct
declaration that beats an inherited one regardless of layer; on <html>,
:root and the theme class target the same element, and :root's
layer-free value wins outright.
Native and CSS-only recipes
The native entrypoint keeps browser behavior and form semantics intact. The CSS-only recipes add appearance and CSS-visible states to ordinary HTML; they do not register elements or replace popups. Load a theme's defaults and bridge when you want its token values, then opt into the two layers:
@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 fills in controls that a component recipe does not style, including
consumer-authored controls inside toolbars, dialogs, cards, and rich popup
content. A component's themed presentation takes precedence for controls it
styles itself, such as menu rows and triggers. The boundary follows the
control's role in that component rather than every descendant of an RC host.
Add data-rc-native="off" to an element to opt it and its descendants out of
the native layer, for example when embedding a separately styled widget.
The same entrypoints exist for the Substrate theme README, Material theme README, and Win31 theme README. Supported class recipes use native elements directly:
<main class="rc-theme-material">
<button class="rc-button" type="button">Save</button>
<label class="rc-chip"><input type="checkbox" /> Filter</label>
<div class="rc-chip-group"><button class="rc-chip" type="button">One</button></div>
<label for="css-choice">Choice</label>
<select id="css-choice" class="rc-select">
<option>Choose one</option>
</select>
<textarea class="rc-textarea" aria-label="Notes"></textarea>
<article class="rc-card">Card content</article>
<ul class="rc-list">
<li>
<label><input type="checkbox" checked /> Selected item</label>
</li>
</ul>
<details class="rc-disclosure">
<summary>More</summary>
<p>Details</p>
</details>
</main>
Use a[href].rc-button or a[href].rc-chip for links. A checkbox or radio
inside .rc-chip remains in the document and is visually concealed only by
the recipe, so its label, keyboard focus, and form behavior remain native.
Substrate reference theme
The optional @rcarls/rc-theme-substrate package is the canonical reference
theme. It is a lightweight, app-oriented foundation that maps a small orange
brand palette and neutral surface system onto the RC token layer. Use it as-is,
or copy its token bridge as a starting point for your own branded theme.
npm install @rcarls/rc-theme-substrate
Import the full theme bundle:
@import '@rcarls/rc-theme-substrate/theme.css';
Or import the token bridge and selected component polish:
@import '@rcarls/rc-theme-substrate/bridge.css';
@import '@rcarls/rc-theme-substrate/components.css';
Native controls and CSS-only recipes are independent opt-ins:
@import '@rcarls/rc-theme-substrate/defaults.css';
@import '@rcarls/rc-theme-substrate/bridge.css';
@import '@rcarls/rc-theme-substrate/native.css';
@import '@rcarls/rc-theme-substrate/css-components.css';
Apply the rc-theme-substrate class to a container to scope the theme:
<div class="rc-theme-substrate">
<rc-select>...</rc-select>
<rc-dialog>...</rc-dialog>
</div>
Substrate includes modern CSS such as cascade layers, color-mix(),
oklch(), @starting-style, and discrete transition rules where supported.
View Transitions remain application opt-in: the theme exposes CSS hooks, but
application code decides when to call document.startViewTransition().
Material theme
The optional @rcarls/rc-theme-material package maps Material 3 design
tokens to the RC token layer. It changes styling only; no behavior changes.
For composing components into a Material 3 app, including adaptive layouts, dialogs, sheets, lists and navigation, see the package's design guide.
npm install @rcarls/rc-theme-material
Import the full theme bundle:
@import '@rcarls/rc-theme-material/theme.css';
Or import layers selectively if your app already provides Material system tokens:
@import '@rcarls/rc-theme-material/bridge.css';
@import '@rcarls/rc-theme-material/components.css';
Native controls and CSS-only recipes are independent opt-ins. Add native.css
for ordinary controls inside the theme scope and css-components.css (or a
selective css-components/<name>.css) for native HTML using the documented
classes:
@import '@rcarls/rc-theme-material/bridge.css';
@import '@rcarls/rc-theme-material/native.css';
@import '@rcarls/rc-theme-material/css-components.css';
components.css includes the .rc-state-layer utility. Apply that class to
interactive elements that already own their border radius when you want a
CSS-only Material state layer.
Apply the rc-theme-material class to a container to scope the theme:
<div class="rc-theme-material">
<rc-select>...</rc-select>
<rc-fab>...</rc-fab>
</div>
Scale text within a Material theme region
Add data-rc-type-scale to a region and set --rc-type-scale to a positive
number. The full theme.css bundle multiplies Material type sizes and line
heights, along with RC text tokens, inside that region. Text outside it retains
its existing scale.
<div class="rc-theme-material">
<main data-rc-type-scale style="--rc-type-scale: 1.25">
<p>Reading view</p>
<rc-button><button type="button">Continue</button></rc-button>
</main>
</div>
Place the marker on the rc-theme-material root to scale the whole theme.
A nested marker uses its own factor in place of the outer factor. If you import
only bridge.css with your own Material tokens, the marker scales RC text
tokens from those values; your application's Material tokens remain unchanged.
When both final Material type tokens and their *-value source tokens are
present, the source tokens supply the scale baseline.
For rc-button[icon-only], Material supplies
rc-button--extra-small, rc-button--medium, rc-button--large, and
rc-button--extra-large size classes. Combine them with
rc-button--narrow or rc-button--wide to change the container width while
keeping the selected height and icon size. The unmodified size is the Material
small icon button. rc-menu-button[icon-only] also supports
rc-menu-button--narrow for a narrow small trigger. All visually compact
variants retain the component package's independent 3rem activation area.
Direct native buttons in an rc-app-bar's leading and trailing slots use
the same small icon-button geometry, while nested component controls retain
their own sizing.
Windows 3.1 theme
The optional @rcarls/rc-theme-win31 package is a period theme: the beveled,
square, motionless chrome of Windows 3.1 as it looked to applications that
linked CTL3D. It changes styling only.
npm install @rcarls/rc-theme-win31
@import '@rcarls/rc-theme-win31/theme.css';
<div class="rc-theme-win31">
<rc-select>...</rc-select>
<rc-dialog>...</rc-dialog>
</div>
Unlike the other packaged themes, its component stylesheets read the
--win31-* tokens with no literal fallbacks, so a value lives in exactly one
place and cannot drift between the token layer and thirty-nine component
sheets. Import defaults.css before any selective import, or supply the
--win31-* set yourself:
@import '@rcarls/rc-theme-win31/defaults.css';
@import '@rcarls/rc-theme-win31/bridge.css';
@import '@rcarls/rc-theme-win31/components/button.css';
Native controls and CSS-only recipes are separate opt-ins. With the defaults
and bridge loaded, import native.css for ordinary controls or
css-components.css (or a selective css-components/<name>.css) for the
documented native classes and details.rc-disclosure.
Three properties of the theme are deliberate and worth knowing before you adopt it:
- It is light only. Windows 3.1 had user-selectable whole-system color
schemes rather than an automatic dark mode. Override the
--win31-color-*roles together. The dither follows the surface token, while the black glyph image tokens may need replacement for a contrasting scheme. - It has no hover states, except on menus, which is period-correct and can surprise people. Push buttons and list rows look identical at rest and under the pointer.
- It disappears under forced colors. Every bevel is an inset shadow, a
four-value
border-color, or a dither image, and High Contrast removes all three. The theme yields completely rather than fighting it.
Scale the whole theme from one token when you need it larger, without changing any proportion:
.rc-theme-win31 {
--win31-unit: 2px;
}
See Theme previews to compare components with and without each packaged theme applied. The package design guide documents composition, historical references, and visual limitations.