Create a custom theme

The C3 AI UI Framework supports two ways to customize themes:

• Tweak an existing base theme such as C3DefaultLight or C3DefaultDark
• Define a new theme Type when your components need additional design tokens

Use the first option to override standard fields like color and background. Use the second when your components require tokens that the built-in themes don’t define—such as a custom border radius or shadow.

Copy link to this section

Tweak an existing theme

You can override only the fields you want without creating a new .c3typ.

Copy link to this section

Step 1: Choose a base theme

Start with one of the supported base Types:

• UiSdlLightTheme
• UiSdlDarkTheme

Copy link to this section

Step 2: Create a theme configuration file

Define your customizations in a new file:

// {package}/metadata/UiSdlThemeTemplate/MyTheme.json
{
  "type": "UiSdlDarkTheme",
  "id": "MyTheme",
  "accentColor": "#F4A30C",
  "componentBackgroundColor": "#f6ff00ff"
}

The platform fills in any missing fields using defaults from the specified base theme.

To view available fields, run:

c3ShowType(UiSdlDarkTheme)

Replace UiSdlDarkTheme with UiSdlLightTheme if needed.

Copy link to this section

Step 3: Apply the theme

Update your configuration to apply the new theme by updating the id field:

// {package}/config/UiSdlConfig/UiSdlConfig.json
{
  "style": {
    "theme": {
      "id": "MyTheme"
    }
  }
}

Once you add a theme to your application package, all app deployments will use that theme by default.

To override the theme at runtime, use the browser console:

UiSdlConfig.make().setConfigValue("style.theme.id", "MyTheme");

Runtime overrides take precedence over the package configuration but reset after each redeploy. Reapply them manually if needed.

Copy link to this section

Create a new theme Type with custom fields

Create a new theme Type when your components need a token that the platform themes don’t include.

Copy link to this section

Step 1: Define the custom Type

Create a .c3typ file and define the custom field:

// {package}/src/MyRoundedTheme.c3typ
type MyRoundedTheme mixes UiSdlThemeTemplate {
  borderRoundness: !string = "2px"
}

This Type extends the base theme Type and adds a new token.

Copy link to this section

Step 2: Create a theme instance

Create a new metadata file and define your theme values:

// {package}/metadata/UiSdlThemeTemplate/MyRoundedTheme.json
{
  "type": "MyRoundedTheme",
  "id": "MyRoundedTheme",
  "accentColor": "#F4A30C",
  "componentBackgroundColor": "#011E4D",
  "borderRoundness": "4px"
}

Copy link to this section

Step 3: Reference the token in your component styles

Use your new token inside a component SCSS module:

// {package}/src/ui/components/Button.module.scss
.btn {
  border-radius: var(--c3-style-borderRoundness);
}

The platform injects the token value during the build process.

Copy link to this section

Step 4: Apply the new theme

Point your configuration to the custom theme:

// {package}/config/UiSdlConfig/UiSdlConfig.json
{
  "style": {
    "theme": {
      "id": "MyRoundedTheme"
    }
  }
}

This configuration ensures that all deployments use your custom theme. Use the runtime override to test changes temporarily without redeploying.