// 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.

// Project Presets

Complete Project Bundles

Project presets bundle themes, fonts, icons, and configuration into complete shadcn/create bases. Create entire projects with one command.

Create Project from Preset

bunx shadcn@latest create --preset "https://themetoken.dev/init?project=[origin]"

Replace [origin] with the project inscription origin

Project Bundle Contents

Theme Styles

Complete light/dark CSS variables including sidebar and chart colors

Dependencies

shadcn, CVA, animations, icon library packages

CLI Configuration

Base color, menu style, icon library, font settings

On-Chain Assets(optional)

Bundled fonts, patterns, or wallpapers via vout references

Query parameter overrides:

iconLibrary

baseColor

menuColor

menuAccent

registry:base Schema

{
  "type": "registry:base",
  "name": "My Project",
  "extends": "none",
  "dependencies": [
    "shadcn@latest",
    "class-variance-authority",
    "tw-animate-css",
    "lucide-react"
  ],
  "registryDependencies": [
    "utils"
  ],
  "cssVars": {
    "light": {
      "background": "oklch(...)",
      "primary": "oklch(...)",
      "sidebar": "oklch(...)",
      "chart-1": "oklch(...)"
    },
    "dark": {
      "background": "oklch(...)",
      "primary": "oklch(...)",
      "sidebar": "oklch(...)",
      "chart-1": "oklch(...)"
    }
  },
  "css": {
    "@import \"tw-animate-css\"": {},
    "@import \"shadcn/tailwind.css\"": {},
    "@layer base": {
      "*": {
        "@apply border-border outline-ring/50": ""
      },
      "body": {
        "@apply bg-background text-foreground": ""
      }
    }
  },
  "config": {
    "style": "my-style",
    "tailwind": {
      "baseColor": "zinc"
    },
    "iconLibrary": "lucide",
    "menuColor": "default",
    "menuAccent": "subtle"
  },
  "bundle": {
    "version": 2,
    "assets": [
      {
        "vout": 0,
        "type": "font",
        "slot": "sans"
      }
    ]
  }
}

Served via /init?project=[origin] for shadcn create --preset. Bundle assets use {{vout:N}} references resolved to ORDFS URLs.

// 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

Install Themes from Blockchain

ShadCN Registry Format

Theme Properties

Full Schema Structure

Complete Project Bundles

Project Bundle Contents

registry:base Schema

MAP Metadata Protocol

Inscribe on Any Chain

@theme-token/sdk

validateThemeToken

fetchThemeByOrigin

parseCss

applyTheme

AI Agent Resources

llms.txt

llms-full.txt

@theme-token/sdk

1Sat Ordinals

ORDFS Network