chore: #5 Reference @singleton-sd/tokens in meta/BRAND

BRAND.md

@@ -6,9 +6,25 @@ Source of truth for **InkAds logo / favicon / OG binaries** is this package
 Public catalog: [assets.inkads.poc.singletonsd.com](https://assets.inkads.poc.singletonsd.com)
 (`config/product.json` → `publicUrl`).
 
-Token **values** should align with `@singleton-sd/tokens` semantic yellows/grays
-when the product adopts the design-system package; until then the hex values in
-`meta.json` are authoritative for these masters.
+## Colors ↔ `@singleton-sd/tokens`
+
+Authoritative semantic package: **`@singleton-sd/tokens@1.5.0`**
+(source: [design-system/tokens](https://gitlab.com/singleton-sd/design-system/tokens)).
+That package is private; InkAds SVG masters **do not** import it at build or
+runtime. Hex values below are baked into masters; token ids keep marketing /
+CSS / firmware in sync when those surfaces use the design-system package.
+
+| Master key (`meta.json`) | Hex | Token id | CSS var | Use |
+| --- | --- | --- | --- | --- |
+| `yellowDark500` | `#FFB300` | `yellow-dark-500` | `--ssd-color-yellow-dark-500` | Mark on black / dark UI |
+| `yellowLight500` | `#C89200` | `yellow-light-500` | `--ssd-color-yellow-light-500` | Mark on white / light UI |
+| `gray500` | `#7F848A` | `gray-600` | `--ssd-color-gray-600` | Secondary bars / byline (legacy key name; not `gray-500`) |
+| `gray300` | `#C9CCD1` | `gray-300` | `--ssd-color-gray-300` | Muted accents on light |
+| `black` | `#000000` | `black` | `--ssd-color-black` | Dark ground / mono ink |
+| `white` | `#FFFFFF` | `white` | `--ssd-color-white` | Light ground / mono paper |
+
+When bumping alignment, compare hex against `@singleton-sd/tokens` core
+colors and update both this table and `meta.json` → `tokens.version`.
 
 ## Formats
 
@@ -29,7 +45,8 @@ when the product adopts the design-system package; until then the hex values in
 
 - Do not stretch. Keep aspect ratio.
 - Clear space ≈ mark height.
-- Yellow-dark (`#FFB300`) on black; yellow-light (`#C89200`) on white.
+- Yellow-dark (`yellow-dark-500` / `#FFB300`) on black; yellow-light
+  (`yellow-light-500` / `#C89200`) on white.
 - Use `favicon` / 16px simplified mark for browser favicons.
 - Lockup SVGs still contain `<text>` (Open Sauce Sans). Browsers render them;
   CI PNG rasterization may fall back to a system font until text is outlined.
@@ -48,3 +65,4 @@ dist/                             # build output (Pages CDN) — do not edit
 
 - Blueprint: GitLab `@singleton-sd/assets`
 - Consumer: [poc-inkads-marketing](https://github.com/singleton-sd/poc-inkads-marketing)
+- Tokens: `@singleton-sd/tokens` (GitLab design-system/tokens)

meta.json

@@ -16,13 +16,50 @@
     "marketing": "src/marketing/"
   },
   "legacySvgRoot": "svg/",
+  "tokens": {
+    "package": "@singleton-sd/tokens",
+    "version": "1.5.0",
+    "source": "gitlab.com/singleton-sd/design-system/tokens",
+    "note": "Authoritative semantic ids for product yellows/grays. SVG masters keep baked hex and do not import the package at runtime."
+  },
   "colors": {
-    "yellowDark500": "#FFB300",
-    "yellowLight500": "#C89200",
-    "gray500": "#7F848A",
-    "gray300": "#C9CCD1",
-    "black": "#000000",
-    "white": "#FFFFFF"
+    "yellowDark500": {
+      "hex": "#FFB300",
+      "tokenId": "yellow-dark-500",
+      "cssVar": "--ssd-color-yellow-dark-500",
+      "usage": "primary mark on dark / black backgrounds"
+    },
+    "yellowLight500": {
+      "hex": "#C89200",
+      "tokenId": "yellow-light-500",
+      "cssVar": "--ssd-color-yellow-light-500",
+      "usage": "primary mark on light / white backgrounds"
+    },
+    "gray500": {
+      "hex": "#7F848A",
+      "tokenId": "gray-600",
+      "cssVar": "--ssd-color-gray-600",
+      "usage": "secondary bars / “BY SINGLETON SD” on dark lockups",
+      "note": "Legacy camelCase key gray500; hex matches tokens gray-600, not gray-500 (#9DA1A6)."
+    },
+    "gray300": {
+      "hex": "#C9CCD1",
+      "tokenId": "gray-300",
+      "cssVar": "--ssd-color-gray-300",
+      "usage": "muted gray accents on light themes"
+    },
+    "black": {
+      "hex": "#000000",
+      "tokenId": "black",
+      "cssVar": "--ssd-color-black",
+      "usage": "dark backgrounds / mono ink"
+    },
+    "white": {
+      "hex": "#FFFFFF",
+      "tokenId": "white",
+      "cssVar": "--ssd-color-white",
+      "usage": "light backgrounds / mono paper"
+    }
   },
   "designSource": "InkAds Logo.dc.html — recommended system 3a (icon) + 3b (wordmark / horizontal lockup)"
 }

scripts/validate-assets.test.mjs

@@ -26,6 +26,17 @@ test("meta.json declares mono theme for e-paper", async () => {
   assert.ok(meta.roles.includes("lockup-horizontal"));
 });
 
+test("meta.json maps brand hex to @singleton-sd/tokens ids", async () => {
+  const meta = JSON.parse(await readFile(join(ROOT, "meta.json"), "utf8"));
+  assert.equal(meta.tokens?.package, "@singleton-sd/tokens");
+  assert.match(String(meta.tokens?.version ?? ""), /^\d+\.\d+\.\d+/);
+  assert.equal(meta.colors.yellowDark500.tokenId, "yellow-dark-500");
+  assert.equal(meta.colors.yellowDark500.hex.toUpperCase(), "#FFB300");
+  assert.equal(meta.colors.yellowLight500.tokenId, "yellow-light-500");
+  assert.equal(meta.colors.gray500.tokenId, "gray-600");
+  assert.equal(meta.colors.gray300.tokenId, "gray-300");
+});
+
 test("assertSvgSafe rejects external href even with xmlns", () => {
   const evil = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10">
   <image href="https://attacker.example/x.png"/>