Skip to content
CFA Design System

Theming and Tokens

React Core components are styled with design tokens exposed as CSS variables (--ds-*). Theming is controlled by your app, not by individual components.

How it works

  • Importing @cfa/react-core/index.css loads the token variables for every theme. You do not need to install or import @cfa/design-tokens-core separately to use them.
  • The default theme is applied on :root, so no attribute is needed.
  • To use another theme, set a data-theme attribute on an element. The base themes are experimental-red (default) and experimental-navy. cfa-red and cfa-navy are legacy themes; prefer the base themes.
  • Components do not accept a theme prop and do not set data-theme themselves. They read the variables from the nearest themed ancestor.
<html data-theme="experimental-navy">
  ...
</html>

Recommendations

  • Set the theme once at the app level, on <html> (preferred) or an element that contains everything you render.
  • Overlays such as Modal, Drawer, and Popover render outside your component tree, so a theme set on a nested wrapper may not reach them. Put data-theme on <html> so overlays inherit it.
  • Reference tokens through the --ds-* variables in your own styles instead of hard-coded colors, sizes, or radii. Use the search_tokens MCP tool to look up names.
  • Do not rely on token values being the same across themes. Always use the variable.