Theming
Tokens

Design Tokens

Design tokens are the atomic building blocks of the visual system. They define colors, spacing, typography, and more. All tokens live in @gtcx/tokens.

Primitive Colors

Raw color values organized by hue and shade:

import { colorPrimitives } from '@gtcx/tokens';
 
colorPrimitives.primary[500];   // '#0ea5e9' (sky blue)
colorPrimitives.success[500];   // '#22c55e' (green)
colorPrimitives.warning[500];   // '#f59e0b' (amber)
colorPrimitives.error[500];     // '#ef4444' (red)
colorPrimitives.neutral[500];   // '#737373' (gray)

Each color has 10 shades (50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950).

Semantic Colors

Named by intent, not by visual value:

import { semanticColors } from '@gtcx/tokens';
 
semanticColors.text;            // Primary text
semanticColors.textSecondary;   // Secondary text
semanticColors.textMuted;       // Muted/disabled text
semanticColors.background;      // Page background
semanticColors.surface;         // Card/panel surface
semanticColors.border;          // Default border
semanticColors.borderSubtle;    // Subtle border
semanticColors.brandPrimary;    // Brand primary
semanticColors.success;         // Success state
semanticColors.warning;         // Warning state
semanticColors.error;           // Error state
semanticColors.info;            // Info state

Spacing

4px base unit system:

import { semanticSpacing } from '@gtcx/tokens';
 
semanticSpacing.xs;   // 4px
semanticSpacing.sm;   // 8px
semanticSpacing.md;   // 16px
semanticSpacing.lg;   // 24px
semanticSpacing.xl;   // 32px
semanticSpacing.xxl;  // 48px

Typography

import { typography } from '@gtcx/tokens';
 
typography.fontFamily;     // 'Inter, -apple-system, sans-serif'
typography.fontSize.sm;    // 12px
typography.fontSize.base;  // 14px
typography.fontSize.lg;    // 16px
typography.fontSize.xl;    // 20px
typography.fontSize.xxl;   // 24px

Breakpoints

import { breakpoints } from '@gtcx/tokens';
 
breakpoints.sm;   // 640px
breakpoints.md;   // 768px
breakpoints.lg;   // 1024px
breakpoints.xl;   // 1280px
breakpoints.xxl;  // 1536px

Z-Index Scale

import { zIndex } from '@gtcx/tokens';
 
zIndex.dropdown;   // 1000
zIndex.sticky;     // 1020
zIndex.fixed;      // 1030
zIndex.modal;      // 1040
zIndex.popover;    // 1050
zIndex.tooltip;    // 1060

Dark Theme Tokens

Dark mode tokens mirror the semantic color structure with appropriate dark-mode values:

import { darkSemanticColors } from '@gtcx/tokens';
 
darkSemanticColors.text;         // neutral[50]  — light text on dark bg
darkSemanticColors.background;   // neutral[950] — dark page background
darkSemanticColors.surface;      // neutral[900] — dark card surface
darkSemanticColors.border;       // neutral[700] — subtle dark border

Dark tokens are automatically applied when using GtcxConfigProvider mode="dark".

Usage Guidelines

  • Always use semantic tokens in application code, not primitives
  • Primitives are for the theme system and component library internals
  • Override tokens via createAntdTheme(), not CSS variables
RTLLayout Switcher