Theming

Customize Aki UI to match your brand with powerful theming capabilities.

Overview

Aki UI provides a flexible theming system built on CSS custom properties and Tailwind CSS. You can customize colors, typography, spacing, and more to match your brand identity.

  • • CSS Custom Properties: Dynamic theme switching
  • • Tailwind Integration: Seamless with your design system
  • • Dark Mode Support: Built-in dark theme variants
  • • Component Variants: Multiple style options per component

Color System

Default Color Palette

Primary
#3B82F6
Secondary
#6B7280
Success
#10B981
Warning
#F59E0B
Error
#EF4444

Custom Theme Configuration

Tailwind Config

Extend your Tailwind configuration to customize Aki UI's color system:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@akitectio/aki-ui/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          500: '#3b82f6',
          600: '#2563eb',
          700: '#1d4ed8',
          900: '#1e3a8a',
        },
        gray: {
          50: '#f9fafb',
          100: '#f3f4f6',
          200: '#e5e7eb',
          300: '#d1d5db',
          400: '#9ca3af',
          500: '#6b7280',
          600: '#4b5563',
          700: '#374151',
          800: '#1f2937',
          900: '#111827',
        }
      }
    }
  },
  plugins: []
}

CSS Custom Properties

Theme Variables

Aki UI uses CSS custom properties for dynamic theming. You can override these in your CSS:

:root {
  /* Primary Colors */
  --aki-primary-50: 239 246 255;
  --aki-primary-500: 59 130 246;
  --aki-primary-600: 37 99 235;
  --aki-primary-700: 29 78 216;
  
  /* Gray Scale */
  --aki-gray-50: 249 250 251;
  --aki-gray-100: 243 244 246;
  --aki-gray-200: 229 231 235;
  --aki-gray-300: 209 213 219;
  --aki-gray-400: 156 163 175;
  --aki-gray-500: 107 114 128;
  --aki-gray-600: 75 85 99;
  --aki-gray-700: 55 65 81;
  --aki-gray-800: 31 41 55;
  --aki-gray-900: 17 24 39;
  
  /* Component Specific */
  --aki-border-radius: 0.5rem;
  --aki-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1);
  --aki-shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
}

/* Dark theme overrides */
.dark {
  --aki-primary-500: 96 165 250;
  --aki-primary-600: 59 130 246;
}

Dark Mode

Setup

Enable dark mode in your Tailwind configuration:

// tailwind.config.js
module.exports = {
  darkMode: 'class', // or 'media' for system preference
  // ... rest of your config
}

Implementation

Toggle dark mode by adding/removing the 'dark' class:

// Theme toggle component
import { useState, useEffect } from 'react'
import { Button } from '@akitectio/aki-ui'

export function ThemeToggle() {
  const [isDark, setIsDark] = useState(false)

  useEffect(() => {
    const isDarkMode = localStorage.getItem('darkMode') === 'true'
    setIsDark(isDarkMode)
    document.documentElement.classList.toggle('dark', isDarkMode)
  }, [])

  const toggleTheme = () => {
    const newIsDark = !isDark
    setIsDark(newIsDark)
    localStorage.setItem('darkMode', newIsDark.toString())
    document.documentElement.classList.toggle('dark', newIsDark)
  }

  return (
    <Button onClick={toggleTheme} variant="outline">
      {isDark ? '☀️' : '🌙'} {isDark ? 'Light' : 'Dark'} Mode
    </Button>
  )
}

Component Customization

Custom Button Styles

Create custom component variants using Tailwind classes:

<Button className="bg-gradient-to-r from-purple-500 to-pink-500 
                  hover:from-purple-600 hover:to-pink-600 text-white">
  Gradient Button
</Button>

<Button className="bg-orange-500 hover:bg-orange-600 text-white shadow-lg">
  Custom Orange
</Button>

<Button className="border-2 border-green-500 text-green-500 
                  hover:bg-green-500 hover:text-white">
  Green Outline
</Button>

Typography

Font Customization

Customize typography in your Tailwind configuration:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
        heading: ['Poppins', 'system-ui', 'sans-serif'],
      },
      fontSize: {
        'xs': '0.75rem',
        'sm': '0.875rem',
        'base': '1rem',
        'lg': '1.125rem',
        'xl': '1.25rem',
        '2xl': '1.5rem',
        '3xl': '1.875rem',
        '4xl': '2.25rem',
      }
    }
  }
}

Best Practices

Theme Design Guidelines

  • • Consistency: Use a limited color palette consistently
  • • Contrast: Ensure sufficient contrast for accessibility
  • • Hierarchy: Use color and typography to establish visual hierarchy
  • • Testing: Test your theme in both light and dark modes
  • • Performance: Minimize CSS custom property usage for better performance

Accessibility Considerations

  • • Maintain WCAG AA contrast ratios (4.5:1 for normal text)
  • • Test with screen readers and keyboard navigation
  • • Provide alternative ways to convey information beyond color
  • • Consider users with color vision deficiencies