Design tokens

The design tokens are the SDK's named colors, spacing, corner radii, type sizes and shadows. The components build their styles from them. For example, the bubbles of the user's own messages use the chatBgOutgoing token, which points at brand100, which is the blue100 color, #e3edff, in the light scheme.

The tokens come in four tiers. Only the semantic tokens are part of the theme, under theme.semantics, so they're the only tokens you can override. This page lists every token with its value on iOS and Android, in the light and the dark scheme. Theme object lists the rest of the theme, and Theming shows how to set it.

How the tokens are organized

Each tier is built from the one above it:

The foundations, the primitives and the component tokens aren't exported. The components import them as constants, so they don't change with the theme. To change the spacing, radius or size of one part, set its component style in the theme, or replace the component.

A semantic token holds a color, or points at another token. A pointer is either a foundation color, resolved when the SDK loads, or a $ reference to another semantic token, such as accentPrimary: "$brand500". The SDK resolves the $ references each time it builds the theme. The brand and chrome scales are semantic tokens too. The brand scale, brand50 to brand900, carries the accent hue, and the chrome scale, chrome0 to chrome1000, carries the neutrals of text, backgrounds and borders.

Light and dark

The semantic tokens have a light and a dark set, with the same 209 names. The SDK picks the set by the color scheme useColorScheme() returns, and builds the theme again when the scheme changes. The foundations, the primitives and the component tokens are the same in both schemes.

The dark scheme flips mostly through the two scales. textPrimary points at chrome900 in both schemes. In the light scheme chrome900 is slate900, #1a1b25. In the dark scheme it's neutral50, #f8f8f8. The brand scale runs in reverse in the dark scheme, and a few tokens point at a different step, such as accentPrimary, which is brand500 in the light scheme and brand400 in the dark one.

Platforms

The tokens are generated for each platform. The semantic tokens are the same on iOS and Android. These differ:

• The type sizes follow each platform's scale. For example, typographyFontSizeMd is 17 on iOS and 16 on Android.
• The shadows, lightElevation1 to darkElevation4, are tuned for each platform. On Android the shadow color carries the opacity, and elevation draws the shadow.
• deviceRadius, deviceSafeAreaTop and deviceSafeAreaBottom differ too. No component reads them.

The font family tokens, such as typographyFontFamilySans, hold the design file's font names, in quotes. No component reads them, and the components set no font family. See Fonts.

Where the tokens come from

The tokens are generated from Stream's design files, and the SDK keeps them in package/src/theme/generated/ in its repository, one file per scheme and platform:

Metro picks the .ios.ts or .android.ts file of the platform it builds for. The SDK reads the foundations, the primitives and the component tokens from the light files, which hold the same values as the dark ones.

The files are never edited by hand. package/sync-theme.sh copies them from the build output of the design tokens and formats them.

Overriding a semantic token

Set the token under semantics in your theme:

import type { DeepPartial, Theme } from "stream-chat-react-native";

export const theme: DeepPartial<Theme> = {
  semantics: {
    accentPrimary: "#6d28d9",
    badgeBgPrimary: "#6d28d9",
    buttonPrimaryBg: "#6d28d9",
    buttonPrimaryText: "#6d28d9",
    chatTextMention: "#6d28d9",
  },
};

The SDK resolves the default tokens before it merges your theme. A token you set changes the components that read it, and nothing else. The tokens that point at it keep their default values, which is why the example sets badgeBgPrimary, buttonPrimaryBg, buttonPrimaryText and chatTextMention next to accentPrimary. Tokens that point at another token lists them. Three more things to know:

• A $ reference in your theme isn't resolved. "$brand500" stays that string and renders as an invalid color, so write the color itself.
• A token no component reads changes nothing when you set it. The tables mark these tokens. They include the brand and chrome scales, so setting brand500 doesn't recolor the accent.
• Your semantics apply to whichever scheme is active. To use different values in each scheme, pick the theme by the scheme, as Light and dark shows.

To color your own components with the tokens, read them from useTheme().theme.semantics, where every reference is resolved.

Reading the tables

• Light and Dark are the token's values in each scheme. When the token points at another token, the table names that token, with a $ for a semantic token, and the value it resolves to is in brackets.
• iOS and Android are the values on each platform, named the same way.
• Read by components is "no" when no component reads the token. Setting such a semantic token has no effect.

Semantic tokens

The 209 tokens of theme.semantics, by group. No component reads 86 of them.

Accent

Avatar

Background

Badge

Border

Brand scale

Button

Chat

Chrome scale

Controls

Input

Presence

Reaction

Skeleton

System

Text

Tokens that point at another token

Each row lists the semantic tokens whose default points at a token with a $ reference. Setting the token in the first column doesn't change them, so set the ones you want to follow it. The rows hold for both schemes. The brand and chrome scales are left out, because the tokens that point at a step of them differ between the schemes. The tables above show those.

Primitives

The primitives aren't part of the theme.

Component tokens

The component tokens aren't part of the theme.

Foundations

The foundations aren't part of the theme, and no component reads them directly. They're the same on both platforms and in both schemes.

Color scales

Each token is the scale name and a step, for example green300.

Base colors

Other foundations

Best practices

• Override semantic tokens, not component styles, for colors, and pick the theme by the color scheme to use different colors in each.
• Set every token the parts you want to change read. A token you set doesn't reach the tokens that point at it.
• Check both schemes after a change. A token can point at different steps in the light and the dark scheme.
• Read colors for your own components from useTheme().theme.semantics, so they follow your theme.
• Don't import the generated files. They aren't part of the public API, and the theme doesn't override them.

The tables on this page are generated by a script that reads package/src/theme/generated/{light,dark}/StreamTokens.{ios,android}.ts in the SDK's repository. It takes what each token points at from the source, and each value from the transpiled module. A token is listed as not read when its name appears nowhere in the SDK's source outside the generated files and tests, except the avatar palette tokens, which the avatars read by index.