feat(cli): show semantic tokens and named themes in panda studio

Author: Adebesin-Cell

.changeset/cli-studio-semantic.md

@@ -0,0 +1,5 @@
+---
+'@pandacss/cli': patch
+---
+
+Show semantic tokens in `panda studio`. Each semantic token renders a swatch per condition (`base`, `_dark`, …) and per named theme, resolved to real values, so you can see what a token becomes in every mode.

packages/cli/__tests__/studio.test.ts

@@ -1,7 +1,14 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
-import { buildTokensSnapshot, runStudioGenerate, runStudioServe, viewFiles, viewerFiles } from '../src'
+import {
+  buildSemanticMap,
+  buildTokensSnapshot,
+  runStudioGenerate,
+  runStudioServe,
+  viewFiles,
+  viewerFiles,
+} from '../src'
 import type { StudioToken } from '../src'
 import { cleanupFixture, createFixture } from './helpers'
 
@@ -119,3 +126,34 @@ describe('studio viewer', () => {
     }
   })
 })
+
+describe('studio semantic tokens', () => {
+  const spec = { tokens: { categories: {}, values: { 'colors.white': '#fff', 'colors.black': '#000' } } } as never
+  const config = {
+    theme: { semanticTokens: { colors: { bg: { value: { base: '{colors.white}', _dark: '{colors.black}' } } } } },
+    themes: { ocean: { semanticTokens: { colors: { bg: { value: { base: '#e0f2fe' } } } } } },
+  }
+
+  it('resolves semantic conditions and named themes against token values', () => {
+    expect(buildSemanticMap(spec, config)).toEqual({
+      'colors.bg': { base: '#fff', _dark: '#000', 'ocean · base': '#e0f2fe' },
+    })
+  })
+
+  it('emits semantic tokens with conditions, base as the display value', () => {
+    const semantic = buildSemanticMap(spec, config)
+    const tokens = buildTokensSnapshot(spec, semantic)
+    const bg = tokens.find((token) => token.path === 'colors.bg')
+    expect(bg).toMatchObject({ category: 'colors', name: 'bg', value: '#fff' })
+    expect(bg?.conditions).toEqual({ base: '#fff', _dark: '#000', 'ocean · base': '#e0f2fe' })
+  })
+
+  it('keeps semantic paths out of the primitive list', () => {
+    const specWithSemantic = {
+      tokens: { categories: { colors: { values: ['bg'] } }, values: { 'colors.bg': 'var(--colors-white)' } },
+    } as never
+    const tokens = buildTokensSnapshot(specWithSemantic, { 'colors.bg': { base: '#fff' } })
+    expect(tokens.filter((token) => token.path === 'colors.bg')).toHaveLength(1)
+    expect(tokens[0].value).toBe('#fff')
+  })
+})

packages/cli/src/commands/studio.ts

@@ -10,6 +10,7 @@ import { studioGenerateFlagsSchema, studioServeFlagsSchema } from '../schema'
 import type { StudioGenerateFlags, StudioGenerateResult, StudioServeFlags, StudioServeResult } from '../schema'
 import { serveStudio, type StudioServer } from '../studio-server'
 import {
+  buildSemanticMap,
   buildTokensSnapshot,
   keyframesToCss,
   viewFiles,
@@ -58,7 +59,8 @@ export async function runStudioGenerate(
     failData: () => ({ files: [], framework: 'react' as StudioFramework }),
     async execute(ctx) {
       const framework = resolveFramework(ctx.driver.config.jsxFramework)
-      const tokens = buildTokensSnapshot(ctx.driver.compiler.spec())
+      const spec = ctx.driver.compiler.spec()
+      const tokens = buildTokensSnapshot(spec, buildSemanticMap(spec, ctx.driver.config))
       const keyframes = keyframesToCss(readKeyframes(ctx.driver.config))
       const outdir = flags.outdir ? ctx.driver.resolvePath(flags.outdir) : join(ctx.driver.getOutdir(), 'studio')
 
@@ -86,7 +88,8 @@ export async function runStudioServe(
     keepTracing: true,
     failData: () => ({}),
     async execute(ctx) {
-      const tokens = buildTokensSnapshot(ctx.driver.compiler.spec())
+      const spec = ctx.driver.compiler.spec()
+      const tokens = buildTokensSnapshot(spec, buildSemanticMap(spec, ctx.driver.config))
       const keyframes = keyframesToCss(readKeyframes(ctx.driver.config))
       const dir = mkdtempSync(join(tmpdir(), 'panda-studio-'))
       writeStudioFiles(dir, viewerFiles(tokens, keyframes))

packages/cli/src/index.ts

@@ -9,7 +9,7 @@ export { runAnalyze } from './commands/analyze'
 export { infoDriver, runInfo } from './commands/info'
 export { runInit, setupGitIgnore } from './commands/init'
 export { runStudioGenerate, runStudioServe } from './commands/studio'
-export { buildTokensSnapshot, viewFiles, viewerFiles } from './studio-codegen'
+export { buildSemanticMap, buildTokensSnapshot, keyframesToCss, viewFiles, viewerFiles } from './studio-codegen'
 export type { StudioToken, StudioFile, StudioFramework } from './studio-codegen'
 export { serveStudio } from './studio-server'
 export type {