@bcc-code/design-tokens

BCC Design System tokens with support for CSS variables, Tailwind CSS v4, and PrimeVue themes. Generates consistent design tokens from Figma Token Studio with automatic light/dark mode support.

Installation

npm install @bcc-code/design-tokens

Usage

CSS Variables (Recommended)

Import auto-switching CSS variables with light/dark mode support:

@import '@bcc-code/design-tokens/css';

This automatically provides light theme by default and switches to dark theme when the .dark class is applied to any parent element (typically html or body).

Use semantic tokens in your styles:

.card {
  background: var(--color-elevation-surface-default);
  color: var(--color-text-default);
  padding: var(--space-300);
  border-radius: var(--border-radius-md);
  font-family: var(--font-family-archivo);
}

Manual theme switching:

// Toggle dark mode
document.documentElement.classList.toggle('dark');

// Or set theme based on user preference
const isDark = localStorage.getItem('theme') === 'dark';
document.documentElement.classList.toggle('dark', isDark);

Alternative theme-specific imports (optional):

@import '@bcc-code/design-tokens/css/light';
@import '@bcc-code/design-tokens/css/dark';

Tailwind CSS v4 (Recommended)

Import Tailwind utilities with auto-switching themes and .dark class support:

@import '@bcc-code/design-tokens/tailwind';

This provides light theme by default and dark theme when using the .dark class on any parent element.

Use utility classes:

<div class="bg-elevation-surface-default text-default p-300 radius-md">
  Content with BCC design tokens
</div>

<!-- Dark mode with .dark class -->
<div class="dark">
  <div class="bg-elevation-surface-default text-default p-300 radius-md">
    Content in dark mode
  </div>
</div>

Alternative theme-specific imports (optional):

@import '@bcc-code/design-tokens/tailwind/light';
@import '@bcc-code/design-tokens/tailwind/dark';

PrimeVue Integration

Configure PrimeVue with BCC theme preset:

import { createApp } from 'vue'
import PrimeVue from 'primevue/config'
import BCCPreset from '@bcc-code/design-tokens/primevue'

const app = createApp(App)

app.use(PrimeVue, {
  theme: {
    preset: BCCPreset,
    options: {
      prefix: 'p',
      darkModeSelector: '.dark',
      cssLayer: false
    }
  }
})

Enable dark mode by adding the dark class to your root element:

// Toggle dark mode
document.documentElement.classList.toggle('dark')

// Or with system preference fallback
function setTheme(isDark) {
  document.documentElement.classList.toggle('dark', isDark);
  document.documentElement.style.colorScheme = isDark ? 'dark' : 'light';
}

Token Categories

• Colors: Semantic color tokens for text, backgrounds, borders, and states
• Typography: Font families, sizes, weights, and line heights
• Spacing: Consistent spacing scale for margins, padding, and gaps
• Border Radius: Border radius values for consistent corner rounding
• Elevation: Surface tokens for different elevation levels

CDN Usage

<!-- Auto-switching CSS variables with .dark class support (recommended) -->
<link rel="stylesheet" href="https://unpkg.com/@bcc-code/design-tokens@latest/build/bcc/css/auto.css">

<!-- Or Tailwind utilities with .dark class support -->
<link rel="stylesheet" href="https://unpkg.com/@bcc-code/design-tokens@latest/build/bcc/css/tailwind-auto.css">

<!-- Then add JavaScript for theme switching -->
<script>
  // Basic theme toggle
  function toggleTheme() {
    document.documentElement.classList.toggle('dark');
  }
  
  // Theme with system preference detection
  function initTheme() {
    const savedTheme = localStorage.getItem('theme');
    const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    const isDark = savedTheme ? savedTheme === 'dark' : systemDark;
    
    document.documentElement.classList.toggle('dark', isDark);
    document.documentElement.style.colorScheme = isDark ? 'dark' : 'light';
  }
  
  initTheme();
</script>

Contributing

We welcome contributions! Here's how to get started:

Development Setup

1. Clone and install dependencies:

   git clone https://github.com/bcc-code/design-tokens.git
   cd design-tokens
   npm install

2. Build tokens:

   npm run build

3. Test with demo application:

   cd demo
   npm install
   npm run dev

   The demo application showcases all three integration methods (CSS variables, Tailwind utilities, and PrimeVue components) with a comprehensive dashboard featuring theme switching, real-world examples, and live token demonstrations.

Token Structure

• Source tokens are located in tokens/ directory, synced from Figma Token Studio
• Build configuration is in export-tokens/build.js using Style Dictionary
• Output files are generated in build/bcc/ with organized folders for css/ and js/

Making Changes

1. Token updates: Modify files in tokens/ directory or sync from Figma Token Studio
2. Build system changes: Update export-tokens/build.js for new formats or transformations
3. PrimeVue preset: Modify config/primevue.config.js for theme mapping changes

Pull Requests

• Ensure npm run build runs successfully
• Test changes with the demo application
• Update documentation if adding new features
• Follow conventional commit messages

Development

A comprehensive demo application is available in the demo/ directory featuring:

• CSS Variables showcase: E-commerce product cards, newsletter forms, and status displays using pure CSS with BCC tokens
• Tailwind Utilities showcase: Project management dashboard with utility-first CSS classes
• PrimeVue Components showcase: User profiles, settings panels, and component galleries
• Theme switching: Manual dark/light mode toggle with system preference detection
• Live token demonstrations: Real-time examples of all token categories in action

Access the demo at http://localhost:5173 after running npm run dev in the demo/ directory.

License

MIT © BCC Code