@bcc-code/design-tokens

BCC Design System tokens for CSS, Tailwind v4, and PrimeVue with light/dark mode support.

Migrating from @bcc-code/design-library-vue? This package replaces the deprecated design-library. See the Migration Guide below.

Quick Start

Choose your integration method:

Installation

npm install @bcc-code/design-tokens

Usage

CSS Variables

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

Provides light theme by default, dark theme with .dark class:

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

Toggle dark mode:

document.documentElement.classList.toggle('dark');

Tailwind CSS v4

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

Use utility classes:

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

<!-- Dark mode -->
<div class="dark">
  <div class="bg-elevation-surface-default text-default">
    Dark content
  </div>
</div>

PrimeVue

Install the required peer dependencies:

npm install primevue @primeuix/themes

Import the preset and overrides:

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

const app = createApp(App)

app.use(PrimeVue, {
  theme: {
    preset: BCCPreset,
    options: {
      darkModeSelector: '.dark',
      cssLayer: {
        name: 'primevue',
        order: 'theme, base, primevue, custom'
      }
    }
  }
})

Toggle dark mode:

document.documentElement.classList.toggle('dark')

What's Included:

• @bcc-code/design-tokens/primevue - PrimeVue Aura preset with BCC tokens
• @bcc-code/design-tokens/primevue/overrides - CSS overrides for component styling

Available Exports

CSS

• @bcc-code/design-tokens/css - Auto-switching theme (prefers-color-scheme)
• @bcc-code/design-tokens/css/light - Light theme only
• @bcc-code/design-tokens/css/dark - Dark theme only

Tailwind CSS

• @bcc-code/design-tokens/tailwind - Auto-switching utilities
• @bcc-code/design-tokens/tailwind/light - Light utilities only
• @bcc-code/design-tokens/tailwind/dark - Dark utilities only

JavaScript

• @bcc-code/design-tokens/js/light - Light theme tokens as JS objects
• @bcc-code/design-tokens/js/dark - Dark theme tokens as JS objects

PrimeVue

• @bcc-code/design-tokens/primevue - Aura preset configuration
• @bcc-code/design-tokens/primevue/overrides - Component CSS overrides

Token Categories

• Colors: Text, backgrounds, borders, states
• Typography: Font families, sizes, weights, line heights
• Spacing: Margins, padding, gaps (50-1000 scale)
• Border Radius: Corner rounding
• Elevation: Surface levels

CDN Usage

<!-- CSS variables -->
<link rel="stylesheet" href="https://unpkg.com/@bcc-code/design-tokens@latest/build/bcc/css/auto.css">

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

<!-- Theme toggle -->
<script>
  document.documentElement.classList.toggle('dark');
</script>

Migration from design-library-vue

If you're migrating from @bcc-code/design-library-vue, follow these steps:

1. Install new packages

# Remove old package
npm uninstall @bcc-code/design-library-vue

# Install new packages
npm install @bcc-code/design-tokens primevue @primeuix/themes

2. Update imports

Before (design-library-vue):

import { BccButton, BccModal } from '@bcc-code/design-library-vue'
import '@bcc-code/design-library-vue/style.css'

After (design-tokens + PrimeVue):

import Button from 'primevue/button'
import Dialog from 'primevue/dialog'
import BCCPreset from '@bcc-code/design-tokens/primevue'
import '@bcc-code/design-tokens/primevue/overrides'

3. Configure PrimeVue

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

const app = createApp(App)

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

4. Component mapping

See the PrimeVue documentation for the full component list.

Token Structure

Tokens are organized in two layers:

Primitive Tokens (Base Values)

Static values that don't change between themes:

• --color-neutral-0 through --color-neutral-1000
• --color-green-*, --color-red-*, --color-blue-*
• --space-50 through --space-1000
• --border-radius-sm, --border-radius-md, --border-radius-lg

Semantic Tokens (Theme-Aware)

Reference primitive tokens and change between light/dark:

• --color-text-default - Main text color
• --color-text-subtle - Secondary text
• --color-background-* - Background colors
• --color-elevation-surface-* - Surface elevation levels
• --color-border-* - Border colors
• --color-interactive-* - Interactive element colors

Tailwind Utility Classes

When using Tailwind v4, these utility classes are available:

Colors

<!-- Text colors -->
<p class="text-default">Default text</p>
<p class="text-subtle">Subtle text</p>
<p class="text-success">Success text</p>
<p class="text-danger">Danger text</p>

<!-- Background colors -->
<div class="bg-elevation-surface-default">Surface</div>
<div class="bg-elevation-surface-sunken">Sunken surface</div>
<div class="bg-interactive-primary">Primary button</div>

<!-- Border colors -->
<div class="border border-default">Default border</div>

Spacing Scale

<div class="p-100">Padding 8px</div>
<div class="p-200">Padding 16px</div>
<div class="p-300">Padding 24px</div>
<div class="m-400">Margin 32px</div>
<div class="gap-200">Gap 16px</div>

Border Radius

<div class="radius-sm">Small radius</div>
<div class="radius-md">Medium radius</div>
<div class="radius-lg">Large radius</div>
<div class="radius-full">Full radius (pill)</div>

Dark Mode

<!-- Container with dark mode -->
<div class="dark">
  <div class="bg-elevation-surface-default text-default">
    Automatically uses dark theme colors
  </div>
</div>

<!-- Or toggle on root -->
<script>
document.documentElement.classList.toggle('dark')
</script>

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup, workflow, and publishing instructions.

License

MIT © BCC Code