Skip to content

Theming

Get Ritla UI

A theme is a Figma file and a token set: what it changes, what it never changes, and how to customize the default theme without losing Arabic.

A theme is a Figma file and a token set. Ritla UI components read only tokens, so a theme decides how they look, and the components decide how they behave: direction, digits, keyboard, accessibility. The default theme is the first, and the one every component ships with.

The theme adds its values beside Tailwind's defaults and changes none of your classes, so it works in new and existing apps: see Installation. The one exception is a key of your own with one of the theme's exact names (Tokens).

What a theme is#

  • The Figma file. Every color, type style, radius and spacing value as a variable, and every component in left-to-right and right-to-left variants. Designers work here.
  • The token set. The same variables, built into the variables file, theme.css and tokens.json (see Tokens). Developers install it with npx ritla init.

Both come from one source, the Figma variables, so a designer's change reaches the code as a token change, not as a hand-copied value.

What a theme changes, and what it does not#

A theme changes the values: colors in both modes, the Latin and Arabic font families, type sizes and line heights, radii, spacing, shadows and motion.

It never changes behavior. Which icons mirror, how digits are formatted, how phone and card fields stay left to right, how overlays inherit direction and language: those live in the components and in @ritla/core, and stay the same whatever the theme. The type rules a theme must keep are below.

Customize the default theme#

Override a token in your own stylesheet, after the @import lines npx ritla init added, at the level you need it. Every token's CSS variable starts with --ritla-, and tokens.json lists each one as cssVar:

css
/* After the theme's @import lines */:root {  --ritla-radius-8: 6px; /* a radius, spacing or motion token's cssVar: your value */}

Radius, spacing and motion have one value, so :root is enough. Colors have one per mode and type one per language: override them with the same selectors the theme's files use, or the dark or Arabic value will not change. Dark values take the selector of the dark file you imported: .dark, [data-theme="dark"], or, with the system file, :root:not(.light, [data-theme="light"]) inside @media (prefers-color-scheme: dark).

css
/* Colors: once per mode, with the selectors the theme's files use */:root, .light, [data-theme="light"] { /* the color's cssVar: your light value */ }.dark, [data-theme="dark"] { /* the color's cssVar: your dark value */ } /* Type: once per language */:root, :lang(en) { /* the body font's cssVar: your Latin face, then the Arabic face */ }:lang(ar) { /* the body font's cssVar: the Arabic face, then your Latin face */ }

Change semantic tokens (what a surface or a text strength means) rather than the classes on components; the components pick the new value up everywhere at once. If you change the brand color, keep its contrast with white text at 4.5:1 or more, and keep text colors people need to read at WCAG AA on the surfaces they sit on, in both modes.

Fonts#

Components read their font family from three variables, and fall back to the theme's fonts for each language when a variable is unset:

UtilityVariable
font-family-body--ritla-font-sans
font-family-display--ritla-font-display
font-family-numeric--ritla-font-numeric

To use your own font in every component, add one line after the theme's imports. Keep var(--ritla-font-arabic) in the stack, so Arabic stays on the Arabic face:

css
:root { --ritla-font-sans: "Inter", var(--ritla-font-arabic), system-ui, sans-serif; }

For the same font in headings, set --ritla-font-display in the same line.

npx ritla init --font app takes the other route: the components inherit your page's font (Installation). font-mono is Tailwind's own, so code already follows your app's monospace font.

Arabic in a theme#

A theme has to carry an Arabic face, not only a Latin one. The default theme pairs Geist with IBM Plex Sans Arabic, gives Arabic its own line heights and no letter spacing, and puts both families in every font stack so Arabic never falls back to a system font. A custom theme keeps those rules: see Arabic and RTL principles.

More themes#

More themes are planned on the same token names, so switching one for another is a CSS change. See Themes for what exists today.