@vanduo-oss/core

The source of truth for Vanduo's design system — framework-agnostic design tokens shared by every engine:

• framework (Vanilla — zero-build CDN / static / SPA)
• vd2 (Vue 3 + SSR)

Both engines serve the same look, feel, and design philosophy (Open Color palette, Fibonacci scale). This package owns the values; each engine owns its own rendering. Zero runtime and zero build dependencies — the generator is plain Node.

Install

pnpm add @vanduo-oss/core

// TS / JS consumers (e.g. vd2)
import { PRIMARY_COLORS, NEUTRAL_COLORS, DEFAULTS, tokens } from "@vanduo-oss/core";

/* CSS consumers — :root { --vd-*: … } */
@import "@vanduo-oss/core/css";

| Export | Path | Contents | | --- | --- | --- | | . | dist/index.js + dist/index.d.ts | typed customizer arrays, DEFAULTS, resolved tokens map | | ./css | dist/vanduo-core.css | :root custom properties (--vd-*) | | ./tokens.json | dist/tokens.json | flat, resolved, Figma-ready token map |

What's here

tokens/                     # W3C DTCG source of truth (edit these)
  primitive/color.tokens.json    palette scales (Open Color)
  primitive/scale.tokens.json    spacing (Fibonacci), radius, type, shadow
  semantic/color.tokens.json     canonical --vd-color/bg/text/border-* aliases
  customizer/options.json        theme-customizer option metadata
scripts/
  extract-from-framework.mjs # one-time seed of palette from the framework CSS
  build.mjs                  # DTCG -> CSS + TS + JSON (zero dependencies)
  verify-parity.mjs          # assert primitives match the framework's values
dist/                       # generated (gitignored)
  vanduo-core.css            :root { --vd-*: … }
  index.js / index.d.ts      typed customizer data + resolved token map
  tokens.json                flat, resolved, Figma-ready

Develop

pnpm build     # regenerate dist/ from tokens/
pnpm test      # build determinism, token schema, ref integrity, parity (node:test)
pnpm verify    # assert dist parity with the Vanilla framework's authored values
pnpm extract   # re-seed primitive palette from ../framework (rarely needed)

The test suite is dependency-free (Node's built-in node:test). It checks that the build is deterministic, that the generated CSS exposes only --vd-* properties with no dangling var() references, that tokens.json is fully resolved, that the public API surface is intact, and that every customizer default points at a real option. The parity check runs when a framework checkout is available (sibling dir, or VANDUO_FRAMEWORK_DIR) and is skipped otherwise.

Scope & roadmap

Now: design tokens only. The vd2 Vue engine consumes the customizer token data from here instead of hardcoding it.

Deferred: the framework (Vanilla) engine consuming core's CSS (collapsing the two value sources so core becomes the singular truth); component specs; Figma variables generated from the DTCG tokens.json.

The Vanilla framework's colors.css/tokens.css remain the live values until that migration; pnpm verify guards against drift in the meantime.