feat: first-class design system support

[Adebesin-Cell]

📝 Description

first-class design system support in panda. one config field for consumers (designSystem), one CLI command for lib authors (panda lib), and a manifest that records the chain so intermediate libs never reach into a parent's node_modules.

⛳️ Current behavior (updates)

a consumer of a panda design system has to coordinate four config fields by hand:

import { acmePreset } from '@acme/lib/preset'

defineConfig({
  presets: ['@pandacss/dev/presets', acmePreset],
  importMap: '@acme/styled-system',
  outdir: '@acme/styled-system',
  include: [
    './src/**/*.{ts,tsx}',
    './node_modules/@acme/lib/dist/panda.buildinfo.json',
  ],
})

and intermediate libs in a chain (marketing-ds extending foundations) had to do the same — import { foundationsPreset } from '@acme/foundations/preset' baked into the lib's source. that's the very node_modules reach-in the feature is meant to remove.

lib authors also ran a three-step build:

panda codegen && panda ship && panda emit-pkg

…and hand-wrote panda.lib.json on top.

🚀 New behavior

lib author flow. one command:

panda lib

produces dist/:

• panda.buildinfo.json (replaces panda ship)
• panda.lib.json — manifest including a designSystem field that records the lib's own parent (set when the lib's panda.config.ts declared one)
• preset.mjs — compiled preset (consumers don't need source .ts shipped)
• patched package.json exports including ./preset → ./dist/preset.mjs

panda lib --watch rebuilds on src/ changes.

consumer flow. one field:

defineConfig({
  designSystem: '@acme/lib',
  include: ['./src/**/*.{ts,tsx}'],
})

replaces the four-knob coordination. encoder hydrates from the lib's buildinfo automatically; preset, importMap, and buildinfo path all come from the manifest.

chain composition via manifest walk. intermediate libs declare their parent the same way:

// lib-mid/panda.config.ts
defineConfig({
  designSystem: '@acme/lib',         // record parent in this lib's manifest
  presets: ['@pandacss/dev/presets', midPreset],
  outdir: './styled-system',
})

// lib-mid/preset.ts — declares only mid's own additions
export const midPreset = definePreset({ ... })

panda lib writes that designSystem into panda.lib.json. getResolvedConfig walks the chain by reading each level's manifest — resolving each parent against the previous manifest's directory, not the initial consumer cwd, so transitive parents (chain-N → chain-(N-1) → ... → chain-0) work even when the consumer only depends on the immediate parent.

each lib's preset.ts declares only its own additions. no import { parentPreset } from '@parent/preset'. clean per-lib boundaries.

smart include. bare specifiers in include resolve via Node module resolution. libs without a panda.lib.json get auto-globbed via package.json#files. libs with a panda.lib.json throw — they belong under designSystem, not include. the two fields answer different questions (designSystem = "what's in my design language?", include = "which files use it?"), and silently accepting the wrong shape hid the distinction. errors are batched per getFiles() call, so a config with several misplaced entries surfaces all of them at once instead of failing on the first.

manifest version guard. panda.lib.json carries a schemaVersion. the reader now exact-matches against a single shared constant (CURRENT_LIB_MANIFEST_VERSION in @pandacss/types), with directional error messages:

• consumer is newer than the lib (schemaVersion < current) → "rebuild the lib with panda lib, or downgrade this project to match"
• consumer is older than the lib (schemaVersion > current) → "upgrade @pandacss/dev in this project, or rebuild the lib with the matching version"

lib → consumer propagation. the consumer's panda used to ignore the lib's panda.buildinfo.json and panda.lib.json once it had hydrated them at startup. now those resolved paths are pushed onto explicitDeps, so watchConfig picks them up automatically. this closes the loop for every distribution shape:

• monorepo, lib in panda lib --watch → buildinfo rewrites → consumer's panda --watch regenerates css.
• standalone consumer, pnpm update @acme/lib → pnpm writes new files into node_modules/@acme/lib/dist/ → file watcher fires → regen.
• ci-style, single panda codegen after install → no watcher needed; the next codegen reads the new files fresh.

lib version, on the consumer side. panda doesn't enforce, suggest, or check lib versions — the consumer's package.json and lockfile are the only source of truth. no registry calls, no "upgrade nudge", no panda outdated. staying on @acme/lib@1.0.0 forever is a fully supported choice.

what panda does do is emit a one-line backward-looking receipt when the lib's version changed between codegen runs:

[designSystem] @acme/lib: 1.0.0 → 1.1.0

state is persisted at <outdir>/panda.designsystem-state.json. nothing scary, nothing networked — just a receipt so a consumer who suddenly sees different css can correlate it with the bump they ran earlier.

💣 Is this a breaking change (Yes/No):

Yes.

• panda ship and panda emit-pkg are removed. migration is one command — panda lib does both.
• presetExport in the manifest replaces the older heuristic for finding which preset a module exports. existing v1 manifests still work via the default-export fallback.

migration:

# v1
panda codegen && panda ship && panda emit-pkg

# v2
panda lib

📝 Additional Information

• panda lib compiles preset.ts → dist/preset.mjs via esbuild (packages: 'external'). the chain's parent ref is read from panda.config.ts designSystem at panda lib time and persisted into the emitted manifest.
• three sandbox fixtures land alongside, all in real-world shape (no shared workspace styled-system package; each consumer emits its own local ./styled-system/ via outdir):
  • sandbox/v2-ds-example — 1-to-1 lib → app
  • sandbox/v2-ds-fixture — depth-3 chain (lib → lib-mid → lib-leaf → app)
  • sandbox/v2-ds-stress — depth-7 chain (chain-0 … chain-6) + a separate atlas-lib branch wrapping preset-atlaskit, plus a chain-3-alt sibling that shares chain-2 to verify tree-walk semantics
• strictTokens: true enabled on app demos so the manifest-walked type surface actually enforces at the IDE.
• supersedes feat: first-class design system support #3536.

test plan

• pnpm test packages/core/__tests__/atomic-rule.test.ts — sacred CSS snapshot, no changes
• pnpm test packages/{core,node,config,cli,parser} — green (125 in config+node)
• depth-1 fixture: panda lib in v2-ds-example/lib produces manifest + buildinfo + compiled preset; consumer extracts CSS with all tokens + recipes
• depth-3 fixture: panda lib at L1/L2/L3 of v2-ds-fixture produces 5 → 8 → 12 hashes; consumer override beats every level (--colors-brand: #ff00ff); L1's acmeFade keyframe propagates through the full chain
• depth-7 stress: 7-deep chain composes end-to-end via manifest walk; consumer sees tier0card…tier6card recipes
• sibling-branch verification: chain-3-alt shares parent with chain-3; each leaf walks back to chain-0 picking up only its own ancestors (no cross-pollution)
• non-panda lib in include (smart-include): @v2-ds-example/charts (no manifest) gets auto-globbed; its styles land in consumer CSS
• panda lib in include (hard separation): throws with a directive to use designSystem; multiple misplaced entries report together in a single error
• propagation: manifest + buildinfo paths surface on explicitDeps, so the consumer's watcher rebuilds when the lib rewrites them
• version drift receipt: first hydrate writes state without logging; bumped version on second hydrate logs prev → next exactly once
• manifest schemaVersion guard: older / newer manifest throws with a directional message; matching version passes through

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
panda-docs	Error		May 21, 2026 9:35am

[vercel]

@Adebesin-Cell is attempting to deploy a commit to the Chakra UI Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

🦋 Changeset detected

Latest commit: 45f3910

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 29 packages

Name	Type
@pandacss/dev	Major
@pandacss/node	Major
@pandacss/types	Major
@pandacss/config	Major
@v2-ds-stress/app	Patch
@v2-ds-stress/atlas-lib	Patch
@pandacss/bench	Major
@pandacss/astro-plugin-studio	Major
@pandacss/mcp	Major
@pandacss/postcss	Major
@pandacss/core	Major
@pandacss/generator	Major
@pandacss/logger	Major
@pandacss/parser	Major
@pandacss/plugin-lightningcss	Major
@pandacss/plugin-svelte	Major
@pandacss/plugin-vue	Major
@pandacss/preset-atlaskit	Major
@pandacss/preset-base	Major
@pandacss/preset-open-props	Major
@pandacss/preset-panda	Major
@pandacss/reporter	Major
@pandacss/studio	Major
@pandacss/token-dictionary	Major
@pandacss/binding-wasm	Major
@pandacss/binding	Major
@pandacss/extractor	Major
@pandacss/is-valid-prop	Major
@pandacss/shared	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR