Theme Customization

Ghuo Design provides powerful theming capabilities that allow you to customize the appearance of components to match your brand and design requirements.

Design Tokens

Our theming system is built on design tokens - a set of named entities that store visual design attributes. These tokens ensure consistency across all components.

Color Tokens

:root {
  /* Primary Colors */
  --g-color-primary: #1890ff;
  --g-color-primary-hover: #40a9ff;
  --g-color-primary-active: #096dd9;
  --g-color-primary-light: #e6f7ff;
  
  /* Success Colors */
  --g-color-success: #52c41a;
  --g-color-success-hover: #73d13d;
  --g-color-success-active: #389e0d;
  --g-color-success-light: #f6ffed;
  
  /* Warning Colors */
  --g-color-warning: #faad14;
  --g-color-warning-hover: #ffc53d;
  --g-color-warning-active: #d48806;
  --g-color-warning-light: #fffbe6;
  
  /* Error Colors */
  --g-color-error: #ff4d4f;
  --g-color-error-hover: #ff7875;
  --g-color-error-active: #d9363e;
  --g-color-error-light: #fff2f0;
  
  /* Neutral Colors */
  --g-color-text-primary: #262626;
  --g-color-text-secondary: #595959;
  --g-color-text-tertiary: #8c8c8c;
  --g-color-text-disabled: #bfbfbf;
  
  --g-color-border: #d9d9d9;
  --g-color-border-light: #f0f0f0;
  
  --g-color-background: #ffffff;
  --g-color-background-light: #fafafa;
  --g-color-background-dark: #f5f5f5;
}

Typography Tokens

:root {
  /* Font Family */
  --g-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
  
  /* Font Sizes */
  --g-font-size-xs: 12px;
  --g-font-size-sm: 14px;
  --g-font-size-base: 16px;
  --g-font-size-lg: 18px;
  --g-font-size-xl: 20px;
  --g-font-size-2xl: 24px;
  --g-font-size-3xl: 32px;
  
  /* Font Weights */
  --g-font-weight-normal: 400;
  --g-font-weight-medium: 500;
  --g-font-weight-semibold: 600;
  --g-font-weight-bold: 700;
  
  /* Line Heights */
  --g-line-height-tight: 1.2;
  --g-line-height-normal: 1.5;
  --g-line-height-relaxed: 1.75;
}

Spacing Tokens

:root {
  /* Spacing Scale */
  --g-space-xs: 4px;
  --g-space-sm: 8px;
  --g-space-base: 16px;
  --g-space-lg: 24px;
  --g-space-xl: 32px;
  --g-space-2xl: 48px;
  --g-space-3xl: 64px;
  
  /* Component Spacing */
  --g-padding-xs: 4px 8px;
  --g-padding-sm: 8px 12px;
  --g-padding-base: 12px 16px;
  --g-padding-lg: 16px 24px;
}

Customization Methods

1. CSS Variables Override

The simplest way to customize the theme is by overriding CSS variables:

:root {
  --g-color-primary: #722ed1;
  --g-color-primary-hover: #9254de;
  --g-color-primary-active: #531dab;
}

2. SCSS Variables

If you're using SCSS, you can override variables before importing Ghuo Design:

// Override variables
$primary-color: #722ed1;
$success-color: #52c41a;
$warning-color: #faad14;
$error-color: #ff4d4f;

// Import Ghuo Design
@import 'ghuo-design/dist/ghuo-design.scss';

3. JavaScript Configuration

Configure theme programmatically:

import { ConfigProvider } from 'ghuo-design'

const theme = {
  token: {
    colorPrimary: '#722ed1',
    colorSuccess: '#52c41a',
    colorWarning: '#faad14',
    colorError: '#ff4d4f',
    fontFamily: 'Inter, sans-serif',
  },
}

// In your Vue app
app.use(ConfigProvider, { theme })

4. Component-Level Theming

Apply themes to specific component instances:

<template>
  <g-config-provider :theme="customTheme">
    <g-button type="primary">Custom Themed Button</g-button>
  </g-config-provider>
</template>

<script setup>
const customTheme = {
  token: {
    colorPrimary: '#722ed1',
  },
}
</script>

Dark Mode

Ghuo Design supports dark mode out of the box:

Automatic Dark Mode

import { ConfigProvider } from 'ghuo-design'

const app = createApp(App)
app.use(ConfigProvider, {
  theme: {
    algorithm: 'dark', // or 'light'
  },
})

System Preference Detection

const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
const theme = {
  algorithm: prefersDark ? 'dark' : 'light',
}

Manual Toggle

<template>
  <div>
    <g-switch v-model:checked="isDark" @change="toggleTheme" />
    <g-config-provider :theme="currentTheme">
      <!-- Your app content -->
    </g-config-provider>
  </div>
</template>

<script setup>
import { ref, computed } from 'vue'

const isDark = ref(false)

const currentTheme = computed(() => ({
  algorithm: isDark.value ? 'dark' : 'light',
}))

const toggleTheme = () => {
  document.documentElement.setAttribute('data-theme', isDark.value ? 'dark' : 'light')
}
</script>

Brand Customization

Creating a Brand Theme

const brandTheme = {
  token: {
    // Brand Colors
    colorPrimary: '#1890ff',
    colorSuccess: '#52c41a',
    colorWarning: '#faad14',
    colorError: '#ff4d4f',
    
    // Typography
    fontFamily: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif',
    fontSize: 14,
    
    // Spacing
    sizeUnit: 4,
    sizeStep: 4,
    
    // Border Radius
    borderRadius: 6,
    
    // Shadows
    boxShadow: '0 2px 8px rgba(0, 0, 0, 0.15)',
  },
  components: {
    Button: {
      borderRadius: 8,
      fontWeight: 500,
    },
    Input: {
      borderRadius: 4,
    },
  },
}

Component-Specific Customization

const componentTheme = {
  components: {
    Button: {
      colorPrimary: '#722ed1',
      borderRadius: 8,
      fontWeight: 600,
    },
    Input: {
      colorBorder: '#d9d9d9',
      borderRadius: 4,
    },
    Card: {
      borderRadius: 12,
      boxShadow: '0 4px 12px rgba(0, 0, 0, 0.1)',
    },
  },
}

Advanced Theming

Custom Algorithms

Create custom theme algorithms:

const customAlgorithm = (seedToken, mapToken) => {
  return {
    ...mapToken,
    colorPrimary: seedToken.colorPrimary,
    colorPrimaryHover: lighten(seedToken.colorPrimary, 0.1),
    colorPrimaryActive: darken(seedToken.colorPrimary, 0.1),
  }
}

const theme = {
  algorithm: customAlgorithm,
}

Dynamic Theming

<template>
  <div>
    <g-color-picker v-model:value="primaryColor" @change="updateTheme" />
    <g-config-provider :theme="dynamicTheme">
      <!-- Your components -->
    </g-config-provider>
  </div>
</template>

<script setup>
import { ref, computed } from 'vue'

const primaryColor = ref('#1890ff')

const dynamicTheme = computed(() => ({
  token: {
    colorPrimary: primaryColor.value,
  },
}))

const updateTheme = (color) => {
  primaryColor.value = color
}
</script>

Best Practices

1. Use Design Tokens

Always use design tokens instead of hardcoded values:

/* Good */
.custom-component {
  color: var(--g-color-text-primary);
  padding: var(--g-space-base);
}

/* Avoid */
.custom-component {
  color: #262626;
  padding: 16px;
}

2. Test Accessibility

Ensure your custom themes meet accessibility standards:

// Check color contrast ratios
const contrastRatio = getContrastRatio(backgroundColor, textColor)
if (contrastRatio < 4.5) {
  console.warn('Color contrast ratio is too low')
}

3. Provide Theme Presets

Create predefined themes for common use cases:

export const themes = {
  default: { /* default theme */ },
  dark: { /* dark theme */ },
  corporate: { /* corporate theme */ },
  creative: { /* creative theme */ },
}

4. Document Custom Tokens

Document any custom tokens you create:

:root {
  /* Custom brand colors */
  --g-color-brand-primary: #1890ff;
  --g-color-brand-secondary: #722ed1;
  
  /* Custom spacing for specific layouts */
  --g-space-section: 80px;
  --g-space-container: 120px;
}

Migration Guide

From v1.x to v2.x

// v1.x
const theme = {
  primaryColor: '#1890ff',
  successColor: '#52c41a',
}

// v2.x
const theme = {
  token: {
    colorPrimary: '#1890ff',
    colorSuccess: '#52c41a',
  },
}

Resources

• Design Tokens Reference
• Color System Guide
• Typography Guide
• Theme Examples

Need help with theming? Check our community discussions or reach out to our team!