@bongos/core 1.19.394 → 1.19.396

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.394",
-  "core_contract": "1.19.394",
-  "source_commit": "5a7626e4bdab0cb761ab691fee78c0f704138083",
+  "core_version": "1.19.396",
+  "core_contract": "1.19.396",
+  "source_commit": "b4632d6e8d92e8096e958762a36e810fc24c9c35",
   "source_ref": "HEAD",
-  "built_at": "2026-08-28T14:55:17.474Z",
+  "built_at": "2026-08-28T16:08:46.136Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 340,
-    "agent_docs_stubbed": 22,
-    "functional_verbatim": 1630,
+    "docs_redacted": 345,
+    "agent_docs_stubbed": 23,
+    "functional_verbatim": 1635,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1992,
-  "tree_sha256": "d5bea2a4ea5e68e17d91faefcba9aa4862fbe210a419b7022dde0b42831a9f41",
+  "file_count": 2003,
+  "tree_sha256": "950c8c43ac98c0e161e25a1c17cd699ad9582392105dcd0abadc8efc090a95c8",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -122,7 +122,12 @@
     {
       "path": ".claude/skills/design-sync/SKILL.md",
       "mode": "0000644",
-      "sha256": "9fe1d51e1bbf277bb197dcdc7f514971c390bbb33186454b2e2ccf318f5bd544"
+      "sha256": "7ef4539cc8f7a588cac1ab1c81a0bcd2403e1e3f5d67422e53a4973d057b55c7"
+    },
+    {
+      "path": ".claude/skills/design/SKILL.md",
+      "mode": "0000644",
+      "sha256": "83f2d423421bc08e7f460847616bc0cfba636cb24563566724776b2c7c1a1662"
     },
     {
       "path": ".claude/skills/dev/SKILL.md",
@@ -137,7 +142,7 @@
     {
       "path": ".claude/skills/figma-design-sync/SKILL.md",
       "mode": "0000644",
-      "sha256": "2f9d2b9c2d0377a582c71262462c08237f30b31d91ef748f40a188e4e7aadbf2"
+      "sha256": "f3abceebc2b098b61e9f0765bf0a515beaf340aa5138b23db1c59ba761a195cd"
     },
     {
       "path": ".claude/skills/fix-task/SKILL.md",
@@ -367,7 +372,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "e2924c48715177477a8f828e2118f832acad6b3f63ae7b4fe5f124e80a4e7c17"
+      "sha256": "88bfa3b136c58ce104a56cb2b7c922f11b55ae9e8ca0ec0d30d67bdb78ed70cf"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -387,12 +392,12 @@
     {
       "path": "config/design-tokens.neutral.json",
       "mode": "0000644",
-      "sha256": "386558d2c902f81b4b9a9cb74aa41b89e7195e5cba5ec043f96fc7beab899630"
+      "sha256": "50d0705a8e37af0bda238327ba0a09f96bcec3d8d1eb0e090ea5a2fb22d9f928"
     },
     {
       "path": "config/design-tokens.schema.json",
       "mode": "0000644",
-      "sha256": "f7030358eb36b01ebe252fd52dbd6bc5763e28aa169a6f84a373ce949182511b"
+      "sha256": "0e1d5d75d0c990b4092876650875330adaaf4b1086d2731c14374a1f5659a31c"
     },
     {
       "path": "config/government.neutral.json",
@@ -1479,25 +1484,30 @@
       "mode": "0000644",
       "sha256": "838197eef10523949529e6ca906a8b489e5a512df8915a48dc0edb15414a390e"
     },
+    {
+      "path": "docs/adr/0197-the-ui-design-module.md",
+      "mode": "0000644",
+      "sha256": "901dcd1ca9748e999ea0db27e213f76c7e38caf620fb6b17fc8d1cf9dbee5e9d"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "f8fb053b786e60f3213e0038c994f10492c87fa24ec89deeb8bea66182356285"
+      "sha256": "34f327bac4b238f5af2c47e2eb5298f20c9aac35c336dcab29c11396be992e48"
     },
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "3e488311a87f4db6ffbb85b26c7a61fba0204ff6cc1cc8ab6c09b2ae21cea24b"
+      "sha256": "567afe22acead45477a501c61b9aea2f6a99eac1cfa3cf87e143f7b5077567ca"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "6e93e2f283103158bc46062459b79b5528424ffb57f4730eb29a1cdba1b4976b"
+      "sha256": "e53b70240119fe856005a7627177d26bf559ab60fb003db5a7a31274fa432616"
     },
     {
       "path": "docs/architecture.md",
       "mode": "0000644",
-      "sha256": "92cbe2a55fff82a842e7ac3668c99d4eef05e922079d036a5984f607a64496ae"
+      "sha256": "68d30a764a36e963d40e4271010c56b61a824b9e2fad61599fdc62ee1bc2fddf"
     },
     {
       "path": "docs/branding-contract.md",
@@ -1517,17 +1527,12 @@
     {
       "path": "docs/copy-inventory.md",
       "mode": "0000644",
-      "sha256": "f69f8b883ec8bf7ecc3e5fbfb2fc8644af9c0c5263cc71e6d076ac76e151b7a0"
+      "sha256": "52655bf8c7a2c5860a1ce4486f1715769eba8b3e7162a4e43c78d582c935b7b0"
     },
     {
       "path": "docs/copy-registry.json",
       "mode": "0000644",
-      "sha256": "8061b7a220fddb82f5dabf4099cf8e6f16c39a59c56e2e1f7802825b6452e0fd"
-    },
-    {
-      "path": "docs/design-contract.md",
-      "mode": "0000644",
-      "sha256": "9623542a240479c3ecec12dd0c9050d4b79b2791a414bc2cd6b05d99530a9c44"
+      "sha256": "da37e58c70ef12e106d81be96072ee66ec52cb26ac4e624b18ca2455b90719d3"
     },
     {
       "path": "docs/design/apex-pass-2-direction.md",
@@ -1817,7 +1822,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "4da98da4c1d5bc5e2a1c1949775f362d8867faa5a2a0321ccd954dc0a5b71202"
+      "sha256": "3789594e075f2501de76ac637a3adcb383e3bc611f84f985ed9e385e5d5c8169"
     },
     {
       "path": "docs/handoff-template.md",
@@ -1827,7 +1832,7 @@
     {
       "path": "docs/modules-contract.md",
       "mode": "0000644",
-      "sha256": "60701a916fa001bfb160a46ef2f5d565384df2515f1cce097c5af39313d5d370"
+      "sha256": "1dddea16f7716cf500e329a73159d5f3a0548e4eed380148668b085712e985a7"
     },
     {
       "path": "docs/onboarding/browser-terminal-guide.md",
@@ -1892,7 +1897,7 @@
     {
       "path": "docs/onboarding/slash-commands.md",
       "mode": "0000644",
-      "sha256": "c9e898609ff1287f63dc1bb2edb6653711d396dcbd77c0e25a6a984425ff9476"
+      "sha256": "8e8d5c7d0843faa2dc550a640676a824c9be319c751cf1a1cb19eaebeb86b153"
     },
     {
       "path": "docs/project-context.template.md",
@@ -1922,7 +1927,7 @@
     {
       "path": "docs/recipes/claude-design-loop.md",
       "mode": "0000644",
-      "sha256": "389dbbbfb7c941315731d533e300b5d43f40a8aac866c5a1c74c32d5be212a22"
+      "sha256": "96e8774c29aa5444dd0035af55a24ded99894caff5f901a7dc1eac35e75f605d"
     },
     {
       "path": "docs/recipes/core-release-pipeline.md",
@@ -1947,7 +1952,7 @@
     {
       "path": "docs/recipes/figma-design-loop.md",
       "mode": "0000644",
-      "sha256": "6bfee82bddc07a5743316e310dda1e6cb7266fa7805fc1eed67bc8cc17980b46"
+      "sha256": "80fcc5cb6e10e6f55bf518604c64072e8a0848cf157dbc1f761519f14eab8399"
     },
     {
       "path": "docs/recipes/gds-db-backup.md",
@@ -3907,17 +3912,17 @@
     {
       "path": "modules/hall-ui/public/my-projects.css",
       "mode": "0000644",
-      "sha256": "5c702a9c2054287a8523b6901cd46e7caa1cb9580b7e8f04a3898b2c8bd82fd0"
+      "sha256": "443e24fc3e403cfc97c36a8f81fe81a540be84cbe52b6af86a1476fb87bc44b6"
     },
     {
       "path": "modules/hall-ui/public/my-projects.html",
       "mode": "0000644",
-      "sha256": "49c63ef48e0fc6450ba15d76743c8220b5d5f27702843be71fa077551d92c35b"
+      "sha256": "764221e2425c7430e83469fc865198e1020bcc8c5950aae6c3c1cecb49132721"
     },
     {
       "path": "modules/hall-ui/public/my-projects.js",
       "mode": "0000644",
-      "sha256": "25195cabf71890f93f065e2aa15e899d51c251807e59ba14a147150c5b6228a3"
+      "sha256": "e664a08787727fcd7019fe3008e3b9d63d07b9ab8be5043a46d3fcac5218f261"
     },
     {
       "path": "modules/hall-ui/public/not-ready.html",
@@ -4732,7 +4737,7 @@
     {
       "path": "modules/platform-identity/routes/my-projects.js",
       "mode": "0000644",
-      "sha256": "4fadf91c0d40f3e5dd5d53f9ebe3ec825fd16a13aab41a76e8af25c911e11edf"
+      "sha256": "fc948963cef6f7ef71b488cc5627310b6b217f3f62e13030b4da42a08e92796c"
     },
     {
       "path": "modules/platform-identity/routes/profile.js",
@@ -5149,15 +5154,70 @@
       "mode": "0000644",
       "sha256": "75a40d70207669ab57b0be05e4b6be70a2936cb9febf333b0a34224a80047e7e"
     },
+    {
+      "path": "modules/ui-design/CLAUDE.md",
+      "mode": "0000644",
+      "sha256": "7cb9dac9cb87b679e1ae50e4112b3a7928a38ebb9902c8947a74d17bec4d9009"
+    },
+    {
+      "path": "modules/ui-design/adapters/claude-design/index.js",
+      "mode": "0000644",
+      "sha256": "3794d5b8736824033a916c77661caf995385334047f3167d29aa3e0aa32b5bed"
+    },
+    {
+      "path": "modules/ui-design/adapters/figma/index.js",
+      "mode": "0000644",
+      "sha256": "859a23a1a10fe74717b37a4c86962750b7fd6d13b56ed801f6e217a245fea956"
+    },
+    {
+      "path": "modules/ui-design/docs/design-contract.md",
+      "mode": "0000644",
+      "sha256": "2095ddb991fa02e6800b4f92e5536e82512af6abb9e791596365a87c541a0530"
+    },
+    {
+      "path": "modules/ui-design/kit/README.md",
+      "mode": "0000644",
+      "sha256": "70f65052951335b63def03590ee971e2f482d6db08365484b532e4bc3c676495"
+    },
+    {
+      "path": "modules/ui-design/module.json",
+      "mode": "0000644",
+      "sha256": "1dedeb68927743a51b048b7d3f70ea939958fcfe3831b22c4120d53d78beb2f8"
+    },
+    {
+      "path": "modules/ui-design/scripts/design-sync.js",
+      "mode": "0000644",
+      "sha256": "c9376b96f9f963425f2cb2552b5b7b2e4d8264e3f4dac27c7e0410f95dfc3e7a"
+    },
+    {
+      "path": "modules/ui-design/scripts/figma-design-sync.js",
+      "mode": "0000644",
+      "sha256": "ce7c64e5068be597e9676e184fc1f411b4a4661a00b4f1df11ea8bb511fb8347"
+    },
+    {
+      "path": "modules/ui-design/scripts/validate-design.js",
+      "mode": "0000644",
+      "sha256": "c9d90b5ffb6e3895c8e98cefbdc89ff4fdd52a22a1073d8fe956a487c4b7816d"
+    },
+    {
+      "path": "modules/ui-design/skills/README.md",
+      "mode": "0000644",
+      "sha256": "709a99b3879eec15552c7ce18291fad5a4922d477955982eb51b718577ee7948"
+    },
+    {
+      "path": "modules/ui-design/styles/README.md",
+      "mode": "0000644",
+      "sha256": "5f98022a5edc4c1b405823cbf8ba8da745f60c3d47a7cb59eba537edf9bf29be"
+    },
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "279c305e827a45c35dc16e1b7194ae6d7983df5f6389b40432bba28e94e46f82"
+      "sha256": "7dd6552859e62daf201d9fdd1c17f95ea4a97bac3e5dc95d175ed0c8bbac88c7"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "633d0c823d2f0d515bf004a4ab75ce7e8578fa292ab16c3dcbe0597627bfae53"
+      "sha256": "292bfaf5419d894c03339b6363173872ba73e896a9dceec60ff625568fe9ed60"
     },
     {
       "path": "public-docs/index.html",
@@ -5797,7 +5857,7 @@
     {
       "path": "scripts/gds/copy-inventory.js",
       "mode": "0000644",
-      "sha256": "24e875eaace524598d18b5bf4a931700296f580404b79166da1e7c1d2d906de3"
+      "sha256": "40d3f8bb29ccc13e12fd79de5f79b25eb9d7df5d0500b887c965199187f4ab8b"
     },
     {
       "path": "scripts/gds/coreB-carve-proof.sh",
@@ -5837,7 +5897,7 @@
     {
       "path": "scripts/gds/design-sync.js",
       "mode": "0000644",
-      "sha256": "a10293363019251a22051af207aa9ece83f9384942f7ae09065072aa77e57570"
+      "sha256": "06901aa9fa0fcf89e0710f8f35274bc589f4711024e88350a981a453d5937f96"
     },
     {
       "path": "scripts/gds/dev-lib.js",
@@ -5877,7 +5937,7 @@
     {
       "path": "scripts/gds/doc-cli-guard.js",
       "mode": "0000644",
-      "sha256": "9cf6c8ead8129799d17a18eadedf0423828cb457fa07fd317dcf2853254861e9"
+      "sha256": "de19e1ffe48ffb9ad942828dafe858a7d88a9269fa812474be5018b263772a3e"
     },
     {
       "path": "scripts/gds/doc-comment-coverage.js",
@@ -5912,12 +5972,12 @@
     {
       "path": "scripts/gds/figma-design-sync.js",
       "mode": "0000644",
-      "sha256": "7a7721155c8c7cb169a48e6f279e5d7c0ba0dc4462678a4a2ec41a2686501962"
+      "sha256": "b8b1a7ed1d8dd217b24757a3ec9f4b3aa58b26a3e2a7b2cef9de217792e5ea43"
     },
     {
       "path": "scripts/gds/fitness-checks-identity.js",
       "mode": "0000644",
-      "sha256": "f87265779d60ae2d642e370f7af2d1d70fa6a1354a7389835d887b0dfe3c5dfc"
+      "sha256": "142b37957cd6205da618001d8a14d45979a8d81107ce60791302b008df276555"
     },
     {
       "path": "scripts/gds/fitness-checks-vocabulary.js",
@@ -6287,7 +6347,7 @@
     {
       "path": "scripts/gds/publish-manifest.js",
       "mode": "0000644",
-      "sha256": "12b3b200c1f60cc8a287d9a3ca2dd28201fda3cc219e83dffb60913c084e0413"
+      "sha256": "6d97163d0d8019642105d0eef8b8e017ec6763679255053969a8f8db020773a8"
     },
     {
       "path": "scripts/gds/pulse.js",
@@ -6742,7 +6802,7 @@
     {
       "path": "scripts/gds/validate-design.js",
       "mode": "0000644",
-      "sha256": "3d417b8510d58afec754d2a4dd62d5029dbc41140868ff74f633e56ef06f90d6"
+      "sha256": "49e169d297e73fd32f27bc2af746a47c04a107abc39ae720122aa80f1ab1dff1"
     },
     {
       "path": "scripts/gds/version-close.js",
@@ -6972,7 +7032,7 @@
     {
       "path": "src/bongos/module-scope-map.js",
       "mode": "0000644",
-      "sha256": "c3b5499005ae5150d1e3288437dbfd422e28068a28e3c5783a8c4b3fa2edd09c"
+      "sha256": "77dd62d640862624066bfcd2845c6ed2801091ce49ed676a809da3cce5077761"
     },
     {
       "path": "src/bongos/module-submissions.js",
@@ -7147,7 +7207,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "2d79f048ed86a766da3d79abb3e0504e835c986982884dce1f34335a04fa1a72"
+      "sha256": "711a3add8803459721523364c9c993e30908475bebdf65eb83789f5520e91104"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7189,16 +7249,6 @@
       "mode": "0000644",
       "sha256": "a012619e42522c8b38ffdaf00cfe8d89a9438fc0cea00752474ab22f13d3f722"
     },
-    {
-      "path": "src/ui/adapters/claude-design/index.js",
-      "mode": "0000644",
-      "sha256": "69ec9f8c405987a67570aca7375e8b29951898775cdb56fa7bc68a74dfcfd10b"
-    },
-    {
-      "path": "src/ui/adapters/figma/index.js",
-      "mode": "0000644",
-      "sha256": "4331ee8d20ad98faac520cd42bcee2614820e15d1b1691ad3cee4584bbab9fb7"
-    },
     {
       "path": "tests/abandon_task.mjs",
       "mode": "0000644",
@@ -7837,7 +7887,7 @@
     {
       "path": "tests/design_tokens_sync.mjs",
       "mode": "0000644",
-      "sha256": "9dcbd0bc8f34f98ec0b0ff63a629780928c9d60199f3d961733e03ab6a7bb4fa"
+      "sha256": "0454ee692bbbf19d02c7f19c029f4da5a4dd939b84c4d67ebb713d12de179c2a"
     },
     {
       "path": "tests/dev_lib.mjs",
@@ -7967,7 +8017,7 @@
     {
       "path": "tests/doc_cli_guard.mjs",
       "mode": "0000644",
-      "sha256": "4e68c67489daa51167b8d738a36f7c0187016b342e8a57731d14241563262878"
+      "sha256": "3c7567070ad3ce59fdfef9d57da39d62cf1e7c745bfeefd432c1b96c247b42ec"
     },
     {
       "path": "tests/doc_comment_coverage.mjs",
@@ -8012,7 +8062,7 @@
     {
       "path": "tests/figma_adapter.mjs",
       "mode": "0000644",
-      "sha256": "73a9099549d21f33f1bc88a30991aacef129e2c9a567aaaaf5bd51117a19541c"
+      "sha256": "73bb1d6cbbf6301a8aa92e9cb4fd4b7fe222cf3bb77d01778cbc5438fa549512"
     },
     {
       "path": "tests/file_map.mjs",
@@ -8694,6 +8744,11 @@
       "mode": "0000644",
       "sha256": "d00e82184fbf7aab49c9b6efe5709b14f300ca0cea277a0eb140f073ded7ff50"
     },
+    {
+      "path": "tests/join_application_note.mjs",
+      "mode": "0000644",
+      "sha256": "6db72752d69ebdfcc82bdf4f0e2445d7c8a939f6b4b88c1915c9f1d2f8eb9d76"
+    },
     {
       "path": "tests/join_relay_outcome.mjs",
       "mode": "0000644",
@@ -8927,7 +8982,7 @@
     {
       "path": "tests/module_loader.mjs",
       "mode": "0000644",
-      "sha256": "c768beda710cc8446023d95cf5736cb70364403ed6412c41eef7c3c5039c1604"
+      "sha256": "157fbb9db4830c87654edf6c6548fba2e535830c0c832bbdf0fd199019d6219f"
     },
     {
       "path": "tests/module_manifest.mjs",

package/.claude/skills/design/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: design
+description: The UI design session — the operating playbook for ui-discipline work (layouts, pages, components, design systems, the hall / status / landing surfaces) on ANY Cloud Bongos instance. Triggers when the user says "/design", "design this page", "let's work on the UI", "make this look right", "start a design session", or when a claimed task's discipline routes here (claim.js prints a directive to invoke /design for ui tasks). Show-first like /paint — the interface is judged by looking at it — and world-first: the instance's branding pack + DESIGN.md are read before any taste rule applies. Shipped by the ui-design module (ADR 0197).
+---
+
+You are running a **UI design session**. Two things make it different from `/dev`: the work is judged **by looking at it** (so every step ends in a rendered screen, not a paragraph), and it is done **inside a world that is not yours** — the instance's, which you read first and never override. The `ui-design` module's [CLAUDE.md](../../../modules/ui-design/CLAUDE.md) is the reference; this file is the loop.
+
+## Step 0 — detect the mode
+
+- **Interactive** (someone is here to look and react): show, let them steer, iterate. One or two lines per step, then a screen.
+- **Autonomous** (no one will look): build inside the contract, prove it in both modes, stage or park the screens for review, and **never ship an interface change blind** — a task that cannot be verified visually gets a release with a reason, not a guess.
+
+## Step 1 — load the world before you draw anything
+
+Read, in this order, and quote nothing from memory:
+
+1. `config/branding.json` over `config/branding.neutral.json` — `theme.ui` is **the fifteen tokens** (thirteen colours + two font stacks): the only palette a platform surface may rely on.
+2. `config/design-tokens.json` over `config/design-tokens.neutral.json` — the `--dt-*` tokens an adapter emits; `config/design-sources.json` — which tool authors each surface.
+3. **`DESIGN.md` at the repo root** — the instance's world: palette + derived tiers, faces, materials, motion grammar, components, do's and don'ts, accessibility floors. If it names a rule, it wins over your taste.
+4. The surface's own sheet and the nested `CLAUDE.md` of the directory you're in; `/recall <surface>` for what was already decided.
+
+**No `DESIGN.md`?** Then the neutral pack *is* the world and the platform floors below are the whole rulebook. Say so in your notes and build to them. Do not invent a palette.
+
+## Step 2 — look before you ship
+
+Render the real surface before and after — never reason about layout from source alone:
+
+- Stage it (`/builder-stage` on a box; a local stub + Playwright on a laptop — the kit under `modules/ui-design/kit/` ports the apex probes once [task 1003320](https://cloudbongos.com/builders#/task/1003320) lands) and screenshot **three widths (≥1280 / ~900 / ≤480) × two modes (light / dark)** at minimum.
+- Show the screens, then caption them in one line. The person you're working with judges the picture.
+- Grep the receiving page for class collisions before porting a component across pages (the landing's content sections are `.band`; the menu is `.menuBand`).
+
+## Step 3 — build inside the contract (the platform floors)
+
+These hold on every instance; a `DESIGN.md` may tighten them, never loosen them:
+
+- **The Fifteen Rule** — every colour is a `var()` or a `color-mix()` of the fifteen; the only legal literal is pure black or white with alpha as a scrim, mask or halo.
+- **The dark twins** — every dark rule written twice, byte-identical: `:root[data-mode="dark"]` and `@media (prefers-color-scheme: dark) { :root:not([data-mode="light"]) }`.
+- **No page `:root`** — the pack's `:root` is spliced at the end of `<head>`; page tokens live on `body`.
+- **The 24px floor** — every control clears 24px on both sides; primary pills 46–48px.
+- **AA in both modes** — 4.5:1 body text, 3:1 large text and non-text, light *and* dark, measured from the real stylesheet.
+- **The Kill Switch** — `prefers-reduced-motion: reduce` at the foot of the token layer kills every animation and transition; no motion in JavaScript; the rest frame is a complete composition.
+
+Generated code uses the `--dt-*` variables; adapters write only `src/ui/<surface>/`, `assets/ui/<surface>/` and `config/design-sources.json`.
+
+## Step 4 — prove it, then ship the tests with the UI
+
+- `node scripts/gds/validate-design.js --strict` after touching adapters, tokens or `design-sources.json` (fitness runs it on every PR).
+- **New interactive code gets a pin in the page's own test file in the same diff** — the grader's Quality worker fails a chrome change that arrives with no test. Contrast pairs are measured in CI, not eyeballed.
+- The task's DONE WHEN is read literally — "both pages" means both pages. Deliberate deviations from a mock stay minor if the ship notes say why.
+- `/builder-ship` with real `--notes` (what changed, which screens you looked at, in which modes) and a plain-language `--summary`.
+
+## Round-tripping with a design tool
+
+- **Claude Design** (`/design-sync`): export the tokens + surfaces in, land the generated code back under the claimed task. Design is code; it merges like code.
+- **Figma** (`/figma-design-sync`): push the current state so a designer never opens a stale file; land their edit back as committed code. Canvas art that won't translate becomes an asset, never forced into code.
+- Both are adapters against `modules/ui-design/docs/design-contract.md`; a third tool is a third adapter, not a new integration.
+
+## Stay clear of
+
+- The pack's neutral values and `DESIGN.md`'s named rules — changing the world is the owner's decision and an ADR, not a session's taste.
+- A page-private palette, a hex that isn't one of the fifteen, a `:root` in a page, motion in JavaScript.
+- Text: the copy half belongs to `copy-desk` — flag a string, don't rewrite the product's voice in passing.
+- Image generation for anything but text-free hero plates (the owner's rule); UI is rebuilt from templates and the instance's world, not painted.
+
+## How sessions reach this skill
+
+- **Standalone:** invoke `/design` to have the loop in front of you.
+- **From a claim:** a `ui`-discipline task makes `claim.js` print the `/design` directive from `scripts/gds/discipline-modes.json` — one carrier, one lookup, the same map `/dev`, `/paint` and `/ideate` ride.

package/.claude/skills/design-sync/SKILL.md

@@ -7,7 +7,7 @@ You are helping the builder run the Claude Design sync loop: export the repo's d
 
 ## What this skill does
 
-1. **Import** — `node scripts/gds/design-sync.js` builds a token-preview bundle (HTML color/typography/spacing/radii cards, `tokens.css`, `tokens.json`, `surfaces.json`) in a temp directory and prints a JSON manifest.
+1. **Import** — `node scripts/gds/design-sync.js` (a thin shim over `modules/ui-design/scripts/design-sync.js`, the module home — ADR 0197) builds a token-preview bundle (HTML color/typography/spacing/radii cards, `tokens.css`, `tokens.json`, `surfaces.json`) in a temp directory and prints a JSON manifest.
 2. **Push** — the DesignSync MCP tool (`list_projects` → `finalize_plan` → `write_files`) uploads the bundle to a Claude Design project.
 3. **Export (handoff)** — when Claude Design generates UI code, the handoff lands it under a claimed Bongos task via `adapter.export()`.
 
@@ -41,7 +41,7 @@ HTML files with `<!-- @dsCard group="Tokens" -->` appear as Design System cards
 When Claude Design finishes and hands off to Claude Code, call the adapter directly in Node:
 
 ```js
-const adapter = require('./src/ui/adapters/claude-design/index.js');
+const adapter = require('./modules/ui-design/adapters/claude-design/index.js');
 await adapter.export({
   repoRoot: process.cwd(),
   surfaceId: '<surface-id>',       // e.g. "hall-ui"

package/.claude/skills/figma-design-sync/SKILL.md

@@ -7,7 +7,7 @@ You are helping the builder run the Figma round-trip loop for the `ui` disciplin
 
 ## What this skill does
 
-1. **Import (push)** — `node scripts/gds/figma-design-sync.js` builds a push plan (`figma-plan.json`: color-swatch frame, typography-specimen frame, one reference frame per surface) in a temp directory and prints a JSON manifest.
+1. **Import (push)** — `node scripts/gds/figma-design-sync.js` (a thin shim over `modules/ui-design/scripts/figma-design-sync.js`, the module home — ADR 0197) builds a push plan (`figma-plan.json`: color-swatch frame, typography-specimen frame, one reference frame per surface) in a temp directory and prints a JSON manifest.
 2. **Push** — the live Figma MCP tool (`mcp__figma__*` write capability, or `use_figma`) creates/updates the frames described in the plan inside the target Figma file. If write capability isn't available in this session, stop and surface the gap — do not fake the push.
 3. **Export (handoff)** — when a designer finishes a Figma edit, hand its output to `adapter.export()`.
 
@@ -34,7 +34,7 @@ Figma hands back one of two shapes, depending on whether Code Connect is wired f
 
 **Code Connect output (ready code — the common case):**
 ```js
-const adapter = require('./src/ui/adapters/figma/index.js');
+const adapter = require('./modules/ui-design/adapters/figma/index.js');
 await adapter.export({
   repoRoot: process.cwd(),
   surfaceId: '<surface-id>',
@@ -61,7 +61,7 @@ Round-trip fidelity is limited to what Code Connect or the Figma MCP can extract
 
 ## Code-canonical vs. Figma-canonical
 
-Code-canonical is the default: the repo is authoritative, Figma is a synced view. A surface may be flagged `"figmaCanonical": true` in `config/design-sources.json` as an explicit exception (docs/design-contract.md §3.4) — only do this when the builder explicitly asks for a surface a designer actively iterates on in Figma.
+Code-canonical is the default: the repo is authoritative, Figma is a synced view. A surface may be flagged `"figmaCanonical": true` in `config/design-sources.json` as an explicit exception (modules/ui-design/docs/design-contract.md §3.4) — only do this when the builder explicitly asks for a surface a designer actively iterates on in Figma.
 
 ## Path safety
 

package/clients/bongos-client/index.d.ts

@@ -292,7 +292,7 @@ export interface PostModulesKeySubmitResponse { ok: boolean; submission: unknown
 export interface PostMyProjectsClientIdLeaveResponse { ok: boolean; left: unknown }
 export interface PostMyProjectsInvitesClientIdAcceptResponse { ok: boolean; accepted: boolean }
 export interface PostMyProjectsInvitesClientIdDeclineResponse { ok: boolean; accepted: boolean }
-export interface PostMyProjectsJoinRequest { origin: string }
+export interface PostMyProjectsJoinRequest { origin: string; note?: string }
 export interface PostMyProjectsJoinResponse { ok: boolean; status: unknown; project: unknown; message: unknown }
 export interface PostOverrideRequestsIdDecideRequest { decision: string; note?: string }
 export interface PostProjectsInviteRequest { client_id: string; github_login: string }

package/config/design-tokens.neutral.json

@@ -1,5 +1,5 @@
 {
-  "_note": "Cloud Bongos neutral design tokens — the baseline every instance resolves over. To override, copy values into config/design-tokens.json (the instance pack). These match config/branding.neutral.json theme.ui (the chrome world, task 1003298; tests/design_tokens_sync.mjs fails on drift) so a vanilla instance with no instance pack still renders correctly. The world's derived tokens, materials and motion grammar are recorded in DESIGN.md. See docs/design-contract.md.",
+  "_note": "Cloud Bongos neutral design tokens — the baseline every instance resolves over. To override, copy values into config/design-tokens.json (the instance pack). These match config/branding.neutral.json theme.ui (the chrome world, task 1003298; tests/design_tokens_sync.mjs fails on drift) so a vanilla instance with no instance pack still renders correctly. The world's derived tokens, materials and motion grammar are recorded in DESIGN.md. See modules/ui-design/docs/design-contract.md.",
   "colors": {
     "bg": "#edecee",
     "bgCard": "#fbfafc",

package/config/design-tokens.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "cloud-bongos/design-tokens",
   "title": "Cloud Bongos design tokens",
-  "description": "Canonical design-token schema for a Cloud Bongos instance. Extends config/branding.json theme.ui. Validated by scripts/gds/validate-design.js. See docs/design-contract.md.",
+  "description": "Canonical design-token schema for a Cloud Bongos instance. Extends config/branding.json theme.ui. Validated by modules/ui-design/scripts/validate-design.js (node scripts/gds/validate-design.js is its shim). See modules/ui-design/docs/design-contract.md.",
   "type": "object",
   "required": ["colors", "fonts"],
   "additionalProperties": false,

package/docs/adr/0197-the-ui-design-module.md

@@ -0,0 +1,52 @@
+# ADR 0197 — The ui-design module: design is a platform capability; the instance owns its world
+
+- **Status:** accepted
+- **Date:** 2026-08-28
+- **Task:** [task 1003324](https://cloudbongos.com/builders#/task/1003324) (goal 1000080 — Apex UI pass 2; the first of five tasks scoped with the owner on 2026-08-28: 1003320 the kit, 1003321 the skills, 1003322 the apex carve, 1003323 the style library)
+- **Relates to:** [ADR 0081](<redacted>.md) (the tool-agnostic design layer this module absorbs), [ADR 0083](<redacted>.md) (the module system + the one-way rule), [ADR 0062 §7](<redacted>.md) (the core ↔ host split), [ADR 0108 §1](<redacted>.md) (host content vs the core package), [ADR 0196](<redacted>.md) (the chrome world as the token contract), ADR 0178 (the copy half), `modules/ui-design/CLAUDE.md`
+
+## Context
+
+ADR 0081 made the repo the source of truth for design and put its layer in core: two adapters under `src/ui/adapters/`, three CLIs under `scripts/gds/`, the contract at `docs/design-contract.md`, the tokens under `config/`. It shipped as *Cloud Bongos's* design machinery — and the whole-frontend pass under goal 1000080 (tasks 1003296–1003300) then built Cloud Bongos's own world on top of it: the chrome world, the fifteen-token contract, `DESIGN.md`, the probes and renderers that made "look before you ship" real, the vetted taste skills the sessions leaned on.
+
+On 2026-08-28 the owner reframed what that work is. It is **not Cloud Bongos's front door**. It is a **platform capability**: every builder on every instance should be able to create and design good-looking, functional UIs *in line with that instance's world* — its palette, its faces, its materials — and build on them. Cloud Bongos's front door is the first customer of that capability, not its owner. The three things a builder needs (the contract and its tooling; a way to look before shipping; the taste and the looks) were scattered across core, session scratchpads and personal skill installs, with no home, no manifest and no line between "this is the platform's rule" and "this is Cloud Bongos's taste".
+
+Two facts shaped the shape of the module:
+
+1. **The core ↔ host split already had a name for this** (ADR 0062 §7): the core ships method, the instance ships identity. `config/design-tokens.*`, `config/design-sources.json` and `DESIGN.md` are identity; the adapters, the validator, the playbook and the floors are method.
+2. **The module contract is the platform's unit of capability** (ADR 0083): a self-contained directory the loader discovers, that contributes what it ships and reaches core only through the doorway. grading, economy, memory are default-on because every instance grades, pays and remembers. Every instance has a face.
+
+## Decision
+
+1. **`modules/ui-design/` is a default-on core-domain module** that ships METHOD and never a world. It joins the default-on roster beside grading / economy / memory (`default: true`, `maintenance: core-maintained`) and is allowlisted in `publish-manifest.js`, so a released core carries it.
+
+2. **ADR 0081's layer moves in; the host boundary stays out.** `src/ui/adapters/{claude-design,figma}` → `modules/ui-design/adapters/`; `scripts/gds/{design-sync,figma-design-sync,validate-design}.js` → `modules/ui-design/scripts/`; `docs/design-contract.md` → `modules/ui-design/docs/`. `config/design-tokens.neutral.json`, `config/design-tokens.schema.json` and `config/design-sources.json` **stay in `config/`**: they are the branding contract the module reads and never owns. `DESIGN.md` stays at the repo root: it is the instance's world. `src/ui/` is gone from the core tree — the contract's `src/ui/<surface>/` layout is what an adapter *targets* on an instance, not core code.
+
+3. **Declaration-only.** The manifest contributes three skills (`design`, `design-sync`, `figma-design-sync`) and nothing else — no routes, pollers, web surfaces, migrations or ports (the `character-anim` shape). Consequences that matter: `GET /modules` lists it; `claude-materialize` skips its skills on an instance that disables it; disabling it withdraws the skills and touches no served surface, which is the DONE WHEN's "can be disabled without breaking anything" in structural form. It contributes **no `ui` discipline yet**: `enabledDisciplines()` feeds the hall settings page and newcomer-restock, neither of which knows `ui`; `discipline-modes.json` already routes a `ui` task to `/design`, so the playbook works today and offering the discipline on sign-up is a follow-up.
+
+4. **The `/design` playbook exists.** `discipline-modes.json` has pointed `ui` tasks at a `/design` skill since task 1267; the skill was never written, so a claimed `ui` task told the builder to open a door that wasn't there. It is written now, in the `/paint` shape (show-first) with a world-first Step 1: read the instance's pack + `DESIGN.md`, and where an instance has none, the neutral pack + the floors are the whole rulebook — no page invents a palette.
+
+5. **The module's `CLAUDE.md` draws the line between the platform's floors and the instance's world.** Floors — held on every instance, tightenable by a `DESIGN.md`, never loosenable — are the Fifteen Rule (thirteen colours + two font stacks are the only host-overridable surface), the dark twins (every dark rule written twice at (0,2,0)), no page `:root`, the 24px control floor, AA in both modes measured from the real stylesheet, and the Kill Switch (`prefers-reduced-motion` kills everything; no motion in JavaScript). The instance's world is everything those floors leave open: the palette, the faces, the materials, the motion grammar, the taste bans. This is the same split as ADR 0062 §7, written for design.
+
+6. **The CLIs keep thin `scripts/gds/` shims** rather than every caller re-pointing at the module. Three reasons, all mechanical: `node scripts/gds/<x>.js` is the invocation form `claude-materialize` rewrites to `bongos exec scripts/gds/<x>.js` for a packaged core (a module path would not be rewritten and would not resolve at an instance root); `doc-cli-guard` (Check 22) resolves documented flags against `scripts/gds/` sources, so the shims carry the usage lines; and every carved domain before this one kept its commands under `scripts/gds/` (memory, ideas, sessions — "a command travels with its domain but stays under scripts/"). The module file is the implementation and the DONE WHEN's `node modules/ui-design/scripts/validate-design.js` runs it directly; the shim is a `require()` and nothing else. Inside the module the CLIs resolve the repo root by walking up from `__dirname` instead of the computed `require(path.resolve(…, 'src', 'instance-config'))` they carried before — a reach into core that the static boundary scanner could not see and that a module may not make (ADR 0083); the instance root *is* the repo root today (ADR 0108 §1), and when the core installs as a package the root arrives through the doorway.
+
+7. **Three reserved homes, each named for the task that fills it:** `kit/` (task 1003320 — the stub, the renderer/auditor, the probes, the mock checker), `skills/` (task 1003321 — the vendored UI skills with provenance sidecars, a licence allowlist and the PLATFORM PREAMBLE; **the vendoring policy is that task's ADR**, this one only points at it), `styles/` (task 1003323 — looks as branding packs). A README in each so the home is visible in git and a builder landing there knows what belongs.
+
+8. **The front door keeps its own key.** `public-landing` stays a separate module key (and carves to `modules/public-landing/` in task 1003322), because a customer of a capability is not part of it: a second instance's landing must be able to use `ui-design` without inheriting Cloud Bongos's page. The module's scope-map key covers its own dir, the three shims, its contributed skill dirs and the two recipes; none of those paths is protected, so a goal scoped to `ui-design` needs Metic, not Archon.
+
+## Consequences
+
+- **A builder on any instance gets the same entry.** `modules/ui-design/CLAUDE.md` is the door: what the module gives, how the world is resolved, which rules are the platform's and which are the instance's. The next three tasks fill the kit, the skills and the styles into homes that already exist and already have a manifest.
+- **The one-way rule holds for the design layer for the first time.** The adapters and CLIs reach nothing in core; `<redacted>` guards them from now on. The core-side callers (the shims, `checkDesignContract`) live under `scripts/`, outside the kernel boundary.
+- **knip loses sight of the moved files** — its `project` set covers `src/**` and `scripts/**`, not `modules/ui-design/**`. Accepted: the `knip_issue_count` ratchet is shrink-only and a module's files are exercised by its tests and by fitness, not by knip's reachability graph. Extending knip to module trees is a devsecops decision, not this carve's.
+- **`copy-inventory.js`'s recorded mismatch changes wording, not meaning:** `src/ui/` no longer holds "only `adapters/`" — it no longer exists in the core tree. The registry note says so, and regenerates.
+- **Nothing an instance serves changed.** The move is byte-identical in behaviour: same adapters, same CLIs, same validator, same contract text with its paths updated. `validate-design` runs green from the new home on a fresh clone.
+
+## Rejected alternatives
+
+- **Leave the layer in core and put only the kit/skills/styles in a module.** Splits one capability across two homes with two rulebooks — the exact scatter the owner asked to end. The contract and its adapters are the method; they go where the method lives.
+- **Move `config/design-tokens.*` and `design-sources.json` into the module.** Makes the instance's world module-owned and module-versioned: re-theming an instance would mean editing the core package. The host boundary is the point of ADR 0062 §7; the tokens stay in `config/`.
+- **Put the front door in the module (`ui-design` owns `public-landing/`).** A capability that ships its first customer's page cannot be reused by a second customer without inheriting the first's world. First customer, not owner.
+- **Module-hosted CLIs with no shims.** Breaks `claude-materialize`'s rewrite on a packaged core and every documented invocation at once, for no boundary benefit — a shim is a `require()`.
+- **Contribute the `ui` discipline now.** Surfaces it on sign-up before the hall settings page and newcomer-restock know it; a discipline that the restock cannot stock is a newcomer with no chore. Follow-up, once those readers are taught.
+- **A `--dt-*`-only contract with no `DESIGN.md` resolution.** Tokens say *what the colours are*; they cannot say *what the world is* (materials, motion, taste bans). The floors/world split needs the prose file as much as the pack.