feat(cli): add minimal cssgen output

Author: segunadebayo

V2_MIGRATION.md

@@ -285,8 +285,19 @@ means you can annotate an exported inline recipe with only its variant keys and
 import { cva } from 'styled-system/css'
 import type { RecipeRuntimeFn } from 'styled-system/types'
 
-export const button: RecipeRuntimeFn<{ visual?: 'solid' | 'outline' }> =
-  cva({ base: { px: '4' }, variants: { visual: { solid: { /* css */ }, outline: { /* css */ } } } })
+export const button: RecipeRuntimeFn<{ visual?: 'solid' | 'outline' }> = cva({
+  base: { px: '4' },
+  variants: {
+    visual: {
+      solid: {
+        /* css */
+      },
+      outline: {
+        /* css */
+      },
+    },
+  },
+})
 ```
 
 The same works for `styled(tag, {...})` via `StyledComponent<Tag, Props>` and for `sva` via `SlotRecipeRuntimeFn`. This
@@ -413,6 +424,22 @@ Logging flags are consolidated: use `--log-level silent|error|warn|info|debug` i
 
 ---
 
+## CSS output for monorepos
+
+v2 keeps `panda cssgen --minimal` for packages that should emit usage CSS without duplicating foundation CSS. It writes
+recipes and utilities only; reset, base, and tokens should be emitted once by the app/root build.
+
+Recommended monorepo workflow:
+
+1. **App/root:** run a normal `panda build` or `panda cssgen` to emit the full stylesheet once.
+2. **Per package:** run `panda cssgen --minimal` to emit package-local usage CSS.
+3. **Published design systems:** ship `panda buildinfo` and hydrate in consumers (see `design-notes/build-info.md`).
+
+The v1 positional layer names (`preflight`, `global`, `tokens`, …) and positional glob override are not part of the v2
+CLI surface yet.
+
+---
+
 ## Still being finalized
 
 Known gaps in the beta. Expect them to change before stable:
@@ -424,8 +451,6 @@ Known gaps in the beta. Expect them to change before stable:
 - **CSS minification.** `minify: true` works in the native emitter; full parity with the v1 LightningCSS path is still
   open.
 - **PostCSS plugin.** Experimental (above).
-- **CLI `[files]` override.** The v1 positional include override for `panda build` isn't wired yet. The build uses the
-  config `include`.
 
 ---
 

bench/__tests__/edgecases.test.ts

@@ -106,7 +106,7 @@ test('emitter parity battery', () => {
     try {
       const compiler = createCompilerFromSnapshot(snapshot, { crossFile: true }) as any
       compiler.parseFileSource(path, src)
-      v2 = fmt(compiler.layerCss(['recipes', 'utilities']) ?? '')
+      v2 = fmt(compiler.getLayerCss({ layers: ['recipes', 'utilities'] }).css ?? '')
     } catch (e) {
       v2 = `V2_ERROR: ${(e as Error).message}`
     }

crates/pandacss_stylesheet/src/lib.rs

@@ -36,6 +36,9 @@ pub struct StylesheetOptions {
     pub include_static: bool,
     pub source_map: bool,
     pub emit_layer_declaration: bool,
+    /// When set, `split_css` emits only the selected layers (and rebuilds the
+    /// index `@layer` preamble + `@import` lines to match).
+    pub layers: Option<Vec<StylesheetLayer>>,
 }
 
 impl Default for StylesheetOptions {
@@ -45,6 +48,7 @@ impl Default for StylesheetOptions {
             include_static: false,
             source_map: false,
             emit_layer_declaration: true,
+            layers: None,
         }
     }
 }
@@ -296,6 +300,10 @@ pub fn split_css(input: &StylesheetInput<'_>, options: &StylesheetOptions) -> Ve
         true,
     );
 
+    let selected = options.layers.as_deref();
+    let layer_selected =
+        |layer: StylesheetLayer| selected.is_none_or(|layers| layers.contains(&layer));
+
     let mut files: Vec<SplitCssFile> = Vec::new();
     let mut imports: Vec<String> = Vec::new();
 
@@ -305,6 +313,9 @@ pub fn split_css(input: &StylesheetInput<'_>, options: &StylesheetOptions) -> Ve
         (StylesheetLayer::Tokens, "tokens.css"),
         (StylesheetLayer::Utilities, "utilities.css"),
     ] {
+        if !layer_selected(layer) {
+            continue;
+        }
         let css = full
             .layer_ranges
             .get(layer)
@@ -319,38 +330,51 @@ pub fn split_css(input: &StylesheetInput<'_>, options: &StylesheetOptions) -> Ve
         }
     }
 
-    let recipe_files = emitter::emit_recipe_split(input.config, &utility, recipes, options.minify);
-    if !recipe_files.is_empty() {
-        let mut recipe_imports = Vec::with_capacity(recipe_files.len());
-        for (name, css) in &recipe_files {
-            recipe_imports.push(format!("@import './recipes/{name}.css';"));
+    if layer_selected(StylesheetLayer::Recipes) {
+        let recipe_files =
+            emitter::emit_recipe_split(input.config, &utility, recipes, options.minify);
+        if !recipe_files.is_empty() {
+            let mut recipe_imports = Vec::with_capacity(recipe_files.len());
+            for (name, css) in &recipe_files {
+                recipe_imports.push(format!("@import './recipes/{name}.css';"));
+                files.push(SplitCssFile {
+                    path: format!("styles/recipes/{name}.css"),
+                    code: ensure_trailing_newline(css),
+                });
+            }
             files.push(SplitCssFile {
-                path: format!("styles/recipes/{name}.css"),
-                code: ensure_trailing_newline(css),
+                path: "styles/recipes.css".to_owned(),
+                code: format!("{}\n", recipe_imports.join("\n")),
             });
+            imports.push("@import './styles/recipes.css';".to_owned());
         }
-        files.push(SplitCssFile {
-            path: "styles/recipes.css".to_owned(),
-            code: format!("{}\n", recipe_imports.join("\n")),
-        });
-        imports.push("@import './styles/recipes.css';".to_owned());
     }
 
-    for (theme_name, css) in
-        theme_css_entries_from_dictionary(input.config, token_dictionary.as_deref(), options.minify)
-    {
-        if css.trim().is_empty() {
-            continue;
+    if layer_selected(StylesheetLayer::Tokens) {
+        for (theme_name, css) in theme_css_entries_from_dictionary(
+            input.config,
+            token_dictionary.as_deref(),
+            options.minify,
+        ) {
+            if css.trim().is_empty() {
+                continue;
+            }
+            files.push(SplitCssFile {
+                path: format!("styles/themes/{}.css", file_stem(&theme_name)),
+                code: ensure_trailing_newline(&css),
+            });
         }
-        files.push(SplitCssFile {
-            path: format!("styles/themes/{}.css", file_stem(&theme_name)),
-            code: ensure_trailing_newline(&css),
-        });
     }
 
     // `styles.css` entry: the @layer order declaration + the imports above.
-    let mut index = layer_order_line(&input.config.layers);
-    index.push('\n');
+    let mut index = if options.emit_layer_declaration {
+        layer_order_declaration(&input.config.layers, selected)
+    } else {
+        String::new()
+    };
+    if !index.is_empty() {
+        index.push('\n');
+    }
     if !imports.is_empty() {
         index.push_str(&imports.join("\n"));
         index.push('\n');
@@ -441,13 +465,37 @@ fn ensure_trailing_newline(css: &str) -> String {
     }
 }
 
-fn layer_order_line(layers: &pandacss_config::CascadeLayers) -> String {
-    let names = layers.declaration_names();
+/// Return the cascade layer order declaration for all configured layers or a
+/// selected subset.
+#[must_use]
+pub fn layer_order_declaration(
+    layers: &pandacss_config::CascadeLayers,
+    selected: Option<&[StylesheetLayer]>,
+) -> String {
+    let names: Vec<String> = layers
+        .ordered()
+        .iter()
+        .filter_map(|(semantic, name)| {
+            let layer = StylesheetLayer::from_name(semantic)?;
+            selected
+                .is_none_or(|selected_layers| selected_layers.contains(&layer))
+                .then(|| (*name).to_owned())
+        })
+        .collect();
+    if names.is_empty() {
+        return String::new();
+    }
+    if names.len() <= 3 {
+        return format!("@layer {};", names.join(", "));
+    }
+    if names.len() == 4 {
+        return format!("@layer {},\n       {};", names[..3].join(", "), names[3]);
+    }
     format!(
         "@layer {},\n       {},\n       {};",
         names[..3].join(", "),
         names[3..names.len() - 1].join(", "),
-        names.last().expect("layer declaration names")
+        names[names.len() - 1]
     )
 }
 

crates/pandacss_stylesheet/tests/common/mod.rs

@@ -58,7 +58,11 @@ pub fn compile_output(
 }
 
 #[allow(dead_code)]
-pub fn split_output(config: &UserConfig, source: &str) -> Vec<pandacss_stylesheet::SplitCssFile> {
+pub fn split_output(
+    config: &UserConfig,
+    source: &str,
+    options: StylesheetOptions,
+) -> Vec<pandacss_stylesheet::SplitCssFile> {
     let system = System::new(config.clone()).expect("valid project");
     let mut project = Project::new(system);
     project.parse_file("/style.ts", source);
@@ -76,7 +80,7 @@ pub fn split_output(config: &UserConfig, source: &str) -> Vec<pandacss_styleshee
         },
         &StylesheetOptions {
             include_static: true,
-            ..Default::default()
+            ..options
         },
     )
 }

crates/pandacss_stylesheet/tests/split.rs

@@ -1,6 +1,7 @@
 use insta::assert_snapshot;
 
 use crate::common::{config, split_output};
+use pandacss_stylesheet::{StylesheetLayer, StylesheetOptions};
 
 /// Render the split file set as `=== path ===\n<code>` blocks for snapshotting.
 fn render(files: &[pandacss_stylesheet::SplitCssFile]) -> String {
@@ -34,6 +35,7 @@ fn splits_layers_and_recipes_into_files_with_indexes() {
     let files = split_output(
         &config,
         "import { css } from '@panda/css'\nimport { button } from '@panda/recipes'\ncss({ color: 'red' })\nbutton({ size: 'sm' })",
+        StylesheetOptions::default(),
     );
     assert_snapshot!(render(&files), @"
     === styles.css ===
@@ -85,6 +87,41 @@ fn splits_layers_and_recipes_into_files_with_indexes() {
     ");
 }
 
+#[test]
+fn split_css_with_layer_filter_skips_unselected_files() {
+    let config = config(serde_json::json!({
+        "importMap": { "css": ["@panda/css"], "recipe": [], "pattern": [], "jsx": [], "tokens": ["@panda/tokens"] },
+        "theme": {
+            "tokens": { "colors": { "red": { "value": "#f00" } } }
+        },
+        "utilities": {
+            "color": { "className": "c", "values": "colors" }
+        }
+    }));
+    let source = "import { css } from '@panda/css'\ncss({ color: 'red' })";
+    let files = split_output(
+        &config,
+        source,
+        StylesheetOptions {
+            layers: Some(vec![StylesheetLayer::Utilities]),
+            emit_layer_declaration: false,
+            ..StylesheetOptions::default()
+        },
+    );
+
+    assert_snapshot!(render(&files), @"
+    === styles.css ===
+    @import './styles/utilities.css';
+
+    === styles/utilities.css ===
+    @layer utilities {
+      .c_red {
+        color: var(--colors-red);
+      }
+    }
+    ");
+}
+
 #[test]
 fn split_css_emits_theme_files() {
     let config = config(serde_json::json!({
@@ -105,7 +142,7 @@ fn split_css_emits_theme_files() {
             }
         }
     }));
-    let files = split_output(&config, "");
+    let files = split_output(&config, "", StylesheetOptions::default());
 
     assert!(
         files

design-notes/cli.md

@@ -226,7 +226,7 @@ Open gaps that stay outside the current CLI surface:
 
 - `studio` and `analyze` are not ported.
 - `ship` / `emit-pkg` is not ported.
-- the v1 positional `[files]` override is not wired.
+- v1 positional layer type arguments are intentionally not ported. `cssgen --minimal` covers usage-only package CSS.
 - lightningcss minify parity is still an open follow-up.
 
 Those gaps are intentional for now; the CLI prefers a smaller, reliable surface over a partial legacy clone.

design-notes/output-and-host-layer.md

@@ -75,8 +75,8 @@ Three principles fall out of this:
 2. **CSS gen and artifact gen are distinct operations on distinct cadences** — mirroring v1's `panda cssgen` vs
    `panda codegen`. Artifacts regenerate rarely (config change); CSS regenerates every build. The Driver exposes them as
    separate methods, never a combined "build everything." CSS itself has three forms: `compile()` (the merged
-   stylesheet), `compiler.layerCss(layers)` (a merged subset string — `cssgen <type>` / `--minimal`), and
-   `compiler.splitCss()` (the `{path,code}[]` file set — `cssgen --splitting`; written like artifacts). See
+   stylesheet), `compiler.getLayerCss(options)` (a merged subset string — `cssgen --minimal`), and
+   `compiler.getSplitCss()` (the `{path,code}[]` file set — `cssgen --splitting`; written like artifacts). See
    [stylesheet](./stylesheet.md).
 3. **Reads + artifact writes via the engine; CSS routing via the host.** Source discovery + reading run through the
    Rust `pandacss_fs` engine (`scan`/`glob`/`sources`). Artifact *writing* also goes through the engine fs

packages/cli/__tests__/buildinfo.test.ts

@@ -120,7 +120,7 @@ describe('buildinfo command', () => {
         "ok": true,
       }
     `)
-    expect(consumer.compiler.layerCss(['utilities'])).toMatchInlineSnapshot(`
+    expect(consumer.compiler.getLayerCss({ layers: ['utilities'] }).css).toMatchInlineSnapshot(`
       "@layer utilities {
         .background_blue {
           background: blue;
@@ -143,7 +143,7 @@ describe('buildinfo command', () => {
 
     expect(applied.modules).toEqual(['button.tsx'])
     // button's `color: red` hydrated; card's `background: blue` tree-shaken out.
-    expect(consumer.compiler.layerCss(['utilities'])).toMatchInlineSnapshot(`
+    expect(consumer.compiler.getLayerCss({ layers: ['utilities'] }).css).toMatchInlineSnapshot(`
       "@layer utilities {
         .color_red {
           color: red;

packages/cli/__tests__/cli-smoke.test.ts

@@ -85,13 +85,22 @@ describe('cli smoke', () => {
     expect(result.stdout).not.toContain('validate')
   })
 
-  it.each(['build', 'dev', 'check', 'info', 'doctor'])('prints help for panda %s', (command) => {
+  it.each(['build', 'dev', 'check', 'info', 'doctor', 'cssgen'])('prints help for panda %s', (command) => {
     const result = runCli([command, '--help'])
 
     expect(result.exitCode).toBe(0)
     expect(result.stdout).toContain(`panda ${command} v${version}`)
   })
 
+  it('documents cssgen --minimal', () => {
+    const result = runCli(['cssgen', '--help'])
+
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain('--minimal')
+    expect(result.stdout).toContain('--minify')
+    expect(result.stdout).toContain('Emit usage CSS only')
+  })
+
   it.each(['inspect', 'validate', 'frobnicate'])('rejects unknown command %s', (command) => {
     const result = runCli([command])