feat(showcase): consume the shared design tokens in the preview generator

.github/workflows/design-tokens.yml

@@ -0,0 +1,67 @@
+name: Design Tokens
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'packages/tokens/**'
+      - 'docs/BRAND.md'
+      - '.github/workflows/design-tokens.yml'
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - 'packages/tokens/**'
+      - 'docs/BRAND.md'
+      - '.github/workflows/design-tokens.yml'
+
+concurrency:
+  group: design-tokens-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tokens:
+    name: Build and verify tokens
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+
+      # docs/BRAND.md is the source of truth; this fails when tokens.json has
+      # drifted from it, which is the drift a generated-and-ignored dist/ cannot
+      # catch on its own.
+      - name: Verify tokens match docs/BRAND.md
+        working-directory: ./packages/tokens
+        run: node build.js --check
+
+      - name: Build
+        working-directory: ./packages/tokens
+        run: node build.js
+
+      - name: Confirm the built outputs load
+        working-directory: ./packages/tokens
+        run: |
+          test -s dist/tokens.css
+          node --input-type=module -e "
+            import { light, dark, tokens, theme, version } from './dist/tokens.js';
+            const names = Object.keys(light);
+            if (names.length === 0) throw new Error('no tokens exported');
+            for (const mode of ['light', 'dark']) {
+              const missing = names.filter((n) => tokens[mode][n] === undefined);
+              if (missing.length) throw new Error(\`\${mode} is missing: \${missing.join(', ')}\`);
+            }
+            if (theme('dark') !== dark) throw new Error('theme(\"dark\") did not resolve');
+            console.log(\`ok: v\${version}, \${names.length} tokens in both modes\`);
+          "
+
+      - name: Confirm dist/ is not tracked
+        run: |
+          if git ls-files --error-unmatch packages/tokens/dist >/dev/null 2>&1; then
+            echo "packages/tokens/dist is generated and must not be committed."
+            exit 1
+          fi
+          echo "dist/ is untracked, as expected."

README.md

@@ -329,4 +329,5 @@ stellar contract build
 - [docs/PRIVACY_MODEL.md](docs/PRIVACY_MODEL.md) — ZK proof tiers
 - [docs/ACCOUNT_KERNEL.md](docs/ACCOUNT_KERNEL.md) — session keys and recovery
 - [docs/PATTERNS.md](docs/PATTERNS.md) — recommended gameplay patterns
+- [docs/ONCHAIN_OFFCHAIN_BOUNDARY.md](docs/ONCHAIN_OFFCHAIN_BOUNDARY.md) — deciding what belongs on-chain
 - [examples/README.md](examples/README.md) — example catalog and usage guide

docs/BRAND.md

@@ -146,6 +146,8 @@ if a future pass wants a further-simplified glyph specifically for 16px contexts
   written vocabulary list) to be their own follow-up rather than folded into this color/type/logo
   pass.
 - Consuming these tokens as an actual code package (CSS variables / Tailwind config / etc.) —
-  explicitly out of scope per #259, tracked as a sibling sub-issue.
+  explicitly out of scope per #259, and now shipped separately as
+  [`packages/tokens`](../packages/tokens). This document stays the source of truth; that package
+  encodes it. Change a value here first, then mirror it there and rebuild.
 - Any change to `README.md`'s current logo usage — a follow-up application of this system, not
   part of defining it.

docs/PATTERNS.md

@@ -23,6 +23,7 @@ Start here if you know what you're trying to build but not which Cougr module an
 | **To serialize mutations / guard against reentrancy-like issues** | `ExecutionGuard` | — | [STANDARDS_LAYER.md § ExecutionGuard](./STANDARDS_LAYER.md#executionguard) |
 | **Delayed or timelocked execution** | `DelayedExecutionPolicy` | — | [STANDARDS_LAYER.md § DelayedExecutionPolicy](./STANDARDS_LAYER.md#delayedexecutionpolicy) |
 | **To batch several operations safely** | `BatchExecutor` | — | [STANDARDS_LAYER.md § BatchExecutor](./STANDARDS_LAYER.md#batchexecutor) |
+| **To decide what belongs on-chain at all** (which state and rules justify their cost, and which should stay client-side) | The five-question boundary framework, applied per piece of state | [`battleship`](../examples/battleship), [`snake`](../examples/snake), [`blind_auction`](../examples/blind_auction) | [ONCHAIN_OFFCHAIN_BOUNDARY.md](./ONCHAIN_OFFCHAIN_BOUNDARY.md) |
 | **To know whether I even need ECS** | Direct contract model for small/config-driven contracts | — | [When Not To Use ECS](#when-not-to-use-ecs) below |
 | **To pick table vs. sparse storage** | Table for hot-loop state, sparse for infrequent markers | — | [Storage Guidance](#storage-guidance) below |
 | **A thin, explicit contract entrypoint / gameplay loop** | `GameApp` + explicit stage placement | [`spawn_and_move`](../examples/spawn_and_move), [`snake`](../examples/snake) | [Default Entry Point](#default-entry-point) and [Stage Layout](#stage-layout) below |

docs/PERFORMANCE.md

@@ -140,3 +140,9 @@ For real contracts, evaluate:
 Performance guidance should always be tied back to those conditions.
 
 If benchmark results and your data shape disagree, trust the data shape first.
+
+## Related
+
+This guide answers where a component should live once you have decided it belongs on-chain. For
+the prior decision, whether a piece of state or logic justifies being on-chain in the first place,
+see [ONCHAIN_OFFCHAIN_BOUNDARY.md](./ONCHAIN_OFFCHAIN_BOUNDARY.md).