Primary |
Main brand emphasis and highest-priority actions. |
Use as the filled background for primary buttons, selected tabs, focused toggles, and primary selection indicators. Put OnPrimary text or icons on it. |
Establishes the strongest interactive emphasis. |
OnPrimary |
Content is drawn on Primary. |
Use for text, icons, and glyphs inside primary-filled controls. |
Keeps primary controls readable. |
PrimaryContainer |
Primary-family UI needs lower emphasis than Primary. |
Use for tonal buttons, chips, and selected list items. Put OnPrimaryContainer content on it. |
Keeps brand association without making every element compete with the main action. |
OnPrimaryContainer |
Content is drawn on PrimaryContainer. |
Use for text and icons in tonal primary controls and selected primary-family items. |
Provides contrast for softer primary containers. |
Secondary |
A supporting accent is needed for interactive elements. |
Use for secondary buttons, filter chips, accent icons, and secondary emphasis. Put OnSecondary content on it. |
Extends the palette without competing with Primary. |
OnSecondary |
Content is drawn on Secondary. |
Use for text and icons on secondary-filled controls. |
Keeps secondary-filled controls readable. |
SecondaryContainer |
Secondary-family UI needs low emphasis. |
Use for secondary chips, toggle backgrounds, and selected items in secondary areas. Put OnSecondaryContainer content on it. |
Gives secondary UI a visible but calm container. |
OnSecondaryContainer |
Content is drawn on SecondaryContainer. |
Use for text and icons on tonal secondary components. |
Provides contrast for secondary containers. |
Tertiary |
A third accent is needed for specific information or specialized areas. |
Use for input focus rings, special status markers, accent icons, charts, or graphs. Put OnTertiary content on it. |
Separates special-purpose emphasis from primary and secondary actions. |
OnTertiary |
Content is drawn on Tertiary. |
Use for text and icons on tertiary-filled controls. |
Keeps tertiary-filled controls readable. |
TertiaryContainer |
Tertiary-family UI needs low emphasis. |
Use for special cards, highlighted list items, and tertiary chips. Put OnTertiaryContainer content on it. |
Highlights special content without using a strong filled accent. |
OnTertiaryContainer |
Content is drawn on TertiaryContainer. |
Use for text and icons on tonal tertiary components. |
Provides contrast for tertiary containers. |
Error |
The UI communicates destructive actions or critical validation. |
Use for destructive buttons, error icons, error text, and critical validation states. Put OnError content on error-filled backgrounds. |
Signals high-severity problems immediately. |
OnError |
Content is drawn on Error. |
Use for text and icons on error-filled buttons or banners. |
Keeps critical error surfaces readable. |
ErrorContainer |
An error state needs visible but lower-intensity emphasis. |
Use for highlighted text box backgrounds, error panels, and validation summary areas. Put OnErrorContainer content on it. |
Makes errors prominent without the intensity of Error. |
OnErrorContainer |
Content is drawn on ErrorContainer. |
Use for error messages, icons, and links inside error panels or highlighted inputs. |
Provides contrast for softer error surfaces. |
Warning |
The UI communicates a high-emphasis warning. |
Use for warning icons, warning text, and warning-filled controls. Put OnWarning content on it. |
Distinguishes caution from destructive error. |
OnWarning |
Content is drawn on Warning. |
Use for text and icons on warning-filled controls or banners. |
Keeps high-emphasis warning surfaces readable. |
WarningContainer |
A warning needs visible but lower-intensity emphasis. |
Use for warning panels, validation areas, and highlighted warning rows. Put OnWarningContainer content on it. |
Surfaces caution without blocking the user like an error. |
OnWarningContainer |
Content is drawn on WarningContainer. |
Use for warning messages, icons, and links inside warning containers. |
Provides contrast for warning containers. |
WarningLow |
The UI communicates a low-severity warning or advisory. |
Use for advisory icons, non-blocking caution text, and low-priority warning accents. Put OnWarningLow content on it. |
Separates advisory warnings from stronger warning states. |
OnWarningLow |
Content is drawn on WarningLow. |
Use for text and icons on low-warning filled accents. |
Keeps low-warning surfaces readable. |
WarningLowContainer |
A low-severity warning needs a soft background. |
Use for advisory panels, soft warning rows, and non-blocking validation hints. Put OnWarningLowContainer content on it. |
Gives cautionary context without strong visual weight. |
OnWarningLowContainer |
Content is drawn on WarningLowContainer. |
Use for advisory text and icons inside low-warning containers. |
Provides contrast for soft warning backgrounds. |
Information |
The UI communicates informational status or guidance. |
Use for info icons, info text, and information-filled controls. Put OnInformation content on it. |
Marks neutral informational content separately from success, warning, or error. |
OnInformation |
Content is drawn on Information. |
Use for text and icons on information-filled controls or banners. |
Keeps informational surfaces readable. |
InformationContainer |
Informational content needs a soft background. |
Use for help panels, informational callouts, and neutral status areas. Put OnInformationContainer content on it. |
Makes supporting information visible without implying a problem. |
OnInformationContainer |
Content is drawn on InformationContainer. |
Use for text, icons, and links inside informational containers. |
Provides contrast for information containers. |
Safe |
The UI communicates success, safe state, or allowed action. |
Use for success icons, safe-state text, and positive filled controls. Put OnSafe content on it. |
Communicates positive or permitted status distinctly. |
OnSafe |
Content is drawn on Safe. |
Use for text and icons on safe or success-filled controls. |
Keeps positive-status surfaces readable. |
SafeContainer |
A success or safe state needs a soft background. |
Use for success panels, safe-state rows, completed-step backgrounds, and positive status callouts. Put OnSafeContainer content on it. |
Shows positive status without over-emphasizing it. |
OnSafeContainer |
Content is drawn on SafeContainer. |
Use for success messages, icons, and links inside safe containers. |
Provides contrast for safe containers. |
Background |
Painting the app's outermost window background. |
Use for the main form background and full-window regions behind scrollable content or surfaces. Put OnBackground content on it. |
Creates the base environment behind surfaces. |
OnBackground |
Content is drawn directly on Background. |
Use for primary text, icons, and glyphs on the main window background. |
Keeps content readable on the app background. |
Surface |
UI elements sit above the background. |
Use for panels, group boxes, user controls, card-like backgrounds, and content surfaces. Put OnSurface content on it. |
Provides the default material surface layer. |
OnSurface |
Content is drawn on Surface. |
Use for primary text and icons on panels, cards, tool windows, and other surfaces. |
Keeps normal surface content readable. |
SurfaceVariant |
A secondary surface must differ from the main surface. |
Use for data grid backgrounds, status panels, navigation panes, subtle labels, and supporting information. Put OnSurfaceVariant content on it. |
Creates hierarchy without using accent colors. |
OnSurfaceVariant |
Content is drawn on SurfaceVariant or needs lower emphasis. |
Use for text and icons on secondary surfaces and supporting labels. |
Provides appropriate contrast for variant surfaces and de-emphasized content. |
SurfaceDim |
The UI needs the darkest surface tone. |
Use for main backgrounds or recessed areas in dark themes; use sparingly for strongly de-emphasized regions in light themes. |
Expresses depth at the low end of the surface range. |
SurfaceBright |
The UI needs the lightest surface tone. |
Use as a high-level background in light themes; use for elevated sheets, floating tool windows, or popups in dark themes. |
Expresses depth at the high end of the surface range. |
SurfaceContainerLowest |
The outermost container needs the least emphasis. |
Use behind cards and panels, such as scrollable content hosts. |
Establishes the lowest container layer. |
SurfaceContainerLow |
A base content container needs slightly more emphasis. |
Use for primary panels, tab pages, and standard card backgrounds. |
Creates a subtle step above the outermost container. |
SurfaceContainer |
A default container tone is needed. |
Use for standard cards, panel levels, and list item backgrounds. |
Provides the normal layered-interface container. |
SurfaceContainerHigh |
A surface should stand out above regular content. |
Use for modal panels, pinned tool windows, and important dashboard cards. |
Signals higher visual priority. |
SurfaceContainerHighest |
A surface is the most prominent container in the hierarchy. |
Use for dialogs, modal sheets, and critical overlays, usually with Scrim behind it. |
Marks the top container layer. |
SurfaceTint |
A raised custom-drawn surface needs elevation treatment. |
Apply as a translucent overlay on the base surface or surface container. |
Expresses elevation without relying on pure opacity changes. |
Outline |
A standard-emphasis stroke or divider is needed. |
Use for text box borders, group box borders, separator lines, and grid lines. |
Defines boundaries clearly. |
OutlineVariant |
A lower-emphasis stroke or divider is needed. |
Use for subtle separators, low-contrast grid lines, and disabled or de-emphasized borders. |
Defines boundaries without drawing too much attention. |
Shadow |
A custom elevated component needs a drop shadow. |
Use as the shadow color for raised panels, floating tool windows, popups, and menus; control alpha separately. |
Adds depth to elevated UI. |
Scrim |
Modal UI needs to de-emphasize the content behind it. |
Use as a semi-transparent overlay behind dialogs, popups, and side panels. |
Preserves context while focusing attention on the modal element. |
InverseSurface |
A region intentionally inverts normal surface treatment. |
Use for status bars, snackbars, and banners. Put InverseOnSurface content on it. |
Creates a distinct overlay region above normal surfaces. |
InverseOnSurface |
Content is drawn on InverseSurface. |
Use for text, icons, and action glyphs in inverted regions. |
Keeps inverted regions readable. |
InversePrimary |
A primary action appears inside an inverse region. |
Use for action buttons or accents in snackbars and banners using InverseSurface. |
Preserves primary-action meaning on inverted surfaces. |
PrimaryFixed |
A primary-family container must look stable across light and dark themes. |
Use for persistent brand panels, logo title bars, and non-theme-switching controls. Put OnPrimaryFixed content on it. |
Keeps brand surfaces visually consistent across themes. |
OnPrimaryFixed |
Content is drawn on PrimaryFixed. |
Use for text and icons on fixed primary containers. |
Keeps fixed primary surfaces readable. |
PrimaryFixedDim |
A stronger fixed-primary state is needed. |
Use for hover or pressed states and higher-emphasis primary-fixed areas. Pair with OnPrimaryFixedVariant or OnPrimaryFixed, depending on contrast. |
Adds emphasis while staying light/dark invariant. |
OnPrimaryFixedVariant |
Content is drawn on stronger fixed-primary surfaces. |
Use on PrimaryFixedDim when more contrast is required. |
Keeps stronger fixed-primary surfaces readable. |
SecondaryFixed |
A secondary-family container must look stable across light and dark themes. |
Use for secondary brand panels and stable sidebar backgrounds. Put OnSecondaryFixed content on it. |
Keeps secondary brand surfaces visually consistent across themes. |
OnSecondaryFixed |
Content is drawn on SecondaryFixed. |
Use for text and icons on fixed secondary containers. |
Keeps fixed secondary surfaces readable. |
SecondaryFixedDim |
A stronger fixed-secondary state is needed. |
Use for hover or pressed states and more prominent secondary-fixed components. Put OnSecondaryFixedVariant content on it. |
Adds emphasis while staying light/dark invariant. |
OnSecondaryFixedVariant |
Content is drawn on stronger fixed-secondary surfaces. |
Use on SecondaryFixedDim when more contrast is required. |
Keeps stronger fixed-secondary surfaces readable. |
TertiaryFixed |
A tertiary-family container must look stable across light and dark themes. |
Use for special feature areas, analytic views, and domain-specific accent panels. Put OnTertiaryFixed content on it. |
Keeps special-purpose accent surfaces visually consistent across themes. |
OnTertiaryFixed |
Content is drawn on TertiaryFixed. |
Use for text and icons on fixed tertiary containers. |
Keeps fixed tertiary surfaces readable. |
TertiaryFixedDim |
A stronger fixed-tertiary state is needed. |
Use for hover or pressed states and highly emphasized tertiary-fixed components. Put OnTertiaryFixedVariant content on it. |
Adds emphasis while staying light/dark invariant. |
OnTertiaryFixedVariant |
Content is drawn on stronger fixed-tertiary surfaces. |
Use on TertiaryFixedDim when more contrast is required. |
Keeps stronger fixed-tertiary surfaces readable. |
