// ShadCN Registry Format

Install Themes from Blockchain

Theme Token uses the ShadCN Registry Format. Install any on-chain theme directly with the ShadCN CLI.

Install via CLI

bunx shadcn@latest add https://themetoken.dev/r/themes/[origin]

Replace [origin] with the inscription origin ID

// The Schema

ShadCN Registry Format

Theme Token uses the same CSS custom properties that power thousands of ShadCN-based applications. 100% compatible with the ShadCN CLI ecosystem.

Theme Properties

19 Core Colors *

background

foreground

card

popover

primary

secondary

muted

accent

destructive

border

input

ring

Charts (optional)

chart-1

chart-2

chart-3

chart-4

chart-5

Sidebar (optional)

sidebar

sidebar-primary

sidebar-accent

sidebar-border

sidebar-ring

Typography & Layout

radius*

font-sans

font-serif

font-mono

letter-spacing

spacing

Font values: Google Font name or /content/origin for on-chain fonts

Shadows (optional)

shadow-2xs

shadow-xs

shadow-sm

shadow

shadow-md

shadow-lg

shadow-xl

shadow-2xl

Colors include -foreground variants. All color values use oklch() format.* = required.

Full Schema Structure

{
  "$schema": "https://themetoken.dev/v1/schema.json",
  "name": "My Theme",
  "author": "Name (https://github.com/username)",
  "styles": {
    "light": {
      "background": "oklch(0.98 0.005 240)",
      "foreground": "oklch(0.15 0.01 240)",
      "card": "oklch(1 0 0)",
      "card-foreground": "oklch(0.15 0.01 240)",
      "popover": "oklch(1 0 0)",
      "popover-foreground": "oklch(0.15 0.01 240)",
      "primary": "oklch(0.55 0.22 255)",
      "primary-foreground": "oklch(0.98 0 0)",
      "secondary": "oklch(0.95 0.005 240)",
      "secondary-foreground": "oklch(0.25 0.01 240)",
      "muted": "oklch(0.95 0.005 240)",
      "muted-foreground": "oklch(0.5 0.01 240)",
      "accent": "oklch(0.95 0.01 255)",
      "accent-foreground": "oklch(0.25 0.01 240)",
      "destructive": "oklch(0.55 0.22 25)",
      "destructive-foreground": "oklch(0.98 0 0)",
      "border": "oklch(0.9 0.005 240)",
      "input": "oklch(0.9 0.005 240)",
      "ring": "oklch(0.55 0.22 255)",
      "radius": "0.5rem",
      "font-sans": "Inter",
      "font-mono": "/content/abc123_0"
    },
    "dark": {
      "background": "oklch(0.12 0.015 240)",
      "foreground": "oklch(0.95 0.005 240)",
      "card": "oklch(0.16 0.015 240)",
      "card-foreground": "oklch(0.95 0.005 240)",
      "popover": "oklch(0.16 0.015 240)",
      "popover-foreground": "oklch(0.95 0.005 240)",
      "primary": "oklch(0.65 0.22 255)",
      "primary-foreground": "oklch(0.12 0.015 240)",
      "secondary": "oklch(0.2 0.015 240)",
      "secondary-foreground": "oklch(0.95 0.005 240)",
      "muted": "oklch(0.2 0.015 240)",
      "muted-foreground": "oklch(0.65 0.01 240)",
      "accent": "oklch(0.25 0.02 255)",
      "accent-foreground": "oklch(0.95 0.005 240)",
      "destructive": "oklch(0.6 0.22 25)",
      "destructive-foreground": "oklch(0.98 0 0)",
      "border": "oklch(0.25 0.015 240)",
      "input": "oklch(0.25 0.015 240)",
      "ring": "oklch(0.65 0.22 255)",
      "radius": "0.5rem",
      "font-sans": "Inter",
      "font-mono": "/content/abc123_0"
    }
  }
}

Our /r/themes/[origin] endpoint serves this as ShadCN Registry Format. Also compatible with tweakcn. Name and author follow npm conventions.

// On-Chain Metadata

MAP Metadata Protocol

Assets use the MAP (Magic Attribute Protocol) for on-chain metadata.

Theme Fields

appAlways "theme-token"

req

typeAsset type identifier

req

promptAI generation prompt

opt

providerAI provider

opt

modelAI model ID

opt

MAP_DATA

JSON

{
  "app": "theme-token",
  "type": "theme",
  "prompt": "cyberpunk neon",
  "provider": "anthropic",
  "model": "claude-opus-4-5"
}

MAP (Magic Attribute Protocol) metadata is inscribed alongside the asset content. Theme JSON includes name, author, cssVars. Font metadata is embedded in the binary.

// Blockchain Implementations

Inscribe on Any Chain

Theme Tokens can be inscribed on multiple blockchains. Choose based on your cost, speed, and ecosystem requirements.

inscribe-bsv.ts

1satordinals.com

import { createOrdinals } from "js-1sat-ord";

const themeToken = { /* Theme Token JSON */ };

await createOrdinals({
  utxos,
  destinations: [{
    address: ownerAddress,
    inscription: {
      dataB64: btoa(JSON.stringify(themeToken)),
      contentType: "application/json",
    },
  }],
  paymentPk,
});

Storage

Full JSON on-chain

Cost per token

~$0.001

Finality

Instant

// TypeScript SDK

@theme-token/sdk

TypeScript utilities for working with Theme Tokens. Validate, fetch, convert, and apply themes programmatically.

Install

bun add @theme-token/sdk

validateThemeToken

Zod-powered schema validation

fetchThemeByOrigin

Fetch themes from blockchain

parseCss

Convert CSS to ThemeToken

applyTheme

Apply themes to DOM at runtime

View on GitHub npm

// For AI Assistants

AI Agent Resources

Machine-readable documentation for AI coding assistants. Copy context directly into your AI tool or feed the URLs. Following the llms.txt specification.

llms.txt

Quick reference (~2KB)

llms-full.txt

Complete docs (~6KB)

@theme-token/sdk

TypeScript SDK

AI tools can also fetch directly: themetoken.dev/llms.txt or themetoken.dev/llms-full.txt