Theming with ComposeTheme and Material 3 Color Schemes

Compose Svelted models its theme system closely after Material Design 3. A single <ComposeTheme> component wraps your application and injects all design tokens as CSS custom properties on a root <div>. Components consume those properties at render time, so changing the theme — including switching between light and dark schemes — triggers a single reactive update that cascades through the entire tree without any JavaScript traversal.

`<ComposeTheme>` component

Place <ComposeTheme> at the top of your component tree, above everything that needs access to theme tokens.

<script lang="ts">
  import { ComposeTheme } from "@danielito1996/compose-svelted";
</script>

<ComposeTheme mode="system">
  <!-- Your entire app lives here -->
  <AppRoot />
</ComposeTheme>

<ComposeTheme> renders a full-size <div> with background-color: var(--md-sys-color-surface) and color: var(--md-sys-color-onSurface) as baseline styles. All resolved theme tokens are written as inline CSS custom properties on that same element.

Props

light

ComposeTheme

The theme object to use when the active mode resolves to "light". Defaults to defaultLightTheme when omitted.

dark

ComposeTheme

The theme object to use when the active mode resolves to "dark". Defaults to defaultDarkTheme when omitted.

mode

"light" | "dark" | "system"

Controls which scheme is active. "system" reads the OS preference via prefers-color-scheme and switches automatically when the user changes their system setting. Defaults to "system".

The `ComposeTheme` type

A theme object carries five sub-systems. Every field is required when constructing a custom theme. See the custom theme example below for a complete starting point.

interface ComposeTheme {
  colorScheme: ColorScheme; // Palette of semantic colour roles
  typography:  Typography;  // Type-scale: 15 named text styles
  shapes:      Shapes;      // Corner-radius scale: 5 steps
  spacing:     Spacing;     // Spacing scale: 5 steps
  elevation:   Elevation;   // Box-shadow scale: 5 levels
}

Color scheme tokens

The ColorScheme object provides named constants for every semantic role. Use these constants anywhere a colour is expected (e.g. Modifier.background(ColorScheme.Primary)) instead of raw hex strings so that your UI respects the active theme automatically. Each token resolves to the CSS custom property --md-sys-color-<token>.

Constant	CSS variable	Light default	Dark default	Meaning
`ColorScheme.Primary`	`--md-sys-color-primary`	`#FF732F`	`#FC4B19`	Brand / action colour
`ColorScheme.OnPrimary`	`--md-sys-color-onPrimary`	`#FFFBF2`	`#E6E6E6`	Content placed on Primary
`ColorScheme.Secondary`	`--md-sys-color-secondary`	`#3A3E49`	`#3A3E49`	Secondary brand colour
`ColorScheme.OnSecondary`	`--md-sys-color-onSecondary`	`#FFFFFF`	`#E6E6E6`	Content placed on Secondary
`ColorScheme.Tertiary`	`--md-sys-color-tertiary`	`#6750A4`	`#D0BCFF`	Accent / complementary colour
`ColorScheme.OnTertiary`	`--md-sys-color-onTertiary`	`#FFFFFF`	`#381E72`	Content placed on Tertiary
`ColorScheme.Background`	`--md-sys-color-background`	`#FFFBF2`	`#080808`	Page / canvas background
`ColorScheme.OnBackground`	`--md-sys-color-onBackground`	`#1C1B1F`	`#E6E6E6`	Content placed on Background
`ColorScheme.Surface`	`--md-sys-color-surface`	`#FFFFFF`	`#101010`	Card / sheet surface
`ColorScheme.OnSurface`	`--md-sys-color-onSurface`	`#1C1B1F`	`#E6E6E6`	Content placed on Surface
`ColorScheme.SurfaceVariant`	`--md-sys-color-surfaceVariant`	`#F8F9FA`	`#1E1E1E`	Alternate surface (inputs, chips)
`ColorScheme.OnSurfaceVariant`	`--md-sys-color-onSurfaceVariant`	`#DEE1E6`	`#CAC4D0`	Content on SurfaceVariant
`ColorScheme.Outline`	`--md-sys-color-outline`	`#B0B0B0`	`#4A4A4A`	Dividers and borders
`ColorScheme.Error`	`--md-sys-color-error`	`#BA1A1A`	`#FF6F61`	Destructive / error state
`ColorScheme.OnError`	`--md-sys-color-onError`	`#FFFFFF`	`#080808`	Content placed on Error

Typography tokens

The TextStyle object maps Jetpack Compose-style constant names to the 15 roles of the Material 3 type scale. Every role exposes five CSS custom properties (font-family, font-size, line-height, letter-spacing, font-weight), all following the pattern --md-sys-typescale-<role>-<property>.

Constant	Role	Size	Weight
`TextStyle.DisplayLarge`	`displayLarge`	57 px	400
`TextStyle.DisplayMedium`	`displayMedium`	45 px	400
`TextStyle.DisplaySmall`	`displaySmall`	36 px	400
`TextStyle.HeadlineLarge`	`headlineLarge`	32 px	400
`TextStyle.HeadlineMedium`	`headlineMedium`	28 px	400
`TextStyle.HeadlineSmall`	`headlineSmall`	24 px	400
`TextStyle.TitleLarge`	`titleLarge`	22 px	400
`TextStyle.TitleMedium`	`titleMedium`	16 px	500
`TextStyle.TitleSmall`	`titleSmall`	14 px	500
`TextStyle.BodyLarge`	`bodyLarge`	16 px	400
`TextStyle.BodyMedium`	`bodyMedium`	14 px	400
`TextStyle.BodySmall`	`bodySmall`	12 px	400
`TextStyle.LabelLarge`	`labelLarge`	14 px	500
`TextStyle.LabelMedium`	`labelMedium`	12 px	500
`TextStyle.LabelSmall`	`labelSmall`	11 px	500

The default font family for every role is system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif. Override it per-role in a custom typography object.

Shapes, spacing, and elevation

Shapes

The shapes object defines a five-step corner-radius scale. Values are written to CSS as --md-sys-shape-<key>.

Key	Default value	Typical use
`none`	`0px`	Square elements (full-bleed images)
`extraSmall`	`4px`	Chips, tooltips
`small`	`8px`	Buttons, text fields
`medium`	`12px`	Cards
`large`	`16px`	Bottom sheets, dialogs

Spacing

The spacing object provides a five-step spacing scale. Values are written to CSS as --md-sys-spacing-<key>.

Key	Default value
`xs`	`4px`
`sm`	`8px`
`md`	`16px`
`lg`	`24px`
`xl`	`32px`

Elevation

The elevation object defines five shadow levels that map to Material 3 tonal elevation. Values are written to CSS as --md-sys-elevation-<key>.

Key	Default value
`level0`	`none`
`level1`	`0 1px 2px rgba(0,0,0,0.2)`
`level2`	`0 2px 6px rgba(0,0,0,0.2)`
`level3`	`0 6px 12px rgba(0,0,0,0.25)`
`level4`	`0 12px 24px rgba(0,0,0,0.3)`

Custom theme example

Spread the default theme and override only the parts you need. The dark theme automatically inherits the shapes, spacing, typography, and elevation from the light theme unless you override them explicitly.

// theme.ts
// Build theme objects that satisfy the ComposeTheme shape.
// All five top-level fields (colorScheme, typography, shapes, spacing, elevation) are required.
// Copy the typography block from the defaults below and adjust individual roles as needed.

const fontFamily = "system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif";

const baseTypography = {
  displayLarge:   { fontFamily, fontSize: "57px", lineHeight: "64px", letterSpacing: "-0.25px", fontWeight: 400 },
  displayMedium:  { fontFamily, fontSize: "45px", lineHeight: "52px", letterSpacing: "0px",     fontWeight: 400 },
  displaySmall:   { fontFamily, fontSize: "36px", lineHeight: "44px", letterSpacing: "0px",     fontWeight: 400 },
  headlineLarge:  { fontFamily, fontSize: "32px", lineHeight: "40px", letterSpacing: "0px",     fontWeight: 400 },
  headlineMedium: { fontFamily, fontSize: "28px", lineHeight: "36px", letterSpacing: "0px",     fontWeight: 400 },
  headlineSmall:  { fontFamily, fontSize: "24px", lineHeight: "32px", letterSpacing: "0px",     fontWeight: 400 },
  titleLarge:     { fontFamily, fontSize: "22px", lineHeight: "28px", letterSpacing: "0px",     fontWeight: 400 },
  titleMedium:    { fontFamily, fontSize: "16px", lineHeight: "24px", letterSpacing: "0.15px",  fontWeight: 500 },
  titleSmall:     { fontFamily, fontSize: "14px", lineHeight: "20px", letterSpacing: "0.1px",   fontWeight: 500 },
  bodyLarge:      { fontFamily, fontSize: "16px", lineHeight: "24px", letterSpacing: "0.5px",   fontWeight: 400 },
  bodyMedium:     { fontFamily, fontSize: "14px", lineHeight: "20px", letterSpacing: "0.25px",  fontWeight: 400 },
  bodySmall:      { fontFamily, fontSize: "12px", lineHeight: "16px", letterSpacing: "0.4px",   fontWeight: 400 },
  labelLarge:     { fontFamily, fontSize: "14px", lineHeight: "20px", letterSpacing: "0.1px",   fontWeight: 500 },
  labelMedium:    { fontFamily, fontSize: "12px", lineHeight: "16px", letterSpacing: "0.5px",   fontWeight: 500 },
  labelSmall:     { fontFamily, fontSize: "11px", lineHeight: "16px", letterSpacing: "0.5px",   fontWeight: 500 },
};

const baseShapes    = { none: "0px", extraSmall: "2px", small: "4px", medium: "8px", large: "12px" };
const baseSpacing   = { xs: "4px", sm: "8px", md: "16px", lg: "24px", xl: "32px" };
const baseElevation = {
  level0: "none",
  level1: "0 1px 2px rgba(0,0,0,0.2)",
  level2: "0 2px 6px rgba(0,0,0,0.2)",
  level3: "0 6px 12px rgba(0,0,0,0.25)",
  level4: "0 12px 24px rgba(0,0,0,0.3)",
};

export const myLightTheme = {
  colorScheme: {
    primary: "#0057B8",
    onPrimary: "#FFFFFF",
    secondary: "#005F73",
    onSecondary: "#FFFFFF",
    tertiary: "#6750A4",
    onTertiary: "#FFFFFF",
    background: "#FFFFFF",
    onBackground: "#1C1B1F",
    surface: "#FFFFFF",
    onSurface: "#1C1B1F",
    surfaceVariant: "#F4F4F4",
    onSurfaceVariant: "#D0D0D0",
    outline: "#B0B0B0",
    error: "#BA1A1A",
    onError: "#FFFFFF",
  },
  typography: baseTypography,
  shapes: baseShapes,
  spacing: baseSpacing,
  elevation: baseElevation,
};

export const myDarkTheme = {
  ...myLightTheme,
  colorScheme: {
    ...myLightTheme.colorScheme,
    primary: "#5EA9FF",
    onPrimary: "#003070",
    background: "#080808",
    onBackground: "#E6E6E6",
    surface: "#101010",
    onSurface: "#E6E6E6",
  },
};

<!-- App.svelte -->
<script lang="ts">
  import { ComposeTheme } from "@danielito1996/compose-svelted";
  import { myLightTheme, myDarkTheme } from "./theme";
</script>

<ComposeTheme light={myLightTheme} dark={myDarkTheme} mode="system">
  <AppRoot />
</ComposeTheme>

Density

The Density object exposes named constants for UI density modes. Components that support density-aware sizing adjust their touch targets and internal padding accordingly.

import { Density } from "@danielito1996/compose-svelted";

Density.Default   // "default" — standard Material 3 touch targets
Density.Compact   // "compact" — reduced padding for information-dense UIs

DensityToken is the union type "default" | "compact". Pass a DensityToken to any component that accepts a density prop to override the default for that subtree.

Get Started

Core Concepts

Layout Components

UI Components

Motion

Navigation

Examples

Theming with ComposeTheme and Material 3 Color Schemes

`<ComposeTheme>` component

Props

The `ComposeTheme` type

Color scheme tokens

Typography tokens

Shapes, spacing, and elevation

Shapes

Spacing

Elevation

Custom theme example

Density

Build docs developers (and LLMs) love

Get Started

Core Concepts

Layout Components

UI Components

Motion

Navigation

Examples

Documentation Index

​<ComposeTheme> component

​Props

​The ComposeTheme type

​Color scheme tokens

​Typography tokens

​Shapes, spacing, and elevation

​Shapes

​Spacing

​Elevation

​Custom theme example

​Density

Build docs developers (and LLMs) love

`<ComposeTheme>` component

Props

The `ComposeTheme` type

Color scheme tokens

Typography tokens

Shapes, spacing, and elevation

Shapes

Spacing

Elevation

Custom theme example

Density