diff --git a/DESIGN.md b/DESIGN.md
index 12249aa..5590d46 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -1,3 +1,7 @@
+> ⚠ SUPERSEDED FOR SPECIFICS — the centralized token set is the single source of truth for all numeric values (colors, sizes, spacing).
+> This document is kept for Rams design philosophy only. Consult the token package (see README.md) for specific value definitions.
+> Conflicting typography claims in this document (Helvetica/Inter, 5-color palette) are superseded by the token package.
+
 DESIGN.md
 
 Design Philosophy
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0fa7603
--- /dev/null
+++ b/README.md
@@ -0,0 +1,7 @@
+# araharah
+
+A privacy-respecting, Telegram-first GPS navigator — Rams-inspired instrument-panel design, OpenStreetMap-based routing, KL metro first.
+
+## Design system
+
+The Telemetry Rams design system lives in `theme/` as a Tailwind v4 CSS-first token package — the single source of truth for every color, spacing, typography, and radius value in the project. Consume the tokens by importing `theme/src/tokens.css` (plain CSS custom properties, usable by any stylesheet or the MapLibre basemap) or the compiled stylesheet produced by `npm run build`. The token vocabulary mirrors the mockup screens verbatim, so markup derived from them maps one to one. Rams philosophy lives on in `DESIGN.md`, which is superseded for specifics — values are never restated outside the token package.