Skip to content

COLOR_SYSTEM.md

Latest commit

 

History

History
247 lines (177 loc) · 7.7 KB

COLOR_SYSTEM.md

File metadata and controls

247 lines (177 loc) · 7.7 KB

Canva Color System

Overview

This project uses Canva's custom color system, which overrides Tailwind CSS default colors to maintain brand consistency. All color utilities work with standard Tailwind naming conventions (e.g., purple-500, red-600) while using Canva's carefully crafted color palette.

Approved Color Families

The following color families are available and should be used exclusively:

Core Brand Colors

  • Purple - Interactive elements, primary actions, and brand emphasis
  • Red - Critical moments, errors, and warnings
  • Green - Positive moments, success states, and confirmations
  • Yellow - Wary moments, caution states, and attention-grabbing elements
  • Blue - Informational moments, secondary actions, and content areas
  • Teal - Legacy brand color (limited to 4 shades)

Neutral Colors

  • Gray - UI elements, backgrounds, and neutral content
  • Black - Text, borders, and high-contrast elements (with alpha variants)
  • White - Backgrounds, cards, and light elements (with alpha variants)

Color Scale

All colors use Tailwind's standard 100-900 scale where:

  • 100 = Lightest shade (most subtle)
  • 500 = Base/mid-tone color
  • 900 = Darkest shade (most prominent)
  • 950 = Ultra-dark variant (where applicable)

Usage Examples

// Primary interactive elements
<button className="bg-purple-600 text-white hover:bg-purple-700">

// Success states
<div className="bg-green-100 text-green-800 border border-green-200">

// Error states
<div className="bg-red-100 text-red-800 border border-red-200">

// Warning states
<div className="bg-yellow-100 text-yellow-800 border border-yellow-200">

// Informational content
<div className="bg-blue-100 text-blue-800 border border-blue-200">

// Neutral UI elements
<div className="bg-gray-100 text-gray-800 border border-gray-200">

Special Color Variants

Purple Alpha

For overlay states and subtle interactions, use the purple-alpha namespace:

// Overlay backgrounds
<div className="bg-purple-alpha-20">

// Selected states
<div className="bg-purple-alpha-30 border-purple-alpha-50">

Available opacity levels: 0, 7, 15, 20, 30, 40, 50, 60, 70, 86, 100

Black & White Alpha

These colors have unique color values (not pure black/white) with transparency:

// Subtle overlays
<div className="bg-black-200">

// Card backgrounds
<div className="bg-white-900">

Color Usage Guidelines

When to Use Each Color

  • Purple: Interactive buttons, links, primary CTAs, brand elements
  • Red: Error messages, destructive actions, critical alerts
  • Green: Success messages, confirmations, positive feedback
  • Yellow: Warning messages, caution states, temporary highlights
  • Blue: Information messages, secondary actions, content areas
  • Gray: Neutral UI elements, disabled states, subtle borders
  • Black: Primary text, strong borders, high-contrast elements
  • White: Backgrounds, cards, light UI elements
  • Teal: Legacy brand elements (use sparingly)

Accessibility

  • Always ensure sufficient contrast ratios (4.5:1 for normal text, 3:1 for large text)
  • Test color combinations for colorblind accessibility
  • Use semantic color meanings consistently

Brand Compliance

  • Use the canva namespace for explicit brand colors when needed: 
    <div className="bg-canva-turq">
<div className="text-canva-blue">
  • Prefer standard color utilities for most UI elements
  • Maintain consistency with Canva's design language

Prohibited Colors

Do NOT use Tailwind default colors that are not part of the Canva system:

  • ❌ slate, zinc, neutral, stone (use gray instead)
  • ❌ orange (use yellow for warning states)
  • ❌ lime, emerald, cyan, sky, indigo, violet, fuchsia, pink, rose

Migration Notes

When updating existing code:

  1. Replace gray-* classes with gray-* (already mapped)
  2. Replace red-* classes with red-* (already mapped)
  3. Replace blue-* classes with blue-* (already mapped)
  4. Replace green-* classes with green-* (already mapped)
  5. Replace yellow-* classes with yellow-* (already mapped)
  6. Replace purple-* classes with purple-* (already mapped)

The color system maintains backward compatibility with standard Tailwind class names while providing Canva's brand-consistent colors.

Semantic Tokens

In addition to the base color palette, we provide semantic tokens that map component-specific use cases to the appropriate colors. These tokens make it easier to maintain consistent UI patterns and ensure proper color usage across different contexts.

Action Tokens

For buttons, CTAs, and interactive elements:

// Primary actions (main purpose buttons)
<button className="bg-action-primary-bg text-action-primary-fg hover:bg-action-primary-bg-hovered">

// Secondary actions (supporting buttons)
<button className="bg-action-secondary-bg text-action-secondary-fg border-action-secondary-border">

// Critical actions (destructive/dangerous)
<button className="bg-action-critical-bg text-action-critical-fg hover:bg-action-critical-bg-hovered">

// Selected states
<button className="bg-action-selected-bg text-action-selected-fg border-action-selected-border">

Feedback Tokens

For badges, alerts, and status indicators:

// Success feedback
<div className="bg-feedback-positive-bg text-feedback-positive-fg">

// Subtle success feedback
<div className="bg-feedback-positive-subtle-bg text-feedback-positive-subtle-fg">

// Error feedback
<div className="bg-feedback-critical-bg text-feedback-critical-fg">

// Warning feedback
<div className="bg-feedback-warn-bg text-feedback-warn-fg">

UI Tokens

For backgrounds, borders, and overlays:

// Card backgrounds
<div className="bg-ui-neutral-bg border-ui-border">

// Focus states
<input className="border-ui-border-focused">

// Overlay backgrounds
<div className="bg-ui-overlay-bg">

Content Tokens

For text and icon colors:

// Primary text
<p className="text-content-fg">

// Secondary text
<p className="text-content-subtle-fg">

// Placeholder text
<input placeholder="Enter text" className="placeholder-content-placeholder-fg">

// Status text
<span className="text-content-positive-fg">Success!</span>

Control Tokens

For form elements:

// Default form controls
<input className="bg-control-bg border-control-border focus:border-control-border-focused">

// Error states
<input className="border-control-critical-border">

// Selected states (toggles, checkboxes)
<div className="bg-control-selected-bg text-control-selected-fg">

Link Tokens

For navigational elements:

// Standard links
<a className="text-link-fg hover:text-link-fg-hovered">

// Critical links
<a className="text-link-critical-fg hover:text-link-critical-fg-hovered">

Handle Tokens

For drag handles and grabbers:

// Drag handles
<div className="bg-handle-bg">

// Disabled handles
<div className="bg-handle-bg-disabled">

Semantic Token Benefits

  1. Consistency: Ensures the same visual treatment across similar components
  2. Maintainability: Changes to semantic tokens automatically update all usage
  3. Accessibility: Semantic tokens include proper contrast ratios and state indicators
  4. Design System Compliance: Follows Canva's established design patterns
  5. Developer Experience: Clear, descriptive names make intent obvious

Usage Guidelines for Semantic Tokens

  • Prefer semantic tokens over direct color utilities when building components
  • Use base colors (purple-600, red-500) for custom designs that don't fit standard patterns
  • Combine tokens as needed (e.g., bg-action-primary-bg text-action-primary-fg)
  • Test accessibility when combining tokens in new ways