# Theme property reference
This reference describes the public theme construction types and every token/component property currently supported by the semantic component themes. The values below are the resolved output of `createASTheme()` and `createASTheme({ preset: 'neutral' })`, read directly from the factory. They are CSS inputs, not browser-computed pixel measurements. CSS inheritance, fonts, layout, and explicit component props can still affect the rendered result.
For composition and compatibility rules, see [Applying an ASUI theme](./theme-provider.md). For native button behavior, see [Native buttons](./native-buttons.md).
## Create a project theme
```tsx
import { ASThemeProvider, ComponentSize, createASTheme } from '@eleventheye/asui';
import type { ASThemeInput } from '@eleventheye/asui';
const themeInput = {
preset: 'neutral',
tokens: {
color: {
accent: 'var(--project-primary, #175cd3)',
onAccent: 'var(--project-on-primary, #ffffff)',
accentHover: 'var(--project-primary-hover, #1849a9)',
accentPressed: 'var(--project-primary-pressed, #194185)',
},
typography: { fontFamily: 'Barlow Condensed, sans-serif' },
},
components: {
button: { sizes: { [ComponentSize.Small]: { padding: '0 12px' } } },
textfield: { sizes: { [ComponentSize.Small]: { inputFocusShadow: 'none' } } },
},
} satisfies ASThemeInput;
const projectTheme = createASTheme(themeInput);
// Wrap the application (or a subtree):
{children};
```
Load the font in the consuming application. Define project CSS variables on an ancestor shared with portal content, usually `:root`; a theme provider supplies React context but creates no CSS-variable scope in the DOM.
## Public types and defaults
| Type / property | Meaning | Default when omitted |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `ASThemePreset` | `'classic'` preserves ASUI styling; `'neutral'` supplies a flat token-derived starting point. | `'classic'` in the factory |
| `ASThemeInput.preset` | Preset for `createASTheme(input)`. | `'classic'` |
| `ASThemeInput.tokens` / `ASThemeOverrides.tokens` | Deep partial `ASThemeTokens`. | Preset tokens, or inherited tokens when extending |
| `ASThemeInput.components` / `ASThemeOverrides.components` | Deep partial `ASThemeComponents`; explicit exceptions after token derivation. | Derived component styles, retaining inherited explicit exceptions |
| `ASThemePartial` | Makes nested object properties optional; arrays replace atomically. | No independent runtime default |
| `ASThemeProps.theme` | Complete replacement of the inherited theme. | Nearest provider, otherwise ASUI classic defaults |
| `ASThemeProps.themeOverrides` | Partial changes applied to the inherited theme. | No local changes |
| `ASThemeProviderInput` | Mutually exclusive `theme` or `themeOverrides`. | Inherit the parent/default theme |
| `ASResolvedTheme.themeVersion` | Resolved theme format marker. | `2` |
| `ASResolvedTheme.preset` | Preset used to construct the resolved theme. | Factory input, otherwise `'classic'` |
| `ASResolvedTheme.tokens` | Complete token values. | Tables below |
| `ASResolvedTheme.components` | Complete styles for `icon`, `button`, `iconbutton`, `dropdown`, `textfield`, `loader`, `switch`, `snackbar`, `modal`, `choicebar`, `chartbar`, and `chartdonut`. | Tables below |
`createASTheme(input)` and `extendASTheme(theme, overrides)` return detached, deeply frozen themes. Use the factory/extension APIs rather than mutating or reconstructing resolved objects. Persist the input definition instead of JSON-serializing the resolved output, which carries private composition metadata.
Do not supply both `theme` and `themeOverrides`. The provider enforces that in TypeScript; component props remain extendable interfaces and reject conflicting inputs at runtime. `ASLoader.theme` is the compatibility exception: it accepts a complete legacy `ASLoaderTheme` section, while its `themeOverrides` accepts the modern full-theme override shape.
## Values and precedence
1. Start with the selected preset.
2. Apply token overrides and derive the affected component recipes.
3. Apply explicit component overrides. These exceptions remain in place when a theme is extended later.
4. Components use the resolved styles, with documented explicit props such as icon size/fill/stroke taking precedence.
`undefined` leaves the existing value intact. Explicit `0`, empty strings, and `'none'` are retained. Unknown properties, null, invalid value types, and non-finite numbers are rejected. CSS strings are not parsed or validated for browser support.
Most values are CSS strings: supply units for lengths (for example `'8px'`), complete shorthands for backgrounds/shadows/outlines, and a time unit for motion duration. Properties named fontWeight accept strings or numbers; loader textWeight currently requires a string at runtime despite its wider TypeScript type; `interactionScale` and icon sizes are numbers. A CSS variable is valid wherever its resolved value matches the target CSS property's grammar. Color tokens must resolve to colors; a full gradient belongs in a component background slot.
**Classic token defaults are not identical to the classic component recipe.** Classic deliberately preserves historical gradients, typography, radii, and spacing until a relevant token is explicitly supplied. Supplying even a token's default value is an intentional override and can activate a derived recipe. For `chartdonut`, explicit `typography.fontFamily` updates both label fonts, and explicit `typography.fontWeight` updates main and secondary labels at every size. Supplying `motion` derives both arc durations and easing from the resolved motion tokens, even when only one motion field is supplied; `motionDelay` remains unchanged. Explicit `components.chartdonut` overrides take precedence over these derived values. Neutral derives its styles from the full token set. Hover, pressed, and on-accent colors are independent inputs, not automatically computed shades or contrast colors.
`tokens.size` uses `ASSmall`, `ASMedium`, and `ASLarge` (the values of `ComponentSize.Small`, `Medium`, and `Large`). Component tables use the same keys under `sizes`. Loader geometry is separate from `tokens.size`. Motion tokens do not configure loader animation durations or dropdown transitions.
## Theme tokens — @interface [`ASThemeTokens`](../src/astheme/ASTheme.types.ts#L17)
Configure these properties under `tokens` in `createASTheme`, `extendASTheme`, or `themeOverrides`.
Shared tokens supply defaults to component recipes. Component overrides remain explicit exceptions; see [Values and precedence](#values-and-precedence).
| Property | Description | Classic default | Neutral default |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | ----------------------- |
| `color.surface` | Surface color for fields, dropdowns, and classic gradient recipes. | `#fff5b2` | `#ffffff` |
| `color.text` | Primary text color for fields and dropdowns; also loader text in the classic recipe. | `#333333` | `#333333` |
| `color.mutedText` | Placeholder and secondary icon color. | `#666666` | `#666666` |
| `color.accent` | Primary action color; also drives loader borders and neutral grow-track background. | `#ffd321` | `#175cd3` |
| `color.onAccent` | Text and icon color on action surfaces; also neutral loader text. | `#585858` | `#ffffff` |
| `color.accentHover` | Hovered action color and secondary loader color. Set explicitly; it is not calculated from accent. | `#fff5b2` | `#1849a9` |
| `color.accentPressed` | Pressed and selected action color. Set explicitly; it is not calculated from accent. | `#ffd321` | `#194185` |
| `color.border` | Control outline and field border color. | `#ffd321` | `#667085` |
| `color.focus` | Focus outline color and field focus border color. | `#867017` | `#175cd3` |
| `color.disabledSurface` | Disabled control background. | `#333333` | `#eaecf0` |
| `color.disabledText` | Disabled control text and icon color. | `#999999` | `#667085` |
| `color.invalid` | Invalid text-field border color. | `#b42318` | `#b42318` |
| `typography.fontFamily` | CSS font-family for buttons, icon buttons, dropdowns, text fields, loaders, switches, snackbars, choice bars, bar-chart labels, and donut labels/sublabels. Does not load a font. | `inherit` | `system-ui, sans-serif` |
| `typography.fontWeight` | CSS font-weight for buttons, icon buttons, dropdowns, text fields, choice-bar items, bar-chart labels, and all donut label/sublabel sizes. Loader weights remain per-size component settings. | `400` | `400` |
| `radius.control` | CSS border-radius for buttons, icon buttons, dropdowns, the text-field outer container, and grow loaders. The inner input radius is separate. | `75px` | `6px` |
| `motion.duration` | CSS time used for control transitions, bar-chart fills, and both primary/additional donut arcs. Donut delay remains a component setting; loader animation timing is unchanged. | `0.25s` | `0.25s` |
| `motion.easing` | CSS easing function used for control and chart transitions, including donut arcs. | `ease-in-out` | `ease-in-out` |
| `size.ASSmall.height` | Control height; button rendering uses a minimum height. Does not size loaders. | `30px` | `30px` |
| `size.ASSmall.fontSize` | Control font-size. Does not change loader text size. | `1rem` | `1rem` |
| `size.ASSmall.paddingInline` | Horizontal padding recipe input for buttons and dropdowns. Icon buttons keep zero padding; text fields and loaders use component slots. Classic dropdown paddingWithIcon remains separate. | `10px` | `10px` |
| `size.ASMedium.height` | Control height; button rendering uses a minimum height. Does not size loaders. | `40px` | `40px` |
| `size.ASMedium.fontSize` | Control font-size. Does not change loader text size. | `1.2rem` | `1.2rem` |
| `size.ASMedium.paddingInline` | Horizontal padding recipe input for buttons and dropdowns. Icon buttons keep zero padding; text fields and loaders use component slots. Classic dropdown paddingWithIcon remains separate. | `30px` | `30px` |
| `size.ASLarge.height` | Control height; button rendering uses a minimum height. Does not size loaders. | `50px` | `50px` |
| `size.ASLarge.fontSize` | Control font-size. Does not change loader text size. | `1.5rem` | `1.5rem` |
| `size.ASLarge.paddingInline` | Horizontal padding recipe input for buttons and dropdowns. Icon buttons keep zero padding; text fields and loaders use component slots. Classic dropdown paddingWithIcon remains separate. | `50px` | `50px` |
## ASButton — @interface [`ASControlStyles`](../src/astheme/ASTheme.types.ts#L93)
Configure these properties under `components.button` in `createASTheme`, `extendASTheme`, or `themeOverrides`.
ASButton rendering modes share these surface states and typography. Native mode does not use the default label scaling or labelHoverShadow decoration. Icon color slots belong to the shared type but are only read by ASIconButton.
State order is rest, hover (enabled and neither active nor selected), selected, pressed, then disabled. Visible focus has a separate outline. Per-size hoverShadows/pressedShadows only work when the state shadow references the corresponding CSS variable; neutral defaults use none.
| Property | Description | Classic default | Neutral default |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| `fontFamily` | CSS font-family. | `inherit` | `system-ui, sans-serif` |
| `fontWeight` | CSS font-weight. | `400` | `400` |
| `textTransform` | CSS text-transform. | `uppercase` | `none` |
| `radius` | CSS border-radius. | `75px` | `6px` |
| `minWidth` | CSS min-width. | `100px` | `0` |
| `borderWidth` | CSS outline width for ordinary states; focusRing defines its own width. | `2px` | `2px` |
| `transition` | Complete CSS transition declaration. Reduced-motion styles disable it. | `all 0.25s ease-in-out` | `background 0.25s ease-in-out, color 0.25s ease-in-out, box-shadow 0.25s ease-in-out` |
| `interactionScale` | Numeric scale for the default button label and active/selected icon-button content. Native ASButton does not use this decoration. | `0.95` | `1` |
| `focusRing` | Complete CSS outline shorthand for visible keyboard focus, such as 2px solid blue or none. | `2px solid #ffd321` | `2px solid #175cd3` |
| `focusRingOffset` | CSS outline-offset for visible focus. | `3px` | `3px` |
| `outlineOffset` | Ordinary button/icon-button outline offset; keyboard focus uses focusRingOffset. | `0px` | `0px` |
| `labelHoverShadow` | CSS box-shadow for the default ASButton label hover decoration. Not used by native buttons or icon buttons. | `none` | `none` |
| `iconColor` | ASIconButton default glyph fill; explicit fillColor wins. Disabled/loading uses disabled.color. ASButton does not read this slot. | `#585858` | `#ffffff` |
| `iconStrokeColor` | ASIconButton default glyph stroke; explicit strokeColor wins. Disabled/loading uses disabled.color. ASButton does not read this slot. | `#fff5b2` | `#ffffff` |
| `sizes.ASSmall.height` | Button minimum height; icon-button height. | `30px` | `30px` |
| `sizes.ASSmall.fontSize` | CSS font-size. | `1rem` | `1rem` |
| `sizes.ASSmall.lineHeight` | CSS line-height, either unitless or a length. | `1.875rem` | `1.25` |
| `sizes.ASSmall.padding` | Complete CSS padding shorthand for the button content or icon-button surface. | `0 10px` | `0 10px` |
| `sizes.ASMedium.height` | Button minimum height; icon-button height. | `40px` | `40px` |
| `sizes.ASMedium.fontSize` | CSS font-size. | `1.2rem` | `1.2rem` |
| `sizes.ASMedium.lineHeight` | CSS line-height, either unitless or a length. | `2.25rem` | `1.25` |
| `sizes.ASMedium.padding` | Complete CSS padding shorthand for the button content or icon-button surface. | `2px 30px` | `0 30px` |
| `sizes.ASLarge.height` | Button minimum height; icon-button height. | `50px` | `50px` |
| `sizes.ASLarge.fontSize` | CSS font-size. | `1.5rem` | `1.5rem` |
| `sizes.ASLarge.lineHeight` | CSS line-height, either unitless or a length. | `2.5rem` | `1.25` |
| `sizes.ASLarge.padding` | Complete CSS padding shorthand for the button content or icon-button surface. | `5px 50px` | `0 50px` |
| `rest.background` | Complete CSS background, including a solid color or gradient. | `linear-gradient(to bottom, #fff5b2 0%, #ffd321 100%)` | `#175cd3` |
| `rest.color` | CSS text color. | `#585858` | `#ffffff` |
| `rest.borderColor` | CSS outline color; the control uses an outline rather than a border for this state. | `#ffd321` | `#667085` |
| `rest.shadow` | Complete CSS box-shadow, or none. | `inset 0 0 1px 0 #fff5b2` | `none` |
| `rest.textShadow` | Complete CSS text-shadow, or none. | `-1px -1px 1px rgba(255, 255, 255, 0.3), 1px 1px 1px rgba(0, 0, 0, 0.2)` | `none` |
| `hover.background` | Complete CSS background, including a solid color or gradient. | `linear-gradient(to top, #fff5b2 0%, #ffd321 100%)` | `#1849a9` |
| `hover.color` | CSS text color. | `#414141` | `#ffffff` |
| `hover.borderColor` | CSS outline color; the control uses an outline rather than a border for this state. | `#ffd321` | `#667085` |
| `hover.shadow` | Complete CSS box-shadow, or none. | `var(--asui-control-hover-shadow)` | `none` |
| `hover.textShadow` | Complete CSS text-shadow, or none. | `-1px -1px 1px rgba(255, 255, 255, 0.3), 1px 1px 1px rgba(0, 0, 0, 0.2)` | `none` |
| `pressed.background` | Complete CSS background, including a solid color or gradient. | `linear-gradient(to top, #fff5b2 0%, #ffd321 100%)` | `#194185` |
| `pressed.color` | CSS text color. | `#414141` | `#ffffff` |
| `pressed.borderColor` | CSS outline color; the control uses an outline rather than a border for this state. | `#ffd321` | `#667085` |
| `pressed.shadow` | Complete CSS box-shadow, or none. | `var(--asui-control-pressed-shadow)` | `none` |
| `pressed.textShadow` | Complete CSS text-shadow, or none. | `-1px -1px 1px rgba(255, 255, 255, 0.3), 1px 1px 1px rgba(0, 0, 0, 0.2)` | `none` |
| `selected.background` | Complete CSS background, including a solid color or gradient. | `linear-gradient(to top, #fff5b2 0%, #ffd321 100%)` | `#194185` |
| `selected.color` | CSS text color. | `#414141` | `#ffffff` |
| `selected.borderColor` | CSS outline color; the control uses an outline rather than a border for this state. | `#ffd321` | `#667085` |
| `selected.shadow` | Complete CSS box-shadow, or none. | `var(--asui-control-pressed-shadow)` | `none` |
| `selected.textShadow` | Complete CSS text-shadow, or none. | `-1px -1px 1px rgba(255, 255, 255, 0.3), 1px 1px 1px rgba(0, 0, 0, 0.2)` | `none` |
| `disabled.background` | Complete CSS background, including a solid color or gradient. | `#333333` | `#eaecf0` |
| `disabled.color` | CSS text color. | `#999999` | `#667085` |
| `disabled.borderColor` | CSS outline color; the control uses an outline rather than a border for this state. | `#ffd321` | `#667085` |
| `disabled.shadow` | Complete CSS box-shadow, or none. | `none` | `none` |
| `disabled.textShadow` | Complete CSS text-shadow, or none. | `none` | `none` |
| `hoverShadows.ASSmall` | Per-size CSS box-shadow; effective when the corresponding state shadow references its size variable. | `inset 0 0 1px 0 #a47200` | `none` |
| `hoverShadows.ASMedium` | Per-size CSS box-shadow; effective when the corresponding state shadow references its size variable. | `inset 0 0 4px 0 #a47200` | `none` |
| `hoverShadows.ASLarge` | Per-size CSS box-shadow; effective when the corresponding state shadow references its size variable. | `inset 0 0 6px 0 #a47200` | `none` |
| `pressedShadows.ASSmall` | Per-size CSS box-shadow; effective when the corresponding state shadow references its size variable. | `inset 0 0 5px 1px #a47200` | `none` |
| `pressedShadows.ASMedium` | Per-size CSS box-shadow; effective when the corresponding state shadow references its size variable. | `inset 0 0 6px 1px #a47200` | `none` |
| `pressedShadows.ASLarge` | Per-size CSS box-shadow; effective when the corresponding state shadow references its size variable. | `inset 0 0 11px 2px #a47200` | `none` |
## ASIconButton — @interface [`ASIconButtonStyles`](../src/astheme/ASTheme.types.ts#L153)
Configure these properties under `components.iconbutton` in `createASTheme`, `extendASTheme`, or `themeOverrides`.
Includes the complete control style contract plus iconSizes. Defaults are shown separately because geometry and classic transition duration differ from ASButton. Explicit iconSize, fillColor, and strokeColor props take precedence.
| Property | Description | Classic default | Neutral default |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| `fontFamily` | CSS font-family. | `inherit` | `system-ui, sans-serif` |
| `fontWeight` | CSS font-weight. | `400` | `400` |
| `textTransform` | CSS text-transform. | `uppercase` | `none` |
| `radius` | CSS border-radius. | `75px` | `6px` |
| `minWidth` | CSS min-width. | `0` | `0` |
| `borderWidth` | CSS outline width for ordinary states; focusRing defines its own width. | `2px` | `2px` |
| `transition` | Complete CSS transition declaration. Reduced-motion styles disable it. | `all 0.15s ease-in-out` | `background 0.25s ease-in-out, color 0.25s ease-in-out, box-shadow 0.25s ease-in-out` |
| `interactionScale` | Numeric scale for the default button label and active/selected icon-button content. Native ASButton does not use this decoration. | `0.95` | `1` |
| `focusRing` | Complete CSS outline shorthand for visible keyboard focus, such as 2px solid blue or none. | `2px solid #ffd321` | `2px solid #175cd3` |
| `focusRingOffset` | CSS outline-offset for visible focus. | `3px` | `3px` |
| `outlineOffset` | Ordinary button/icon-button outline offset; keyboard focus uses focusRingOffset. | `0px` | `0px` |
| `labelHoverShadow` | CSS box-shadow for the default ASButton label hover decoration. Not used by native buttons or icon buttons. | `none` | `none` |
| `iconColor` | ASIconButton default glyph fill; explicit fillColor wins. Disabled/loading uses disabled.color. ASButton does not read this slot. | `#585858` | `#ffffff` |
| `iconStrokeColor` | ASIconButton default glyph stroke; explicit strokeColor wins. Disabled/loading uses disabled.color. ASButton does not read this slot. | `#fff5b2` | `#ffffff` |
| `sizes.ASSmall.height` | Button minimum height; icon-button height. | `30px` | `30px` |
| `sizes.ASSmall.fontSize` | CSS font-size. | `1rem` | `1rem` |
| `sizes.ASSmall.lineHeight` | CSS line-height, either unitless or a length. | `1.875rem` | `1.25` |
| `sizes.ASSmall.padding` | Complete CSS padding shorthand for the button content or icon-button surface. | `0` | `0` |
| `sizes.ASMedium.height` | Button minimum height; icon-button height. | `40px` | `40px` |
| `sizes.ASMedium.fontSize` | CSS font-size. | `1.2rem` | `1.2rem` |
| `sizes.ASMedium.lineHeight` | CSS line-height, either unitless or a length. | `2.25rem` | `1.25` |
| `sizes.ASMedium.padding` | Complete CSS padding shorthand for the button content or icon-button surface. | `0` | `0` |
| `sizes.ASLarge.height` | Button minimum height; icon-button height. | `50px` | `50px` |
| `sizes.ASLarge.fontSize` | CSS font-size. | `1.5rem` | `1.5rem` |
| `sizes.ASLarge.lineHeight` | CSS line-height, either unitless or a length. | `2.5rem` | `1.25` |
| `sizes.ASLarge.padding` | Complete CSS padding shorthand for the button content or icon-button surface. | `0` | `0` |
| `rest.background` | Complete CSS background, including a solid color or gradient. | `linear-gradient(to bottom, #fff5b2 0%, #ffd321 100%)` | `#175cd3` |
| `rest.color` | CSS text color. | `#585858` | `#ffffff` |
| `rest.borderColor` | CSS outline color; the control uses an outline rather than a border for this state. | `#ffd321` | `#667085` |
| `rest.shadow` | Complete CSS box-shadow, or none. | `inset 0 0 1px 0 #fff5b2` | `none` |
| `rest.textShadow` | Complete CSS text-shadow, or none. | `-1px -1px 1px rgba(255, 255, 255, 0.3), 1px 1px 1px rgba(0, 0, 0, 0.2)` | `none` |
| `hover.background` | Complete CSS background, including a solid color or gradient. | `linear-gradient(to top, #fff5b2 0%, #ffd321 100%)` | `#1849a9` |
| `hover.color` | CSS text color. | `#414141` | `#ffffff` |
| `hover.borderColor` | CSS outline color; the control uses an outline rather than a border for this state. | `#ffd321` | `#667085` |
| `hover.shadow` | Complete CSS box-shadow, or none. | `var(--asui-control-hover-shadow)` | `none` |
| `hover.textShadow` | Complete CSS text-shadow, or none. | `-1px -1px 1px rgba(255, 255, 255, 0.3), 1px 1px 1px rgba(0, 0, 0, 0.2)` | `none` |
| `pressed.background` | Complete CSS background, including a solid color or gradient. | `linear-gradient(to top, #fff5b2 0%, #ffd321 100%)` | `#194185` |
| `pressed.color` | CSS text color. | `#414141` | `#ffffff` |
| `pressed.borderColor` | CSS outline color; the control uses an outline rather than a border for this state. | `#ffd321` | `#667085` |
| `pressed.shadow` | Complete CSS box-shadow, or none. | `var(--asui-control-pressed-shadow)` | `none` |
| `pressed.textShadow` | Complete CSS text-shadow, or none. | `-1px -1px 1px rgba(255, 255, 255, 0.3), 1px 1px 1px rgba(0, 0, 0, 0.2)` | `none` |
| `selected.background` | Complete CSS background, including a solid color or gradient. | `linear-gradient(to top, #fff5b2 0%, #ffd321 100%)` | `#194185` |
| `selected.color` | CSS text color. | `#414141` | `#ffffff` |
| `selected.borderColor` | CSS outline color; the control uses an outline rather than a border for this state. | `#ffd321` | `#667085` |
| `selected.shadow` | Complete CSS box-shadow, or none. | `var(--asui-control-pressed-shadow)` | `none` |
| `selected.textShadow` | Complete CSS text-shadow, or none. | `-1px -1px 1px rgba(255, 255, 255, 0.3), 1px 1px 1px rgba(0, 0, 0, 0.2)` | `none` |
| `disabled.background` | Complete CSS background, including a solid color or gradient. | `#333333` | `#eaecf0` |
| `disabled.color` | CSS text color. | `#999999` | `#667085` |
| `disabled.borderColor` | CSS outline color; the control uses an outline rather than a border for this state. | `#ffd321` | `#667085` |
| `disabled.shadow` | Complete CSS box-shadow, or none. | `none` | `none` |
| `disabled.textShadow` | Complete CSS text-shadow, or none. | `none` | `none` |
| `hoverShadows.ASSmall` | Per-size CSS box-shadow; effective when the corresponding state shadow references its size variable. | `inset 0 0 1px 0 #a47200` | `none` |
| `hoverShadows.ASMedium` | Per-size CSS box-shadow; effective when the corresponding state shadow references its size variable. | `inset 0 0 4px 0 #a47200` | `none` |
| `hoverShadows.ASLarge` | Per-size CSS box-shadow; effective when the corresponding state shadow references its size variable. | `inset 0 0 6px 0 #a47200` | `none` |
| `pressedShadows.ASSmall` | Per-size CSS box-shadow; effective when the corresponding state shadow references its size variable. | `inset 0 0 5px 1px #a47200` | `none` |
| `pressedShadows.ASMedium` | Per-size CSS box-shadow; effective when the corresponding state shadow references its size variable. | `inset 0 0 6px 1px #a47200` | `none` |
| `pressedShadows.ASLarge` | Per-size CSS box-shadow; effective when the corresponding state shadow references its size variable. | `inset 0 0 11px 2px #a47200` | `none` |
| `iconSizes.ASSmall` | Default glyph size in pixels. Explicit iconSize wins. | `18` | `18` |
| `iconSizes.ASMedium` | Default glyph size in pixels. Explicit iconSize wins. | `24` | `24` |
| `iconSizes.ASLarge` | Default glyph size in pixels. Explicit iconSize wins. | `30` | `30` |
## ASDropdown — @interface [`ASDropdownStyles`](../src/astheme/ASTheme.types.ts#L159)
Configure these properties under `components.dropdown` in `createASTheme`, `extendASTheme`, or `themeOverrides`.
The select and custom caret use these styles. Native option-menu rendering remains platform-dependent. iconInset moves the leading icon; paddingWithIcon independently reserves text space.
| Property | Description | Classic default | Neutral default |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ----------------------- |
| `fontFamily` | CSS font-family for the select. | `inherit` | `system-ui, sans-serif` |
| `fontWeight` | CSS font-weight for the select. | `600` | `400` |
| `radius` | Select CSS border-radius. | `40px` | `6px` |
| `borderWidth` | Select CSS outline width for ordinary states. | `1px` | `1px` |
| `focusRing` | Complete CSS outline shorthand for visible keyboard focus. Pointer selection suppresses the persistent focus ring. | `2px solid #ffd321` | `2px solid #175cd3` |
| `focusRingOffset` | CSS outline-offset for visible focus. | `3px` | `3px` |
| `iconInset` | CSS left offset for the optional leading icon; adjust paddingWithIcon separately to retain a gap. | `8px` | `12px` |
| `caretColor` | CSS background-color of the custom caret; disabled uses disabled.color. | `#333333` | `#333333` |
| `caretHoverColor` | CSS background-color of the custom caret while enabled and hovered. | `#414141` | `#333333` |
| `rest.background` | Complete CSS background, including a solid color or gradient. | `linear-gradient(to top, #fff5b2 0%, #ffd321 100%)` | `#ffffff` |
| `rest.color` | CSS text color. | `#585858` | `#333333` |
| `rest.borderColor` | CSS outline color; the control uses an outline rather than a border for this state. | `#ffd321` | `#667085` |
| `rest.shadow` | Complete CSS box-shadow, or none. | `none` | `none` |
| `rest.textShadow` | Complete CSS text-shadow, or none. | `-1px -1px 1px rgba(255, 255, 255, 0.3), 1px 1px 1px rgba(0, 0, 0, 0.2)` | `none` |
| `hover.background` | Complete CSS background, including a solid color or gradient. | `linear-gradient(to bottom, #fff5b2 0%, #ffd321 100%)` | `#ffffff` |
| `hover.color` | CSS text color. | `#585858` | `#333333` |
| `hover.borderColor` | CSS outline color; the control uses an outline rather than a border for this state. | `#ffd321` | `#667085` |
| `hover.shadow` | Complete CSS box-shadow, or none. | `none` | `none` |
| `hover.textShadow` | Complete CSS text-shadow, or none. | `-1px -1px 1px rgba(255, 255, 255, 0.3), 0 0 1px rgba(0, 0, 0, 0.2)` | `none` |
| `disabled.background` | Complete CSS background, including a solid color or gradient. | `#333333` | `#eaecf0` |
| `disabled.color` | CSS text color. | `#999999` | `#667085` |
| `disabled.borderColor` | CSS outline color; the control uses an outline rather than a border for this state. | `#ffd321` | `#667085` |
| `disabled.shadow` | Complete CSS box-shadow, or none. | `none` | `none` |
| `disabled.textShadow` | Complete CSS text-shadow, or none. | `none` | `none` |
| `sizes.ASSmall.height` | Select CSS height. | `30px` | `30px` |
| `sizes.ASSmall.fontSize` | Select CSS font-size. | `1.05rem` | `1rem` |
| `sizes.ASSmall.padding` | Complete CSS padding shorthand without a leading icon; leave room for the caret. | `5px 30px 5px 15px` | `0 36px 0 10px` |
| `sizes.ASSmall.paddingWithIcon` | Complete CSS padding shorthand with a leading icon; leave room for both icon and caret. | `5px 30px 5px 36px` | `0 36px 0 48px` |
| `sizes.ASMedium.height` | Select CSS height. | `40px` | `40px` |
| `sizes.ASMedium.fontSize` | Select CSS font-size. | `1.35rem` | `1.2rem` |
| `sizes.ASMedium.padding` | Complete CSS padding shorthand without a leading icon; leave room for the caret. | `7px 35px 7px 15px` | `0 36px 0 30px` |
| `sizes.ASMedium.paddingWithIcon` | Complete CSS padding shorthand with a leading icon; leave room for both icon and caret. | `5px 35px 5px 40px` | `0 36px 0 48px` |
| `sizes.ASLarge.height` | Select CSS height. | `50px` | `50px` |
| `sizes.ASLarge.fontSize` | Select CSS font-size. | `1.55rem` | `1.5rem` |
| `sizes.ASLarge.padding` | Complete CSS padding shorthand without a leading icon; leave room for the caret. | `10px 40px 10px 20px` | `0 36px 0 50px` |
| `sizes.ASLarge.paddingWithIcon` | Complete CSS padding shorthand with a leading icon; leave room for both icon and caret. | `10px 40px 10px 44px` | `0 36px 0 48px` |
## ASTextField — @interface [`ASTextFieldStyles`](../src/astheme/ASTheme.types.ts#L201)
Configure these properties under `components.textfield` in `createASTheme`, `extendASTheme`, or `themeOverrides`.
Outer container and inner input have separate appearance slots. The shared inputFocusShadow defaults to a CSS variable that selects the active size’s shadow. Set a sizes entry for a one-size change, or replace the shared inputFocusShadow for every size. Autofill background is a color used in an inset shadow, not a general CSS background.
| Property | Description | Classic default | Neutral default |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| `fontFamily` | CSS font-family inherited by the input. | `inherit` | `system-ui, sans-serif` |
| `containerBackground` | Complete CSS background of the outer container. | `linear-gradient(to bottom, #fff5b2 5%, #ffd321 100%)` | `#ffffff` |
| `containerHoverShadow` | Outer container box-shadow while enabled and hovered without focus. | `none` | `none` |
| `containerFocusShadow` | Outer container box-shadow while focus is within the enabled field; takes precedence over hover. | `none` | `none` |
| `counterColor` | Multiline character-counter color; disabled uses disabledColor. | `#666666` | `#666666` |
| `counterFontSize` | Counter CSS font-size. | `0.875rem` | `0.875rem` |
| `counterFontWeight` | Counter CSS font-weight, supplied as a string. | `400` | `400` |
| `containerColor` | CSS text color of the outer container. | `#fff5b2` | `#333333` |
| `containerBorderColor` | Color of the outer container’s 1px solid outline. | `#ffd321` | `#667085` |
| `containerBorderRadius` | Outer container CSS border-radius. | `35px` | `6px` |
| `containerPadding` | Outer container CSS padding shorthand. | `0 12px` | `0 12px` |
| `containerPaddingWithoutIcons` | Single-line outer padding when neither icon is rendered. | `0` | `0` |
| `inputMarginInlineWithoutIcons` | Input margin on each side without an icon; explicit lengths override size insets. | `var(--asui-textfield-size-inset, 8px)` | `4px` |
| `inputMarginInline` | Horizontal input margin when icons are present. | `8px` | `8px` |
| `trailingIconMarginRight` | Right margin of clear/password controls. | `-2px` | `-2px` |
| `inputPaddingInline` | Horizontal padding inside the input/textarea, keeping text away from rounded corners. | `12px` | `12px` |
| `minWidth` | Outer container CSS min-width. | `250px` | `0` |
| `inputBackground` | Complete CSS background of the inner input. | `linear-gradient(to bottom, #ffd321 5%, #fff5b2 100%)` | `#ffffff` |
| `inputColor` | Inner input CSS text color. | `#333333` | `#333333` |
| `inputBorderColor` | Inner input border color; border width/style remain thin solid. | `#818181` | `transparent` |
| `inputBorderRadius` | Inner input CSS border-radius. | `4px` | `4px` |
| `multilineContainerBorderRadius` | Multiline outer-container corner radius. | `16px` | Control radius token |
| `multilineContainerPadding` | Multiline outer-container padding. | `4px 12px` | `0 12px` |
| `multilineSmallInputFocusShadow` | Small multiline hover/focus/active shadow when inputFocusShadow uses its default variable. | `inset 0 1px 8px 0px #333333` | `none` |
| `inputPlaceholderColor` | Placeholder CSS color; placeholder weight remains 300. | `#666666` | `#666666` |
| `inputFocusBackground` | Complete input background while focused or active. | `linear-gradient(to top, #ffd321 15%, #fff5b2 100%)` | `#ffffff` |
| `inputFocusBorderColor` | Input border color while hovered, focused, or active. | `#555555` | `#175cd3` |
| `inputFocusColor` | Input text color while focused or active. | `#333333` | `#333333` |
| `inputFocusShadow` | Input box-shadow on hover, focus, or active. The default variable selects sizes[size].inputFocusShadow; a direct value overrides every size. | `var(--asui-textfield-size-focus-shadow)` | `var(--asui-textfield-size-focus-shadow)` |
| `iconColor` | Default clear/search/password icon color. | `#333333` | `#333333` |
| `iconHoverColor` | Interactive field icon hover color. | `#333333` | `#333333` |
| `iconCircleColor` | Circle stroke color passed to the clear icon; currently has no visible effect because its circle is not enabled. | `#666666` | `#666666` |
| `autofillBackground` | CSS color painted as a large inset autofill shadow; use a color, not a gradient. | `#979797` | `#ffffff` |
| `autofillColor` | Autofill text fill color. | `#818181` | `#333333` |
| `autofillBorderColor` | Autofill border color. | `#979797` | `#667085` |
| `disabledBackground` | Complete CSS background of the disabled input and outer container. | `#333333` | `#eaecf0` |
| `disabledColor` | Disabled input and outer-container text color. | `#999999` | `#667085` |
| `invalidBorderColor` | Border and visible focus outline color when the input has aria-invalid=true. | `#cf410d` | `#b42318` |
| `invalidContainerBackground` | Outer field background when invalid. | `var(--asui-textfield-container-background)` (retains normal background) | `#ff927d` (`corral40`) |
| `invalidColor` | Invalid input and validation-message text color. | `#982900` | Text token (`#101828`) |
| `invalidFocusOutlineWidth` | Focus outline width when invalid. | `2px` | `2px` |
| `focusRing` | Complete CSS outline shorthand for visible focus on the input and clickable field icons. | `1px solid #555555` | `2px solid #175cd3` |
| `focusRingOffset` | CSS outline-offset for visible focus. | `0px` | `0px` |
| `transition` | Complete input CSS transition declaration. Reduced-motion styles disable it. | `all 0.5s ease-in-out` | `background 0.25s ease-in-out, color 0.25s ease-in-out, box-shadow 0.25s ease-in-out` |
| `sizes.ASSmall.height` | Outer container height. | `30px` | `30px` |
| `sizes.ASSmall.fontSize` | Input CSS font-size. | `0.9rem` | `1rem` |
| `sizes.ASSmall.fontWeight` | Input CSS font-weight. | `400` | `400` |
| `sizes.ASSmall.inputMarginBlock` | CSS length for each vertical input margin; subtracted twice from the container height to size the input. | `4px` | `4px` |
| `sizes.ASSmall.inputMarginInlineWithoutIcons` | Inset on each side without an icon when the shared margin uses its size variable. | `12px` | `4px` |
| `sizes.ASSmall.inputFocusShadow` | Per-size input box-shadow used when the shared inputFocusShadow retains its default CSS variable. | `none` | `none` |
| `sizes.ASMedium.height` | Outer container height. | `40px` | `40px` |
| `sizes.ASMedium.fontSize` | Input CSS font-size. | `1.25rem` | `1.2rem` |
| `sizes.ASMedium.fontWeight` | Input CSS font-weight. | `600` | `400` |
| `sizes.ASMedium.inputMarginBlock` | CSS length for each vertical input margin; subtracted twice from the container height to size the input. | `5px` | `4px` |
| `sizes.ASMedium.inputMarginInlineWithoutIcons` | Inset on each side without an icon when the shared margin uses its size variable. | `16px` | `4px` |
| `sizes.ASMedium.inputFocusShadow` | Per-size input box-shadow used when the shared inputFocusShadow retains its default CSS variable. | `inset 0 1px 7px 1px #333333` | `none` |
| `sizes.ASLarge.height` | Outer container height. | `50px` | `50px` |
| `sizes.ASLarge.fontSize` | Input CSS font-size. | `1.4rem` | `1.5rem` |
| `sizes.ASLarge.fontWeight` | Input CSS font-weight. | `600` | `400` |
| `sizes.ASLarge.inputMarginBlock` | CSS length for each vertical input margin; subtracted twice from the container height to size the input. | `6px` | `4px` |
| `sizes.ASLarge.inputMarginInlineWithoutIcons` | Inset on each side without an icon when the shared margin uses its size variable. | `20px` | `4px` |
| `sizes.ASLarge.inputFocusShadow` | Per-size input box-shadow used when the shared inputFocusShadow retains its default CSS variable. | `inset 0 1px 7px 1px #333333` | `none` |
## ASLoader — @interface [`ASLoaderStyles`](../src/astheme/ASTheme.types.ts#L311)
Configure these properties under `components.loader` in `createASTheme`, `extendASTheme`, or `themeOverrides`.
The grow loader has separate track and animated-fill backgrounds. Setting growTrackBackground keeps the area behind the fill opaque (as in the neutral preset). growColor does not set the label color; use textColor. Geometry and label typography are independent of tokens.size. Grow/dots/spinner animation durations are currently fixed in CSS; reduced-motion styles stop those animations.
| Property | Description | Classic default | Neutral default |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | ---------------------------------------------------------- |
| `backdropFilter` | Complete CSS backdrop-filter for modal loader overlays only. | `blur(2px) contrast(0.5) brightness(0.5) opacity(0.75)` | `blur(2px) contrast(0.5) brightness(0.5) opacity(0.75)` |
| `fontFamily` | Loader text CSS font-family. | `inherit` | `system-ui, sans-serif` |
| `textColor` | Loader label CSS color. | `#474747` | `#ffffff` |
| `textShadow` | Complete loader label CSS text-shadow, or none. | `0 0 5px #fff8dc` | `none` |
| `growColor` | Grow wrapper CSS color; the label has its own textColor and does not inherit this value. | `#ffd700` | `#175cd3` |
| `growBorderColor` | Grow track border color; border width is fixed at 3px. | `#ffd321` | `#175cd3` |
| `growBackground` | Complete CSS background of the animated grow fill. | `linear-gradient(to bottom, #fff5b2 5%, #ffd321 100%)` | `#1849a9` |
| `growTrackBackground` | Complete CSS background behind the animated grow fill; remains visible where the fill is absent. | `transparent` | `#175cd3` |
| `growRadius` | Grow track CSS border-radius, inherited by its fill. | `30px` | `6px` |
| `spinBorderColor` | Outer spinner CSS border-color; accepts one to four colors. | `#ffd700` | `#175cd3` |
| `spinBeforeColor` | Spinning inner pseudo-element CSS border-color; accepts one to four colors. | `#ffd700 #0000` | `#175cd3 transparent` |
| `spinAfterColor` | Other inner pseudo-element CSS border-color; accepts one to four colors. | `#ffd700 #0000` | `#1849a9 transparent` |
| `dotsPrimaryBackground` | CSS background image for the first and third dots, normally a radial-gradient. | `radial-gradient(farthest-side, #ffd700 90%, #0000)` | `radial-gradient(farthest-side, #175cd3 90%, transparent)` |
| `dotsSecondaryBackground` | CSS background image for the second and fourth dots, normally a radial-gradient. | `radial-gradient(farthest-side, #ffbe5c 90%, #0000)` | `radial-gradient(farthest-side, #1849a9 90%, transparent)` |
| `sizes.ASSmall.growWidth` | Grow track CSS width. | `120px` | `120px` |
| `sizes.ASSmall.growHeight` | Grow track CSS height. | `24px` | `24px` |
| `sizes.ASSmall.dotsSize` | Width and height of the dots animation area. | `16px` | `16px` |
| `sizes.ASSmall.dotSize` | Width and height of each dot background image. | `6px` | `6px` |
| `sizes.ASSmall.spinSize` | Width and height of the spinner wrapper. | `30px` | `30px` |
| `sizes.ASSmall.spinInnerSize` | Width and height of the bordered spinner inside the wrapper. | `26px` | `26px` |
| `sizes.ASSmall.spinBorderWidth` | CSS border-width for the spinner and its inherited inner borders. | `2px` | `2px` |
| `sizes.ASSmall.spinInset` | CSS margin around the inner spinner pseudo-elements. | `4px` | `4px` |
| `sizes.ASSmall.textSize` | Loader label CSS font-size. | `1.25rem` | `1.25rem` |
| `sizes.ASSmall.textWeight` | Loader label CSS font-weight. Use a string (for example, '500'); the current runtime validator rejects numeric textWeight overrides. | `500` | `500` |
| `sizes.ASSmall.letterSpacing` | Loader label CSS letter-spacing. | `0.1rem` | `0.1rem` |
| `sizes.ASMedium.growWidth` | Grow track CSS width. | `160px` | `160px` |
| `sizes.ASMedium.growHeight` | Grow track CSS height. | `34px` | `34px` |
| `sizes.ASMedium.dotsSize` | Width and height of the dots animation area. | `32px` | `32px` |
| `sizes.ASMedium.dotSize` | Width and height of each dot background image. | `12px` | `12px` |
| `sizes.ASMedium.spinSize` | Width and height of the spinner wrapper. | `50px` | `50px` |
| `sizes.ASMedium.spinInnerSize` | Width and height of the bordered spinner inside the wrapper. | `42px` | `42px` |
| `sizes.ASMedium.spinBorderWidth` | CSS border-width for the spinner and its inherited inner borders. | `4px` | `4px` |
| `sizes.ASMedium.spinInset` | CSS margin around the inner spinner pseudo-elements. | `8px` | `8px` |
| `sizes.ASMedium.textSize` | Loader label CSS font-size. | `1.85rem` | `1.85rem` |
| `sizes.ASMedium.textWeight` | Loader label CSS font-weight. Use a string (for example, '500'); the current runtime validator rejects numeric textWeight overrides. | `500` | `500` |
| `sizes.ASMedium.letterSpacing` | Loader label CSS letter-spacing. | `0.2rem` | `0.2rem` |
| `sizes.ASLarge.growWidth` | Grow track CSS width. | `200px` | `200px` |
| `sizes.ASLarge.growHeight` | Grow track CSS height. | `44px` | `44px` |
| `sizes.ASLarge.dotsSize` | Width and height of the dots animation area. | `64px` | `64px` |
| `sizes.ASLarge.dotSize` | Width and height of each dot background image. | `24px` | `24px` |
| `sizes.ASLarge.spinSize` | Width and height of the spinner wrapper. | `100px` | `100px` |
| `sizes.ASLarge.spinInnerSize` | Width and height of the bordered spinner inside the wrapper. | `84px` | `84px` |
| `sizes.ASLarge.spinBorderWidth` | CSS border-width for the spinner and its inherited inner borders. | `8px` | `8px` |
| `sizes.ASLarge.spinInset` | CSS margin around the inner spinner pseudo-elements. | `16px` | `16px` |
| `sizes.ASLarge.textSize` | Loader label CSS font-size. | `2.5rem` | `2.5rem` |
| `sizes.ASLarge.textWeight` | Loader label CSS font-weight. Use a string (for example, '500'); the current runtime validator rejects numeric textWeight overrides. | `700` | `700` |
| `sizes.ASLarge.letterSpacing` | Loader label CSS letter-spacing. | `0.2rem` | `0.2rem` |
## ASSwitch — @interface [`ASSwitchStyles`](../src/astheme/ASTheme.types.ts#L375)
Configure these properties under `components.switch` in `createASTheme`, `extendASTheme`, or `themeOverrides`.
These styles configure the switch track, thumb backgrounds, label typography, state colors, focus outline, sizing, and transition timing. Thumb outlines and shadows use the inherited icon-button styles. See [ASSwitch](./switch.md) for usage, accessibility, and controlled state.
| Property | Description | Classic default | Neutral default |
| --- | --- | --- | --- |
| `fontFamily` | Label font family; follows the typography token. | `inherit` | `system-ui, sans-serif` |
| `labelColor` | Enabled label color; follows text. | `#333333` | `#333333` |
| `disabledLabelColor` | Disabled label color; follows disabledText. | `#999999` | `#667085` |
| `trackColor` | Unchecked track background; classic follows accent, neutral follows border. | `#ffd321` | `#667085` |
| `checkedTrackColor` | Checked track background; follows accent. | `#ffd321` | `#175cd3` |
| `trackOutlineWidth` | Track outline width; its negative value also sets the inset outline offset. | `2px` | `2px` |
| `trackOutlineColor` | Track outline color, including disabled states. | `#52565e` | `#52565e` |
| `thumbColor` | Unchecked thumb background; classic derives a surface-to-accent gradient, neutral follows surface. | `linear-gradient(to bottom, #fff5b2 0%, #ffd321 100%)` | `#ffffff` |
| `checkedThumbColor` | Checked thumb background; neutral follows onAccent. | `#333333` | `#ffffff` |
| `disabledTrackColor` | Disabled track background for either checked state; follows disabledSurface. | `#333333` | `#eaecf0` |
| `disabledThumbColor` | Disabled thumb background for either checked state; follows disabledSurface. | `#333333` | `#eaecf0` |
| `focusRing` | Keyboard focus outline, independent of the track outline; follows focus. | `2px solid #867017` | `2px solid #175cd3` |
| `gap` | Track-to-label spacing. | `10px` | `10px` |
| `transition` | Thumb slide transition; its timing also controls the checked-background cross-fade. Follows motion tokens. | `transform 0.25s ease-in-out` | `transform 0.25s ease-in-out` |
| `sizes.ASSmall.height` | Minimum control height; follows the matching size height token. | `30px` | `30px` |
| `sizes.ASSmall.fontSize` | Label font size; follows the matching size fontSize token. | `1rem` | `1rem` |
| `sizes.ASSmall.trackWidth` | Visible track width; twice the matching size height token. | `calc(30px * 2)` | `calc(30px * 2)` |
| `sizes.ASSmall.trackHeight` | Visible track height; follows the matching size height token. | `30px` | `30px` |
| `sizes.ASMedium.height` | Minimum control height; follows the matching size height token. | `40px` | `40px` |
| `sizes.ASMedium.fontSize` | Label font size; follows the matching size fontSize token. | `1.2rem` | `1.2rem` |
| `sizes.ASMedium.trackWidth` | Visible track width; twice the matching size height token. | `calc(40px * 2)` | `calc(40px * 2)` |
| `sizes.ASMedium.trackHeight` | Visible track height; follows the matching size height token. | `40px` | `40px` |
| `sizes.ASLarge.height` | Minimum control height; follows the matching size height token. | `50px` | `50px` |
| `sizes.ASLarge.fontSize` | Label font size; follows the matching size fontSize token. | `1.5rem` | `1.5rem` |
| `sizes.ASLarge.trackWidth` | Visible track width; twice the matching size height token. | `calc(50px * 2)` | `calc(50px * 2)` |
| `sizes.ASLarge.trackHeight` | Visible track height; follows the matching size height token. | `50px` | `50px` |
The thumb retains a 3px inset. Its outline and shadow use the inherited `components.iconbutton` states; its backgrounds use the switch slots above. Track outlines apply to enabled and disabled states. Reduced-motion preferences suppress the thumb transition. Existing complete themes without switch styles receive the classic switch recipe.
## ASSnackbar — @interface [`ASSnackbarStyles`](../src/astheme/ASTheme.types.ts#L434)
Configure these properties under `components.snackbar` in `createASTheme`, `extendASTheme`, or `themeOverrides`.
These styles configure the portaled notification surface, variant colors, message typography, spacing, viewport placement, and entry/exit motion. The dismissal button uses the inherited button styles. See [ASSnackbar](./snackbar.md) for displaying notifications, duration, and dismissal callbacks.
| Property | Description | Classic default | Neutral default |
| --- | --- | --- | --- |
| `fontFamily` | Message font family; follows the typography token. | `inherit` | `system-ui, sans-serif` |
| `radius` | Surface corner radius, independent of the control radius token. | `8px` | `8px` |
| `maxWidth` | Maximum surface width, constrained by the viewport. | `560px` | `560px` |
| `gutter` | Minimum viewport edge spacing; larger safe-area insets take precedence. | `16px` | `16px` |
| `shadow` | Surface box-shadow. | `0 4px 16px #0003` | `0 4px 16px #0003` |
| `zIndex` | Fixed surface stacking order (number). | `1400` | `1400` |
| `motionDuration` | Entry and exit duration; follows the motion duration token. | `0.25s` | `0.25s` |
| `motionEasing` | Entry and exit easing; follows the motion easing token. | `ease-in-out` | `ease-in-out` |
| `info.background` | Informational surface background; follows accent. | `#ffd321` | `#175cd3` |
| `info.color` | Informational message color; follows onAccent. | `#585858` | `#ffffff` |
| `success.background` | Success surface background; follows surface. | `#fff5b2` | `#ffffff` |
| `success.color` | Success message color; follows text. | `#333333` | `#333333` |
| `error.background` | Error surface background; follows surface. | `#fff5b2` | `#ffffff` |
| `error.color` | Error message color; follows invalid. | `#b42318` | `#b42318` |
| `sizes.ASSmall.fontSize` | Message font size; follows the matching size fontSize token. | `1rem` | `1rem` |
| `sizes.ASSmall.padding` | Surface padding. | `12px` | `12px` |
| `sizes.ASSmall.gap` | Message-to-dismissal spacing. | `12px` | `12px` |
| `sizes.ASMedium.fontSize` | Message font size; follows the matching size fontSize token. | `1.2rem` | `1.2rem` |
| `sizes.ASMedium.padding` | Surface padding. | `16px` | `16px` |
| `sizes.ASMedium.gap` | Message-to-dismissal spacing. | `16px` | `16px` |
| `sizes.ASLarge.fontSize` | Message font size; follows the matching size fontSize token. | `1.5rem` | `1.5rem` |
| `sizes.ASLarge.padding` | Surface padding. | `20px` | `20px` |
| `sizes.ASLarge.gap` | Message-to-dismissal spacing. | `20px` | `20px` |
The public `size` prop defaults to `ASMedium` and also sizes the dismissal button, which uses `components.button`. Brand-specific success colors are explicit component overrides rather than a separate global palette. Existing complete themes without snackbar styles receive the classic snackbar recipe.
The display countdown begins after entry completes; `onClosed` runs after exit removes the surface. Reduced-motion preferences skip both animations. These lifecycle rules are independent of the selected color variant.
## ASModal — @interface [`ASModalStyles`](../src/astheme/ASTheme.types.ts#L498)
Configure these properties under `components.modal` in `createASTheme`, `extendASTheme`, or `themeOverrides`.
These properties style the portaled surface and backdrop. Explicit wrapper options take precedence over matching slots. See [ASModal](./modal.md) for layout, visibility, and accessibility responsibilities.
| Property | Description | Classic default | Neutral default |
| -------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------- |
| `background` | Surface CSS background. | Existing translucent gray-to-black gradient; explicit surface token overrides it. | `tokens.color.surface` |
| `outline` | Complete surface outline. | `thin solid #727272`; explicit border token overrides its color. | Thin solid `tokens.color.border` |
| `shadow` | Surface box-shadow. | `inset 0 0 6px 1px #818181` | `none` |
| `backdropBackground` | Backdrop CSS background. | `rgb(0 0 0 / 50%)` | Same |
| `zIndex` | Backdrop stacking level (number or CSS expression); surface uses this plus one. | `100` | Same |
| `radius` | Surface border-radius, independent of control radius. | `4px` | Same |
| `padding` | Surface padding. | `16px` | Same |
| `backdropFilter` | Surface backdrop-filter. | `blur(2px)` | Same |
| `innerBorderShadow` | Decorative inset border shadow; `'none'` hides it. The deprecated `$showInnerBorder` option has no effect. | Layered light/dark inset shadows | `none` |
| `innerBorderRadius` | Decorative border radius. | `4px` | Same |
| `innerBorderMargin` | Decorative border inset margin. | `16px` | Same |
| `backdropTransition` | Complete backdrop entry transition. | Opacity, `0.3s`, `cubic-bezier(0.39, 0.575, 0.565, 1)` | Opacity using shared motion tokens |
| `surfaceTransition` | Complete surface entry transition. | Opacity, `1.2s`, same easing, `0.3s` delay | Opacity using shared motion tokens |
Explicit shared motion tokens also update classic transitions. Reduced-motion preferences disable both transitions. Existing complete themes retain their modal background, backdrop color, outline color, stacking level, and gray inset shadow through the compatibility adapter.
## ASChoiceBar — @interface [`ASChoiceBarStyles`](../src/astheme/ASTheme.types.ts#L538)
Configure these properties under `components.choicebar` in `createASTheme`, `extendASTheme`, or `themeOverrides`.
See [ASChoiceBar](./choicebar.md) for selection, layout, and keyboard behavior. Arrow controls inherit `components.iconbutton`; the picker backdrop inherits `components.modal`.
| Property | Description | Classic default | Neutral default |
| --- | --- | --- | --- |
| `fontFamily` | Bar and picker font family. | Complete theme font family | `tokens.typography.fontFamily` |
| `background`, `shadow` | Bar/picker background and shadow. | choicebar background and shadow | Surface token, no shadow |
| `itemColor`, `itemHoverColor` | Unselected item text and hover color. | choicebar normal and hover text | Text and accent tokens |
| `selectedColor`, `selectedBackground` | Selected item foreground and background. | Selected text and background | On-accent and accent tokens |
| `radius`, `itemRadius` | Bar/picker and item/highlight corner radii. | Bar/picker `6px`; item/highlight `4px` | Control radius; item `4px` |
| `itemPadding`, `itemGap` | Item padding and horizontal gap. | `0 8px`; desktop gap `16px` | `0 8px`; desktop gap `16px` |
| `pickerWidth` | Modal picker width, capped to available viewport space. | Responsive modal width: `min(420px, calc(100vw - 32px))` | Responsive modal width: `min(420px, calc(100vw - 32px))` |
| `pickerMaxHeight` | Maximum height of the scrollable option list. | Scrollable picker height limit: `min(80dvh, 640px)` | Scrollable picker height limit: `min(80dvh, 640px)` |
| `pickerPadding`, `pickerGap`, `pickerItemPadding` | List padding, vertical option gap, and option padding. | `16px`, `8px`, `8px` | `16px`, `8px`, `8px` |
| `pickerItemBackground` | Unselected picker option background. | `radial-gradient(black, transparent)` | Surface token |
| `pickerItemShadow` | Unselected picker option shadow. | `1px 2px 2px 1px #000000, 0 0 1px 0 #ffffff` | `none` |
| `pickerSelectedShadow` | Selected picker option shadow. | `1px 2px 2px 0 #000000 inset, 0 0 1px 0 #ffffff` | `none` |
| `scrollbarColor` | Visible scrollbar thumb color. | Selected background | Accent token |
| `focusRing` | Keyboard focus outline. | `2px solid` selected background | `2px solid` focus token |
| `transition` | Item background and color transition. | Background and color, `0.25s ease-in-out` | Token motion duration/easing |
| `motionDuration`, `motionEasing` | Mobile slide and desktop highlight duration and easing. | Mobile slide and desktop highlight: `250ms`, `ease-in-out` | Token motion duration/easing |
| `sizes[ComponentSize].height` | Control height for Small, Medium, and Large. | Small/medium/large: `30px`, `40px`, `50px` | Corresponding size token |
| `sizes[ComponentSize].fontSize` | Item font size for Small, Medium, and Large. | `1.3rem`, `1.7rem`, `2.1rem` | Corresponding size token |
| `sizes[ComponentSize].fontWeight` | Item font weight for Small, Medium, and Large. | `400`, `400`, `500` | Typography weight token |
Reduced-motion preferences disable slide/highlight animations and smooth selection scrolling. Desktop scroll animation timing is browser-owned; `motionDuration` controls the highlight and mobile slide, not native scrolling.
ChoiceBar's visible scrollbar uses its existing `components.choicebar.scrollbarColor` in both standard and WebKit scrollbar styling. Shared width and scrollbar-hiding helpers only control layout/visibility and contain no project palette.
## ASChartHBar and ASChartVBar — @interface [`ASChartBarStyles`](../src/astheme/ASTheme.types.ts#L678)
Configure these properties under `components.chartbar` in `createASTheme`, `extendASTheme`, or `themeOverrides`.
Shared by [ASChartHBar](./chart-hbar.md) and [ASChartVBar](./chart-vbar.md). Component fill and color props override theme defaults. Complete-theme `chartbar` colors remain supported through adaptation.
| Property | Description | Classic default | Neutral default |
| --- | --- | --- | --- |
| `barKind` | Fill pattern: striped or solid. | `striped` | `solid` |
| `primaryColor` | Primary fill color. | Complete theme chart primary color | Accent token |
| `secondaryColor` | Secondary stripe color. | Complete theme chart secondary color | Surface token; used for stripes |
| `radius` | Filled-bar corner radius. | `16px` | `16px` |
| `shadow` | Box-shadow, applied only when withShadow is enabled. | `1px 1px 4px black` | `1px 1px 4px black` |
| `fontFamily` | Label font family. | Complete theme font | Typography font token |
| `labelColor` | Label text color. | `inherit` | Text token |
| `labelFontSize` | Label font size. | `inherit` | `inherit` |
| `labelFontWeight` | Label font weight. | `inherit` | Typography weight token |
| `labelGap` | Gap between the endpoint and label. | `4px` | `4px` |
| `length` | Default HBar width or VBar height. | `400px` | `400px` |
| `crossSize` | Outer cross-axis dimension. | `20px` | `20px` |
| `motionDuration`, `motionEasing` | Fill transition duration and easing. | `0.5s`, `ease-in` | Motion tokens |
| `sizes[size].thickness` | Bar thickness for Small, Medium, and Large. | Small/medium/large: `6px`, `10px`, `15px` | Small/medium/large: `6px`, `10px`, `15px` |
| `sizes[size].stripeSize` | Square stripe tile size for Small, Medium, and Large. | Small/medium/large: `4px`, `8px`, `12px` | Small/medium/large: `4px`, `8px`, `12px` |
Bar thickness uses chart-specific geometry rather than the shared button-height tokens. Reduced-motion preferences disable percentage transitions. Explicit `style` dimensions override default outer dimensions.
## ASChartDonut — @interface [`ASChartDonutStyles`](../src/astheme/ASTheme.types.ts#L628)
Configure these properties under `components.chartdonut` in `createASTheme`, `extendASTheme`, or `themeOverrides`.
[ASChartDonut](./chart-donut.md) shares these styles across its one to four rings. Explicit data-color props override arc defaults. Ring paths, angular sweep, and thickness are structural geometry owned by the component.
| Property | Description | Classic default | Neutral default |
| --- | --- | --- | --- |
| `diameter` | Default chart width; `donutSize` takes precedence | `200px` | `200px` |
| `fontFamily`, `subLabelFontFamily` | Main and secondary label fonts | Complete-theme font settings | typography token |
| `labelColor`, `subLabelColor` | Main and secondary label colors | Complete-theme text colors | `text`, `mutedText` tokens |
| `primaryColor` | Primary data arc | Complete-theme gold | `accent` token |
| `secondaryColor`, `tertiaryColor`, `quaternaryColor` | Additional data arcs | Complete-theme blue, green, coral palette | Complete-theme blue, green, coral palette |
| `innerTrackColor`, `outerTrackColor` | Shared track interior and edge | Complete-theme gray colors | `surface`, `border` tokens |
| `primaryTrackColor`, `tertiaryTrackColor` | Individual ring backgrounds | `transparent` | `transparent` |
| `secondaryTrackColor` | Second ring background | `#ffffff30` | `transparent` |
| `quaternaryTrackColor` | Fourth ring background, independent of the data arc | Complete-theme fourth color | `transparent` |
| `quaternaryTrackOpacity` | Fourth ring background opacity | `48 / 255`, equivalent to hexadecimal alpha `30` | `48 / 255`, equivalent to hexadecimal alpha `30` |
| `motionDuration` | Primary arc transition duration | `2s` | motion duration token |
| `secondaryMotionDuration` | Additional arc transition duration | `1s` | motion duration token |
| `motionEasing` | Arc transition easing | `ease-out` | motion easing token |
| `motionDelay` | Delay before arc transitions | `0.5s` | `0s` |
| `sizes[size].labelFontSize` | Main label font size | Small `2.3rem`, Medium `1.7rem`, Large `1rem` | Small `2.3rem`, Medium `1.7rem`, Large `1rem` |
| `sizes[size].labelFontWeight` | Main label font weight | Small/Medium `400`, Large `300` | typography weight token |
| `sizes[size].labelShadow` | Main label shadow | Complete-theme per-size shadow | `none` |
| `sizes[size].subLabelFontSize` | Secondary label font size | `1.5rem`, or complete-theme per-size override | `1.5rem`, or complete-theme per-size override |
| `sizes[size].subLabelFontWeight` | Secondary label weight | Small/Medium `300`, Large `200` | typography weight token |
| `sizes[size].subLabelShadow` | Secondary label shadow | Complete-theme per-size shadow | `none` |
| `sizes[size].subLabelOffset` | Secondary label bottom offset relative to the main label | Small `-40px`, Medium `-43px`, Large `-50px` | Small `-40px`, Medium `-43px`, Large `-50px` |
Complete-theme per-size text settings take precedence over their scalar fallback fields. CSS colors are used directly; opacity is separate from the fourth track color, so named colors, CSS variables, and functional color syntax work without appended hexadecimal alpha. Reduced-motion preferences disable arc transitions.
## ASIcon and SVG icons — @interface [`ASIconStyles`](../src/astheme/ASTheme.types.ts#L720)
Configure these properties under `components.icon` in `createASTheme`, `extendASTheme`, or `themeOverrides`.
[SVG icons](./svg-icons.md) resolve these defaults through ASIcon. Every corresponding explicit IconProps value takes precedence. These properties do not affect glyph rendering or replace state colors explicitly supplied by an owning control such as ASIconButton.
| Property | Description | Classic default | Neutral default |
| --- | --- | --- | --- |
| `color` | SVG path stroke color | `#fffff0` | `currentColor` |
| `fillColor` | SVG path fill color | `transparent` | `transparent` |
| `circleStrokeColor` | Optional circle outline color | `#fffff0` | `currentColor` |
| `circleFillColor` | Optional circle background color | `transparent` | `transparent` |
| `circleStrokeWidth` | Optional circle outline width in SVG units | `1.5` | `1.5` |
The neutral stroke follows surrounding CSS text color. These slots are not derived directly from color tokens; changing `tokens.color.text` does not itself set a DOM text color. Use surrounding CSS or explicit component slots. Icon size, path stroke width, opacity, and circle visibility remain instance props. SVG paths and circle geometry are component structure rather than theme values.
## Legacy theme sections
ASResolvedTheme also carries the legacy ASTheme shape for compatibility. Its top-level button, dropdown, textfield, loader, and other sections are not synchronized mirrors of components.*. Donut charts consume `components.chartdonut`; complete-theme donut settings are adapted into this slot. Standalone SVG icons consume `components.icon`, with transparent fills in both presets and currentColor strokes in neutral. Explicit icon colors take precedence; glyph icons retain their separate font API. ASChoiceBar consumes `components.choicebar` and follows the selected preset. See [Applying an ASUI theme](./theme-provider.md) and the [legacy type declarations](../src/apptypes/ASUI.types.ts).
A custom complete legacy theme is adapted with its existing component values treated as explicit exceptions; token overrides cannot reliably recolor those preserved gradients. Use component overrides or build a new project theme through createASTheme.
## Maintaining this reference
Follow the [theme reference section format](./component-workflow.md#theme-reference-section-format) for every token and component section. Keep compatibility notes after the component catalogue and this maintenance section last.
When changing a theme property or recipe, update its description here and in [ASTheme.types.ts](../src/astheme/ASTheme.types.ts). Re-evaluate both factory presets when updating default tables; do not infer component defaults from token values alone. Defaults above describe the unmodified presets, not inherited project overrides or browser-computed styles.