Concepts

styled-system

What is it?

While Panda generates your CSS at build-time using static extraction, we still need a lightweight runtime to transform the CSS-in-JS syntax (either object or template-literal) to class names strings. This is where the styled-system folder comes in.

When running the panda or panda codegen commands, the config.outdir will be used as output path to generate the styled-system in.

This is the core of what the styled-system does:

css({ color: 'blue.300' }) // => "text_blue_300"

Since Panda doesn't rely on any bundler's (vite, webpack, etc) plugin, there is no code transformation happening to convert the CSS-in-JS syntax to class names at compile-time. This is why we need a lightweight runtime to do that.

The same principles applies to patterns, recipes and even jsx components, as they all use the css function under the hood.

If you look inside your styled-system folder, you should see the main entrypoints for the runtime:

  • styled-system

    • Feel free to explore the files inside the styled-system folder to get a better understanding of how it works in details!

    💡

    Note: The styled-system folder is not meant to be edited manually. It is generated by Panda and should be treated as a build artifact. This also means you don't need to commit it to your repository.

    How does it work?

    When running the panda command or with the postcss plugin, here's what's happening under the hood:

    1. Load Panda context:
    • Find and evaluate app config, merge result with presets.
    • Create panda context: prepare code generator from config, parse user's file as AST.
    1. Generating artifacts:
    • Write lightweight JS runtime and types to output directory
    1. Extracting used styles in app code:
    • Run parser on each user's file: identify and extract styles, compute CSS, write to styles.css.

    That 2. Generating artifacts step is where the styled-system folder is generated, using the resolved config that contains all your tokens, patterns, recipes, utilities etc. We generate a tailored runtime for your app, so that it only contains enough code (and types!) to support the styles you're using.

    Pre-rendering

    If you use some way to pre-render your components to static HTML, for example using Astro or RSC, the styled-system functions like css and others will be removed at build-time and replaced by the generated class names, so that you don't have to ship the runtime to your users.

    HooksThe extend keyword