SyncupSuite Docs

Appearance

Package Reference ​

Four npm packages with strict dependency order. Install @syncupsuite/themes -- it re-exports everything you need.

bash
pnpm add @syncupsuite/themes

Dependency Graph ​

@syncupsuite/tokens           <- DTCG types, utilities, validation (zero deps)
       |
       +-- @syncupsuite/foundations    <- Color engine, cultural data, seed colors
       +-- @syncupsuite/transformers   <- CSS + Tailwind v4 output generators
                |
                v
@syncupsuite/themes           <- Published theme bundles (consumer package)

tokens is the leaf dependency. foundations and transformers both depend on tokens. themes depends on all three at build time, but only on tokens at runtime.

@syncupsuite/themes v0.4.0 ​

The consumer package. Contains all 12 theme bundles with CSS, Tailwind, and DTCG output. This is what you install.

bash
pnpm add @syncupsuite/themes

Per-Theme Exports ​

Every theme slug exposes four files:

@syncupsuite/themes/{slug}/tokens.css    # CSS custom properties
@syncupsuite/themes/{slug}/tailwind.css  # Tailwind v4 @theme
@syncupsuite/themes/{slug}/tokens.json   # DTCG JSON
@syncupsuite/themes/{slug}/meta.json     # Cultural metadata

Available Slugs ​

swiss-international, nihon-traditional, nordic-modern, tang-imperial, shuimo-modern, nihon-minimal, renaissance, art-deco, wiener-werkstaette, milanese-design, de-stijl, swiss-modernist

Import Patterns ​

css
/* Registers theme tokens + semantic color API as Tailwind utilities */
@import "@syncupsuite/themes/nordic-modern/tailwind.css";

/* Use in markup: bg-canvas, text-foreground, bg-primary, etc. */
css
/* Registers CSS custom properties on :root */
@import "@syncupsuite/themes/nordic-modern/tokens.css";

/* Use in styles: var(--background-canvas), var(--text-primary), etc. */
ts
// DTCG token tree for tooling integration
import tokens from "@syncupsuite/themes/nordic-modern/tokens.json";

// Cultural provenance metadata
import meta from "@syncupsuite/themes/nordic-modern/meta.json";
// meta.name, meta.slug, meta.origin, meta.culturalContext

Dark Mode ​

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

html
<html data-theme="dark">

No additional imports required. All semantic tokens remap automatically.

@syncupsuite/tokens v0.2.0 ​

DTCG type definitions, token utilities, and validation. Zero runtime dependencies. You do not install this directly unless you are building tooling on top of the token format.

bash
pnpm add @syncupsuite/tokens

Types ​

ts
import type {
  DTCGToken,          // Single token: { $value, $type, $description? }
  DTCGTokenGroup,     // Nested token group
  DTCGRoot,           // Full token tree root
  CulturalFoundation, // Foundation definition (seed colors, harmony, typography)
  SeedColor,          // { name, hex, role }
  Provenance,         // { tradition, period, principles[] }
  HarmonyMode,        // 'complementary' | 'analogous' | 'triadic' | 'split-complementary' | 'monochromatic'
  BuiltTheme,         // Build output: { dtcg, css, tailwind, meta }
  TransformOptions,   // Transform config for CSS/Tailwind generators
  FoundationMeta,     // Foundation metadata
} from "@syncupsuite/tokens";

Utilities ​

ts
import {
  isToken,           // Check if a node is a DTCG token (has $value)
  flattenTokens,     // Flatten nested token tree to path-value pairs
  walkTokens,        // Walk token tree with visitor callback
  pathToProperty,    // Convert token path to CSS property name
  slugify,           // Slugify a theme name
  sanitizeCssValue,  // Sanitize a value for CSS output
} from "@syncupsuite/tokens";

Validation ​

ts
import {
  validateSchema,        // Validate DTCG structure
  validateCompleteness,  // Check all required semantic tokens exist
  validateContrast,      // WCAG contrast audit
  validateReferences,    // Check $value references resolve
} from "@syncupsuite/tokens";

import type {
  ValidationResult,   // { valid, errors[], warnings[] }
  ContrastAuditResult, // Per-theme contrast pair results
} from "@syncupsuite/tokens";

Constants ​

ts
import {
  PROTECTED_TOKEN_PATHS,      // Paths that T1/T2 cannot override
  REQUIRED_SEMANTIC_TOKENS,   // Tokens every theme must provide
  CONTRAST_PAIRS,             // WCAG-required fg/bg combinations
  PERF_BUDGETS,               // Size/count limits for theme output
} from "@syncupsuite/tokens";

@syncupsuite/foundations v0.2.0 ​

Color engine and cultural token data. Takes a foundation definition (seed colors, harmony mode, typography category) and expands it into a full DTCG token tree.

bash
pnpm add @syncupsuite/foundations

Build a Foundation ​

ts
import { buildFoundation } from "@syncupsuite/foundations";
import type { FoundationData, BuildResult } from "@syncupsuite/foundations";

const result: BuildResult = buildFoundation({
  name: "My Custom Theme",
  slug: "my-custom-theme",
  seedColors: [
    { name: "primary", hex: "#2563eb", role: "primary" },
    { name: "accent", hex: "#dc2626", role: "accent" },
  ],
  harmonyMode: "complementary",
  typographyCategory: "sans-serif",
  borderRadius: "md",
  provenance: {
    tradition: "Custom",
    period: "2024",
    principles: ["clarity"],
  },
});

// result.dtcg   -> Full DTCG token tree
// result.meta   -> Cultural metadata

Color Science ​

ts
import {
  hexToOklch,              // Convert hex to OKLCH
  oklchToHex,              // Convert OKLCH to hex
  generateLightnessScale,  // Generate 50-900 scale from a seed color
  generateNeutrals,        // Generate neutral scale with hue tinting
  generateHarmonyAccents,  // Generate accent colors from harmony mode
} from "@syncupsuite/foundations";

Built-In Foundation Data ​

The package includes foundation JSON for all 12 shipped themes in @syncupsuite/foundations/data/. These files are the single source of truth -- the entire theme pipeline generates from them.

@syncupsuite/transformers v0.2.1 ​

CSS and Tailwind v4 output generators. Reads a DTCG token tree and produces CSS files.

bash
pnpm add @syncupsuite/transformers

Transform to CSS ​

ts
import { transformToCSS } from "@syncupsuite/transformers";

const css = transformToCSS(dtcgTokenTree, {
  prefix: "primitive",        // CSS variable prefix
  includeDarkMode: true,      // Generate [data-theme="dark"] block
  includeSemanticTokens: true // Generate semantic token layer
});

// Returns a string of CSS custom properties

Transform to Tailwind v4 ​

ts
import { transformToTailwindV4 } from "@syncupsuite/transformers";

const tailwindCss = transformToTailwindV4(dtcgTokenTree, {
  prefix: "",                  // Tailwind uses unprefixed names
  includeDarkMode: true,
  includeSemanticTokens: true
});

// Returns CSS with @theme blocks for Tailwind v4

Both generators produce the same semantic token API (--background-canvas, --text-primary, --interactive-primary, etc.). The difference is output format: transformToCSS writes plain :root blocks, while transformToTailwindV4 writes @theme blocks that Tailwind v4 picks up automatically.

Token Structure (DTCG) ​

All themes follow the Design Tokens Community Group format:

json
{
  "color": {
    "primary": {
      "50":  { "$value": "#eff6ff", "$type": "color" },
      "100": { "$value": "#dbeafe", "$type": "color" },
      "500": { "$value": "#3b82f6", "$type": "color" },
      "900": { "$value": "#1e3a8a", "$type": "color" }
    },
    "neutral": { "...": "..." },
    "semantic": { "...": "..." }
  },
  "typography": {
    "family": {
      "heading": { "$value": "\"Inter\", sans-serif", "$type": "fontFamily" }
    }
  },
  "spacing": { "...": "..." },
  "borderRadius": { "...": "..." }
}

CSS Custom Properties ​

Semantic tokens are the consumer API. Use these in your styles:

css
:root {
  /* Backgrounds */
  --background-canvas: ...;     /* Page background */
  --background-surface: ...;    /* Card/panel */
  --background-muted: ...;      /* Subdued areas */

  /* Text */
  --text-primary: ...;          /* Primary text */
  --text-secondary: ...;        /* Secondary text */
  --text-muted: ...;            /* Disabled/muted */
  --text-inverse: ...;          /* Text on dark bg */

  /* Interactive */
  --interactive-primary: ...;       /* Buttons, links */
  --interactive-primary-hover: ...; /* Hover state */
  --interactive-primary-active: ...; /* Active/pressed */

  /* Borders */
  --border-default: ...;        /* Default border */
  --border-strong: ...;         /* Emphasized border */

  /* Status */
  --status-error: ...;
  --status-success: ...;
  --status-warning: ...;
  --status-info: ...;

  /* Focus */
  --focus-ring: ...;
}

Primitive tokens (--primitive-color-*, --primitive-spacing-*, --primitive-radius-*, --primitive-typography-*) are also available for direct access, but semantic tokens are the intended API.

Theme Metadata ​

meta.json provides cultural context for each theme:

json
{
  "name": "Swiss International",
  "slug": "swiss-international",
  "origin": "Swiss modernist design movement",
  "description": "Clean geometric precision inspired by the International Typographic Style",
  "culturalContext": {
    "tradition": "International Typographic Style",
    "period": "1950s-present",
    "principles": ["clarity", "objectivity", "systematic grid"]
  }
}

Use this metadata for theme pickers, admin panels, or documentation generation.

Released under the MIT License.

Copyright © 2026 HabitusNet