react-styling

name	react-styling
description	Use when building or styling a React component in libs/ui-react (and ui-react-visualization) — cva usage, props-drilling, and design-system Tailwind token usage (typography, colors, spacing, sizes, shadows, gradients, and classname rules).
paths	libs/ui-react/**/*.ts, libs/ui-react/**/*.tsx, libs/ui-react-visualization/**/*.ts, libs/ui-react-visualization/**/*.tsx

React styling & component patterns (libs/ui-react)

Conventions for composing classnames and authoring React components in the UI Kit.

class-variance-authority (cva)

• Use cva at the top of the file to compose classnames when there is variant composition.
• Use cva at the top of the file when an element has many classnames to declare.
• Otherwise, for only a few classnames, set them inline in the JSX.

Props drilling

• Component props should be props-drilled to the top-level element so behaviour is never hidden or misleading.
• For legitimate exceptions (e.g. a nested ref or a nested className), give the prop a distinct name that makes the target explicit rather than overloading the top-level prop.

Design-system Tailwind tokens

• Use the figma mcp server when working from Figma, but these rules always apply even without it.
• You can see our custom Tailwind plugins in libs/design-core/src/lib/presets/allBrands.ts.
• All -default suffixes are removed via code syntax, so omit them from Tailwind utilities.

Typography Utilities Guidelines

• Do not use Tailwind Typography utilities (e.g., font-bold, text-sm, etc.).
• Use our custom typography utilities from the design system.
• Source of truth: libs/design-core/src/lib/utils/createCustomPlugin.ts (see createTypographyPlugin).
• Available utility classes include:
  • .responsive-display-1 to .responsive-display-4
  • .heading-0, .heading-0-semi-bold through .heading-4, .heading-4-semi-bold
  • .body-1, .body-1-semi-bold through .body-4, .body-4-semi-bold

Colors and Background

• Do not use Tailwind default color palette (e.g., text-gray-500, bg-blue-600).
• Use our design tokens from createThemePlugin:
  • Text colors: text-base, text-on-accent, text-muted, etc.
  • Background colors: bg-base, bg-muted, bg-accent, etc.
  • Border colors: border-base, border-muted, border-accent, etc.
  • Crypto colors: crypto-btc, crypto-eth, etc. (and their variants like crypto-btc-0)
  • Discovery colors: discover-base, discover-muted, etc.

Spacing and Layout

• Use pixel values for spacing when raw values are needed
• Available spacing utilities:
  • Padding: p-{size}, px-{size}, py-{size}, pt-{size}, etc.
  • Margin: m-{size}, mx-{size}, my-{size}, mt-{size}, etc.
  • Where size is a pixel-based value (e.g., 4, 8, 16, etc.)

Width, Height, and Size Utilities

• Do not use arbitrary size values (e.g., w-[108px], h-[90px])
• Only use size tokens that exist in libs/design-core/src/lib/themes/css/primitives.css
• Source of truth: libs/design-core/src/lib/themes/css/primitives.css (see --size-* tokens)

Available Size Tokens

Sizes available for width, height, max-width, max-height, min-width, min-height utilities:

Small sizes: 0, 1, 2, 4, 6, 8, 10, 12, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 56, 64, 72, 80, 96

Large sizes: 112, 128, 144, 176, 192, 208, 224, 256, 288, 320, 400, 480, 560

How to Check Available Tokens

Before using width/height utilities:

1. Check libs/design-core/src/lib/themes/css/primitives.css for --size-* tokens
2. Or use VSCode IntelliSense with Tailwind CSS extension
3. If uncertain, use the Tailwind CSS IntelliSense autocomplete

Borders and Shadows

• Border radius utilities from createThemePlugin:

  • rounded-sm, rounded-md, rounded-lg, etc.

• Border width utilities:

  • Use border for default width
  • Use border-2 for active/emphasized states

• Shadow utilities from createShadowPlugin:

  • shadow-sm: 1px 4px rgba(0, 0, 0, 0.16)
  • shadow-md: 2px 8px rgba(0, 0, 0, 0.16)
  • shadow-lg: 4px 16px rgba(0, 0, 0, 0.16)
  • shadow-xl: 6px 24px rgba(0, 0, 0, 0.16)
  • shadow-2xl: 8px 32px rgba(0, 0, 0, 0.16)

Gradients

• Background gradients from createGradientPlugin:
  • bg-gradient-top: 180deg gradient for top overlays
  • bg-gradient-bottom: 180deg gradient for bottom overlays
  • bg-gradient-{crypto}: 161deg gradient for crypto colors

Tailwind Classnames

• Tailwind utilities should never be concatenated
• Always use complete class names as strings
• Use template literals or array joining for dynamic class names
• Example: className="text-base bg-muted" ✅
• Example: className={text-${color}} ❌
• Example: className={cn("text-base", color && "bg-muted")} ✅