NewCo Design System — Tokens

@helloimjolopez-newco/newco-tokens

The single source of truth for NewCo's visual language, delivered as a versioned npm package. Every value is a 1:1 reflection of the Figma variable library (the NewCo branch) — pulled programmatically, never hand-maintained.

▶ Live Storybook: https://helloimjolopez-collab.github.io/newco-ds/

Packages

Both registries publish from the same build, in lockstep — identical version, identical values.

| Registry | Package | Install | |----------|---------|---------| | npm | @helloimjolopez-newco/newco-tokens | npm install @helloimjolopez-newco/newco-tokens | | NuGet (.NET / Blazor / Radzen) | NewCo.Tokens | dotnet add package NewCo.Tokens |

.NET delivery details (Razor Class Library, static-web-asset stylesheet, C# constants): nuget/README.md.

The contract is 294 names

That is the number to quote a developer — the names you may actually use, not the line count. The rest is infrastructure you load but never name. The colour system follows the canonical Pathway architecture: meaning-named tones (Negative, Positive, Attention, Severe, Info, Neutral, Brand) with two rungs each — Subtle and Strong — plus Accent/<hue> for the decorative hues; only Neutral and Brand carry the long ladder. Every foreground-on-fill pairing clears AAA (7:1), verified by luminance in check-color. The CSS ships as small, self-describing files (each with a stamped CONTRACT / INFRASTRUCTURE / COMPONENT-INTERNALS header and a computed count), never one giant tokens.css:

| File | Names | Name it? | What it is | |---|---|---|---| | primitives.css | 466 | no | Raw ramps. Load it; never name it. | | themes/light.css + themes/midnight.css | 197 | yes | Colour + elevation, one name per token, flipped by data-theme. | | type.css | 39 | yes | Type scale (compose the atomic tokens). | | layout.css | 39 | yes | Spacing, radii, border widths. | | layout-contextual.css | 38 | no | Per-component metrics. | | motion.css / breakpoints.css | 14 / 5 | yes | Durations + easings / breakpoints. |

Load order, the region→surface map, and the theming/type recipes are in src/tokens/README.md (and repeated inside the published package as npm/README.md + machine-readable npm/contract.json). One import loads everything in order: @import "@helloimjolopez-newco/newco-tokens/css";.

Delivered as CSS / JS / JSON (npm) and a Razor Class Library (NuGet), from one lockstep build. Colour + elevation theme by data-theme (midnight / dark); no mode is ever baked into a property name.

What a consuming team gets

Install once, theme forever. Three artifacts are published in npm/:

| File | Format | Use it when… | |------|--------|--------------| | npm/tokens.css | CSS custom properties | You style with CSS/SCSS/Tailwind/Blazor/Radzen — the default | | npm/tokens.js | ESM object | You need tokens in JS/TS (theming logic, RN, charts) | | npm/tokens.json| W3C DTCG | You feed your own Style Dictionary / tooling |

npm install @helloimjolopez-newco/newco-tokens

/* one import; every token becomes a CSS variable */
@import "@helloimjolopez-newco/newco-tokens/css";

.card {
  background: var(--semantic-color-fill-surface-elevated);
  color:      var(--semantic-color-foreground-static-neutral-base);
  border:     1px solid var(--semantic-color-stroke-static-neutral-base);
}

Because it's just CSS variables, any framework can absorb it — React, Vue, Angular, Svelte, plain HTML, and Blazor / Radzen (they render normal DOM, so var(--…) works with zero interop). That framework-agnostic surface is the whole point; see docs/adoption.md.

Naming convention

--{collection}-{mode?}-{group}-{...path}
   primitive-color                → --primitive-color-brand-600
   semantic-color · light-mode    → --semantic-color-light-mode-surface-sheet-base
   semantic-color · midnight-mode → --semantic-color-midnight-mode-surface-sheet-base

Semantics reference primitives (var()), so the alias chain from Figma is preserved in the output. This is the same naming the live NewCo demo already consumes.

Theming note (open design decision). Modes are currently namespaced in the variable name (…-light-mode-… / …-midnight-mode-…). A thin role-alias layer (--surface-sheet resolving per :root[data-theme="midnight"]) is the intended next iteration so apps flip themes with one attribute. Flagged for the dev review.

Architecture

Figma (NewCo branch variables)          <- single source of truth
      |  sync-tokens.js  (REST, Plan Access Token, in CI - no manual export)
      v
tokens/figma-source/*.json               <- raw graph: color + type + layout/units + motion + elevation + breakpoints
      |  build-token-source.js           <- -> W3C DTCG, validates every alias resolves
      v
tokens/newco-design-tokens.json          <- DTCG source of truth (committed)
      |  style-dictionary.config.js      <- Style Dictionary v5
      v
src/tokens/{tokens.css,tokens.js}
      |  build-dist.js   ->  npm/{tokens.css,tokens.js,tokens.json}   (npm package)
      |  build-nuget.js  ->  nuget/  (NewCo.Tokens RCL: newco-tokens.css + C# constants)
      v
npm publish  +  dotnet nuget push   ->  consuming teams   (single build, lockstep version)

Every step is a plain, reviewable Node script. No bespoke build server.

Staying in sync with Figma

There is no Figma REST/Variables API sync in this repo. The org is not on the Enterprise plan, so the variables/local REST endpoint is not available to us — any REST-based auto-sync is impossible, and none is wired up.

Instead, the seed dumps under tokens/figma-source/*.json are refreshed from the Figma variable library through the Dev-Mode / plugin (MCP) pull, run from a session against the NewCo file. That writes the same seed shape the pipeline already expects, then:

npm run build-all   # figma-source -> DTCG -> CSS/JS/JSON + NuGet (validates every alias)

The build fails loudly if any alias does not resolve, so a bad pull cannot ship. Nothing in the build reads a Figma file — the committed seeds are the input.

Local development

npm install
npm run build-tokens     # figma-source -> DTCG -> CSS/JS  (validates aliases)
npm run build-dist       # + assemble npm/
npm run storybook        # browse the token galleries
npm run sync-tokens      # pull latest from Figma (needs FIGMA_TOKEN, FIGMA_FILE_KEY)

Roadmap

• ✅ Type, spacing/layout (incl. radius), motion, elevation, breakpoints collections — shipped, same pipeline.
• ✅ NuGet delivery (NewCo.Tokens RCL) — shipped, lockstep with npm.
• Role-alias theming layer ([data-theme="midnight"]).
• Web Components (Lit) — framework-agnostic, accessible, consumable by Blazor/ Radzen and everything else. First component: Button. Mapped back to Figma via Code Connect. (Radix/shadcn are React-only and can't be the shared base; see docs/adoption.md.)
• Surface system polish: fold Fill/Static/Neutral/* dark values into the Midnight palette; add role variants where groups are currently single-option.

See docs/governance.md for versioning, ownership, and security posture, and docs/adoption.md for how tribes migrate.