Add Cultural Design Tokens to an Existing Project

You have a project. It works. Now you want to ground its visual identity in a cultural design tradition instead of picking colors from a generic palette.

This tutorial walks through adding @syncupsuite/themes to an existing project, with parallel paths for Tailwind CSS v4 and vanilla CSS.

What You'll Do

1. Install the package
2. Choose a cultural identity
3. Import the theme CSS
4. Create semantic aliases for your app
5. Verify light and dark mode

Total time: 10-15 minutes.

Prerequisites

• A working web project with a CSS build pipeline (Vite, webpack, etc.)
• Node.js 18+ and npm/pnpm/bun
• For the Tailwind path: Tailwind CSS v4 with CSS-first config

---

Step 1: Install

npm install @syncupsuite/themes

This installs all 12 themes. You only import the ones you use — unused themes are tree-shaken by your bundler.

The package has zero runtime JavaScript dependencies. Each theme is a set of static files: tokens.json, tokens.css, tailwind.css, and meta.json.

Step 2: Choose a Cultural Identity

Browse the Theme Gallery and pick the tradition that fits your product's personality.

Theme	Character	Good For
swiss-international	Clean, precise, corporate-neutral	B2B dashboards, developer tools
nihon-traditional	Warm, contemplative, nature-inspired	Content platforms, wellness apps
nordic-modern	Light, functional, democratic	Consumer SaaS, productivity apps
tang-imperial	Rich, ceremonial, confident	Premium products, cultural platforms
shuimo-modern	Monochromatic, restrained, calligraphic	Document editors, reading apps
nihon-minimal	Stripped to essentials, content-first	Portfolios, minimal UIs
renaissance	Rich purples and golds, material warmth	Creative tools, luxury brands
art-deco	Bold geometry, high contrast	Marketing sites, entertainment
wiener-werkstaette	Graphic black-and-white with jewel accents	Design studios, editorial
milanese-design	Red-black-white, Olivetti rationalism	Industrial tools, hardware UIs
de-stijl	Primary colors, absolute abstraction	Experimental interfaces, art tools
swiss-modernist	Editorial, signal red, assertive	News sites, bold marketing

For this tutorial, we'll use nordic-modern. Replace the slug with your choice throughout.

Step 3: Import the Theme

Tailwind v4

/* In your main CSS file (e.g., src/app.css) */
@import "tailwindcss";
@import "@syncupsuite/themes/nordic-modern/tailwind.css";

Vanilla CSS

/* In your main CSS file */
@import "@syncupsuite/themes/nordic-modern/tokens.css";

Your bundler resolves the import from node_modules. If you're using Vite, webpack, or esbuild, this works without additional configuration.

After this step, every semantic CSS custom property from the theme is available in your project:

/* These now resolve to Nordic Modern's values */
var(--background-canvas)      /* Light, warm off-white */
var(--text-primary)           /* Dark slate */
var(--interactive-primary)    /* Fjord blue */
var(--border-default)         /* Birch grey */

Step 4: Create Semantic Aliases

Don't scatter var(--background-canvas) throughout your components. Create a thin alias layer that decouples your app from the specific theme:

/* Below the theme import */
:root {
  /* Backgrounds */
  --app-bg: var(--background-canvas);
  --app-surface: var(--background-surface);
  --app-muted: var(--background-muted);

  /* Text */
  --app-text: var(--text-primary);
  --app-text-secondary: var(--text-secondary);
  --app-text-muted: var(--text-muted);

  /* Interactive */
  --app-accent: var(--interactive-primary);
  --app-accent-hover: var(--interactive-primary-hover);

  /* Borders */
  --app-border: var(--border-default);

  /* Status */
  --app-error: var(--status-error);
  --app-success: var(--status-success);
}

Now use var(--app-bg) in your components instead of the raw theme tokens. If you ever switch from Nordic Modern to Art Deco, you change one import line and your entire app repaints.

Tailwind v4 users

Wire your aliases into a @theme block so Tailwind generates utility classes:

@theme {
  --color-app-bg: var(--app-bg);
  --color-app-surface: var(--app-surface);
  --color-app-text: var(--app-text);
  --color-app-accent: var(--app-accent);
  --color-app-border: var(--app-border);
}

Then use bg-app-bg, text-app-text, border-app-border in your markup.

Step 5: Verify Dark Mode

Every theme includes dark mode values. Activate dark mode by adding data-theme="dark" to any parent element:

<html data-theme="dark">

The semantic tokens (--background-canvas, --text-primary, etc.) automatically switch to their dark mode values. Your aliases follow, since they reference the semantic tokens.

Test both modes:

// Quick toggle for testing
document.documentElement.toggleAttribute('data-theme');
// Or set explicitly:
document.documentElement.setAttribute('data-theme', 'dark');

If you have custom aliases that reference primitive tokens directly (e.g., var(--primitive-color-fjordbl-500)), those won't switch in dark mode. Override them in a [data-theme="dark"] block:

[data-theme="dark"] {
  --app-accent-subtle: rgba(2, 132, 199, 0.15); /* fjord blue at low opacity */
}

You're Done

Your project now has a culturally-grounded visual identity with:

• Semantic CSS custom properties that work across any component
• Dark mode that activates with a single attribute
• An alias layer that lets you swap themes without touching components
• WCAG AA contrast validation built into every theme

Switching Themes Later

To switch from Nordic Modern to, say, Renaissance:

/* Change this one line */
@import "@syncupsuite/themes/renaissance/tokens.css";

Your aliases, dark mode, and all components update automatically. The semantic token API is identical across all 12 themes.

Next Steps

• Semantic Colors for the full token reference
• Custom Foundations to build your own cultural identity
• Theme Gallery to explore all 12 themes