Skip to content

Tokens

Get Ritla UI

How a Figma variable becomes a CSS variable and a Tailwind utility with the same name, and why modes switch variables, not classes.

Every color, size, font and motion value in Ritla UI is a token. Components never hard-code a value, which is what lets a theme change the look without changing a line of layout, and what keeps the Figma file and the code from drifting apart.

What you get#

Three CSS files and one JSON file, plus an opt-in stylesheet for strict mode:

FileWhat it holds
ritla.css, the variables fileThe values, as CSS variables: light colors, English and Arabic type, spacing, radii, border widths, shadows, motion and layers.
The dark fileThe dark colors and the theme-dark: variant, for one dark switch: ritla-dark-class.css, ritla-dark-attr.css or ritla-dark-system.css (see Dark mode).
theme.cssThe Tailwind v4 theme. It maps utilities like bg-surface-default and p-space-16 onto those variables, beside Tailwind's own palette and scales, and adds the dir-rtl: and dir-ltr: variants (see Direction).
tokens.jsonA flat list of every token with its CSS variable, type, value per mode and alias. For tools and AI agents.

npx ritla init adds the three CSS files to lib/ritla/ in your project and imports them after Tailwind. ritla-strict.css is added only when you ask for it: see Strict mode.

How names work#

A token's name is its path in Figma. Its CSS variable is that path with slashes turned into dashes, behind the --ritla- prefix, and tokens.json lists each one as cssVar. The utility is the path without its first group, so the name a designer reads in Figma is the class a developer types. Where Tailwind already uses a name, the theme's utility takes a group of its own so the two never meet: spacing is space-, shadows and blurs are elevation-, container widths are container-.

FigmaTailwind
background/surface/defaultbg-surface-default
text/gray/txt-primarytext-gray-txt-primary
text/brand/txt-subtletext-brand-txt-subtle
icons/gray/icon-strongtext-gray-icon-strong
border/gray/softborder-gray-soft
space-16p-space-16, gap-space-16, ms-space-16
radius/8rounded-8
shadow/mdshadow-elevation-md
body-14 (text style: size, line height, letter spacing)text-body-14
duration/moderate, easing/standardduration-moderate, ease-standard
z-index/dropdownz-dropdown

Color names read from general to specific: what it paints (background, text, icons, border), the family (gray, brand, red, amber, green), then the strength. Text strengths run txt-primary, txt-secondary, txt-subtle, txt-muted, txt-dim, txt-soft, txt-faint. Use primary, secondary or subtle for anything people need to read: those meet WCAG AA (4.5:1) on the page and card surfaces (surface/lowest to surface/high, container/soft to container/muted) in both themes. On surface/highest and container/strong, green and amber txt-subtle fall just under (4.25 and 4.28 in light), so use their txt-secondary there. surface/inverse and container/fixed take the invert and static text tokens, not these. Muted and dim are low emphasis; soft and faint are for decoration and placeholders.

Token groups#

  • Color: background, text, icons, border, alpha (tint and shade overlays), accent, theme ramps and focus ring colors, each with a light and a dark value.
  • Typography: family, weight, size, line height and letter spacing, with an English and an Arabic value.
  • Spacing: one scale used for padding, gaps, margins and sizes.
  • Borders: radii and border widths.
  • Widths: containers, components, the touch target and breakpoints (in rem).
  • Effects: shadows, focus rings and backdrop blur.
  • Motion: durations and easings.
  • Layers: a fixed z-index order from base to tooltip.

Light and dark#

The theme switches the variables, not the classes, so most of a component never needs a dark variant. Where one does, it uses theme-dark:, which npx ritla init points at your app's own dark switch: the .dark class by default, data-theme="dark" or the system setting. Tailwind's dark: stays yours. Light is the default. The default theme's dark mode is a neutral gray: every gray in it has equal red, green and blue, so nothing reads blue-tinted next to the brand color. More in Dark mode.

English and Arabic type#

lang="ar" on any element switches it to the Arabic type values: IBM Plex Sans Arabic, taller line heights and no letter spacing. English uses Geist. Every font stack contains both families, so Arabic text inside an English layout still renders in the Arabic face, never in a Latin fallback.

html
<section lang="ar" dir="rtl">...</section>

Direction#

Write layout with logical utilities: ms-space-*, me-space-*, ps-space-*, pe-space-*, start-*, end-*, text-start, border-s, rounded-s-*. They follow dir on their own. When you need a direction-specific style, use dir-rtl: and dir-ltr:. They match the nearest dir attribute, not any ancestor, so an English island inside an Arabic page (a code sample, a phone number field) stays left to right. Tailwind's own rtl: and ltr: are untouched and keep their meaning: any ancestor with that direction. See Arabic and RTL principles.

Beside Tailwind's own values#

The theme adds its values; it removes none of Tailwind's. bg-red-500, text-sm, p-4 and font-bold keep working, and the theme's names sit beside them: bg-red-normal, text-body-14, p-space-16, font-semibold. Use the theme's names in anything built with Ritla UI, so a theme change reaches it.

Spacing steps are 0 2 4 6 8 10 12 14 16 20 24 32 40 48 64 80 96 128 160 192 224 256 320, named in pixels: p-space-12 is 12px. Tailwind's p-12 is still Tailwind's (3rem), so the space- in the name matters. To combine tokens, use an arbitrary value made of their CSS variables (each one's cssVar in tokens.json), never a raw number.

To use only the theme's values, with Tailwind's defaults removed, turn on strict mode.

Names your theme might share#

Ritla UI's colors live in role namespaces, so a key of yours meets one of them only when the whole name after the namespace is the same. Check your own @theme against these:

Your utilityRitla UI's names start with
bg-amber-, brand-, container-, danger-, disabled-, green-, overlay-, red-, skeleton-, static-, success-, surface-, warning-
text-amber-, brand-, danger-, disabled-, gray-, green-, icon-, invert-, red-, static-, success-, warning-
border-amber-, brand-, danger-, disabled-, gray-, green-, red-, success-, surface-, warning-
fill-, stroke-amber-, brand-, disabled-, gray-, green-, icon-, red-, static-
any color utilityaccent-, alpha-, chart-, theme-
rounded-a bare number: --radius-0, --radius-2 to --radius-24

Each name continues with a role, such as surface-default, gray-txt-primary or chart-series-1; tokens.json lists every one as cssVar. Two cases meet:

  • The same key in both. If your @theme declares the same key, such as --radius-8, the later @theme wins, in both directions.
  • The same name in a wider namespace. Tailwind reads bg-surface-default from --background-color-surface-default before --color-surface-default, and text- and border- the same way. So a --color-surface-default of yours loses to Ritla UI's for bg-surface-default.

None of these names is a Tailwind default or a shadcn convention key, such as --color-primary, --color-chart-1 or --radius-lg.

Where tokens come from#

Figma variables are the source of truth. The token build takes a snapshot of the Ritla for Figma file's variables and styles, converts it to a DTCG tokens.json, and runs Style Dictionary to write the variables file, theme.css, ritla-strict.css and the flat tokens.json. The build is one command and reproducible: the same snapshot always produces the same files, byte for byte. You never edit the generated files; a change starts in Figma.

For AI agents#

Point your agent at tokens.json rather than the CSS: each entry has name (the Figma path), cssVar, type, values per mode (light and dark, or default) and aliases (the primitive it points to). An agent that writes text-gray-txt-primary instead of #151515 keeps your UI correct in both themes.