feat(cssgen): splitting

Author: segunadebayo

.changeset/css-splitting-mode.md

@@ -0,0 +1,30 @@
+---
+'@pandacss/node': minor
+'@pandacss/generator': minor
+'@pandacss/cli': minor
+---
+
+Add `--splitting` flag to `cssgen` command for per-layer CSS output.
+
+When enabled, CSS is emitted as separate files instead of a single `styles.css`:
+
+```
+styled-system/
+├── styles.css              # @layer declaration + @imports
+└── styles/
+    ├── reset.css           # Preflight/reset CSS
+    ├── global.css          # Global CSS
+    ├── tokens.css          # Design tokens
+    ├── utilities.css       # Utility classes
+    ├── recipes/
+    │   ├── index.css       # @imports all recipe files
+    │   └── {recipe}.css    # Individual recipe styles
+    └── themes/
+        └── {theme}.css     # Theme tokens (not auto-imported)
+```
+
+Usage:
+
+```bash
+panda cssgen --splitting
+```

packages/cli/src/cli-main.ts

@@ -185,11 +185,12 @@ export async function main() {
     .option('--polyfill', 'Polyfill CSS @layers at-rules for older browsers.')
     .option('-p, --poll', 'Use polling instead of filesystem events when watching')
     .option('-o, --outfile [file]', "Output file for extracted css, default to './styled-system/styles.css'")
+    .option('--splitting', 'Emit CSS as separate files per layer (reset, global, tokens, utilities) and per recipe')
     .option('--cwd <cwd>', 'Current working directory', { default: cwd })
     .option('--cpu-prof', 'Generates a `.cpuprofile` to help debug performance issues')
     .option('--logfile <file>', 'Outputs logs to a file')
     .action(async (maybeGlob?: string, flags: CssGenCommandFlags = {}) => {
-      const { silent, config: configPath, outfile, watch, poll, minimal, ...rest } = flags
+      const { silent, config: configPath, outfile, watch, poll, minimal, splitting, ...rest } = flags
 
       const cwd = resolve(flags.cwd ?? '')
       const stream = setLogStream({ cwd, logfile: flags.logfile })
@@ -225,6 +226,7 @@ export async function main() {
         outfile,
         type: cssArtifact,
         minimal,
+        splitting,
       }
 
       await cssgen(ctx, options)

packages/cli/src/types.ts

@@ -25,6 +25,7 @@ export interface CssGenCommandFlags {
   polyfill?: boolean
   cpuProf?: boolean
   logfile?: string
+  splitting?: boolean
 }
 
 export interface StudioCommandFlags extends Pick<Config, 'cwd'> {

packages/config/src/config-deps.ts

@@ -73,6 +73,9 @@ const artifactConfigDeps: Record<ArtifactId, ConfigPath[]> = {
   themes: ['themes'].concat(tokens),
   // staticCss depends on tokens (for wildcards) and recipes (for recipe rules)
   'static-css': ['staticCss', 'patterns', 'theme.recipes', 'theme.slotRecipes'].concat(tokens),
+  // Split CSS artifacts (generated via cssgen --splitting)
+  styles: [],
+  'styles.css': [],
 }
 
 // Prepare a list of regex that resolves to an artifact id from a list of config paths

packages/core/src/stylesheet.ts

@@ -94,6 +94,29 @@ export class Stylesheet {
     })
   }
 
+  /**
+   * Process only the styles for a specific recipe from the decoder
+   */
+  processDecoderForRecipe = (decoder: StyleDecoder, recipeName: string) => {
+    const recipeSet = decoder.recipes.get(recipeName)
+    if (recipeSet) {
+      recipeSet.forEach((recipe) => {
+        this.processCss(recipe.result, recipe.entry.slot ? 'recipes_slots' : 'recipes')
+      })
+    }
+
+    // Process recipe base styles (may include slot-specific keys like "button__root")
+    decoder.recipes_base.forEach((baseSet, recipeKey) => {
+      // recipeKey could be "button" or "button__root" for slot recipes
+      const [baseRecipeName] = recipeKey.split('__')
+      if (baseRecipeName === recipeName) {
+        baseSet.forEach((recipe) => {
+          this.processCss(recipe.result, recipe.slot ? 'recipes_slots_base' : 'recipes_base')
+        })
+      }
+    })
+  }
+
   getLayerCss = (...layers: CascadeLayer[]) => {
     const breakpoints = this.context.conditions.breakpoints
     return optimizeCss(

packages/generator/src/artifacts/js/themes.ts

@@ -6,38 +6,42 @@ import { stringifyVars } from '../css/token-css'
 
 const getThemeId = (themeName: string) => 'panda-theme-' + themeName
 
-export function generateThemes(ctx: Context) {
-  const { themes } = ctx.config
-  if (!themes) return
-
+/**
+ * Get CSS for a specific theme
+ */
+export function getThemeCss(ctx: Context, themeName: string): string {
   const { tokens, conditions } = ctx
-
-  return Object.entries(themes).map(([name, _themeVariant]) => {
-    const results = [] as string[]
-    const condName = ctx.conditions.getThemeName(name)
-
-    for (const [key, values] of tokens.view.vars.entries()) {
-      if (key.startsWith(condName)) {
-        const css = stringifyVars({ values, conditionKey: key, root: '', conditions })
-        if (css) {
-          results.push(css)
-        }
+  const results: string[] = []
+  const condName = conditions.getThemeName(themeName)
+
+  for (const [key, values] of tokens.view.vars.entries()) {
+    if (key.startsWith(condName)) {
+      const css = stringifyVars({ values, conditionKey: key, root: '', conditions })
+      if (css) {
+        results.push(css)
       }
     }
+  }
 
-    return {
-      name: `theme-${name}`,
-      json: JSON.stringify(
-        compact({
-          name,
-          id: getThemeId(name),
-          css: results.join('\n\n'),
-        }),
-        null,
-        2,
-      ),
-    }
-  })
+  return results.join('\n\n')
+}
+
+export function generateThemes(ctx: Context) {
+  const { themes } = ctx.config
+  if (!themes) return
+
+  return Object.entries(themes).map(([name, _themeVariant]) => ({
+    name: `theme-${name}`,
+    json: JSON.stringify(
+      compact({
+        name,
+        id: getThemeId(name),
+        css: getThemeCss(ctx, name),
+      }),
+      null,
+      2,
+    ),
+  }))
 }
 
 export function generateThemesIndex(ctx: Context, files: ReturnType<typeof generateThemes>) {

packages/generator/src/generator.ts

@@ -1,5 +1,5 @@
 import { Context, type StyleDecoder, type Stylesheet } from '@pandacss/core'
-import { PandaError } from '@pandacss/shared'
+import { dashCase, PandaError } from '@pandacss/shared'
 import type { ArtifactId, CssArtifactType, LoadConfigResult } from '@pandacss/types'
 import { match } from 'ts-pattern'
 import { generateArtifacts } from './artifacts'
@@ -9,6 +9,29 @@ import { generateParserCss } from './artifacts/css/parser-css'
 import { generateResetCss } from './artifacts/css/reset-css'
 import { generateStaticCss } from './artifacts/css/static-css'
 import { generateTokenCss } from './artifacts/css/token-css'
+import { getThemeCss } from './artifacts/js/themes'
+
+export interface SplitCssArtifact {
+  type: 'layer' | 'recipe' | 'theme'
+  name: string
+  file: string
+  code: string
+  /** Directory relative to styles/ */
+  dir?: string
+}
+
+export interface SplitCssResult {
+  /** Layer CSS files (reset, global, tokens, utilities) */
+  layers: SplitCssArtifact[]
+  /** Recipe CSS files */
+  recipes: SplitCssArtifact[]
+  /** Theme CSS files (not auto-imported) */
+  themes: SplitCssArtifact[]
+  /** Content for recipes/index.css */
+  recipesIndex: string
+  /** Content for main styles.css */
+  index: string
+}
 
 export class Generator extends Context {
   constructor(conf: LoadConfigResult) {
@@ -65,4 +88,111 @@ export class Generator extends Context {
 
     return css
   }
+
+  /**
+   * Get CSS for a specific layer from the stylesheet
+   */
+  getLayerCss = (sheet: Stylesheet, layer: 'reset' | 'base' | 'tokens' | 'recipes' | 'utilities') => {
+    return sheet.getLayerCss(layer)
+  }
+
+  /**
+   * Get CSS for a specific recipe
+   */
+  getRecipeCss = (recipeName: string) => {
+    const sheet = this.createSheet()
+    const decoder = this.decoder.collect(this.encoder)
+    sheet.processDecoderForRecipe(decoder, recipeName)
+    return sheet.getLayerCss('recipes')
+  }
+
+  /**
+   * Get all recipe names from the decoder
+   */
+  getRecipeNames = () => {
+    const decoder = this.decoder.collect(this.encoder)
+    return Array.from(decoder.recipes.keys())
+  }
+
+  /**
+   * Get all split CSS artifacts for the stylesheet
+   * Used when --splitting flag is enabled
+   */
+  getSplitCssArtifacts = (sheet: Stylesheet): SplitCssResult => {
+    const layerNames = this.config.layers as Record<string, string>
+    const decoder = this.decoder.collect(this.encoder)
+
+    // Layer artifacts
+    const layerDefs = [
+      { name: 'reset', file: 'reset.css', css: sheet.getLayerCss('reset') },
+      { name: 'global', file: 'global.css', css: sheet.getLayerCss('base') },
+      { name: 'tokens', file: 'tokens.css', css: sheet.getLayerCss('tokens') },
+      { name: 'utilities', file: 'utilities.css', css: sheet.getLayerCss('utilities') },
+    ]
+
+    const layers: SplitCssArtifact[] = layerDefs
+      .filter((l) => l.css.trim())
+      .map((l) => ({
+        type: 'layer' as const,
+        name: l.name,
+        file: l.file,
+        code: l.css,
+      }))
+
+    // Recipe artifacts
+    const recipes: SplitCssArtifact[] = []
+    for (const recipeName of decoder.recipes.keys()) {
+      const recipeSheet = this.createSheet()
+      recipeSheet.processDecoderForRecipe(decoder, recipeName)
+      const code = recipeSheet.getLayerCss('recipes')
+      if (code.trim()) {
+        recipes.push({
+          type: 'recipe',
+          name: recipeName,
+          file: `${dashCase(recipeName)}.css`,
+          code,
+          dir: 'recipes',
+        })
+      }
+    }
+
+    // Theme artifacts (not auto-imported in styles.css)
+    const themes: SplitCssArtifact[] = []
+    if (this.config.themes) {
+      for (const themeName of Object.keys(this.config.themes)) {
+        const css = getThemeCss(this, themeName)
+        if (css.trim()) {
+          themes.push({
+            type: 'theme',
+            name: themeName,
+            file: `${dashCase(themeName)}.css`,
+            code: `@layer ${layerNames.tokens} {\n${css}\n}`,
+            dir: 'themes',
+          })
+        }
+      }
+    }
+
+    // Build recipes/index.css content
+    const recipesIndex = recipes.map((r) => `@import './${r.file}';`).join('\n')
+
+    // Build main styles.css content
+    const layerOrder = [layerNames.reset, layerNames.base, layerNames.tokens, layerNames.recipes, layerNames.utilities]
+    const imports = [`@layer ${layerOrder.join(', ')};`, '']
+
+    for (const layer of layers) {
+      imports.push(`@import './styles/${layer.file}';`)
+    }
+    if (recipes.length) {
+      imports.push(`@import './styles/recipes/index.css';`)
+    }
+
+    return {
+      layers,
+      recipes,
+      themes,
+      recipesIndex,
+      index: imports.join('\n'),
+    }
+  }
 }

packages/generator/src/index.ts

@@ -1 +1,2 @@
 export * from './generator'
+export { getThemeCss } from './artifacts/js/themes'

packages/node/src/create-context.ts

@@ -110,12 +110,68 @@ export class PandaContext extends Generator {
   writeCss = (sheet?: Stylesheet) => {
     logger.info('css', this.runtime.path.join(...this.paths.root, 'styles.css'))
     return this.output.write({
-      id: 'styles.css' as any,
+      id: 'styles.css',
       dir: this.paths.root,
       files: [{ file: 'styles.css', code: this.getCss(sheet) }],
     })
   }
 
+  writeSplitCss = async (sheet: Stylesheet) => {
+    const { path: pathUtil, fs } = this.runtime
+    const rootDir = this.paths.root
+    const stylesDir = [...rootDir, 'styles']
+
+    // Get all artifacts from the generator
+    const artifacts = this.getSplitCssArtifacts(sheet)
+
+    // Derive and create directories from artifacts
+    const subDirs = new Set([...artifacts.recipes, ...artifacts.themes].map((a) => a.dir).filter(Boolean))
+    fs.ensureDirSync(pathUtil.join(...stylesDir))
+    subDirs.forEach((dir) => fs.ensureDirSync(pathUtil.join(...stylesDir, dir!)))
+
+    // Collect all files for batched write
+    const styleFiles: Array<{ file: string; code: string }> = []
+
+    // Layer files
+    for (const layer of artifacts.layers) {
+      styleFiles.push({ file: layer.file, code: layer.code })
+      logger.info('css', pathUtil.join(...stylesDir, layer.file))
+    }
+
+    // Recipe files
+    for (const recipe of artifacts.recipes) {
+      styleFiles.push({ file: `${recipe.dir}/${recipe.file}`, code: recipe.code })
+      logger.info('css', pathUtil.join(...stylesDir, recipe.dir!, recipe.file))
+    }
+
+    // Recipes index
+    if (artifacts.recipes.length) {
+      styleFiles.push({ file: `${artifacts.recipes[0].dir}/index.css`, code: artifacts.recipesIndex })
+      logger.info('css', pathUtil.join(...stylesDir, artifacts.recipes[0].dir!, 'index.css'))
+    }
+
+    // Theme files
+    for (const theme of artifacts.themes) {
+      styleFiles.push({ file: `${theme.dir}/${theme.file}`, code: theme.code })
+      logger.info('css', pathUtil.join(...stylesDir, theme.dir!, theme.file))
+    }
+
+    // Write all split files to styles/ directory
+    await this.output.write({
+      id: 'styles',
+      dir: stylesDir,
+      files: styleFiles,
+    })
+
+    // Write main styles.css
+    logger.info('css', pathUtil.join(...rootDir, 'styles.css'))
+    await this.output.write({
+      id: 'styles.css',
+      dir: rootDir,
+      files: [{ file: 'styles.css', code: artifacts.index }],
+    })
+  }
+
   watchConfig = (cb: (file: string) => void | Promise<void>, opts?: Omit<WatchOptions, 'include'>) => {
     const { cwd, poll, exclude } = opts ?? {}
     logger.info('ctx:watch', this.messages.configWatch())