docs: add project README; provide preview example

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: Id9ad9be666857e1b52a00634fb7cdc036a6a6964

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.