diff --git a/.kiro/hooks/tokens-story-sync.kiro.hook b/.kiro/hooks/tokens-story-sync.kiro.hook
index 0121e15..1672621 100644
--- a/.kiro/hooks/tokens-story-sync.kiro.hook
+++ b/.kiro/hooks/tokens-story-sync.kiro.hook
@@ -1,16 +1,16 @@
 {
   "enabled": true,
   "name": "Sync Design Tokens Story",
-  "description": "When public/tokens.json is edited, reminds the agent to verify the DesignTokens story still renders correctly and covers any new token categories.",
+  "description": "When tokens/tokens.json (the source) is edited, reminds the agent to verify the DesignTokens story still renders correctly and covers any new token categories.",
   "version": "1",
   "when": {
     "type": "fileEdited",
     "patterns": [
-      "public/tokens.json"
+      "tokens/tokens.json"
     ]
   },
   "then": {
     "type": "askAgent",
-    "prompt": "public/tokens.json was just modified. Check if src/stories/DesignTokens.stories.tsx needs updates to reflect new or removed token categories (e.g. new color families, new gradient entries, new spacing groups). The story derives most data dynamically, but verify that any new top-level token groups are represented and that the page still compiles cleanly."
+    "prompt": "tokens/tokens.json was just modified. Check if src/stories/DesignTokens.stories.tsx needs updates to reflect new or removed token categories (e.g. new color families, new gradient entries, new spacing groups). The story imports from tokens/tokens.json and adds semantic color aliases inline — verify both the dynamic rendering and the inline semantic mapping are still correct."
   }
 }
\ No newline at end of file
diff --git a/README.md b/README.md
index 601fe5c..5928253 100644
--- a/README.md
+++ b/README.md
@@ -99,6 +99,8 @@ The distributable file is available in two places:
 - `dist/tokens.json` — included in the npm package (`@pglevy/sailwind/tokens.json`)
 - `public/tokens.json` — committed to the repo for versioned CDN access
 
+> ⚠️ **Do not remove `public/tokens.json` from the repo.** External tools (Kiro skills, Aurora) fetch tokens at runtime from the jsdelivr CDN, which serves files directly from this path on the `main` branch.
+
 You can access the latest version here:
 ```
 https://cdn.jsdelivr.net/gh/pglevy/sailwind@latest/public/tokens.json
diff --git a/scripts/generate-tokens.ts b/scripts/generate-tokens.ts
index 19d51ed..f113b83 100644
--- a/scripts/generate-tokens.ts
+++ b/scripts/generate-tokens.ts
@@ -7,8 +7,11 @@
  *   - src/types/sail.ts    (SAIL enum types for semantic color tokens)
  *
  * Writes:
- *   - dist/tokens.json
- *   - public/tokens.json
+ *   - dist/tokens.json   — included in the npm package (@pglevy/sailwind/tokens.json)
+ *   - public/tokens.json — committed to the repo for versioned CDN access via jsdelivr
+ *
+ * ⚠️  Do NOT remove the public/ output. External tools (e.g. Kiro skills, Aurora)
+ *     fetch tokens from: https://cdn.jsdelivr.net/gh/pglevy/sailwind@main/public/tokens.json
  *
  * The source file is mostly passed through. This script adds:
  *   - color.black alias
diff --git a/src/stories/DesignTokens.stories.tsx b/src/stories/DesignTokens.stories.tsx
index c16ef0f..ce8e135 100644
--- a/src/stories/DesignTokens.stories.tsx
+++ b/src/stories/DesignTokens.stories.tsx
@@ -1,5 +1,22 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
-import tokens from '../../public/tokens.json'
+import sourceTokens from '../../tokens/tokens.json'
+
+// Augment the source tokens with semantic color aliases (same logic as generate-tokens.ts)
+// so this story doesn't need to import from public/ (which Vite warns about).
+const tokens = {
+  ...sourceTokens,
+  color: {
+    ...sourceTokens.color,
+    black: { $value: '#171717', $type: 'color', $description: 'Black — sourced from studio grey-1000' },
+    semantic: {
+      accent:      { $value: '{color.blue.500}',  $type: 'color', $description: 'SAILSemanticColor.ACCENT' },
+      positive:    { $value: '{color.green.500}',  $type: 'color', $description: 'SAILSemanticColor.POSITIVE' },
+      destructive: { $value: '{color.red.500}',   $type: 'color', $description: 'SAILSemanticColor.NEGATIVE' },
+      secondary:   { $value: '{color.gray.700}',  $type: 'color', $description: 'SAILSemanticColor.SECONDARY' },
+      standard:    { $value: '{color.gray.900}',  $type: 'color', $description: 'SAILSemanticColor.STANDARD' },
+    },
+  },
+}
 
 // ─── helpers ────────────────────────────────────────────────────────────────
 
@@ -307,7 +324,7 @@ function DesignTokensPage() {
       <h1 style={{ fontSize: 28, fontWeight: 700, color: '#222', margin: '0 0 4px' }}>Design Tokens</h1>
       <p style={{ color: '#6C6C75', fontSize: 14, margin: '0 0 8px' }}>
         Aurora color palette, semantic mappings, typography, spacing, and gradients — sourced from{' '}
-        <code style={{ fontFamily: 'monospace', background: '#EDEDF2', padding: '1px 5px', borderRadius: 4 }}>public/tokens.json</code>
+        <code style={{ fontFamily: 'monospace', background: '#EDEDF2', padding: '1px 5px', borderRadius: 4 }}>tokens/tokens.json</code>
       </p>
       <hr style={{ border: 'none', borderTop: '1px solid #E0E0E0', margin: '20px 0 0' }} />
       <ColorPalette />