diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..16e48ee
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,40 @@
+# @frozendev/tokens
+
+Single source of truth for `frzn.dev` color system. You may use the sources in
+`tokens/` and run `pnpm run build` to generate outputs. Every platform gets an
+up-to-date file. No manual syncing.
+
+## Editing tokens
+
+All changes start in `tokens/`:
+
+- **New colour stop** -> add to `tokens/color.json`
+- **Semantic role change**-> edit `tokens/semantic.json`
+- Never edit anything in `outputs/` directly. It will be overwritten on the next
+  build
+
+After editing:
+
+```bash
+# Execute the build script in scripts/build.mjs
+$ pnpm run build   # regenerates all outputs
+```
+
+Commit both `tokens/` and `outputs/` so the CDN/raw GitHub URL paths keep
+working.
+
+## Local development
+
+```bash
+# This repository is designed to work with pnpm. Prefer it over npm or yarn.
+$ pnpm install
+$ pnpm run build
+```
+
+Outputs land in `outputs/`.
+
+### Previewing Colors
+
+A preview script is provided in `scripts/preview.mjs` that you can invoke with
+`pnpm preview`. It will generate a HTML page in `build/` that you can open with
+your browser to preview the colors before publishing any packages.
diff --git a/docs/assets/preview.png b/docs/assets/preview.png
new file mode 100644
index 0000000..cd0f72d
Binary files /dev/null and b/docs/assets/preview.png differ