1 files changed, 39 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..306dfa0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# swarm.moe design-language
+
+Conservative Starsector-derived baseline for shared UI language.
+
+## Scope (v0.1)
+
+- frame geometry and material vocabulary
+- frame palette (background, edges, glow, zero roundedness)
+- typography families (`Remnant UI`, `Remnant Mono`)
+- control skin primitives (range slider, checkbox, scrollbar)
+- lightweight layout helpers for control rows (`.range-field`, `.range-value`, `.check-control`)
+
+## Explicitly Out Of Scope (v0.1)
+
+- product-specific spacing and layout systems
+- semantic status channels (success/warn/error)
+- app-specific color-picking UIs and interaction models
+
+## Artifacts
+
+- `tokens/starsector-dark.frame-font.tokens.json`
+- `tokens/starsector-dark.controls.tokens.json`
+- `css/starsector-dark.frame-font.css`
+- `css/starsector-dark.controls.css`
+- `examples/frame-font-preview.html`
+- `assets/fonts/*.woff2`
+
+## Consumption
+
+1. Copy or import `css/starsector-dark.frame-font.css`.
+2. Optionally add `css/starsector-dark.controls.css` for control theming.
+3. Apply `.swarm-frame`, `.swarm-surface`, `.swarm-surface-elevated`, `.swarm-frame-header` where needed.
+4. Use `--swarm-font-ui` and `--swarm-font-mono` or helper classes.
+5. For control rows, use `.range-field`, `.range-value`, and `.check-control`.
+
+## Notes
+
+Token values are derived from the Starsector dark baseline in `/home/main/swarm-ui`.
+Control styling values are tuned to stay palette-compatible with that baseline.