Overview

Our design system is built on Tailwind CSS with minimal adjustments. We preserve all standard Tailwind utilities while adding custom tokens through a cn- prefix for design system-specific values like colors, spacing, and typography.

How It Works

The design system extends Tailwind’s default configuration rather than replacing it. This means you have access to both our design system tokens and all standard Tailwind utilities.

// ✅ Using design system tokens
<Layout.Horizontal className="bg-cn-1 text-cn-2 p-cn-md">
  <Text>Content</Text>
</Layout.Horizontal>

// ✅ Using standard Tailwind utilities
<Layout.Horizontal className="items-center justify-between">
  <Text>Content</Text>
</Layout.Horizontal>

// ✅ Combining both
<Layout.Horizontal className="items-center gap-cn-sm bg-cn-2 rounded-3">
  <Text>Content</Text>
</Layout.Horizontal>

Customizing Components

All components accept a className prop for customization. Use design system tokens for theme-aware styling and standard Tailwind utilities for layout and positioning.

Color Customization

Our color system provides semantic colors optimized for light and dark modes. Use design system color tokens to ensure proper theme support.

Semantic Color Sets

Important

Always use matching text, background, and border classes together (e.g., text-cn-success-primary with bg-cn-success-primary). Mixing variants (like text-cn-success-primary with bg-cn-success-secondary) will produce incorrect visual results.

Practical Examples

Custom Card component

Custom Alert Component

Custom Button Layouts

Standard Tailwind Utilities

All standard Tailwind utilities work alongside our design system. Use them for layout, positioning, responsive design, and state variants.

// Layout utilities
<Layout.Horizontal className="flex-col md:flex-row items-center justify-between">
  <Text>Content</Text>
</Layout.Horizontal>

// Responsive design
<Layout.Horizontal className="w-full md:w-1/2 lg:w-1/3">
  <Text>Content</Text>
</Layout.Horizontal>

// State variants
<Button className="hover:opacity-80 focus:ring-2 active:scale-95">
  Interactive Button
</Button>

// Grid utilities
<Layout.Grid className="grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
  <Text>Item</Text>
</Layout.Grid>

Arbitrary Values

Use Sparingly

While Tailwind supports arbitrary values like w-[347px] or bg-[#bada55], use them only when design system tokens don’t fit your needs. Never use arbitrary values for colors as this creates visual inconsistency and breaks theme support. Always prefer design system tokens for maintainability and consistency.

// ⚠️ Use only when necessary
<Layout.Horizontal className="w-[347px] h-[52px]">
  <Text>Fixed dimensions</Text>
</Layout.Horizontal>

// ❌ Never do this - breaks theming
<Button className="bg-[#ff0000] text-[#ffffff]">
  Bad Practice
</Button>

// ✅ Use design tokens instead
<Button className="bg-cn-danger-primary text-cn-danger-primary">
  Good Practice
</Button>

Best Practices

1. Use design system tokens for colors, spacing, typography, and borders to ensure consistency and proper theme support
2. Use standard Tailwind for layout (flex, grid), positioning, and responsive utilities (md:, lg:)
3. Always match semantic color variants (primary with primary, outline with outline)
4. Leverage Layout components instead of raw div elements for consistent spacing and structure
5. Prefer Text component for text content to maintain typography consistency
6. Use opacity utilities for color variations: bg-cn-2/50 for 50% opacity
7. Avoid arbitrary color values to maintain visual consistency across themes

Resources

• Tailwind CSS Documentation - Complete guide to all Tailwind utilities
• Tailwind CSS IntelliSense - VS Code extension for autocomplete
• Tailwind CSS Cheat Sheet - Quick reference for all utilities

Next Steps

Explore specific component documentation to see how these customization patterns are applied in practice. Each component page includes live examples you can modify and experiment with.