VB Design System

<theme-import>

Apply a DTCG (Design Tokens Community Group) tokens.json file to a preview scope. Sibling of theme-export — paste, file, or URL input feeds a pure deserializer.

Overview

The <theme-import> component applies a DTCG tokens.json file to a preview scope. It is the sibling of <theme-export>: three input modes — paste, file, URL — feed a pure deserializer that reverses VB's prefix mapping and rebuilds CSS values.

Tokens land on the host's preview scope (default #preview), never on :root, so import experiments don't leak into the live site. Round-trip is lossless for VB-authored DTCG: $extensions["com.vanilla-breeze"] preserves relative-color expressions, light-dark() literals, and em/% units.

  • primary
  • secondary
  • accent
  • success
  • border

Sample content in the preview scope — imported tokens land here and recolor the swatches, buttons, surface, and text, never the live page.

New to DTCG? Copy this sample and paste it into the Paste tab above, then apply — the preview swatches will switch to a warm rose/cyan palette:

Attributes

Attribute Type Default Description
target string #preview CSS selector for the scope to apply tokens to. Tokens are written as inline custom properties on this element.
placeholder string Paste DTCG tokens.json here… Textarea placeholder for the paste input mode.

Input modes

Three tabs feed the same deserializer:

  • Paste — paste raw DTCG JSON into a textarea and apply it directly.
  • File — pick a local .json file from disk.
  • URL — fetch a tokens.json from a remote URL.

Each mode reports how many tokens were applied and lists any ignored entries (tokens with prefixes or types theme-import doesn't recognize) in a collapsible details panel.

Scoping to a custom target

Pass target to apply imported tokens to any element other than the default #preview — useful for previewing a theme against a specific component subtree.

Events

Event Detail Description
theme-import:applied { tokens, applied, ignored, source } Fires after tokens are applied. source is paste, file, or url.
theme-import:error { error, phase } Fires when parsing, fetching, or applying the tokens fails.

What happens to “foreign” DTCG

The deserializer reverses the prefix mapping established by <theme-export format="dtcg">. DTCG tokens that don't map to a known VB CSS-variable prefix land in an “ignored” panel rather than being silently dropped — the user always sees what was lost. The importer never writes new VB token names, only known-good ones from the prefix map. This preserves the “themes override existing tokens only” contract from Vanilla Breeze's core token layer.

Composite typography unpacking

DTCG's composite typography token bundles font-family, size, weight, line-height, and letter-spacing into one object. VB stores these as separate scalars. On import, composite typography unpacks into --font-{name}, --font-size-{name}, --font-weight-{name}, --line-height-{name}, and --letter-spacing-{name} as appropriate.

Design system workflow

Use theme-import alongside <theme-export> and <token-specimen> to round-trip themes:

  1. Export the current theme with theme-export as DTCG JSON.
  2. Edit the file, or grab a curated set from a third-party design system.
  3. Paste, upload, or link it back in with theme-import to preview the result.

Accessibility

  • Paste, file, and URL are native <textarea>, <input type="file">, and <input type="url"> elements.
  • Mode tabs use role="tablist" with an accessible label.
  • Apply results and ignored-token counts are announced via an <output> element.
↑