@theme-token/sdk

The core library for Theme Token. Handles validation, parsing, and transformation of themes between raw CSS, on-chain storage format, and ShadCN Registry format.

Why This Exists

ShadCN CLI (bunx shadcn add <url>) expects a specific JSON format with resolved color values—not raw CSS. This SDK bridges that gap.

flowchart LR
    A[Raw CSS] -->|parseCss| B[ThemeToken JSON]
    B -->|inscribe| C[Bitcoin]
    C -->|fetch| D[Registry API]
    D -->|toShadcnRegistry| E[ShadCN Format]
    E -->|bunx shadcn add| F[Your Project]

Loading

Installation

bun add @theme-token/sdk

Usage

Parse CSS to ThemeToken

Convert raw CSS into structured JSON for inscription. Automatically resolves var() references.

import { parseCss } from "@theme-token/sdk";

const css = `
:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.6 0.15 250);
  --primary-foreground: oklch(0.98 0 0);
  --radius: 0.5rem;
  /* ... */
}
.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.98 0 0);
  /* ... */
}
`;

const result = parseCss(css, "My Theme");
if (result.valid) {
  console.log(result.theme); // Ready to inscribe
}

Transform to ShadCN Registry

import { toShadcnRegistry } from "@theme-token/sdk";

const registryItem = toShadcnRegistry(theme);
// { $schema, name, type: "registry:style", cssVars: { light, dark } }

Fetch from Blockchain

import { fetchThemeByOrigin } from "@theme-token/sdk";

const published = await fetchThemeByOrigin("85702d92...cf_0");
if (published) {
  console.log(published.theme.name);
}

Apply at Runtime

import { applyThemeMode } from "@theme-token/sdk";

applyThemeMode(theme, "dark");

React Hook

For React applications, use the dedicated hook from the /react entry:

import { useThemeToken } from "@theme-token/sdk/react";

function ThemePicker({ ordinals }) {
  const {
    themeTokens,    // Filtered ThemeToken ordinals
    activeOrigin,   // Currently applied theme origin
    loadTheme,      // Load theme by origin
    resetTheme,     // Reset to default
    isLoading,      // Loading state
    error           // Error state
  } = useThemeToken(ordinals);

  return (
    <div>
      {themeTokens.map(t => (
        <button
          key={t.origin}
          onClick={() => loadTheme(t.origin)}
          disabled={isLoading}
        >
          {t.origin === activeOrigin ? "✓ " : ""}{t.origin.slice(0, 8)}...
        </button>
      ))}
      <button onClick={resetTheme}>Reset</button>
    </div>
  );
}

The hook automatically:

• Filters ordinals for map.app === "ThemeToken"
• Persists selection to localStorage
• Restores saved theme on mount
• Detects light/dark mode from document

Convert to CSS

import { toCss } from "@theme-token/sdk";

const css = toCss(theme);
// :root { --background: oklch(...); ... }
// .dark { --background: oklch(...); ... }

---

API Reference

Parsing and Validation

Function	Description
parseCss(css, name?)	Parse CSS string to ThemeToken, resolving var() references
validateThemeToken(data)	Validate unknown JSON against schema
themeTokenSchema	Zod schema for direct validation

Transformation

Function	Description
toShadcnRegistry(theme)	Convert to ShadCN Registry format
toCss(theme)	Convert to CSS string
toJson(theme, pretty?)	Convert to JSON string

Network

Function	Description
fetchThemeByOrigin(origin)	Fetch theme from blockchain
fetchPublishedThemes()	Fetch all published themes
getRegistryUrl(origin)	Get registry URL for ShadCN CLI

Runtime

Function	Description
applyTheme(styles)	Apply style props to document
applyThemeMode(theme, mode)	Apply light or dark mode
getCurrentTheme()	Read current theme from DOM
clearTheme()	Remove all theme variables

React (@theme-token/sdk/react)

Export	Description
useThemeToken(ordinals)	React hook for managing ThemeToken ordinals

---

ThemeToken Format

interface ThemeToken {
  $schema: string;
  name: string;
  author?: string;
  styles: {
    light: ThemeStyleProps;
    dark: ThemeStyleProps;
  };
}

Colors use OKLCH: oklch(L C H) where L is lightness (0–1), C is chroma (0–0.4), H is hue (0–360).

---

License

MIT