@mtdt/observeops-ds-spec 0.1.0

package/llms.txt

@@ -0,0 +1,60 @@
+# ObserveOps Design System
+
+> The design system of Motadata ObserveOps (a Vue 2.6 enterprise network-monitoring SPA).
+> Machine-readable: components, tokens, page recipes, layout structure, and product coverage —
+> everything an AI tool needs to build ObserveOps UI faithfully instead of guessing.
+
+Any AI tool building ObserveOps UI must follow the operating contract below, then load the spec
+in the given order. All paths are relative to this file (`design-system/`).
+
+## Start here (required reading)
+
+- [AI Operating Contract](AGENTS.md): the rules — use only catalogued components, resolve every
+  colour to a token, compose from recipes/layout, and STOP-and-ASK before using anything not in
+  this DS. Read this before generating anything.
+
+## Spec (load in this order)
+
+- [components/index.json](components/index.json): the machine index — load FIRST. Every component
+  (family, `selectHint`, `summary`, `variants`), plus pointers to tokens, recipes, and layout.
+- [components/registry/](components/registry/): per-component spec — `props` / `events` / `slots` /
+  `apis`, `decisionFlow`, `variants`, `sizes`, `states`, `do` / `dont`, `tokensUsed`, `a11y`.
+- [components/recipes/recipes.json](components/recipes/recipes.json): 7 page templates + 5 flows,
+  each mapping screen regions → components.
+- [layout/layouts.json](layout/layouts.json): app shell, 4 route shells + 2 content layouts,
+  screen regions, 6 content layouts, 10 panel behaviours, 7 page templates.
+- [layout/grid.json](layout/grid.json): the 12-column MRow/MCol grid.
+- [foundation/](foundation/): product page-by-page coverage — which real pages/flows use each
+  layout element (grounding/best practices).
+
+## Tokens (never hardcode a colour)
+
+- [tokens/variables.json](tokens/variables.json): the runtime CSS `--vars` crosswalk (336 vars,
+  light + dark) — the LIVE product token layer. Emit these.
+- [tokens/structural.json](tokens/structural.json): LESS `@vars` — spacing, sizing, radius, type.
+- [tokens/kit-accents.json](tokens/kit-accents.json): Ant 1.x LESS accents (`@primary-color` cyan).
+- [tokens/purpose-map.json](tokens/purpose-map.json): purpose → token (surface / text / border /
+  brand / status / severity / shadow + structural scale) for styling a NEW element by intent.
+- Note: `--primary` = navy `#111c2c` (light) / `#e3e8f2` (dark), NOT cyan. The cyan `@primary-color`
+  `#099dd9` is the Ant form-control accent only. Do NOT emit `mds-*` tokens (a future/unwired layer).
+
+## Live reference
+
+- Storybook (visual catalogue): <https://niravbhatt1317.github.io/motadata-design-system/>
+
+## Key rules (full list in AGENTS.md)
+
+- Use only components in `index.json`; configure only with documented props/events/slots/apis.
+- Resolve every colour/space to a token; never hardcode hex/rgb/rgba/hsl.
+- Compose pages from `recipes` + `layout`; forms use the 12-col MRow/MCol grid. Recipes are examples,
+  not an allow-list — for an undocumented screen (signup, etc.), COMPOSE it from DS parts, don't ask.
+- Never branch on theme — tokens are theme-aware. Honour each component's `a11y`.
+- ASK only when you'd need a BUILDING BLOCK not in the DS (a component/token/primitive that doesn't
+  exist, e.g. charts) — then STOP and ASK before substituting. Never ask permission to combine parts
+  already in the DS.
+
+## Known gaps (expect to ASK here)
+
+- Charts / data-viz / widget tiles / topology graph — only tooltips (`data-viz-tooltips`) are
+  catalogued; the chart/graph components themselves are not in the DS yet.
+- Figma library — not built.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@mtdt/observeops-ds-spec",
+  "version": "0.1.0",
+  "description": "Machine-readable spec and AI operating contract for the Motadata ObserveOps design system — components, tokens, page recipes, layout structure, and the rules an AI tool follows to build ObserveOps UI faithfully.",
+  "license": "UNLICENSED",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "AGENTS.md",
+    "llms.txt",
+    "spec.manifest.json",
+    "components/",
+    "tokens/",
+    "layout/",
+    "foundation/",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./index.js",
+    "./llms.txt": "./llms.txt",
+    "./AGENTS.md": "./AGENTS.md",
+    "./manifest": "./spec.manifest.json",
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "keywords": [
+    "design-system",
+    "observeops",
+    "motadata",
+    "ai",
+    "llms",
+    "design-tokens",
+    "spec",
+    "agents"
+  ],
+  "scripts": {
+    "test": "echo \"spec validated at build time via design-system/scripts/validate-spec.js\" && exit 0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/spec.manifest.json

@@ -0,0 +1,407 @@
+{
+  "name": "@mtdt/observeops-ds-spec",
+  "version": "0.1.0",
+  "generated": "2026-06-18T16:17:51.962Z",
+  "entry": "llms.txt",
+  "contract": "AGENTS.md",
+  "index": "components/index.json",
+  "counts": {
+    "components": 26,
+    "registries": 26,
+    "recipes": 12,
+    "specs": 26,
+    "files": 78
+  },
+  "files": [
+    {
+      "path": "AGENTS.md",
+      "bytes": 6546,
+      "sha256": "d8be4b87ca70d65e97f75a8b9d8cae07be928ec2af15ed0f3b7938f4384b7069"
+    },
+    {
+      "path": "README.md",
+      "bytes": 3476,
+      "sha256": "cdae300727bcd2a9fa8177a5bbb3f406f0ece8a9e6c2e7697d31323b5232a939"
+    },
+    {
+      "path": "components/index.json",
+      "bytes": 39047,
+      "sha256": "d82d1fc5e16dfe7e870dbadd48145f15fb4b95ed7eb7a8b9da34d3f6b1b7bf2d"
+    },
+    {
+      "path": "components/recipes/README.md",
+      "bytes": 2225,
+      "sha256": "bd243736992628b2252338dfffc781eb794e63e2f5c8107420360eebdc658d0c"
+    },
+    {
+      "path": "components/recipes/recipes.json",
+      "bytes": 29120,
+      "sha256": "3fcd699265dd8f6910d31a9e09d1e0652e6dd1b9d50e7b03c0fdce9c953f6b55"
+    },
+    {
+      "path": "components/registry/README.md",
+      "bytes": 2335,
+      "sha256": "fb04a84f87557ca4ea5a60c20a55e6a438592f84c5dbc48390b939b68f9fc239"
+    },
+    {
+      "path": "components/registry/_schema.json",
+      "bytes": 3851,
+      "sha256": "41ecd89f9768437de188468cb8c1d6386720649657390a6880f8ce0fccf2e72a"
+    },
+    {
+      "path": "components/registry/button.json",
+      "bytes": 11751,
+      "sha256": "e9386f39e5f312c7386c6334ee5a7baad27a83d049187f7a3596ebecce1eb05d"
+    },
+    {
+      "path": "components/registry/checkbox.json",
+      "bytes": 6134,
+      "sha256": "3c2c0d792cbbf5cdbea508f1f1b25830c7a9de8bf845ea936bad835fa48d9094"
+    },
+    {
+      "path": "components/registry/data-viz-tooltips.json",
+      "bytes": 10395,
+      "sha256": "4a2534cfca43d1026db23eb513adc83ddb95c70312fed0d3640079d72a913e9e"
+    },
+    {
+      "path": "components/registry/date-time-pickers.json",
+      "bytes": 13126,
+      "sha256": "bd2f41e4beef9332d1a781cf4919ae4118c237e8739f50c82b55ec22d8f75234"
+    },
+    {
+      "path": "components/registry/drawer.json",
+      "bytes": 8083,
+      "sha256": "9694ec900d7b2569cd9e14b913e756a0f70f90828a3ea342b792f7e392d7c2bb"
+    },
+    {
+      "path": "components/registry/dropdown-picker.json",
+      "bytes": 10481,
+      "sha256": "3038e9f5c6bed91092e5d5a0f3986f2e4ea6a5330b97381140c2850e36447d3c"
+    },
+    {
+      "path": "components/registry/filters.json",
+      "bytes": 7343,
+      "sha256": "036bf8dd8cf79f00be42d76eeb702b5c659dde63a7792b4d21741626e2764157"
+    },
+    {
+      "path": "components/registry/form-item.json",
+      "bytes": 9546,
+      "sha256": "1fa620e289e84955e92e9f442115efd0068806eaa31f43a03e23e310d366bdcf"
+    },
+    {
+      "path": "components/registry/input.json",
+      "bytes": 8618,
+      "sha256": "538679e44180798fa6f8a0e644b9e074c4e863d494cc3e27f6fff8e7faa70160"
+    },
+    {
+      "path": "components/registry/link.json",
+      "bytes": 6575,
+      "sha256": "b3362ab4305d631e24c83149482d46723f964f4f9c62d516aaeec14bbf2e6ff4"
+    },
+    {
+      "path": "components/registry/loose-tags.json",
+      "bytes": 6261,
+      "sha256": "01b28b99f5938984176dd09cfae6d59a21c6ec45fedce6eafaf4e29a30b7bdac"
+    },
+    {
+      "path": "components/registry/menu.json",
+      "bytes": 5410,
+      "sha256": "4a6b1f25688d7f9f55b61d2202951548d54051f02c3309646aec8e604cffac3a"
+    },
+    {
+      "path": "components/registry/modal.json",
+      "bytes": 9110,
+      "sha256": "eb56de0ddd2ccb74cedf0ad5c62550d2608ecf649a5d3cef7eee4a939027e365"
+    },
+    {
+      "path": "components/registry/navigation.json",
+      "bytes": 17792,
+      "sha256": "c0d36d2e8775f7c7c04352c626a60b974a13d8b6ddae9fa46162c6c7981216d1"
+    },
+    {
+      "path": "components/registry/popover.json",
+      "bytes": 6373,
+      "sha256": "f24c5f0acbe8810bf583772bcdea8ceeba79ede66a94e794aeedafb76faf8d46"
+    },
+    {
+      "path": "components/registry/radio.json",
+      "bytes": 7951,
+      "sha256": "7c338f1f946f6e9e0e0a4b0d55a7512c6aa695b8f2b4bafc44bfad35b8b7e6fd"
+    },
+    {
+      "path": "components/registry/scheduler.json",
+      "bytes": 8269,
+      "sha256": "7ca9e76b347ecc5a36bb7b80b34c6825028a611b6cc04af4632ca909d63794d9"
+    },
+    {
+      "path": "components/registry/select.json",
+      "bytes": 7514,
+      "sha256": "6643c5479e7347cd08860c821de71d02da9ce286250c27a8b767ef4d24eec394"
+    },
+    {
+      "path": "components/registry/severity.json",
+      "bytes": 6781,
+      "sha256": "d9453cd3151b41ca6a37b5419f8138e152e8a9ff6d39687eeac785af8029ce05"
+    },
+    {
+      "path": "components/registry/switch.json",
+      "bytes": 4771,
+      "sha256": "6ed63cd265b2e25c1c8cee3db4ad46817ec3c9a75e1841dadc091cee9dd2cf61"
+    },
+    {
+      "path": "components/registry/table.json",
+      "bytes": 7841,
+      "sha256": "282c640d00d6b276e2e2ff2440addfa71bd4b5d754568ce4f66ea11627af8b3d"
+    },
+    {
+      "path": "components/registry/tabs.json",
+      "bytes": 9320,
+      "sha256": "ed1255fbca37e258133a39e3043c05b8d328ad7a5b57eb825844bedc41461c7b"
+    },
+    {
+      "path": "components/registry/tag.json",
+      "bytes": 11493,
+      "sha256": "245aef496865fb8ba8ddd065bba02c1f1b4863faa7b9b837bfd2bb09dae8738f"
+    },
+    {
+      "path": "components/registry/tags-list.json",
+      "bytes": 3798,
+      "sha256": "0668ebfab596511042a1789b2c88d0ac2d2223a2699e85405923d1877954f11a"
+    },
+    {
+      "path": "components/registry/toolbars.json",
+      "bytes": 9274,
+      "sha256": "ae49305918b42b3c8049a8cfa3a88b2e1aa529652c66754e6ba5afbb42e16805"
+    },
+    {
+      "path": "components/registry/tooltip.json",
+      "bytes": 5805,
+      "sha256": "86f0a203cdd0d7270c18dabd08feae017ebaebe90408696ccbfa34df00bc7a41"
+    },
+    {
+      "path": "components/specs/README.md",
+      "bytes": 6042,
+      "sha256": "70295fc5d20cbc6f9f19be807c1ffb52429cd736d320b5311f5e7bc60759304e"
+    },
+    {
+      "path": "components/specs/button.md",
+      "bytes": 11302,
+      "sha256": "54ab4ffcacf7076f7948c07bb58b60d802d6eacf284e2b7d8233bbde8136c0a0"
+    },
+    {
+      "path": "components/specs/checkbox.md",
+      "bytes": 7347,
+      "sha256": "9841b45d6f19ea3f2f3ae8678ccf39ece59ddbd148989f59bcda294c59c1a5e2"
+    },
+    {
+      "path": "components/specs/data-viz-tooltips.md",
+      "bytes": 5751,
+      "sha256": "13d481553390cec68f82a8015639186cb3d38c3292f6f1bf66fd7e48aaceb404"
+    },
+    {
+      "path": "components/specs/date-time-pickers.md",
+      "bytes": 9578,
+      "sha256": "b9c4bc271bbc891715450e8f9de196439d93715477a5480416ca52afc4e321af"
+    },
+    {
+      "path": "components/specs/drawer.md",
+      "bytes": 9625,
+      "sha256": "ecbf7f1a19a857baccb8b445c2bbce9a1b9968e03d89f6ff3dfdad0e2e45212b"
+    },
+    {
+      "path": "components/specs/dropdown-picker.md",
+      "bytes": 8938,
+      "sha256": "61ce7e447b70207653a6822d776fbc4189e3c81ed62602d3dbc9f4aacf7daf0e"
+    },
+    {
+      "path": "components/specs/filters.md",
+      "bytes": 6869,
+      "sha256": "f4a59c322c2e3eae01f2cc48c832922d65884d31035424868466b9538afbbb19"
+    },
+    {
+      "path": "components/specs/form-item.md",
+      "bytes": 7210,
+      "sha256": "4cf62a2255c3d84911ffa9e8c88442eaf2d26df38a130cdd6fef6802e9614f8e"
+    },
+    {
+      "path": "components/specs/input.md",
+      "bytes": 6493,
+      "sha256": "7f5778289cd3ae6077e2c6574a74d587d4183da2995b7bd4ce04ea8452e000d2"
+    },
+    {
+      "path": "components/specs/link.md",
+      "bytes": 6628,
+      "sha256": "91311fb9c45bd92419f8d3423dbf5b2ad98b9dd89ddfedfcb0c5f38b67858056"
+    },
+    {
+      "path": "components/specs/loose-tags.md",
+      "bytes": 6731,
+      "sha256": "9c78302407ee658d54d39cfa6b6044b2635f953098c0fb02045589d561dd6256"
+    },
+    {
+      "path": "components/specs/menu.md",
+      "bytes": 5131,
+      "sha256": "bdb0267c3b83ab191837c3a8b00ba66b69de2bfbba1f22664fbc5b7a88b7faea"
+    },
+    {
+      "path": "components/specs/modal.md",
+      "bytes": 10177,
+      "sha256": "93aadb07cf438b5c1671604dbafe566b948afc07280d406aa2f0c40d44a3d9fa"
+    },
+    {
+      "path": "components/specs/navigation.md",
+      "bytes": 12418,
+      "sha256": "c29dba31ba6bd1967a2271bef737cd9eee2ff3225b9af7d5126057fc7e8073f0"
+    },
+    {
+      "path": "components/specs/popover.md",
+      "bytes": 5994,
+      "sha256": "09e162ff0cd518f0627123a12e4fd93d7337640e6ff58e4843d1b1401648cd36"
+    },
+    {
+      "path": "components/specs/radio.md",
+      "bytes": 7547,
+      "sha256": "7884592b99d1bb91ae9b4f779e6ec44ed702b0f67d0908d3da3edd0eb37649cc"
+    },
+    {
+      "path": "components/specs/scheduler.md",
+      "bytes": 7132,
+      "sha256": "9aca6a3c29f9a0c9c97544e58c1bb2804c66560dc9e4b9e5559b38b15347d259"
+    },
+    {
+      "path": "components/specs/select.md",
+      "bytes": 6498,
+      "sha256": "9c260251d31ea3f876780e01b975284871955aae0a55511bedfe5c3709f395f8"
+    },
+    {
+      "path": "components/specs/switch.md",
+      "bytes": 5087,
+      "sha256": "ef3aecc7f363197b36760d16e56176c7e8c2436c52b518201da38ed0b1946dec"
+    },
+    {
+      "path": "components/specs/table.md",
+      "bytes": 5689,
+      "sha256": "af2212b1b08d4cbd7cbf36174b26e14e9778d4672d2c558062e37ba688984312"
+    },
+    {
+      "path": "components/specs/tabs.md",
+      "bytes": 6913,
+      "sha256": "a132c9277c97f5334c45df17e7a349c1f606d58af0dfe67a968da51201a0f620"
+    },
+    {
+      "path": "components/specs/tag.md",
+      "bytes": 10916,
+      "sha256": "b6f967b019dbc79fde7b99c0088f3f6dd11e9e5a6ed63f3e3c02a5e294e854f7"
+    },
+    {
+      "path": "components/specs/tags-list.md",
+      "bytes": 4432,
+      "sha256": "8232fe4ad865308ab7fa2cc99ac356217184e4bb16436bebd722ec86e6deba9b"
+    },
+    {
+      "path": "components/specs/toolbars.md",
+      "bytes": 5962,
+      "sha256": "99fb315247698021f70049752ffb0180a00a885a83c665aa3ccc1ee1536b2d76"
+    },
+    {
+      "path": "components/specs/tooltip.md",
+      "bytes": 5516,
+      "sha256": "6fc27b526ee89a67f57ee62c7313faf1f37da35baf78f224eb397ceb22c71b92"
+    },
+    {
+      "path": "foundation/README.md",
+      "bytes": 2990,
+      "sha256": "94f1523186d10971f2ce457da5e9820904080985c6b11aace4a39912345444df"
+    },
+    {
+      "path": "foundation/layout-shells.md",
+      "bytes": 4705,
+      "sha256": "288447032d22d1ae7772f085d83ae8675ce6bd24107498d7a6da61f4ad4805b2"
+    },
+    {
+      "path": "foundation/page-templates.md",
+      "bytes": 5915,
+      "sha256": "836d92df25504eaf7d8817d8962da2aee1eaaf9722d588dce901a29bf6b8effd"
+    },
+    {
+      "path": "foundation/panel-behaviours.md",
+      "bytes": 5340,
+      "sha256": "591906d7ce58feb0090f1a64d3f3eaa5f9e24a3842d3de2e1066f95a7e19536e"
+    },
+    {
+      "path": "foundation/screen-regions.md",
+      "bytes": 4800,
+      "sha256": "c9f0766013de3aa6061c263ea9ffd3aa87d2936a819915b7527a936e736b3adb"
+    },
+    {
+      "path": "index.js",
+      "bytes": 2501,
+      "sha256": "0da016aa4afee511535107f45d96251027ffd2a657671b5c54fbded7886f4f1d"
+    },
+    {
+      "path": "layout/grid.json",
+      "bytes": 1913,
+      "sha256": "494f090e9b68c11f04b1d00961ba4e337ee07b2e81e7b762266b7b717ba19eec"
+    },
+    {
+      "path": "layout/layouts.json",
+      "bytes": 12255,
+      "sha256": "15ff34879aad3c71f4a05b1fe579b201d71d74d9f933ebf55487f4d6e2b52b38"
+    },
+    {
+      "path": "llms.txt",
+      "bytes": 3562,
+      "sha256": "53945f6464853840a1edf3c34cf1c854e3fed0e4b4145529ed54ea6d2182c4e1"
+    },
+    {
+      "path": "package.json",
+      "bytes": 1049,
+      "sha256": "e41f71682d46fcbffb236a880259b9772acf0e958eeb5330b57057b45d4b7621"
+    },
+    {
+      "path": "tokens/README.md",
+      "bytes": 7022,
+      "sha256": "4c4e8b0d534812963300a75e9894b8b84a62b756e2f52995c66713e2c76367f4"
+    },
+    {
+      "path": "tokens/component.json",
+      "bytes": 923,
+      "sha256": "e32a3474956fe014a03de0e72d726e27ec6d1d434abb0b635e65356caa0b2964"
+    },
+    {
+      "path": "tokens/kit-accents.json",
+      "bytes": 583,
+      "sha256": "003f4b286c7568d2c46ac45e8cad74c55e5eb0a3f202b8cb23007a76266b2592"
+    },
+    {
+      "path": "tokens/primitive.json",
+      "bytes": 2682,
+      "sha256": "00df60a24baed14a14471646c9a90b61003ba85bb66966dbc3ad750cf1bb5740"
+    },
+    {
+      "path": "tokens/purpose-map.json",
+      "bytes": 6096,
+      "sha256": "3f114a1444e4579cc67c30ae3716fbe2f452a61985f0f3dbec50f35494dd8781"
+    },
+    {
+      "path": "tokens/semantic.dark.json",
+      "bytes": 2253,
+      "sha256": "5b13ddb8e1728c6f569e1cea0723b5f61f88a4af249119f62405eb82e3d30c9c"
+    },
+    {
+      "path": "tokens/semantic.light.json",
+      "bytes": 2203,
+      "sha256": "3b3848c76a3e1223230aa8759c6b277daaae9b4413039158cfc1c0e152380200"
+    },
+    {
+      "path": "tokens/structural.json",
+      "bytes": 1042,
+      "sha256": "5441e71a2e1898f3f709781b6dffa7da50bdf60f71c97e703514750dbafd2224"
+    },
+    {
+      "path": "tokens/variables.json",
+      "bytes": 51193,
+      "sha256": "9c7fc743214a6bfc27d294e3fb91d7462ad1d06c43c5db5c234a857f1e86df0f"
+    }
+  ]
+}

package/tokens/README.md

@@ -0,0 +1,125 @@
+# Tokens
+
+Two layers live here:
+
+1. **`variables.json` + `structural.json` + `kit-accents.json` — the complete as-is resolution
+   crosswalk.** This is what an **AI / codegen tool uses today** to render product-faithful values.
+   `variables.json` = themed CSS `--vars`; `structural.json` = LESS `@vars` (spacing/sizing/radii/type);
+   `kit-accents.json` = the Ant 1.x LESS accents not in `variable.less` (e.g. the cyan `@primary-color`
+   `#099dd9` that paints radio dots / checkbox checks). Generated verbatim from the product source.
+   **`purpose-map.json`** sits alongside these — a **purpose → token** map (surface / text / border /
+   brand / status / severity / shadow + the structural scale) so an AI styling a **net-new** element picks
+   the right token by intent instead of hardcoding. Indexed from `components/index.json` → `tokens.purposeMap`.
+2. **`primitive` / `semantic.{light,dark}` / `component.json` — the DTCG token *model*** (a curated
+   slice) that the future Figma / Style-Dictionary pipeline is built on.
+
+## variables.json — the AI crosswalk (use this for product-faithful values)
+
+Every component registry's `tokensUsed` lists product **CSS custom-property names** (`--primary`,
+`--nav-panel-bg`, `--code-tag-background-color`, …). **`variables.json` resolves each one to its actual
+light + dark value**, with aliases (`var(--x)`) followed to a final value:
+
+```json
+"--primary":                   { "light": "#111c2c", "dark": "#e3e8f2", "lightRaw": "#111c2c", "darkRaw": "#e3e8f2" },
+"--code-tag-background-color":  { "light": "#ecf1f9", "dark": "#172336", "lightRaw": "var(--neutral-lightest)", "darkRaw": "var(--left-menu-hover-bg)" }
+```
+
+**How an AI uses it:** registry says a component uses `--primary` → look it up in `variables.json` →
+emit `var(--primary)` in code **and** know it renders `#111c2c` (light) / `#e3e8f2` (dark) for the
+mockup/Figma. `structural.json` does the same for the LESS `@vars` (spacing `@padding-md: 16px`, sizing
+`@input-height-base: 32px`, radius `@btn-radius: 4px`, type `@text-sm: 0.8rem`).
+
+**Coverage:** **336** themed CSS vars (306 with both light + dark, 25 light-only), 313 resolve to a
+colour value. Of the **57** distinct `--vars` referenced across all registries, **100% of the real ones
+resolve** (the only non-resolving entries are prose wildcards like `--severity-*` and two LESS `@vars`
+— `@btn-height` / `@btn-radius` — which live in `structural.json`).
+
+> ### ⚠️ `--primary` drift — resolved
+>
+> Older docs (`/.claude/rules/design-rules.md`, the DTCG `link` role below) describe `--primary` /
+> "brand" as **cyan `#099dd9`**. That is **wrong for the runtime CSS vars**: in `variable.less`,
+> `--primary` = **navy `#111c2c`** (light) / `#e3e8f2` (dark), and **no CSS custom property resolves to
+> `#099dd9` at all**. The cyan exists only as Ant Design's internal LESS `@primary-color` (affecting a
+> few Ant component internals) and the not-yet-wired DTCG `link` role. **For product-faithful output,
+> trust `variables.json` (navy).**
+
+## The DTCG token model (the future Figma / Style-Dictionary slice)
+
+> **Status: SLICE for sign-off.** These files contain a small, representative set
+> (brand/accent split, neutrals, two severity families, surfaces/text/border, a few
+> component tokens) to validate the *shape* before converting all ~322 tokens. Values
+> are extracted verbatim from `src/design/variable.less`.
+
+## Files (the 3 tiers)
+
+| File | Tier | Role |
+| --- | --- | --- |
+| `primitive.json` | 1 · Primitive | Raw values (`color.navy.900`, `space.300`). Never themed, never used directly. |
+| `semantic.light.json` | 2 · Semantic (light mode) | Roles referencing primitives. The **shared contract with Figma**. |
+| `semantic.dark.json` | 2 · Semantic (dark mode) | **Same keys**, dark references. This is what "modes" means. |
+| `component.json` | 3 · Component | Code-only; references semantic. Figma binds components to semantic, so this tier is **excluded** from the Figma export. |
+
+Naming follows [`../strategy/token-taxonomy.md`](../strategy/token-taxonomy.md):
+property-first (`color.background.brand.bold`), prominence ladder, severity as a role,
+`mds` namespace on output.
+
+## What gets generated (verified)
+
+Resolving the references produces these CSS custom properties (output prefixed `mds`).
+The values match `variable.less` exactly in both themes — i.e. **no visual change**
+when the app eventually consumes the generated file:
+
+```css
+/* LIGHT — :root */
+--mds-color-background-brand-bold: #07101f;   /* brand = primary action */
+--mds-color-text-default: #1d2a3e;
+--mds-color-text-subtle: #7186a8;
+--mds-color-text-inverse: #ffffff;            /* on brand/bold surfaces */
+--mds-color-link: #099dd9;                    /* interaction (cyan) */
+--mds-color-border-focused: #099dd9;
+--mds-color-text-accent-teal: #0d9488;        /* accent = decorative */
+--mds-color-text-severity-critical: #ec5b5b;  /* status */
+--mds-color-background-severity-critical-subtle: #fef5f5;
+--mds-color-border-default: #e3e8f2;
+
+/* DARK — [data-theme='dark-theme'] */
+--mds-color-background-brand-bold: #ffffff;
+--mds-color-text-default: #e3e8f2;
+--mds-color-text-inverse: #07101f;
+--mds-color-link: #099dd9;
+--mds-color-background-severity-critical-subtle: #310c0c;
+--mds-color-border-default: #1d2a3e;
+```
+
+Note the corrected color roles (decision D9, Atlassian-aligned): `brand` = primary
+action navy, `link`/`border.focused` = interactive cyan, `accent.*` = decorative
+hues (chart palette), `inverse` = text on bold surfaces, `severity.*` = status.
+
+Note how `color.background.severity.critical.subtle` is `#fef5f5` in light and
+`#310c0c` in dark — same token name, mode-swapped value. That single shared name is
+what guarantees code ↔ Figma fidelity.
+
+## Build pipeline (to wire next)
+
+```text
+tokens/*.json  ──►  Style Dictionary  ──►  ┌─ css/mds-tokens.css   (--mds-* vars, both themes)
+                                           ├─ tailwind/preset.js   (theme-safe utilities)
+                                           ├─ figma/tokens.json    (tiers 1–2 only → Tokens Studio)
+                                           └─ ai/tokens.json       (flat, documented → AI spec)
+```
+
+- **Style Dictionary** resolves the `{alias}` references and emits each target.
+- The two semantic files become **modes** (Figma) / themed blocks (CSS).
+- `component.json` is filtered OUT of the Figma export.
+
+## Conversion plan (rest of Phase 1)
+
+1. Sign off on this slice's shape.
+2. Expand `primitive.json` — full neutral ramp, all 13 severity families, chart hues,
+   spacing/type/radius/z-index scales.
+3. Expand `semantic.{light,dark}.json` — map every themed token in `variable.less` to a
+   property-first role; resolve all hardcodes/typos at the source.
+4. Expand `component.json` — buttons, inputs, grid, nav, tags, etc.
+5. Wire Style Dictionary; diff generated CSS against current rendered values (both
+   themes) to confirm zero visual regression.
+</content>

package/tokens/component.json

@@ -0,0 +1,34 @@
+{
+  "$description": "TIER 3 — COMPONENT. Code-only (Figma binds components to semantic, not these). References the SEMANTIC tier, never primitives. SLICE for sign-off.",
+  "$status": "FUTURE / portable DTCG token layer (mds-*). NOT yet wired to the running product or component tokensUsed — the LIVE product uses tokens/variables.json (--vars). Do not emit mds-* for live output.",
+  "button": {
+    "background": {
+      "primary": {
+        "$type": "color",
+        "$value": "{color.background.brand.bold}"
+      }
+    },
+    "text": {
+      "primary": {
+        "$type": "color",
+        "$value": "{color.text.inverse}"
+      }
+    }
+  },
+  "input": {
+    "border": {
+      "default": {
+        "$type": "color",
+        "$value": "{color.border.subtle}"
+      }
+    }
+  },
+  "grid": {
+    "background": {
+      "header": {
+        "$type": "color",
+        "$value": "{color.surface.raised}"
+      }
+    }
+  }
+}