@payfit/unity-themes 2.55.5 → 2.55.6

package/dist/esm/scripts/agent-references/color-reference.d.ts

@@ -0,0 +1,37 @@
+type ColorToken = {
+    name: string;
+    value?: string;
+    $value?: string;
+    path: string[];
+};
+type ReferenceToken = {
+    name: string;
+    group: string;
+    variable: string;
+};
+type ReferenceFile = {
+    filename: string;
+    content: string;
+};
+type UtilitySection = {
+    title: string;
+    patterns: string[];
+};
+export declare const generateColorGroupReference: ({ title, storybookTitle, description, tokens, utilitySections, }: {
+    title: string;
+    storybookTitle: string;
+    description: string;
+    tokens: ReferenceToken[];
+    utilitySections?: UtilitySection[];
+}) => string;
+export declare const generatePrimitiveColorReferenceFiles: (legacyTokens: ColorToken[]) => ReferenceFile[];
+export declare const generateSemanticColorReferenceFiles: (legacyTokens: ColorToken[]) => ReferenceFile[];
+export declare const generateThemesAgentReferencesReadme: ({ primitiveFiles, semanticFiles, }: {
+    primitiveFiles: ReferenceFile[];
+    semanticFiles: ReferenceFile[];
+}) => string;
+export declare const writeColorAgentReferences: ({ legacyTokens, outputDir, }: {
+    legacyTokens: ColorToken[];
+    outputDir: string;
+}) => void;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payfit/unity-themes",
-  "version": "2.55.5",
+  "version": "2.55.6",
   "main": "./dist/esm/index.js",
   "types": "./dist/esm/index.d.ts",
   "style": "./dist/css/unity.css",
@@ -8,8 +8,7 @@
   "files": [
     "dist",
     "tokens",
-    "src",
-    "skills"
+    "src"
   ],
   "storybook": {
     "url": "https://unity-theme.payfit.io/"
@@ -45,7 +44,6 @@
     "@storybook/addon-vitest": "10.4.6",
     "@storybook/react-vite": "10.4.6",
     "@tailwindcss/vite": "4.3.2",
-    "@tanstack/intent": "0.3.0",
     "@types/lodash": "4.14.202",
     "@types/node": "^24.12.0",
     "@types/react": "18.3.18",
@@ -64,10 +62,10 @@
     "typescript": "6.0.3",
     "vite": "8.0.16",
     "vitest": "4.1.9",
-    "@payfit/hr-app-eslint": "0.0.0-use.local",
     "@payfit/hr-apps-tsconfigs": "0.0.0-use.local",
     "@payfit/storybook-config": "0.0.0-use.local",
-    "@payfit/vite-configs": "0.0.0-use.local"
+    "@payfit/vite-configs": "0.0.0-use.local",
+    "@payfit/hr-app-eslint": "0.0.0-use.local"
   },
   "peerDependencies": {
     "@fontsource/inter": "5.0.19",
@@ -84,8 +82,5 @@
     "tailwind-merge": "3.6.0",
     "tailwind-variants": "3.2.2",
     "tailwindcss": "4.3.2"
-  },
-  "keywords": [
-    "tanstack-intent"
-  ]
+  }
 }

package/src/agent-references/README.mdx

@@ -0,0 +1,25 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title="Agent References/Unity Themes" />
+
+{/* AUTO-GENERATED FILE. DO NOT EDIT.
+Generated by unity-themes:pre-build.
+Source: Unity Style Dictionary color tokens.
+*/}
+
+# Unity Themes Agent References
+
+Static Unity theme references for Storybook MCP, search, and agents.
+
+Storybook includes these MDX files through the shared `../src/**/*.mdx` stories glob, and `@storybook/addon-mcp` exposes docs content to MCP clients.
+
+## Semantic colors
+
+- [semantic-surface-colors](./semantic-surface-colors.mdx)
+- [semantic-content-colors](./semantic-content-colors.mdx)
+- [semantic-border-colors](./semantic-border-colors.mdx)
+- [semantic-utility-colors](./semantic-utility-colors.mdx)
+
+## Primitive colors
+
+- [primitive-colors](./primitive-colors.mdx)

package/src/agent-references/primitive-colors.mdx

@@ -0,0 +1,18 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title="Agent References/Primitive Colors" />
+
+{/* AUTO-GENERATED FILE. DO NOT EDIT.
+Generated by unity-themes:pre-build.
+Source: Unity Style Dictionary color tokens.
+*/}
+
+# Primitive Colors
+
+Prefer semantic color tokens for product UI. Use primitive colors only when no semantic token fits the use case.
+
+Color names: grayscale, blue, red, green, orange, cyan, purple, plum, peach, sunglow, teal, yellow
+
+Scale: l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, l12. Grayscale also has l0.
+
+Tailwind usage: `uy:bg-<color>-<scale>`, for example `uy:bg-blue-l6` or `uy:bg-grayscale-l0`.

package/src/agent-references/semantic-border-colors.mdx

@@ -0,0 +1,16 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title="Agent References/Semantic Colors/Border" />
+
+{/* AUTO-GENERATED FILE. DO NOT EDIT.
+Generated by unity-themes:pre-build.
+Source: Unity Style Dictionary color tokens.
+*/}
+
+# Semantic Border Colors
+
+Use semantic color tokens for product UI. These names encode intent and stay stable across Unity themes. Use border tokens for borders and outlines. Other Tailwind color utilities may exist for these tokens, but using border tokens for backgrounds, text, gradients, or rings is discouraged.
+
+Names: danger, danger-lowest, form-active, form-disabled, form-enabled, form-error, form-focus, form-hover, form-pressed, form-read-only, form-selected, info, info-lowest, inverted, inverted-active, inverted-disabled, inverted-enabled, inverted-focus, inverted-high, inverted-hover, inverted-pressed, neutral, neutral-active, neutral-disabled, neutral-enabled, neutral-high, neutral-high-active, neutral-high-disabled, neutral-high-enabled, neutral-high-focus, neutral-high-hover, neutral-high-pressed, neutral-hover, neutral-low, neutral-pressed, neutral-selected, primary, primary-active, primary-disabled, primary-enabled, primary-focus, primary-hover, primary-lowest, primary-pressed, promo, promo-lowest, success, success-low, success-lowest, warning, warning-lowest
+
+Recommended: `uy:border-border-{name}`, `uy:outline-border-{name}`

package/src/agent-references/semantic-content-colors.mdx

@@ -0,0 +1,16 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title="Agent References/Semantic Colors/Content" />
+
+{/* AUTO-GENERATED FILE. DO NOT EDIT.
+Generated by unity-themes:pre-build.
+Source: Unity Style Dictionary color tokens.
+*/}
+
+# Semantic Content Colors
+
+Use semantic color tokens for product UI. These names encode intent and stay stable across Unity themes. Use content tokens for text, icon color, and text decoration. Other Tailwind color utilities may exist for these tokens, but using content tokens for backgrounds, borders, rings, or outlines is discouraged.
+
+Names: danger, danger-active, danger-disabled, danger-enabled, danger-focus, danger-high, danger-hover, danger-pressed, decorative-orange, decorative-orange-high, decorative-plum, decorative-plum-high, decorative-purple, decorative-purple-high, decorative-teal, decorative-teal-high, form-active, form-disabled, form-enabled, form-focus, form-hover, form-invalid, form-pressed, form-read-only, form-selected, info, info-active, info-disabled, info-enabled, info-focus, info-high, info-hover, info-pressed, inverted, inverted-active, inverted-disabled, inverted-enabled, inverted-focus, inverted-hover, inverted-pressed, neutral, neutral-active, neutral-disabled, neutral-enabled, neutral-focus, neutral-hover, neutral-low, neutral-lowest, neutral-lowest-active, neutral-lowest-disabled, neutral-lowest-enabled, neutral-lowest-focus, neutral-lowest-hover, neutral-lowest-pressed, neutral-pressed, primary, primary-active, primary-disabled, primary-enabled, primary-focus, primary-high, primary-hover, primary-pressed, promo, promo-high, success, success-active, success-disabled, success-enabled, success-focus, success-high, success-hover, success-pressed, warning, warning-active, warning-disabled, warning-enabled, warning-focus, warning-high, warning-hover, warning-pressed
+
+Recommended: `uy:text-content-{name}`, `uy:decoration-content-{name}`

package/src/agent-references/semantic-surface-colors.mdx

@@ -0,0 +1,16 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title="Agent References/Semantic Colors/Surface" />
+
+{/* AUTO-GENERATED FILE. DO NOT EDIT.
+Generated by unity-themes:pre-build.
+Source: Unity Style Dictionary color tokens.
+*/}
+
+# Semantic Surface Colors
+
+Use semantic color tokens for product UI. These names encode intent and stay stable across Unity themes. Use surface tokens for backgrounds and filled UI surfaces. Other Tailwind color utilities may exist for these tokens, but using surface tokens for text, borders, rings, or outlines is discouraged.
+
+Names: ai-low, danger, danger-active, danger-disabled, danger-enabled, danger-focus, danger-hover, danger-low, danger-lowest, danger-lowest-active, danger-lowest-disabled, danger-lowest-enabled, danger-lowest-focus, danger-lowest-hover, danger-lowest-pressed, danger-pressed, decorative-orange, decorative-orange-high, decorative-orange-low, decorative-orange-lowest, decorative-plum, decorative-plum-high, decorative-plum-low, decorative-plum-lowest, decorative-purple, decorative-purple-high, decorative-purple-low, decorative-purple-lowest, decorative-teal, decorative-teal-high, decorative-teal-low, decorative-teal-lowest, form-active, form-disabled, form-enabled, form-error, form-focus, form-high-active, form-high-disabled, form-high-enabled, form-high-error, form-high-focus, form-high-hover, form-high-pressed, form-high-read-only, form-high-selected, form-hover, form-pressed, form-read-only, form-selected, info, info-low, info-lowest, info-lowest-active, info-lowest-disabled, info-lowest-enabled, info-lowest-focus, info-lowest-hover, info-lowest-pressed, inverted, inverted-active, inverted-enabled, inverted-focus, inverted-hover, inverted-pressed, neutral, neutral-active, neutral-disabled, neutral-enabled, neutral-focus, neutral-hover, neutral-low, neutral-low-active, neutral-low-disabled, neutral-low-enabled, neutral-low-focus, neutral-low-hover, neutral-low-pressed, neutral-low-selected, neutral-lowest, neutral-lowest-active, neutral-lowest-disabled, neutral-lowest-enabled, neutral-lowest-focus, neutral-lowest-hover, neutral-lowest-pressed, neutral-lowest-selected, neutral-pressed, neutral-selected, primary, primary-active, primary-disabled, primary-enabled, primary-focus, primary-high, primary-highest, primary-hover, primary-low, primary-lowest, primary-lowest-active, primary-lowest-disabled, primary-lowest-enabled, primary-lowest-focus, primary-lowest-hover, primary-lowest-pressed, primary-pressed, promo, promo-low, promo-lowest, success, success-low, success-lowest, success-lowest-active, success-lowest-disabled, success-lowest-enabled, success-lowest-focus, success-lowest-hover, success-lowest-pressed, warning, warning-active, warning-disabled, warning-enabled, warning-focus, warning-hover, warning-low, warning-lowest, warning-lowest-active, warning-lowest-disabled, warning-lowest-enabled, warning-lowest-focus, warning-lowest-hover, warning-lowest-pressed, warning-pressed
+
+Recommended: `uy:bg-surface-{name}`

package/src/agent-references/semantic-utility-colors.mdx

@@ -0,0 +1,16 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title="Agent References/Semantic Colors/Utility & Canvas" />
+
+{/* AUTO-GENERATED FILE. DO NOT EDIT.
+Generated by unity-themes:pre-build.
+Source: Unity Style Dictionary color tokens.
+*/}
+
+# Semantic Utility & Canvas Colors
+
+Use semantic color tokens for product UI. These names encode intent and stay stable across Unity themes. Use utility and canvas tokens only for their named UI purpose. These tokens are intentionally narrow and should not be treated as a general color palette.
+
+Names: backdrop, focus-ring, inverted-focus-ring, shadow-100, shadow-200, shadow-300, shadow-400, shadow-500, shadow-600
+
+Token-specific: `uy:bg-canvas-{name}`, `uy:ring-utility-focus-ring`, `uy:ring-utility-inverted-focus-ring`, `uy:bg-utility-backdrop`, shadow-\* tokens are not UI colors

package/src/scripts/agent-references/color-reference.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  generatePrimitiveColorReferenceFiles,
+  generateSemanticColorReferenceFiles,
+  generateThemesAgentReferencesReadme,
+} from './color-reference.js'
+
+const createToken = (path: string[], value: string) => ({
+  name: `uy-${path.join('-').toLowerCase()}`,
+  path,
+  $value: value,
+})
+
+describe('color agent references', () => {
+  it('generates one compact primitive reference file for all palettes', () => {
+    const files = generatePrimitiveColorReferenceFiles([
+      createToken(['color', 'grayscale', 'L0'], '#000'),
+      createToken(['color', 'grayscale', 'L1'], '#005'),
+      createToken(['color', 'blue', 'L10'], '#001'),
+      createToken(['color', 'blue', 'L2'], '#002'),
+      createToken(['color', 'blue', 'L1'], '#003'),
+      createToken(['color', 'red', 'L1'], '#004'),
+    ])
+
+    expect(files.map(file => file.filename)).toEqual(['primitive-colors.mdx'])
+
+    const primitiveReference = files[0]?.content
+
+    expect(
+      primitiveReference!.startsWith(
+        `import { Meta } from '@storybook/addon-docs/blocks'\n\n<Meta title="Agent References/Primitive Colors" />`,
+      ),
+    ).toBe(true)
+    expect(primitiveReference).toContain(
+      `{/* AUTO-GENERATED FILE. DO NOT EDIT.
+Generated by unity-themes:pre-build.
+Source: Unity Style Dictionary color tokens.
+*/}`,
+    )
+    expect(primitiveReference).toContain('Color names: grayscale, blue, red')
+    expect(primitiveReference).toContain('Scale: l1, l2, l10')
+    expect(primitiveReference).toContain('Grayscale also has l0')
+    expect(primitiveReference!.indexOf('l1')).toBeLessThan(
+      primitiveReference!.indexOf('l2'),
+    )
+    expect(primitiveReference!.indexOf('l2')).toBeLessThan(
+      primitiveReference!.indexOf('l10'),
+    )
+    expect(primitiveReference).not.toContain('`--uy-color-blue-l1`')
+    expect(primitiveReference).not.toContain('Names: l1')
+    expect(primitiveReference).not.toContain('## Names')
+    expect(primitiveReference).not.toContain('- l1')
+    expect(primitiveReference).toContain('`uy:bg-<color>-<scale>`')
+    expect(primitiveReference).toContain('`uy:bg-blue-l')
+    expect(primitiveReference).not.toContain('Legacy value')
+    expect(primitiveReference).not.toContain('Rebrand value')
+    expect(primitiveReference).not.toContain('#001')
+  })
+
+  it('generates one compact semantic reference file per semantic group', () => {
+    const files = generateSemanticColorReferenceFiles([
+      createToken(['color', 'surface', 'primary'], '#fff'),
+      createToken(['color', 'content', 'neutral'], '#111'),
+      createToken(['color', 'border', 'primary'], '#222'),
+      createToken(['color', 'canvas', 'default'], '#333'),
+    ])
+
+    expect(files.map(file => file.filename)).toEqual([
+      'semantic-surface-colors.mdx',
+      'semantic-content-colors.mdx',
+      'semantic-border-colors.mdx',
+      'semantic-utility-colors.mdx',
+    ])
+
+    const surfaceReference = files[0]!.content
+
+    expect(surfaceReference).toContain(
+      '<Meta title="Agent References/Semantic Colors/Surface" />',
+    )
+    expect(surfaceReference).toContain('Names: primary')
+    expect(surfaceReference).not.toContain('## Names')
+    expect(surfaceReference).not.toContain('- primary')
+    expect(surfaceReference).not.toContain('`--uy-color-surface-primary`')
+    expect(surfaceReference).toContain('`uy:bg-surface-{name}`')
+    expect(surfaceReference).toContain('using surface tokens for text')
+    expect(surfaceReference).not.toContain('`uy:text-surface-{name}`')
+    expect(surfaceReference).not.toContain('CSS properties')
+    expect(surfaceReference).not.toContain(
+      'background-color: var(--uy-color-surface-primary);',
+    )
+    expect(surfaceReference).not.toContain('#fff')
+
+    const contentReference = files[1]!.content
+    expect(contentReference).toContain('`uy:text-content-{name}`')
+    expect(contentReference).toContain('`uy:decoration-content-{name}`')
+    expect(contentReference).not.toContain('`uy:bg-content-{name}`')
+
+    const borderReference = files[2]!.content
+    expect(borderReference).toContain('`uy:border-border-{name}`')
+    expect(borderReference).toContain('`uy:outline-border-{name}`')
+    expect(borderReference).not.toContain('`uy:bg-border-{name}`')
+
+    const utilityReference = files[3]!.content
+    expect(utilityReference).toContain('Use utility and canvas tokens only')
+    expect(utilityReference).toContain('`uy:ring-utility-focus-ring`')
+    expect(utilityReference).not.toContain('`uy:bg-utility-{name}`')
+  })
+
+  it('links generated files from the README', () => {
+    const primitiveFiles = generatePrimitiveColorReferenceFiles([
+      createToken(['color', 'blue', 'L1'], '#001'),
+    ])
+    const semanticFiles = generateSemanticColorReferenceFiles([
+      createToken(['color', 'surface', 'primary'], '#fff'),
+    ])
+
+    const readme = generateThemesAgentReferencesReadme({
+      primitiveFiles,
+      semanticFiles,
+    })
+
+    expect(
+      readme.startsWith(
+        `import { Meta } from '@storybook/addon-docs/blocks'\n\n<Meta title="Agent References/Unity Themes" />`,
+      ),
+    ).toBe(true)
+    expect(readme).toContain(
+      `{/* AUTO-GENERATED FILE. DO NOT EDIT.
+Generated by unity-themes:pre-build.
+Source: Unity Style Dictionary color tokens.
+*/}`,
+    )
+    expect(readme).toContain(
+      '[semantic-surface-colors](./semantic-surface-colors.mdx)',
+    )
+    expect(readme).toContain('[primitive-colors](./primitive-colors.mdx)')
+    expect(readme).not.toContain('primitive-blue-colors')
+  })
+})

package/src/scripts/agent-references/color-reference.ts

@@ -0,0 +1,348 @@
+import fs from 'fs'
+import path from 'path'
+
+type ColorToken = {
+  name: string
+  value?: string
+  $value?: string
+  path: string[]
+}
+
+type ReferenceToken = {
+  name: string
+  group: string
+  variable: string
+}
+
+type ReferenceFile = {
+  filename: string
+  content: string
+}
+
+type UtilitySection = {
+  title: string
+  patterns: string[]
+}
+
+const PRIMITIVE_GROUPS = [
+  'grayscale',
+  'blue',
+  'red',
+  'green',
+  'orange',
+  'cyan',
+  'purple',
+  'plum',
+  'peach',
+  'sunglow',
+  'teal',
+  'yellow',
+]
+
+const SEMANTIC_GROUPS = [
+  {
+    title: 'Surface',
+    slug: 'surface',
+    groups: ['surface'],
+    usageGuidance:
+      'Use surface tokens for backgrounds and filled UI surfaces. Other Tailwind color utilities may exist for these tokens, but using surface tokens for text, borders, rings, or outlines is discouraged.',
+    utilitySections: [
+      {
+        title: 'Recommended',
+        patterns: ['uy:bg-surface-{name}'],
+      },
+    ],
+  },
+  {
+    title: 'Content',
+    slug: 'content',
+    groups: ['content'],
+    usageGuidance:
+      'Use content tokens for text, icon color, and text decoration. Other Tailwind color utilities may exist for these tokens, but using content tokens for backgrounds, borders, rings, or outlines is discouraged.',
+    utilitySections: [
+      {
+        title: 'Recommended',
+        patterns: ['uy:text-content-{name}', 'uy:decoration-content-{name}'],
+      },
+    ],
+  },
+  {
+    title: 'Border',
+    slug: 'border',
+    groups: ['border'],
+    usageGuidance:
+      'Use border tokens for borders and outlines. Other Tailwind color utilities may exist for these tokens, but using border tokens for backgrounds, text, gradients, or rings is discouraged.',
+    utilitySections: [
+      {
+        title: 'Recommended',
+        patterns: ['uy:border-border-{name}', 'uy:outline-border-{name}'],
+      },
+    ],
+  },
+  {
+    title: 'Utility & Canvas',
+    slug: 'utility',
+    groups: ['utility', 'canvas'],
+    usageGuidance:
+      'Use utility and canvas tokens only for their named UI purpose. These tokens are intentionally narrow and should not be treated as a general color palette.',
+    utilitySections: [
+      {
+        title: 'Token-specific',
+        patterns: [
+          'uy:bg-canvas-{name}',
+          'uy:ring-utility-focus-ring',
+          'uy:ring-utility-inverted-focus-ring',
+          'uy:bg-utility-backdrop',
+          'shadow-\\* tokens are not UI colors',
+        ],
+      },
+    ],
+  },
+]
+
+const SEMANTIC_GROUP_NAMES = SEMANTIC_GROUPS.flatMap(group => group.groups)
+
+const generatedNotice = (source: string) =>
+  `{/* AUTO-GENERATED FILE. DO NOT EDIT.
+Generated by unity-themes:pre-build.
+Source: ${source}.
+*/}`
+
+const storybookMeta = (title: string) =>
+  `import { Meta } from '@storybook/addon-docs/blocks'\n\n<Meta title="Agent References/${title}" />`
+
+const parseReferenceToken = (token: ColorToken): ReferenceToken | null => {
+  const normalizedVariableName = token.name
+    .replace(/^uy-color-/, '')
+    .toLowerCase()
+  const [group, ...nameParts] = normalizedVariableName.split('-')
+  const name = nameParts.join('-')
+
+  if (!group || !name) {
+    return null
+  }
+
+  return {
+    name,
+    group,
+    variable: `--uy-color-${normalizedVariableName}`,
+  }
+}
+
+const getReferenceTokens = (tokens: ColorToken[]) =>
+  tokens
+    .filter(token => token.path[0] === 'color')
+    .map(parseReferenceToken)
+    .filter((token): token is ReferenceToken => token !== null)
+
+const naturalLevelOrder = (name: string) => {
+  const levelMatch = /^l(\d+)$/i.exec(name)
+  return levelMatch ? Number(levelMatch[1]) : Number.POSITIVE_INFINITY
+}
+
+const sortByPrimitiveLevel = (a: ReferenceToken, b: ReferenceToken) => {
+  const aLevel = naturalLevelOrder(a.name)
+  const bLevel = naturalLevelOrder(b.name)
+
+  if (aLevel !== bLevel) {
+    return aLevel - bLevel
+  }
+
+  return a.name.localeCompare(b.name)
+}
+
+const sortByName = (a: ReferenceToken, b: ReferenceToken) =>
+  a.name.localeCompare(b.name)
+
+const renderNames = (tokens: ReferenceToken[]) =>
+  `Names: ${tokens.map(token => token.name).join(', ')}`
+
+const renderRecommendedUsageSections = (sections: UtilitySection[]) =>
+  sections.flatMap(section => [
+    `${section.title}: ${section.patterns
+      .map(pattern => (pattern.startsWith('uy:') ? `\`${pattern}\`` : pattern))
+      .join(', ')}`,
+  ])
+
+export const generateColorGroupReference = ({
+  title,
+  storybookTitle,
+  description,
+  tokens,
+  utilitySections,
+}: {
+  title: string
+  storybookTitle: string
+  description: string
+  tokens: ReferenceToken[]
+  utilitySections?: UtilitySection[]
+}) => {
+  const lines = [
+    storybookMeta(storybookTitle),
+    generatedNotice('Unity Style Dictionary color tokens'),
+    `# ${title}`,
+    description,
+    renderNames(tokens),
+    ...(utilitySections ? renderRecommendedUsageSections(utilitySections) : []),
+  ]
+
+  return `${lines.join('\n\n').trimEnd()}\n`
+}
+
+const sortPrimitiveGroups = (groups: string[]) =>
+  groups.slice().sort((a, b) => {
+    const aIndex = PRIMITIVE_GROUPS.indexOf(a)
+    const bIndex = PRIMITIVE_GROUPS.indexOf(b)
+
+    return aIndex - bIndex
+  })
+
+const uniqueSortedPrimitiveLevels = (tokens: ReferenceToken[]) =>
+  [...new Set(tokens.map(token => token.name))].sort((a, b) =>
+    sortByPrimitiveLevel(
+      { name: a, group: '', variable: '' },
+      { name: b, group: '', variable: '' },
+    ),
+  )
+
+const generatePrimitiveColorsReference = (tokens: ReferenceToken[]) => {
+  const colors = sortPrimitiveGroups([
+    ...new Set(tokens.map(token => token.group)),
+  ])
+  const nonGrayscaleLevels = uniqueSortedPrimitiveLevels(
+    tokens.filter(token => token.group !== 'grayscale'),
+  )
+  const grayscaleLevels = uniqueSortedPrimitiveLevels(
+    tokens.filter(token => token.group === 'grayscale'),
+  )
+  const grayscaleExtraLevels = grayscaleLevels.filter(
+    level => !nonGrayscaleLevels.includes(level),
+  )
+  const exampleScale = nonGrayscaleLevels.includes('l6')
+    ? 'l6'
+    : nonGrayscaleLevels[0]
+  const grayscaleExampleScale = grayscaleExtraLevels[0] ?? grayscaleLevels[0]
+
+  const lines = [
+    storybookMeta('Primitive Colors'),
+    generatedNotice('Unity Style Dictionary color tokens'),
+    '# Primitive Colors',
+    'Prefer semantic color tokens for product UI. Use primitive colors only when no semantic token fits the use case.',
+    `Color names: ${colors.join(', ')}`,
+    `Scale: ${nonGrayscaleLevels.join(', ')}${
+      grayscaleExtraLevels.length > 0
+        ? `. Grayscale also has ${grayscaleExtraLevels.join(', ')}`
+        : ''
+    }.`,
+    `Tailwind usage: \`uy:bg-<color>-<scale>\`, for example \`uy:bg-blue-${exampleScale}\`${
+      grayscaleExampleScale
+        ? ` or \`uy:bg-grayscale-${grayscaleExampleScale}\``
+        : ''
+    }.`,
+  ]
+
+  return `${lines.join('\n\n').trimEnd()}\n`
+}
+
+export const generatePrimitiveColorReferenceFiles = (
+  legacyTokens: ColorToken[],
+): ReferenceFile[] => {
+  const tokens = getReferenceTokens(legacyTokens).filter(token =>
+    PRIMITIVE_GROUPS.includes(token.group),
+  )
+
+  if (tokens.length === 0) {
+    return []
+  }
+
+  return [
+    {
+      filename: 'primitive-colors.mdx',
+      content: generatePrimitiveColorsReference(tokens),
+    },
+  ]
+}
+
+export const generateSemanticColorReferenceFiles = (
+  legacyTokens: ColorToken[],
+): ReferenceFile[] => {
+  const tokens = getReferenceTokens(legacyTokens).filter(token =>
+    SEMANTIC_GROUP_NAMES.includes(token.group),
+  )
+
+  return SEMANTIC_GROUPS.flatMap(group => {
+    const groupTokens = tokens
+      .filter(token => group.groups.includes(token.group))
+      .sort(sortByName)
+
+    if (groupTokens.length === 0) {
+      return []
+    }
+
+    return [
+      {
+        filename: `semantic-${group.slug}-colors.mdx`,
+        content: generateColorGroupReference({
+          title: `Semantic ${group.title} Colors`,
+          storybookTitle: `Semantic Colors/${group.title}`,
+          description: `Use semantic color tokens for product UI. These names encode intent and stay stable across Unity themes. ${group.usageGuidance}`,
+          tokens: groupTokens,
+          utilitySections: group.utilitySections,
+        }),
+      },
+    ]
+  })
+}
+
+const linkList = (files: ReferenceFile[]) =>
+  files.map(
+    file => `- [${file.filename.replace(/\.mdx$/, '')}](./${file.filename})`,
+  )
+
+export const generateThemesAgentReferencesReadme = ({
+  primitiveFiles,
+  semanticFiles,
+}: {
+  primitiveFiles: ReferenceFile[]
+  semanticFiles: ReferenceFile[]
+}) => `${storybookMeta('Unity Themes')}
+
+${generatedNotice('Unity Style Dictionary color tokens')}
+
+# Unity Themes Agent References
+
+Static Unity theme references for Storybook MCP, search, and agents.
+
+Storybook includes these MDX files through the shared \`../src/**/*.mdx\` stories glob, and \`@storybook/addon-mcp\` exposes docs content to MCP clients.
+
+## Semantic colors
+
+${linkList(semanticFiles).join('\n')}
+
+## Primitive colors
+
+${linkList(primitiveFiles).join('\n')}
+`
+
+export const writeColorAgentReferences = ({
+  legacyTokens,
+  outputDir,
+}: {
+  legacyTokens: ColorToken[]
+  outputDir: string
+}) => {
+  const primitiveFiles = generatePrimitiveColorReferenceFiles(legacyTokens)
+  const semanticFiles = generateSemanticColorReferenceFiles(legacyTokens)
+
+  fs.rmSync(outputDir, { recursive: true, force: true })
+  fs.mkdirSync(outputDir, { recursive: true })
+  fs.writeFileSync(
+    path.join(outputDir, 'README.mdx'),
+    generateThemesAgentReferencesReadme({ primitiveFiles, semanticFiles }),
+    'utf8',
+  )
+
+  for (const file of [...semanticFiles, ...primitiveFiles]) {
+    fs.writeFileSync(path.join(outputDir, file.filename), file.content, 'utf8')
+  }
+}

package/src/scripts/build.ts

@@ -25,6 +25,7 @@ import * as tailwindGridTokenTransformer from './transforms/tailwind-grid-token.
 import * as tailwindSpacingTokenTransformer from './transforms/tailwind-spacing-token.js'
 import * as tailwindTextTokenTransformer from './transforms/tailwind-text-token.js'
 import * as tailwindTypographyTokenTransformer from './transforms/tailwind-typography-token.js'
+import { writeColorAgentReferences } from './agent-references/color-reference.js'
 
 // ---------------------------------------------------------------------------
 // Register extensions (shared by all SD instances)
@@ -130,6 +131,7 @@ const ANIMATIONS_PATH = './assets/animations/'
 const DIST_FONTS_PATH = './dist/css/fonts/'
 const DIST_ASSETS_FONTS_PATH = './dist/css/assets/fonts/'
 const GENERATED_FONTS_CSS_PATH = './dist/css/generated/proprietary-fonts.css'
+const AGENT_REFERENCES_PATH = './src/agent-references'
 const PREFIX = 'uy'
 
 // ---------------------------------------------------------------------------
@@ -372,11 +374,16 @@ async function build() {
     outputPath,
   })
 
-  // 6. Append animation keyframes + reset CSS
-  logStep(6, TOTAL_STEPS, 'Appending animation keyframes')
-  logDetail(`Source: ${color.yellow(ANIMATIONS_PATH)}`)
+  // 6. Generate static references + append animation keyframes
+  logStep(6, TOTAL_STEPS, 'Generating agent references and animations')
+  logDetail(`Agent references: ${color.yellow(AGENT_REFERENCES_PATH)}`)
+  logDetail(`Animations source: ${color.yellow(ANIMATIONS_PATH)}`)
 
   const legacyDict = await legacySD.getPlatformTokens('css')
+  writeColorAgentReferences({
+    legacyTokens: legacyDict.allTokens,
+    outputDir: AGENT_REFERENCES_PATH,
+  })
   appendAnimations(
     legacyDict,
     {