refactor: spec command

segunadebayo · segunadebayo · commit b3857ab2cd36 · 2025-12-05T16:26:31.000Z
diff --git a/.changeset/add-spec-command.md b/.changeset/add-spec-command.md
@@ -3,6 +3,7 @@
 '@pandacss/generator': minor
 '@pandacss/node': minor
 '@pandacss/types': minor
+'@pandacss/cli': patch
 ---
 
 Add `panda spec` command to generate specification files for your theme (useful for documentation). This command
@@ -12,17 +13,28 @@ generates JSON specification files containing metadata, examples, and usage info
 # Generate all spec files
 panda spec
 
-# Generate with filter (filters across all spec types)
-panda spec --filter "button*"
-
 # Custom output directory
 panda spec --outdir custom/specs
+```
+
+**Token Spec Structure:**
 
-# Include spec entrypoint in package.json
-panda emit-pkg --spec
+```json
+{
+  "type": "tokens",
+  "data": [
+    {
+      "type": "aspectRatios",
+      "values": [{ "name": "square", "value": "1 / 1", "cssVar": "var(--aspect-ratios-square)" }],
+      "tokenFunctionExamples": ["token('aspectRatios.square')"],
+      "functionExamples": ["css({ aspectRatio: 'square' })"],
+      "jsxExamples": ["<Box aspectRatio=\"square\" />"]
+    }
+  ]
+}
 ```
 
-Spec files can be consumed via:
+**Spec Usage:**
 
 ```javascript
 import tokens from 'styled-system/specs/tokens'
diff --git a/packages/cli/src/cli-main.ts b/packages/cli/src/cli-main.ts
@@ -312,11 +312,10 @@ export async function main() {
     .command('spec', 'Generate spec files for your theme (useful for documentation)')
     .option('--silent', "Don't print any logs")
     .option('--outdir <dir>', 'Output directory for spec files')
-    .option('--filter <pattern>', 'Filter specifications by name/pattern')
     .option('-c, --config <path>', 'Path to panda config file')
     .option('--cwd <cwd>', 'Current working directory', { default: cwd })
     .action(async (flags: SpecCommandFlags) => {
-      const { silent, config: configPath, outdir, filter } = flags
+      const { silent, config: configPath, outdir } = flags
       const cwd = resolve(flags.cwd ?? '')
 
       if (silent) {
@@ -329,10 +328,7 @@ export async function main() {
         config: { cwd },
       })
 
-      await spec(ctx, {
-        outdir,
-        filter,
-      })
+      await spec(ctx, { outdir })
     })
 
   cli
diff --git a/packages/cli/src/types.ts b/packages/cli/src/types.ts
@@ -103,5 +103,4 @@ export interface SpecCommandFlags {
   outdir?: string
   cwd?: string
   config?: string
-  filter?: string
 }
diff --git a/packages/generator/src/generator.ts b/packages/generator/src/generator.ts
@@ -1,6 +1,6 @@
 import { Context, type StyleDecoder, type Stylesheet } from '@pandacss/core'
 import { dashCase, PandaError } from '@pandacss/shared'
-import type { ArtifactId, CssArtifactType, LoadConfigResult, SpecType } from '@pandacss/types'
+import type { ArtifactId, CssArtifactType, LoadConfigResult, SpecFile } from '@pandacss/types'
 import { match } from 'ts-pattern'
 import { generateArtifacts } from './artifacts'
 import { generateGlobalCss } from './artifacts/css/global-css'
@@ -17,8 +17,8 @@ import { generateKeyframesSpec } from './spec/keyframes'
 import { generateLayerStylesSpec } from './spec/layer-styles'
 import { generatePatternsSpec } from './spec/patterns'
 import { generateRecipesSpec } from './spec/recipes'
-import { generateSemanticTokensSpec, generateTokensSpec } from './spec/tokens'
 import { generateTextStylesSpec } from './spec/text-styles'
+import { generateSemanticTokensSpec, generateTokensSpec } from './spec/tokens'
 
 export interface SplitCssArtifact {
   type: 'layer' | 'recipe' | 'theme'
@@ -205,33 +205,24 @@ export class Generator extends Context {
     }
   }
 
-  getSpecOfType = (type: SpecType) => {
-    return match(type)
-      .with('tokens', () => generateTokensSpec(this))
-      .with('recipes', () => generateRecipesSpec(this))
-      .with('patterns', () => generatePatternsSpec(this))
-      .with('conditions', () => generateConditionsSpec(this))
-      .with('keyframes', () => generateKeyframesSpec(this))
-      .with('semantic-tokens', () => generateSemanticTokensSpec(this))
-      .with('text-styles', () => generateTextStylesSpec(this))
-      .with('layer-styles', () => generateLayerStylesSpec(this))
-      .with('animation-styles', () => generateAnimationStylesSpec(this))
-      .with('color-palette', () => generateColorPaletteSpec(this))
-      .exhaustive()
-  }
+  getSpec = (): SpecFile[] => {
+    const specs: SpecFile[] = [
+      generateTokensSpec(this),
+      generateRecipesSpec(this),
+      generatePatternsSpec(this),
+      generateConditionsSpec(this),
+      generateKeyframesSpec(this),
+      generateSemanticTokensSpec(this),
+      generateTextStylesSpec(this),
+      generateLayerStylesSpec(this),
+      generateAnimationStylesSpec(this),
+    ]
 
-  getSpec = () => {
-    return {
-      tokens: generateTokensSpec(this),
-      recipes: generateRecipesSpec(this),
-      patterns: generatePatternsSpec(this),
-      conditions: generateConditionsSpec(this),
-      keyframes: generateKeyframesSpec(this),
-      'semantic-tokens': generateSemanticTokensSpec(this),
-      'text-styles': generateTextStylesSpec(this),
-      'layer-styles': generateLayerStylesSpec(this),
-      'animation-styles': generateAnimationStylesSpec(this),
-      'color-palette': generateColorPaletteSpec(this),
+    const colorPaletteSpec = generateColorPaletteSpec(this)
+    if (colorPaletteSpec) {
+      specs.push(colorPaletteSpec)
     }
+
+    return specs
   }
 }
diff --git a/packages/generator/src/spec/color-palette.ts b/packages/generator/src/spec/color-palette.ts
@@ -1,10 +1,21 @@
 import type { Context } from '@pandacss/core'
 import type { ColorPaletteSpec } from '@pandacss/types'
 
-export const generateColorPaletteSpec = (ctx: Context): ColorPaletteSpec => {
+export const generateColorPaletteSpec = (ctx: Context): ColorPaletteSpec | null => {
+  // Don't emit color-palette spec if colorPalette is disabled
+  const colorPaletteConfig = ctx.config.theme?.colorPalette
+  if (colorPaletteConfig?.enabled === false) {
+    return null
+  }
+
   const jsxStyleProps = ctx.config.jsxStyleProps ?? 'all'
   const values = Array.from(ctx.tokens.view.colorPalettes.keys()).sort()
 
+  // If there are no color palettes, don't emit the spec
+  if (!values.length) {
+    return null
+  }
+
   const functionExamples: string[] = [
     `css({ colorPalette: 'blue' })`,
     `css({ colorPalette: 'blue', bg: 'colorPalette.500', color: 'colorPalette.50' })`,
diff --git a/packages/generator/src/spec/tokens.ts b/packages/generator/src/spec/tokens.ts
@@ -1,7 +1,14 @@
 import type { Context } from '@pandacss/core'
 import { walkObject } from '@pandacss/shared'
 import type { Token } from '@pandacss/token-dictionary'
-import type { SemanticTokenSpec, SemanticTokenSpecDefinition, TokenSpec, TokenSpecDefinition } from '@pandacss/types'
+import type {
+  SemanticTokenSpec,
+  SemanticTokenGroupDefinition,
+  SemanticTokenValue,
+  TokenSpec,
+  TokenGroupDefinition,
+  TokenValue,
+} from '@pandacss/types'
 
 const CATEGORY_PROPERTY_MAP: Record<string, string> = {
   colors: 'color',
@@ -56,62 +63,96 @@ const generateTokenExamples = (token: Token, jsxStyleProps: 'all' | 'minimal' |
 
 export const generateTokensSpec = (ctx: Context): TokenSpec => {
   const jsxStyleProps = ctx.config.jsxStyleProps ?? 'all'
-  const tokens = ctx.tokens.allTokens
-    .filter(
-      (token) =>
-        !token.extensions.isSemantic &&
-        !token.extensions.isVirtual &&
-        !token.extensions.conditions &&
-        !token.extensions.isNegative,
-    )
-    .map((token): TokenSpecDefinition => {
-      const { functionExamples, tokenFunctionExamples, jsxExamples } = generateTokenExamples(token, jsxStyleProps)
-      return {
-        name: token.name,
+
+  // Create grouped data structure using tokens.view.categoryMap
+  const groupedData: TokenGroupDefinition[] = Array.from(ctx.tokens.view.categoryMap.entries())
+    .map(([category, tokenMap]) => {
+      // Convert Map values to array and filter
+      const typeTokens = Array.from(tokenMap.values()).filter(
+        (token) =>
+          !token.extensions.isSemantic &&
+          !token.extensions.isVirtual &&
+          !token.extensions.conditions &&
+          !token.extensions.isNegative,
+      )
+
+      // Skip if no tokens after filtering
+      if (!typeTokens.length) return null
+
+      // Get examples from first token of this type (they'll be the same for all)
+      const firstToken = typeTokens[0]
+      const { functionExamples, tokenFunctionExamples, jsxExamples } = generateTokenExamples(firstToken, jsxStyleProps)
+
+      const values: TokenValue[] = typeTokens.map((token) => ({
+        name: token.extensions.prop || token.name,
         value: token.value,
-        type: token.extensions.category,
         description: token.description,
         deprecated: token.deprecated,
         cssVar: token.extensions.varRef,
+      }))
+
+      return {
+        type: category,
+        values,
         tokenFunctionExamples,
         functionExamples,
         jsxExamples,
       }
     })
+    .filter(Boolean) as TokenGroupDefinition[]
 
   return {
     type: 'tokens',
-    data: tokens,
+    data: groupedData,
   }
 }
 
 export const generateSemanticTokensSpec = (ctx: Context): SemanticTokenSpec => {
   const jsxStyleProps = ctx.config.jsxStyleProps ?? 'all'
-  const semanticTokens = ctx.tokens.allTokens
-    .filter((token) => (token.extensions.isSemantic || token.extensions.conditions) && !token.extensions.isVirtual)
-    .map((token): SemanticTokenSpecDefinition => {
-      const { functionExamples, tokenFunctionExamples, jsxExamples } = generateTokenExamples(token, jsxStyleProps)
-      const values: Array<{ value: string; condition?: string }> = []
-
-      walkObject(token.extensions.rawValue, (value, path) => {
-        values.push({ value, condition: path.map((p) => p.replace(/^_/, '')).join('.') })
+
+  // Create grouped data structure using tokens.view.categoryMap
+  const groupedData: SemanticTokenGroupDefinition[] = Array.from(ctx.tokens.view.categoryMap.entries())
+    .map(([category, tokenMap]) => {
+      // Convert Map values to array and filter for semantic tokens
+      const typeTokens = Array.from(tokenMap.values()).filter(
+        (token) => (token.extensions.isSemantic || token.extensions.conditions) && !token.extensions.isVirtual,
+      )
+
+      // Skip if no tokens after filtering
+      if (!typeTokens.length) return null
+
+      // Get examples from first token of this type
+      const firstToken = typeTokens[0]
+      const { functionExamples, tokenFunctionExamples, jsxExamples } = generateTokenExamples(firstToken, jsxStyleProps)
+
+      const values: SemanticTokenValue[] = typeTokens.map((token) => {
+        const conditions: Array<{ value: string; condition?: string }> = []
+
+        walkObject(token.extensions.rawValue, (value, path) => {
+          conditions.push({ value, condition: path.map((p) => p.replace(/^_/, '')).join('.') })
+        })
+
+        return {
+          name: token.extensions.prop || token.name,
+          values: conditions,
+          description: token.description,
+          deprecated: token.deprecated,
+          cssVar: token.extensions.varRef,
+        }
       })
 
       return {
-        name: token.name,
+        type: category,
         values,
-        type: token.extensions.category,
-        description: token.description,
-        deprecated: token.deprecated,
-        cssVar: token.extensions.varRef,
         tokenFunctionExamples,
         functionExamples,
         jsxExamples,
       }
     })
+    .filter(Boolean) as SemanticTokenGroupDefinition[]
 
   return {
     type: 'semantic-tokens',
-    data: semanticTokens,
+    data: groupedData,
   }
 }
diff --git a/packages/node/src/index.ts b/packages/node/src/index.ts
@@ -12,4 +12,4 @@ export { setupGitIgnore } from './git-ignore'
 export { setLogStream } from './logstream'
 export { parseDependency } from './parse-dependency'
 export { setupConfig, setupPostcss } from './setup-config'
-export { spec, isValidSpecType, VALID_SPEC_TYPES } from './spec'
+export { spec } from './spec'
diff --git a/packages/node/src/spec.ts b/packages/node/src/spec.ts
@@ -1,74 +1,31 @@
 import { logger } from '@pandacss/logger'
-import type { ArtifactId, SpecType } from '@pandacss/types'
-import picomatch from 'picomatch'
+import type { ArtifactId, SpecFile } from '@pandacss/types'
 import type { PandaContext } from './create-context'
 
-export const VALID_SPEC_TYPES: SpecType[] = [
-  'tokens',
-  'recipes',
-  'patterns',
-  'conditions',
-  'keyframes',
-  'semantic-tokens',
-  'text-styles',
-  'layer-styles',
-  'animation-styles',
-  'color-palette',
-]
-
-export const isValidSpecType = (value: unknown): value is SpecType => {
-  return typeof value === 'string' && VALID_SPEC_TYPES.includes(value as SpecType)
-}
-
 export interface SpecOptions {
   outdir?: string
-  filter?: string
 }
 
 export async function spec(ctx: PandaContext, options: SpecOptions) {
-  const { outdir, filter } = options
+  const { outdir } = options
 
   const specs = ctx.getSpec()
-  const matcher = filter ? picomatch(filter) : null
-
-  const filterContent = (content: any, specType: string) => {
-    if (!matcher) return content
-    const clone = { ...content }
-
-    if (specType === 'color-palette') {
-      // color-palette has a different structure: data.values is an array
-      clone.data = {
-        ...clone.data,
-        values: clone.data.values.filter((v: string) => matcher(v)),
-      }
-    } else {
-      // All other specs have data as an array of objects with a 'name' property
-      clone.data = clone.data.filter((item: any) => matcher(item.name))
-    }
-    return clone
-  }
 
   // Use ctx.paths.specs (includes configured outdir) or override with provided outdir
   const specDir = outdir ? [ctx.config.cwd, outdir] : ctx.paths.specs
   const specDirPath = ctx.runtime.path.join(...specDir)
 
-  const writeSpec = async (name: string, content: any) => {
-    const filteredContent = filterContent(content, name)
-
+  const writeSpec = async (spec: SpecFile) => {
     await ctx.output.write({
-      id: `spec-${name}` as ArtifactId,
+      id: `spec-${spec.type}` as ArtifactId,
       dir: specDir,
-      files: [{ file: `${name}.json`, code: JSON.stringify(filteredContent, null, 2) }],
+      files: [{ file: `${spec.type}.json`, code: JSON.stringify(spec, null, 2) }],
     })
   }
 
-  await Promise.all(Object.entries(specs as Record<string, any>).map(([key, content]) => writeSpec(key, content)))
-
-  const specTypes = Object.keys(specs as Record<string, any>)
-  const typesList = specTypes.map((t) => `${t}.json`).join(', ')
+  await Promise.all(specs.map(writeSpec))
 
+  const specTypes = specs.map((s) => s.type)
   logger.info('spec', `Generated ${specTypes.length} spec file(s) → ${specDirPath}`)
-  logger.info('spec', `  Types: ${typesList}`)
-
   return specs
 }
diff --git a/packages/types/src/spec.ts b/packages/types/src/spec.ts

Original file line number	Diff line number	Diff line change
`@@ -103,5 +103,4 @@ export interface SpecCommandFlags {`
`103`	`103`	`outdir?: string`
`104`	`104`	`cwd?: string`
`105`	`105`	`config?: string`
`106`		`- filter?: string`
`107`	`106`	`}`