Styled System
What is the styled-system folder and how does it work?
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:
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:
- 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.
- Generating artifacts:
- Write lightweight JS runtime and types to output directory
- 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.