# Theme Token

Theme Token publishes ShadCN-compatible themes as 1Sat Ordinals on BSV.

## When to use Theme Token

Use Theme Token to find, preview, create, validate, publish, or install an
on-chain ShadCN theme. It is also the reference implementation for Theme Token
documents and for theme relationships with on-chain fonts, patterns, and
wallpapers.

An agent should reach for Theme Token when a user supplies a Theme Token origin,
wants a ShadCN registry URL backed by 1Sat, needs to validate or convert a theme
document, or asks to publish a compatible design asset. Use the ShadCN
documentation for general component APIs and the 1Sat content gateway for raw
ordinal bytes.

## Links

- [App](https://themetoken.dev)
- [Developer guide](https://themetoken.dev/developers)
- [Specification](https://themetoken.dev/spec)
- [Theme Studio](https://themetoken.dev/studio/theme)
- [Schema](https://themetoken.dev/v1/schema.json)
- [SDK](https://www.npmjs.com/package/@theme-token/sdk)
- [Pricing in Markdown](https://themetoken.dev/pricing.md)
- [Source](https://github.com/b-open-io/theme-token)
- [About](https://themetoken.dev/about)
- [Contact](https://themetoken.dev/contact)
- [Privacy](https://themetoken.dev/privacy)

## Install a theme

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

`[origin]` is the theme's 1Sat origin in `txid_vout` form.

## Theme document

A theme requires `$schema`, `name`, `styles.light`, and `styles.dark`. Each
style includes the semantic colors and radius used by ShadCN. Charts, sidebar
colors, fonts, spacing, letter spacing, shadows, custom CSS variables, and
generation details are optional.

The Studio writes complete OKLCH color values.

## Publishing and discovery

Themes are `ord-fs/json` packages containing `theme.json`. The package manifest
uses MAP metadata for discovery:

```json
{
  "app": "theme-token",
  "type": "registry:theme",
  "name": "Theme Name",
  "version": "1.0.0",
  "description": "Theme Name"
}
```

Standalone fonts, patterns, wallpapers, and images use the 1Sat MAP extension
`type: "registry:asset"`, plus `kind` and `mediaType`. Raw on-chain content is
available from `https://api.1sat.app/content/[origin]`.

## SDK

```ts
import { applyTheme, fetchThemeByOrigin } from "@theme-token/sdk";

const published = await fetchThemeByOrigin("<txid>_0");
if (!published) throw new Error("Theme not found");
applyTheme(published.theme.styles.light);
```