{"owner":"chakra-ui","repo":"panda","hasSkills":true,"totalSkillsCount":131,"totalTokensCount":56557,"categories":["subagent-persona","anthropic-skill","claude-rule","plugin-manifest","cursor-rule"],"hasMcp":true,"mcpConfig":{"mcpServers":{"panda":{"command":"npx","args":["-y","@modelcontextprotocol/server-panda"]}}},"found":[".claude/agents/panda-preset-creator.md",".claude/agents/cli-design-expert.md",".claude/agents/js-architecture-critic.md","packages/types/CHANGELOG.md","packages/types/package.json","packages/types/tsconfig.json","CLAUDE.md","packages/studio/CHANGELOG.md","packages/studio/package.json","packages/studio/tsconfig.json","packages/shared/CHANGELOG.md","packages/shared/package.json","packages/shared/tsconfig.json","packages/reporter/CHANGELOG.md","packages/reporter/package.json","packages/reporter/tsconfig.json","packages/preset-panda/CHANGELOG.md","packages/preset-panda/package.json","packages/preset-panda/tsconfig.json","packages/preset-open-props/CHANGELOG.md","packages/preset-open-props/package.json","packages/preset-open-props/tsconfig.json","packages/preset-base/CHANGELOG.md","packages/preset-base/package.json","packages/preset-base/tsconfig.json","packages/preset-atlaskit/CHANGELOG.md","packages/preset-atlaskit/package.json","packages/preset-atlaskit/tsconfig.json","packages/postcss/CHANGELOG.md","packages/postcss/package.json","packages/postcss/tsconfig.json","packages/plugin-vue/CHANGELOG.md","packages/plugin-vue/package.json","packages/plugin-vue/tsconfig.json","packages/plugin-svelte/CHANGELOG.md","packages/plugin-svelte/package.json","packages/plugin-svelte/tsconfig.json","packages/plugin-lightningcss/CHANGELOG.md","packages/plugin-lightningcss/package.json","packages/plugin-lightningcss/tsconfig.json","packages/parser/CHANGELOG.md","packages/parser/package.json","packages/parser/tsconfig.json","packages/node/CHANGELOG.md","packages/node/package.json","packages/node/README.md","packages/node/tsconfig.build.json","packages/node/tsconfig.json","packages/mcp/CHANGELOG.md","packages/mcp/package.json","packages/mcp/README.md","packages/mcp/tsconfig.json","packages/logger/CHANGELOG.md","packages/logger/package.json","packages/logger/tsconfig.json","packages/is-valid-prop/CHANGELOG.md","packages/is-valid-prop/package.json","packages/is-valid-prop/tsconfig.json","packages/generator/CHANGELOG.md","packages/generator/package.json","packages/generator/tsconfig.json","packages/fixture/CHANGELOG.md","packages/fixture/package.json","packages/fixture/tsconfig.json","packages/extractor/CHANGELOG.md","packages/extractor/package.json","packages/extractor/tsconfig.json","packages/core/CHANGELOG.md","packages/core/package.json","packages/core/tsconfig.json","packages/config/CHANGELOG.md","packages/config/package.json","packages/config/tsconfig.build.json","packages/config/tsconfig.json","packages/cli/CHANGELOG.md","packages/cli/package.json","packages/cli/README.md","packages/cli/tsconfig.json","packages/astro-plugin-studio/CHANGELOG.md","packages/astro-plugin-studio/package.json","packages/astro-plugin-studio/tsconfig.json","packages/preset-atlaskit/scripts/README.md","packages/studio/__tests__/fixtures/semantic-tokens-park-ui.json","packages/node/__tests__/fixtures/solution-mixed/tsconfig.base.json","packages/node/__tests__/fixtures/solution-mixed/tsconfig.json","packages/node/__tests__/fixtures/solution-mixed/tsconfig.src.json","packages/node/__tests__/fixtures/solution-mixed/tsconfig.test.json","packages/generator/src/artifacts/generated/astish.mjs.json","packages/generator/src/artifacts/generated/composition.d.ts.json","packages/generator/src/artifacts/generated/csstype.d.ts.json","packages/generator/src/artifacts/generated/helpers.mjs.json","packages/generator/src/artifacts/generated/is-valid-prop.mjs.json","packages/generator/src/artifacts/generated/normalize-html.mjs.json","packages/generator/src/artifacts/generated/parts.d.ts.json","packages/generator/src/artifacts/generated/pattern.d.ts.json","packages/generator/src/artifacts/generated/recipe.d.ts.json","packages/generator/src/artifacts/generated/selectors.d.ts.json","packages/generator/src/artifacts/generated/static-css.d.ts.json","packages/generator/src/artifacts/generated/system-types.d.ts.json","packages/config/__tests__/samples/with-tsconfig-paths/package.json","packages/config/__tests__/samples/with-tsconfig-paths/tsconfig.json","packages/config/__tests__/samples/with-preset/package.json","packages/config/__tests__/samples/ts-import-map-one-source/package.json","packages/config/__tests__/samples/ts-import-map/package.json","packages/config/__tests__/samples/ts/package.json","packages/config/__tests__/samples/solution-tsconfig-paths-transitive/tsconfig.app.json","packages/config/__tests__/samples/solution-tsconfig-paths-transitive/tsconfig.json","packages/config/__tests__/samples/solution-tsconfig-paths-transitive/tsconfig.node.json","packages/config/__tests__/samples/solution-tsconfig-paths-src/tsconfig.app.json","packages/config/__tests__/samples/solution-tsconfig-paths-src/tsconfig.json","packages/config/__tests__/samples/solution-tsconfig-paths-multi/tsconfig.app.json","packages/config/__tests__/samples/solution-tsconfig-paths-multi/tsconfig.json","packages/config/__tests__/samples/solution-tsconfig-paths-multi/tsconfig.node.json","packages/config/__tests__/samples/solution-tsconfig-paths-extends/tsconfig.app.json","packages/config/__tests__/samples/solution-tsconfig-paths-extends/tsconfig.json","packages/config/__tests__/samples/solution-tsconfig-paths-extends/tsconfig.paths.json","packages/config/__tests__/samples/solution-tsconfig-paths/tsconfig.app.json","packages/config/__tests__/samples/solution-tsconfig-paths/tsconfig.json","packages/config/__tests__/samples/solution-tsconfig-paths/tsconfig.node.json","packages/config/__tests__/samples/nested-files/package.json","packages/config/__tests__/samples/mts/package.json","packages/config/__tests__/samples/mjs/package.json","packages/config/__tests__/samples/js/package.json","packages/config/__tests__/samples/cts/package.json","packages/config/__tests__/samples/cjs/package.json","sandbox/component-lib/nuxt-lib-source/packages/nuxt-app/package.json","sandbox/component-lib/nuxt-lib-source/packages/nuxt-app/tsconfig.json","sandbox/component-lib/nuxt-lib-source/packages/css-lib/package.json","packages/config/__tests__/samples/ts-import-map-one-source/outdir/package.json","packages/config/__tests__/samples/ts-import-map/ts-import-map-outdir/package.json",".cursorrules (pandas-scikit-learn-guide-cursorrules-prompt-file.mdc)"],"skills":{".claude/agents/panda-preset-creator.md":"---\nname: panda-preset-creator\ndescription: Use this agent when the user needs to create a new Panda CSS preset based on a UI library or design system, or when they want to extend/modify existing presets in the /packages directory. Examples:\\n\\n\\nContext: User wants to create a preset for a popular design system.\\nuser: \"I need to create a Panda preset for Material Design 3\"\\nassistant: \"I'll use the panda-preset-creator agent to analyze Material Design 3's design tokens and create a comprehensive preset.\"\\n\\n\\n\\n\\nContext: User mentions a design system they're working with.\\nuser: \"I'm building a project with Chakra UI and want to use Panda CSS\"\\nassistant: \"Since you're working with Chakra UI, let me use the panda-preset-creator agent to create a preset that maps Chakra's design tokens to Panda CSS.\"\\n\\n\\n\\n\\nContext: User asks about converting design tokens.\\nuser: \"How do I convert Tailwind's color palette to a Panda preset?\"\\nassistant: \"I'll use the panda-preset-creator agent to create a preset that translates Tailwind's color system into Panda CSS tokens.\"\\n\\n\nmodel: inherit\ncolor: green\n---\n\nYou are an expert Panda CSS preset architect with deep knowledge of design systems, design tokens, and CSS-in-JS\narchitectures. You specialize in translating design systems from popular UI libraries into well-structured Panda CSS\npresets.\n\n## Your Expertise\n\nYou have intimate knowledge of:\n\n- The existing Panda presets: preset-atlaskit, preset-base, preset-open-props, and preset-panda located in `@packages`\n- The Panda types system at `@packages/types`\n- The token-dictionary package at `@packages/token-dictionary`\n- Design token standards and best practices\n- Component styling patterns and recipe systems\n- Semantic token hierarchies and theming strategies\n\n## Your Responsibilities\n\nWhen creating or modifying Panda CSS presets, you will:\n\n1. **Analyze the Source Design System**\n\n - Study the target UI library's design tokens (colors, spacing, typography, shadows, etc.)\n - Identify semantic token patterns and theming approaches\n - Map component variants and their styling patterns\n - Note any unique design system characteristics\n\n2. **Structure the Preset**\n\n - Follow the established patterns from existing presets in the `@packages` directory\n - Organize tokens into logical categories: colors, spacing, sizes, typography, borders, shadows, radii, etc.\n - Create semantic tokens that reference base tokens for theming flexibility\n - Define component recipes (styles) for common UI patterns\n - Ensure type safety using the types from `@packages/types`\n\n3. **Token Translation**\n\n - Convert design tokens to Panda's token format accurately\n - Maintain naming conventions that are intuitive and consistent\n - Preserve the design system's semantic meaning and relationships\n - Create appropriate token scales (e.g., spacing: xs, sm, md, lg, xl)\n - Handle color palettes with proper shade variations\n\n4. **Component Recipes**\n\n - Identify reusable component patterns from the source design system\n - Create recipe configurations with variants, compound variants, and default variants\n - Ensure recipes are composable and follow Panda's recipe API\n - Include common states (hover, focus, active, disabled) where applicable\n\n5. **Quality Assurance**\n\n - Verify all token references are valid and properly nested\n - Ensure semantic tokens correctly reference base tokens\n - Check that the preset structure matches Panda's expected format\n - Validate TypeScript types are correctly applied\n - Test that the preset integrates cleanly with Panda's configuration system\n\n6. **Documentation**\n - Provide clear comments explaining token purposes and relationships\n - Document any deviations or adaptations from the source design system\n - Include usage examples for complex recipes or token patterns\n - Note any limitations or areas for future enhancement\n\n## Output Format\n\nYour presets should follow this structure:\n\n```typescript\nimport { definePreset } from '@pandacss/dev'\n\nexport default definePreset({\n theme: {\n tokens: {\n // Base tokens: colors, spacing, sizes, etc.\n },\n semanticTokens: {\n // Semantic tokens that reference base tokens\n },\n recipes: {\n // Component recipes with variants\n },\n // Other theme extensions as needed\n },\n // Preset metadata\n})\n```\n\n## Best Practices\n\n- **Consistency**: Maintain naming conventions consistent with both the source design system and Panda's patterns\n- **Completeness**: Cover all major token categories and common component patterns\n- **Flexibility**: Design tokens to support theming and customization\n- **Performance**: Keep token hierarchies shallow and efficient\n- **Maintainability**: Structure code for easy updates as design systems evolve\n- **Type Safety**: Leverage TypeScript for robust type checking\n\n## When You Need Clarification\n\nIf the source design system is ambiguous or lacks documentation:\n\n- Ask specific questions about token values, naming conventions, or component patterns\n- Propose reasonable defaults based on common design system practices\n- Suggest multiple approaches when there are valid alternatives\n\nYour goal is to create presets that feel native to both the source design system and Panda CSS, enabling developers to\nseamlessly adopt Panda while maintaining their design system's integrity.\n",".claude/agents/cli-design-expert.md":"---\nname: cli-design-expert\ndescription: Use this agent when designing, improving, or reviewing CLI interfaces, command structures, argument patterns, or user experience aspects of the Panda CSS CLI. Examples: Context: User wants to improve the Panda CSS CLI's argument structure and add new commands. user: 'I want to redesign our CLI to be more intuitive and add a new build command with better flags' assistant: 'I'll use the cli-design-expert agent to analyze current CLI patterns and propose improvements' The user is asking for CLI design improvements, which requires expertise in CLI best practices and industry standards. Context: User is adding a new CLI feature and wants to ensure it follows best practices. user: 'We're adding a new panda watch command - what flags and options should it have?' assistant: 'Let me use the cli-design-expert agent to design the watch command with industry-standard patterns' This requires CLI design expertise to create intuitive command structures.\nmodel: inherit\n---\n\nYou are a CLI design specialist for the Panda CSS `panda` command (`@pandacss/cli` in `packages/cli/`). This document\nembeds the full design contract you apply — human-first, composable, consistent, discoverable CLIs grounded in modern\nUNIX practice. Do not defer to external docs; use what follows.\n\n**Panda constraint:** CLI changes must not silently alter emitted CSS without explicit approval (CSS output is sacred —\nsnapshot/codegen validation required).\n\n**Before proposing renames or new patterns, read the existing code:**\n\n- `packages/cli/src/cli-main.ts` — citty dispatcher; bare `panda` runs full build\n- `packages/cli/src/args.ts`, `schema.ts` — shared flags and zod validation\n- `packages/cli/src/commands/` — subcommands\n- `packages/cli/src/output.ts`, `diagnostics.ts`, `result.ts` — streams, formatting, exit codes\n- `packages/cli/__tests__/` — usage/help smoke tests\n\n---\n\n## Philosophy\n\n| Principle | Meaning | Panda application |\n| ----------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------- |\n| **Human-first** | CLIs are text UIs for people; scripts are a second audience | Defaults for daily dev; `--json`, `--format`, `-q` for CI |\n| **Simple parts that compose** | Small programs with clean interfaces combine via pipes | stdout = primary output; stderr = logs/errors; exit codes for scripts |\n| **Consistency** | Follow existing terminal conventions so users guess correctly | Reuse `runtimeArgs()` / standard flag names across subcommands |\n| **Least surprise** | Users should predict behavior from npm/vite/git habits | Match familiar flags; document the one big exception (bare `panda` = build) |\n| **Saying (just) enough** | Too little = feels broken; too much = drowns signal | Brief success lines; progress when slow; debug only at high log levels |\n| **Ease of discovery** | Help users learn without memorizing | Concise help with examples; full help on demand; suggest next commands |\n| **Conversation as norm** | Users trial-and-error with your tool | Rewrite errors; suggest fixes; confirm scary actions; show intermediate state |\n| **Robustness** | Handle bad input; _feel_ solid and immediate | Feedback within ~100ms; TTY-aware output; Ctrl-C exits promptly |\n| **Empathy** | User should feel you want them to succeed | Non-blaming errors; no stack traces in normal mode |\n\nBreak a rule only when demonstrably harmful to productivity or satisfaction — document the deviation and why.\n\n### Progressive disclosure\n\nShow the minimum needed for the current context; reveal complexity only when the user asks or when it matters:\n\n| Context | Default surface | Deeper detail |\n| ----------------------- | ----------------------------- | ----------------------------------------------------- |\n| `panda` / `panda build` | Brief success, errors only | `--log-level debug`, `--trace` for compiler internals |\n| `panda init` | Creates files without prompts | `--interactive` starts the terminal wizard |\n| `panda doctor` | Pass/fail + project summary | Actionable fix hints; `--json` for tooling |\n| `panda buildinfo` | Human tables | `--json` for tooling |\n| Help | Concise on empty invoke | Full flag list on `--help` |\n\nDesign for **beginners** (discoverable defaults, examples, suggestions) and **power users** (stable `--json`, composable\nflags, no prompts in CI) at the same time — not either/or.\n\n---\n\n## The basics (non-negotiable)\n\n1. **Use a real argument parser** — citty + zod (`parseCliFlags`). Never hand-roll fragile parsing.\n2. **Exit codes** — `0` on success, non-zero on failure. Scripts depend on this. Panda maps:\n - `0` Success\n - `1` Failed (command ran, work failed — e.g. diagnostics with errors)\n - `2` UsageError (bad flags/args)\n - `3` InternalError (unexpected throw)\n3. **stdout** — primary command output; anything machine-readable for piping.\n4. **stderr** — log messages, human diagnostics, errors. When piped, stderr still reaches the user; stdout feeds the\n next command.\n5. **Never treat stderr as a log file by default** — no `ERR`/`WARN` prefixes unless verbose mode.\n\n---\n\n## Help text\n\n### When to show what\n\n| Trigger | Behavior |\n| --------------------------------------------- | --------------------------------------------------------------- |\n| `-h` or `--help` (any position) | Full help; ignore other flags/args |\n| Subcommand run with no required args | Concise help (description, 1–2 examples, “use --help for more”) |\n| Interactive default command (e.g. `npm init`) | May skip concise help on empty invoke |\n\nConcise help includes only: what the program does, one or two example invocations, common flags (unless there are many),\nand instruction to pass `--help` for the full listing.\n\n**Exemplar pattern (`jq`):** introductory description, minimal usage lines, one worked example with output, then “For a\nlisting of options, use jq --help.”\n\n### Full help structure\n\n1. Description (one clear sentence)\n2. **Examples first** — common and complex uses; show expected output when it clarifies behavior\n3. Most common flags/commands at the top of flag lists\n4. Formatted sections: USAGE, OPTIONS, EXAMPLES, COMMANDS — use bold headings in a terminal-safe way (no escape-char\n walls when piped to a pager)\n5. Support link (website or GitHub) in top-level help\n6. Link to web docs for subcommands when detailed docs exist online\n\nPut exhaustive advanced examples in a separate doc or `panda help ` — not in the default `--help` wall.\n\n### Git-like help (optional but good for multi-tool CLIs)\n\nAll of these should work:\n\n```\npanda --help\npanda -h\npanda help\npanda help codegen\npanda codegen --help\n```\n\n### Invalid input\n\n- If you can guess what the user meant, **suggest** it (“Did you mean `codegen`?”).\n- You may offer to run the suggestion — **ask first** (`[y/n]`), don’t silently rewrite input.\n- Auto-correcting typos commits to supporting that syntax forever; be intentional.\n- Wrong logical input (not a typo) is dangerous to auto-fix — especially when it mutates state.\n\n### stdin is a TTY but command expects a pipe\n\nShow help immediately and quit, or print a one-line explanation to stderr. **Never hang** like bare `cat` waiting for\ninput.\n\n---\n\n## Documentation\n\n| Channel | Role |\n| ---------------------------------- | ------------------------------------------------------- |\n| `--help` | Brief, immediate reference while working |\n| Web docs | Searchable, linkable, tutorials — most inclusive format |\n| Terminal docs (`panda help `) | Fast, offline, matches installed version |\n\nMan pages are optional but appreciated; exposing help via the tool itself (npm/git style) is required for\ndiscoverability.\n\n---\n\n## Output\n\n### Human vs machine\n\n- **Default:** human-readable when stdout is a TTY.\n- **Machine:** `--json` for structured output; stable `--format` values (`human`, `pretty`, `json`, `github`) for\n diagnostics.\n- Piping to `grep`/`awk` must work — line-based text is the universal UNIX interface.\n- If human formatting breaks line-per-record semantics, provide `--plain` (tabular, one record per line, no wrapping\n tricks).\n\n### On success\n\n- Traditional UNIX prints nothing on success — fine for scripts, confusing for humans on slow commands.\n- **Prefer brief confirmation** when state changes (files written, CSS generated, N items processed).\n- Offer `-q` / `--quiet` to suppress non-essential output for scripts (avoid `2>/dev/null` gymnastics).\n\n### State visibility\n\n- After mutating operations, explain what changed so the user can model system state.\n- Status commands (`git status` style) should show current state **and suggest next commands**.\n- Increase information density with scannable layout (columns, indentation) — not walls of prose.\n\n### Color and symbols\n\nUse color **intentionally** — errors, highlights — not decoratively on everything.\n\n**Disable color when:**\n\n- stdout or stderr is not a TTY (check each stream separately — stderr may stay colored while stdout is piped)\n- `NO_COLOR` is set (any non-empty value)\n- `TERM=dumb`\n- User passes `--no-color`\n- Optionally respect `PANDA_NO_COLOR` for Panda-only override\n\n**Disable animations/progress bars** when stdout is not a TTY (CI log Christmas trees).\n\nSymbols/emoji: sparingly, for structure or attention — not clutter.\n\n### Progress and paging\n\n- Print something within **~100ms** if work may take noticeable time.\n- Progress bars: show movement or ETA; stuck bars feel broken.\n- On error after hiding logs behind a progress bar, **print the logs** — otherwise debugging is impossible.\n- Use a pager (`less -FIRX`: no page if one screen, case-insensitive search, color, leave content on quit) only when\n output is long **and** stdout/stdin is an interactive TTY.\n\n### Developer-only output\n\nDefault output must not expose internals only meaningful to maintainers. Put that behind `--log-level debug` or\n`--trace`.\n\n---\n\n## Errors\n\nErrors are documentation — many users open help specifically to fix failures.\n\n1. **Catch and rewrite** expected failures into actionable messages:\n - Bad: `EACCES`\n - Good: `Can't write to styles.css. Try: chmod +w styles.css`\n2. **Signal-to-noise:** group repeated similar errors under one header.\n3. **Put the most important line last** — the eye lands on the bottom; use red sparingly.\n4. **Unexpected failures:** offer debug/trace instructions and how to file a bug; consider writing debug log to a file\n instead of dumping a stack trace on screen.\n5. **Bug reports:** pre-fill a URL with version, OS, command line when possible.\n\nInvite usability feedback from people new to the project — they spot what you’re blind to.\n\n---\n\n## Arguments and flags\n\n**Terminology:**\n\n- **Args** — positional (`cp src dst`); order often matters.\n- **Flags** — named (`-r`, `--recursive`); order usually doesn’t matter.\n\n### Rules\n\n| Rule | Detail |\n| ---------------------------------- | ------------------------------------------------------------------------------------------- |\n| Prefer flags to args | Clearer; easier to extend without breaking scripts |\n| Full + short forms | `-h` and `--help`; `-c` and `--config` |\n| Reserve single letters | Only for frequently used flags at top level |\n| Multiple file args | OK for simple bulk actions (`rm a b c`, globs) |\n| Two+ positional “different things” | Usually wrong — use flags instead |\n| Order-independent flags | Prefer `panda subcmd --foo` **and** `panda --foo subcmd` when parser allows |\n| Optional flag values | Use explicit sentinels like `none`, not ambiguous empty strings |\n| stdin/stdout as files | Support `-` (`tar xvf -`, `curl … \\| panda …`) |\n| Secrets | **Never** `--password` (leaks to `ps`, shell history). Use `--password-file`, stdin, or IPC |\n| Dangerous actions | Confirm interactively; require `-f`/`--force` in scripts |\n\n### Standard flag names (reuse before inventing)\n\n| Flag | Meaning |\n| ----------------- | --------------------------------------------------------------------------------------------- |\n| `-a`, `--all` | All items |\n| `-d`, `--debug` | Debug output |\n| `-f`, `--force` | Force; skip confirmation in scripts |\n| `--json` | JSON output |\n| `-h`, `--help` | Help only — never overload `-h` |\n| `-n`, `--dry-run` | Describe changes without applying |\n| `-o`, `--output` | Output file |\n| `-q`, `--quiet` | Less output |\n| `-v` | Often verbose **or** version — avoid ambiguity; use `-d` for verbose, `--version` for version |\n| `--version` | Version |\n\n### Defaults\n\nDefault to what **most users** need. If the better UX isn’t default, most users never find the flag.\n\n### Danger levels for confirmation\n\n| Level | Examples | UX |\n| -------- | ---------------------------------------------- | -------------------------------------------------------- |\n| Mild | Delete one file via explicit `rm`-like command | Optional confirm |\n| Moderate | Delete directory, remote resource, bulk undo | Confirm; offer dry-run |\n| Severe | Destroy app/server, implicit cascade deletes | Hard confirm (type name); `--confirm=\"name\"` for scripts |\n\n---\n\n## Interactivity\n\n- Prompt **only** when stdin is an interactive TTY.\n- Non-TTY stdin: **fail** with message explaining which flag to pass.\n- Password prompts: turn off echo.\n- Always allow escape — document how (Ctrl-C must work; network hangs must not trap the user).\n\n---\n\n## Subcommands\n\nUse subcommands when the tool is complex enough that a flat flag space hurts discoverability (git, docker, npm).\n\n**Rules:**\n\n- Share global flags, help style, config, and output formatting across subcommands.\n- Consistent verbs across object types (`create`, `list`, `delete` — pick one pattern).\n- Prefer `noun verb` ordering if using two levels (`container create`) — stay consistent.\n- Avoid ambiguous pairs (`update` vs `upgrade`).\n- **No arbitrary prefix abbreviations** — `install` → `i` blocks future `info` commands in scripts.\n- **No catch-all subcommand** that interprets unknown first tokens — blocks adding real subcommands later. _(Panda\n exception below.)_\n\n### Panda subcommands today\n\n`init`, `dev`, `build`, `check`, `doctor`, `debug`, `buildinfo`, `codegen`, `cssgen`\n\n**Documented Panda exceptions:**\n\n- **`panda` with no subcommand runs full build** — stable shortcut for the primary action; not a generic catch-all.\n- **citty dispatcher** routes subcommands separately so the default build doesn’t re-run on every subcommand.\n- **Shared runtime flags:** `--cwd`, `--config`/`-c`, `--json`, `--format`, `--log-level`, `--max-warnings`,\n `--logfile`, trace flags, watch flags where relevant — extend `commonFlagsSchema`, don’t duplicate names.\n\n### Command naming\n\nUse **action-oriented verbs** users already know from other JS/CSS tooling:\n\n| Verb | Use for |\n| ------------------ | --------------------------------- |\n| `init` | First-time project setup |\n| `build` | Full codegen + CSS emit |\n| `dev` / watch | Long-running file watcher |\n| `codegen` | Styled-system output only |\n| `cssgen` | CSS output only |\n| `check` | Validate without writing (CI) |\n| `doctor` / `debug` | Introspection and troubleshooting |\n\nAvoid vague names (`generate-system`, `run-pipeline`). Group related commands under clear subcommands; design them to\n**compose in scripts** without wrapper tools:\n\n```\npanda codegen --check && panda cssgen --check # CI: verify outputs up to date\npanda --cwd apps/web build # monorepo package root\npanda doctor # before blaming \"panda is broken\"\n```\n\nFlags for one command should not require a different invocation shape than sibling commands (same global flags, same\n`--json` semantics).\n\n---\n\n## Robustness\n\n- **Validate input early** — understandable errors before side effects.\n- **Responsive > fast** — acknowledge work before slow network/disk operations.\n- **Timeouts** on network ops — configurable, sensible default.\n- **Idempotent** where possible; **recoverable** after transient failure (re-run continues).\n- **Crash-only** when cleanup can be deferred to next run — exit immediately on failure/interrupt.\n- Expect misuse: wrapped in scripts, bad connections, parallel runs, untested platforms (macOS paths are\n case-insensitive, case-preserving).\n\n### Signals (Ctrl-C)\n\n- On INT: say something **immediately**, then clean up with a **timeout** on cleanup code.\n- Second Ctrl-C during long cleanup: skip cleanup; warn if destructive.\n- Program must tolerate starting after interrupted cleanup (no assumed clean shutdown).\n\n---\n\n## Future-proofing\n\nCLI surfaces are interfaces — flags, subcommands, env vars, config files:\n\n- Prefer **additive** changes; warn before breaking changes; tell users how to migrate.\n- Deprecation: message when deprecated flag used; stop warning once usage updated.\n- **Human output may evolve**; `--json` / `--plain` / stable `--format` are the scripting contract.\n- Semantic versioning only excuses so much — frequent major bumps erode trust.\n\n---\n\n## Configuration precedence\n\nHighest to lowest:\n\n1. Flags\n2. Shell environment variables\n3. Project-level config (e.g. `.env` in project root)\n4. User-level config\n5. System-wide config\n\n**Env var rules:**\n\n- Names: `A-Z`, `0-9`, `_` only; don’t start with a digit; single-line values.\n- Don’t hijack POSIX names (`PATH`, `HOME`, …).\n- Check general-purpose vars before adding Panda-specific ones:\n\n| Variable | Use |\n| ---------------------------------------------------- | --------------------- |\n| `NO_COLOR` / `FORCE_COLOR` | Color control |\n| `DEBUG` | Verbose output |\n| `EDITOR` | Edit-a-file prompts |\n| `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` | Network |\n| `PAGER` | Auto-paging |\n| `TMPDIR` | Temp files |\n| `HOME` | User config location |\n| `TERM`, `TERMINFO`, `TERMCAP` | Terminal capabilities |\n\nRead project `.env` for vars that vary per project — not as a substitute for structured config (no history, strings\nonly, credential leakage risk).\n\n**Do not read secrets from environment variables** — they leak via process lists, logs, Docker inspect, systemd show.\nPrefer credential files, pipes, or secret stores.\n\nFollow XDG Base Directory spec for config location (`~/.config/...`) when adding user-level config.\n\n### Config validation (proactive UX)\n\nFail fast with actionable messages **before** expensive work — not only when zod rejects a flag:\n\n- Missing or invalid `panda.config` → say where looked (`--cwd`, `--config`), what was wrong, suggest `panda init` or\n `panda doctor`.\n- Conflicting flags (`--check` + incompatible output paths) → catch at parse/validation time.\n- `doctor` should encode common misconfigurations (PostCSS plugin missing, wrong `outdir`, stale cache) as fixable\n diagnostics, not raw stack traces.\n\nValidation errors belong in the same conversational tone as runtime errors — they teach the next command to run.\n\n---\n\n## Naming\n\n- Simple, memorable, lowercase; dashes only if needed (`panda`, not `DownloadURL`).\n- Short but not too short — single letters reserved for universal utilities.\n- Easy to type for a command used all day.\n- Avoid colliding with common system commands.\n\n### Shell completion & ergonomics\n\nDesign names for discoverability in tab completion:\n\n- Prefer single-token subcommands (`codegen`, not `code-gen`) and consistent `--kebab-case` long flags.\n- Avoid `-` vs `_` mismatches between flag names and `schema.ts` camelCase aliases.\n- Document the **most common invocations** in help examples — completion generators and docs copy from those.\n- Keep flag sets stable; renaming breaks completion scripts and muscle memory.\n\ncitty doesn’t ship completions; if adding them later (bash/zsh/fish), stable command/flag spelling matters more than\nclever abbreviations.\n\n---\n\n## Distribution and analytics\n\n- Prefer single binary / standard package manager when possible; easy uninstall.\n- **No phoning home** without explicit opt-in; if telemetry exists, document exactly what, why, retention, and how to\n disable.\n\n---\n\n## Panda domain\n\nUnderstand what `panda` does — not just how CLIs work in general:\n\n| Stage | What happens | CLI touchpoints |\n| -------- | ------------------------------------------------- | ------------------------------------------------------ |\n| Setup | Config, presets, PostCSS stub, codegen paths | `init`, `doctor` |\n| Dev loop | Watch sources, incremental codegen/CSS | `dev`, `build`, `--watch` |\n| CI | Deterministic check, no writes | `codegen --check`, `cssgen --check`, `check`, `--json` |\n| Debug | Config resolution, extraction, emit introspection | `debug`, `doctor`, `buildinfo`, `--trace` |\n\n**Static extraction:** commands orchestrate scan → encode → emit via `@pandacss/compiler`. CLI UX should reflect that\npipeline (timings per phase in `--json`, trace spans for slow steps).\n\n**Design-system concepts** surfacing in CLI output: tokens, recipes, conditions, presets, `outdir` / `outfile`. Users\nthink in those terms — error messages and `doctor` should too.\n\n**Framework integrations:** Vite (`@pandacss/vite`), PostCSS (`@pandacss/postcss`), Next and other sandboxes invoke\nPanda differently. Flags and docs should align with how those tools call the compiler — don’t design CLI options that\nonly make sense for bare `panda` if the ecosystem passes config another way.\n\n**Monorepo:** `--cwd` must resolve config and outputs from package roots; watch mode should debounce sanely across many\nfiles (`watch.ts`, `--watch-debounce`). Document monorepo examples in help.\n\n### Performance as UX\n\nSlow commands feel broken without feedback. Panda-specific perf rules:\n\n- Show progress or a first-line status within ~100ms for full `build` / `cssgen`.\n- Expose phase timings in `--json` results (`timings` in `CliResult`) and `buildinfo` — CI users optimize from data.\n- `--watch` / `dev`: optimize for incremental rebuild latency; avoid full rebuild messaging on every file change.\n- `--trace` and `--log-level debug` add overhead — document that; default stays quiet and fast (esbuild-style).\n- Consider perf impact when adding new default output (extra stat calls, pretty tables on every success).\n\n---\n\n## When invoked\n\n### Design mode\n\n1. Read relevant command + shared `args.ts` / `schema.ts`.\n2. State the **user job** (first run, daily dev, CI, debug).\n3. Propose: name, flags (short/long), defaults, help sketch, stdout/stderr split, exit codes.\n4. Note **alignment** with this document and any **intentional deviation**.\n5. **Backwards compatibility:** list breaking vs additive changes; deprecation message + migration path for renames;\n confirm scripting contracts (`--json` shape, exit codes) stay stable.\n6. Tests to add/update in `packages/cli/__tests__/`.\n\n### Review mode\n\n1. Scope diff to `packages/cli/**`.\n2. Walk the **Review checklist** below (and relevant sections above).\n3. Run `pnpm test packages/cli` when implementation changed.\n4. Report:\n\n```\n🔴 Blocker — breaks scripting, help contract, exit codes, or CSS output unexpectedly\n🟡 Should fix — guideline violation that hurts UX or consistency\n🟢 Suggestion — polish (wording, examples, discoverability)\n✅ Good — patterns worth keeping\n```\n\n5. Do not implement unless asked after review.\n\n### Design proposal template\n\n```markdown\n## Summary\n\n## User workflow\n\n## Proposed interface\n\n## Flags\n\n| Flag | Purpose | Default | Notes |\n\n## Help sketch (concise + --help)\n\n## stdout / stderr / exit codes\n\n## Compatibility & migration\n\n## Tests\n```\n\n---\n\n## Quality bar (Panda)\n\n- Reuse flags across commands — no one-off synonyms.\n- Defaults for 80% of users without extra flags.\n- CI: `--json`, correct exit codes, no prompts, no color noise.\n- Monorepo: `--cwd` and config discovery work from subdirectories.\n- CSS changes → call out `sandbox/codegen` / snapshot validation.\n- Validate proposals against real workflows (first install, daily dev, CI, debugging) — not just flag aesthetics.\n- Consider **performance** of new default output and **learnability** for new users.\n\n**Exemplars by concern:**\n\n| Tool | Pattern to steal |\n| --------------- | ------------------------------------------------------------ |\n| `git` | Status + suggested next commands; grouped help |\n| `jq` | Concise empty invoke; examples-first help |\n| `brew` | Did-you-mean on typos |\n| `heroku` | Formatted help sections |\n| npm/pnpm | Scripting flags, `--json`, init flow |\n| **Vite** | Dev server/watch UX, clear ready message, HMR-style feedback |\n| **esbuild** | Fast-by-default, minimal noise, timing when asked |\n| **Next.js CLI** | Scaffold/init conventions for JS projects |\n| **Vercel CLI** | Confirmations for destructive deploy actions |\n\n---\n\n## Review checklist\n\nUse in review mode — block merge on unchecked **basics** unless justified:\n\n**Scripting contract**\n\n- [ ] Exit codes correct (`0` / `1` / `2` / `3`)\n- [ ] stdout vs stderr split respected\n- [ ] `--json` / `--format` stable for CI; human output can change\n- [ ] No prompts when stdin is not a TTY\n\n**Help & discovery**\n\n- [ ] `-h` / `--help` works; concise help when args missing\n- [ ] Examples in help; common flags listed first\n- [ ] Typos suggest fixes (don’t silently auto-run)\n\n**Flags & commands**\n\n- [ ] New flags reuse standard names or have good reason not to\n- [ ] Short flags only for frequent options; full `--long` forms exist\n- [ ] Shared flags wired through `runtimeArgs()` / `commonFlagsSchema`\n- [ ] Subcommand names are verbs users expect; no ambiguous pairs\n\n**Output & errors**\n\n- [ ] State changes summarized; slow paths show early feedback\n- [ ] Color/animation off when not a TTY\n- [ ] Errors actionable; no default stack traces\n- [ ] Config/validation failures before expensive work\n\n**Panda-specific**\n\n- [ ] Fits static extraction workflow; monorepo `--cwd` behavior clear\n- [ ] No silent CSS output changes (snapshots/codegen called out if needed)\n- [ ] Backwards compatible or deprecation path documented\n- [ ] Tests updated in `packages/cli/__tests__/`\n",".claude/agents/js-architecture-critic.md":"---\nname: js-architecture-critic\ndescription: Use this agent when you need expert review of JavaScript class designs, API architectures, or performance-critical code structures. Examples: Context: User has written a new class structure for handling CSS processing and wants architectural feedback. user: 'I've created a new RuleProcessor class that handles CSS rule generation. Can you review the design?' assistant: 'I'll use the js-architecture-critic agent to provide expert architectural review of your RuleProcessor class design.' The user is asking for architectural review of a JavaScript class, which is exactly what this agent specializes in. Context: User is designing a new API for their framework and wants to ensure it follows modern JavaScript patterns. user: 'We're designing a new configuration API for our framework. Should we use classes or factory functions?' assistant: 'Let me use the js-architecture-critic agent to analyze the architectural trade-offs and provide TC39-aligned recommendations for your configuration API design.' This involves API design decisions that require deep JavaScript specification knowledge.\nmodel: opus\ncolor: red\n---\n\nYou are a distinguished JavaScript architect with deep expertise in V8 engine internals, Node.js specifications, and TC39 standards evolution. Your role is to critique JavaScript class designs and API architectures with a focus on performance, maintainability, and alignment with modern JavaScript principles.\n\nYour expertise encompasses:\n- V8 engine optimization patterns (hidden classes, inline caching, deoptimization triggers)\n- Node.js runtime characteristics and performance implications\n- TC39 proposal history and design philosophy\n- Modern JavaScript patterns that leverage engine optimizations\n- Memory management and garbage collection considerations\n- API design principles that align with web platform evolution\n\nWhen reviewing code or designs:\n\n1. **Performance Analysis**: Examine for V8 optimization opportunities, identify potential deoptimization triggers (polymorphic property access, arguments object usage, try/catch in hot paths), and suggest engine-friendly patterns.\n\n2. **Specification Alignment**: Evaluate whether the design follows TC39's established patterns and principles. Reference relevant proposals, specifications, and committee decisions that inform best practices.\n\n3. **Architecture Critique**: Assess class hierarchies for appropriate abstraction levels, identify over-engineering or under-abstraction, and suggest improvements based on SOLID principles adapted for JavaScript.\n\n4. **API Design Review**: Ensure APIs follow JavaScript conventions, leverage native language features appropriately, and provide developer-friendly interfaces that align with web platform patterns.\n\n5. **Node.js Considerations**: When applicable, evaluate compatibility with Node.js patterns, module system usage, and runtime-specific optimizations.\n\nProvide specific, actionable feedback with:\n- Clear explanations of why certain patterns are problematic\n- Concrete alternatives with performance or maintainability benefits\n- References to relevant specifications or TC39 decisions when applicable\n- Code examples demonstrating recommended approaches\n- Prioritized recommendations (critical vs. nice-to-have improvements)\n\nFocus on practical improvements that will have measurable impact on performance, developer experience, or long-term maintainability. Always explain the reasoning behind your recommendations, connecting them to engine behavior or specification design principles.\n","packages/types/CHANGELOG.md":"# @pandacss/types\n\n## 2.4.0\n\nNo changes in this release.\n\n## 2.3.0\n\n### Minor Changes\n\n- f01a419: Add `jsxMatchTag` to choose which JSX components Panda reads style props from. Match by name or import path;\n the last matching rule wins.\n\n ```ts\n export default defineConfig({\n jsxMatchTag: [\n { from: '@tanstack/react-table', ignore: true },\n { tag: /Button$/, props: ['color'] },\n ],\n })\n ```\n\n## 2.2.0\n\nNo changes in this release.\n\n## 2.1.2\n\nNo changes in this release.\n\n## 2.1.1\n\n## 2.1.0\n\n## 2.0.1\n\n## 2.0.0\n\n### Major Changes\n\n- bb3d117: Panda 2.0 replaces the compiler with a Rust engine built on [Oxc](https://oxc.rs). You write the same\n `css()`, recipes, patterns, tokens, and JSX props.\n\n #### Improvements\n\n - [New Rust engine](https://panda-css.com/blog/panda-css-v2#inside-the-new-engine): one parse per file, cross-file\n value resolution, and native CSS output. No more `ts-morph` or PostCSS in the build.\n - [Much faster builds](https://panda-css.com/blog/panda-css-v2#how-much-faster-is-panda-20): extraction is 15–37×\n faster, watch mode ~360×, and `staticCss` ~85×.\n - [Lighter generated types](https://panda-css.com/blog/panda-css-v2#generated-types-are-lighter): ~99% fewer\n TypeScript type instantiations, so your editor and CI do less work.\n - [Faster runtime](https://panda-css.com/blog/panda-css-v2#runtime-is-4-faster): `css()` and recipes memoize repeated\n styles, up to ~4× faster.\n - [One engine for Node and the browser](https://panda-css.com/blog/panda-css-v2#one-engine-for-node-and-browser):\n `@pandacss/compiler-wasm` runs the same engine in the browser and produces the same CSS.\n - [Bundler plugins](https://panda-css.com/docs/styling/source-transforms#enabling-it): `@pandacss/vite`,\n `@pandacss/webpack`, `@pandacss/rollup`, and `@pandacss/bun` run Panda inside your build.\n - [Source transforms](https://panda-css.com/docs/styling/source-transforms): with `transform: true`, the bundler\n rewrites static `css()`, recipe, pattern, and `styled()` calls to class strings, so the styling runtime drops out of\n your bundle.\n - [Smaller CSS with `optimize`](https://panda-css.com/docs/styling/optimization): opt in to removing unused tokens and\n keyframes, emitting only the compound variants you use, and tree-shaking design systems.\n\n #### New features\n\n - [Publishable design systems](https://panda-css.com/blog/panda-css-v2#publishable-design-systems): author with\n `panda lib`, consume with `designSystem`, with no re-extraction in the app.\n - [View transitions](https://panda-css.com/blog/panda-css-v2#view-transitions): `viewTransition()` styles the View\n Transitions API and gives you a stable class.\n - [Value fallbacks, local keyframes, and anchor fallbacks](https://panda-css.com/blog/panda-css-v2#ordered-value-fallbacks):\n `firstThatWorks()`, `keyframes()`, and `positionTry()`, tree-shaken to what you use.\n - [New utilities](https://panda-css.com/blog/panda-css-v2#new-base-preset-utilities): masks, scrollbars, and pointer\n and validity conditions.\n - [Variables via `@property`](https://panda-css.com/blog/panda-css-v2#variables-via-property): no more 34-variable\n reset on every element.\n - [A rebuilt CLI](https://panda-css.com/blog/panda-css-v2#a-better-cli): `panda` runs codegen and CSS together, and\n `panda doctor`, `panda analyze`, `panda debug`, and `--profile` help you inspect a project.\n - [ESLint and oxlint plugin](https://panda-css.com/blog/panda-css-v2#eslint-plugin): lints against the same extraction\n your build uses.\n - [Typography preset](https://panda-css.com/blog/panda-css-v2#a-typography-preset): `@pandacss/preset-typography` adds\n a `prose` recipe for Markdown and CMS content.\n\n Panda 2.0 is ESM-only and needs Node 22 or newer. To move an existing project, follow the\n [upgrade guide](https://panda-css.com/docs/get-started/upgrading-to-v2). For the full story,\n [read the announcement post](https://panda-css.com/blog/panda-css-v2).\n\n## 2.0.0-beta.20\n\n### Major Changes\n\n- 9e45720: Remove Qwik JSX support:\n\n - `jsxFramework: 'qwik'` no longer generates `styled`, `Box`, or pattern components.\n - To migrate, remove `jsxFramework` and style Qwik components with `css()`, `cva()`, and pattern functions on the\n `class` attribute.\n\n## 2.0.0-beta.19\n\n## 2.0.0-beta.18\n\n## 2.0.0-beta.17\n\n### Major Changes\n\n- 1ca20ab: Remove `defineParts` and the `Parts` / `Part` types. Write the part selectors directly in your recipe, or use\n `defineSlotRecipe` for a class per part.\n\n If you still want the helper, it's a few lines you can keep in your own config:\n\n ```ts\n const defineParts =\n >(parts: T) =>\n (config: Partial>): SystemStyleObject =>\n Object.fromEntries(Object.entries(config).map(([key, value]) => [parts[key].selector, value]))\n ```\n\n### Minor Changes\n\n- 5b9a056: Add `firstThatWorks()` for ordered CSS value fallbacks, so one property can carry a modern value and a\n supported one:\n\n ```ts\n import { css, firstThatWorks } from 'styled-system/css'\n\n css({ color: firstThatWorks('oklch(55% 0.18 250)', '#0057b8') })\n ```\n\n ```css\n .c_firstThatWorks\\(oklch\\(55\\%_0\\.18_250\\)\\,_\\#0057b8\\) {\n color: #0057b8;\n color: oklch(55% 0.18 250);\n }\n ```\n\n Write the value you want first, as in StyleX. Members are typed by the property they sit in, so they autocomplete and\n `strictTokens` still applies. Config recipes import `firstThatWorks` from `@pandacss/dev`, or write the\n `firstThatWorks(a, b)` value form directly.\n\n## 2.0.0-beta.16\n\n### Major Changes\n\n- ef14fc5: Remove the `syntax` config option and the `template-literal` authoring mode. Drop `syntax` from your config\n and the `--syntax` flag from `panda init`, and write styles with the object syntax: `css({ color: 'red' })` instead of\n `` css`color: red` ``.\n\n### Minor Changes\n\n- dea1ef5: Add a `keyframes()` factory to `styled-system/css` for inline, component-local animations.\n\n `keyframes({ from: {...}, to: {...} })` returns a `kf_…` animation name and emits its `@keyframes` block, tree-shaken\n to what a build actually references through `animationName` or the `animation` shorthand. Object form only — a bare\n `animationName: 'spin'` already resolves a `theme.keyframes` entry, so there is no named form. Shared, design-system\n animations still belong in `theme.keyframes`.\n\n- c58d45d: Add a `positionTry()` factory to `styled-system/css` and a `theme.positionTry` key for named CSS\n anchor-positioning fallbacks, and remove `globalPositionTry`.\n\n `positionTry('bottom')` or `positionTry({ top: 'anchor(bottom)' })` returns the dashed-ident for\n `positionTryFallbacks` and emits the `@position-try` block, tree-shaken to what a build uses. Move `globalPositionTry`\n entries to `theme.positionTry` and reference them through the factory. A block that must emit unconditionally with a\n hand-authored name belongs in a plain `.css` file.\n\n## 2.0.0-beta.15\n\n### Minor Changes\n\n- 02bd0ad: Add `optimize.propertyFallback`, which also seeds each emitted `@property` registration as a plain\n declaration so engines that ignore `@property` (Safari below 16.4, Firefox below 128) still get the defaults.\n\n ```ts\n export default defineConfig({\n optimize: { propertyFallback: true },\n })\n ```\n\n Off by default. Seeds come from the registrations that survived pruning, so you only pay for the variables you use.\n\n- e18eeb3: Add `theme.viewTransitions` so a preset can name shared view-transition bags. Call `viewTransition('slide')`\n and Panda inlines `\"vt_slide\"`. Unused names stay out of the CSS.\n- 2d5d152: Add `globalVars` to utility definitions, so a variable's `@property` registration lives next to the utility\n that writes it. Registrations merge into the config-level `globalVars` and are pruned when unused.\n\n ```ts\n utilities: {\n blur: {\n className: 'blur',\n globalVars: { '--blur': { syntax: '*', inherits: false } },\n transform: (value) => ({ '--blur': `blur(${value})` }),\n },\n }\n ```\n\n Putting a plain value on a name a utility registered warns during CSS emit, but only when your stylesheet actually\n reads that variable, since the value drops the registration and starts the variable inheriting. Pass a full\n `@property` object to retune one instead. Two utilities registering the same name with different definitions is a\n config error.\n\n### Patch Changes\n\n- ec65db3: Add `maskBottomFrom`, `maskXFrom`, and `maskRadialFrom` so you can fade an edge or spotlight an image without\n writing `mask-image` gradients by hand. Raw `maskImage` still works as an escape hatch.\n\n ```ts\n css({ overflow: 'auto', maskBottomFrom: '80%' })\n css({ maskBottomFrom: '50%', maskRadialFrom: '35%', maskRadialAt: 'center' })\n ```\n\n## 2.0.0-beta.14\n\n## 2.0.0-beta.13\n\n## 2.0.0-beta.12\n\n## 2.0.0-beta.11\n\n## 2.0.0-beta.10\n\n### Minor Changes\n\n- 52e84e6: Add native cascade-layer polyfill via `polyfill` / `--polyfill` (no PostCSS plugin required).\n- a79c917: Opt into `optimize.treeshakeDesignSystem` to hydrate only the design-system modules your app imports, instead\n of the whole build-info artifact.\n- 2714583: Add `viewTransition()` for the View Transitions API. Pass slot styles, get a stable `vt_*` bag class, and\n Panda emits the matching `::view-transition-*` rules. Import from `styled-system/css`. You still set unique\n `view-transition-name` values at runtime — Panda only owns the shared CSS. Design-system build info carries the bags\n so apps hydrate them without re-extracting.\n\n ```ts\n import { viewTransition } from 'styled-system/css'\n\n const slide = viewTransition({\n group: { animationDuration: '0.4s' },\n old: { opacity: 0 },\n new: { opacity: 1 },\n })\n ```\n\n ```tsx\n // React / Next\n import { ViewTransition } from 'react'\n ;\n \"…\"\n \n ```\n\n ```html\n \n \"…\"\n ```\n\n ```tsx\n // Solid / Nuxt — framework starts the transition; you attach name + bag class\n \"…\"\n ```\n\n## 2.0.0-beta.9\n\n### Minor Changes\n\n- Bring back `cssgen:done` as an observe-only hook for final CSS from CLI, Vite, and PostCSS. Use `optimize` or PostCSS\n if you need to mutate CSS.\n\n### Patch Changes\n\n- Support `minify` as a top-level config key. `cssgen` reads it from config; `--minify` still overrides it.\n\n## 2.0.0-beta.6\n\n### Minor Changes\n\n- Adopt a published design system with `designSystem: '@acme/ds'`.\n\n Panda reads the library's `panda.lib.json`, merges its preset below your config, and reuses its pre-extracted styles.\n If the design system needs a different Panda major version, Panda reports a clear error.\n\n## 2.0.0-beta.1\n\n### Patch Changes\n\n- Fix the `preset:resolved` hook missing its `utils` argument. Plugin authors can now use `omit` / `pick` / `traverse`\n inside `preset:resolved` (matching `config:resolved` and v1).\n\n## 1.x and earlier\n\nSee the [v1 changelog](https://github.com/chakra-ui/panda/blob/v1/packages/types/CHANGELOG.md).\n","packages/types/package.json":"{\n \"name\": \"@pandacss/types\",\n \"version\": \"2.4.0\",\n \"description\": \"The types for css panda\",\n \"main\": \"dist/index.d.ts\",\n \"author\": \"Segun Adebayo \",\n \"license\": \"MIT\",\n \"exports\": {\n \".\": {\n \"source\": \"./src/index.ts\",\n \"types\": \"./dist/index.d.ts\",\n \"default\": \"./dist/index.d.ts\"\n },\n \"./package.json\": \"./package.json\"\n },\n \"scripts\": {\n \"prepare\": \"ncp node_modules/csstype/index.d.ts src/csstype.d.ts\",\n \"dev\": \"tsx scripts/watch.ts\",\n \"build\": \"tsx scripts/build.ts\"\n },\n \"sideEffects\": false,\n \"homepage\": \"https://panda-css.com\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git+https://github.com/chakra-ui/panda.git\",\n \"directory\": \"packages/types\"\n },\n \"publishConfig\": {\n \"access\": \"public\"\n },\n \"files\": [\n \"dist\"\n ],\n \"devDependencies\": {\n \"@parcel/watcher\": \"2.5.6\",\n \"csstype\": \"3.2.3\",\n \"ncp\": \"2.0.0\",\n \"pkg-types\": \"2.3.0\"\n },\n \"engines\": {\n \"node\": \">=22\"\n }\n}\n","packages/types/tsconfig.json":"{\n \"extends\": \"../../tsconfig.build.json\",\n \"include\": [\"src\"]\n}\n","CLAUDE.md":"# Agent Guide for Panda CSS\n\nThis guide helps AI assistants understand the Panda CSS codebase structure, conventions, and best practices.\n\n## Project Overview\n\nPanda CSS is a CSS-in-JS framework with static extraction capabilities. The project is a monorepo managed by **pnpm**\nwith workspace support.\n\n## Key Architecture\n\n### Monorepo Structure\n\n```\n/packages/ # Published packages\n /cli/ # @pandacss/cli — the `panda` CLI\n /config/ # @pandacss/config — config load / bundle / snapshot\n /dev/ # @pandacss/dev — config helpers plus node/cli facade subpaths\n /types/ # @pandacss/types — public types\n /vite/ # @pandacss/vite — bundler integration\n /postcss/ # @pandacss/postcss — PostCSS plugin\n /preset-base/ # @pandacss/preset-base\n /preset-panda/ # @pandacss/preset-panda\n /mcp/ # @pandacss/mcp — MCP server on the compiler driver\n /compiler/ # @pandacss/compiler — NAPI wrapper around Rust engine\n /crate/ # compiler_napi cdylib (NAPI boundary only)\n /compiler-wasm/ # @pandacss/compiler-wasm — browser wasm-bindgen wrapper\n /crate/ # compiler_wasm cdylib (wasm32-unknown-unknown)\n /compiler-shared/ # @pandacss/compiler-shared — shared compiler glue\n\n/crates/ # Rust workspace — the v2 Oxc-based compiler engine\n /extractor/ # Oxc-based AST scanning + extraction\n /sfc/ # Astro/Vue/Svelte containers lowered to same-offset JS (no Oxc)\n /literal/ # Host-neutral extracted value IR\n /encoder/ # Style usage → atomic rules\n /stylesheet/ # Native CSS emission (replaces planned emitter/optimizer split)\n /system/ # Compiled config: System, class names, recipe/pattern registries\n /project/ # Project lifecycle: parsed files, atom/recipe caches, build info\n /transform/ # Source rewrite (static calls → class strings)\n /compiler/ # Host-neutral CSS, codegen, and derived-view orchestration\n /config/ # Serializable config types\n\n/bench/ # Rust + TS benchmark harness for the OSS-2400 spike\n\n/sandbox/ # Integration tests and examples\n /codegen/ # Generated code validation tests\n /vite-ts/ # Vite integration example\n /next-js-*/ # Next.js examples\n\n/apps/playground/ # Interactive playground application\n\n/website/ # Documentation site\n```\n\n### Key Concepts\n\n1. **Static Extraction**: Panda analyzes source files to extract styles at build time\n2. **Design Tokens**: Type-safe design tokens defined in config\n3. **Recipes**: Reusable component style patterns (like variants)\n4. **Conditions**: Responsive and state-based styling (e.g., `_hover`, `md:`, `_dark`)\n5. **CSS Emission**: The Rust stylesheet crate emits CSS, with native formatting and adjacent rule merging\n\n## Critical Rules\n\n### 🚨 CSS Output is Sacred\n\n**NEVER** accept changes that modify CSS output snapshots without explicit user approval:\n\n- Run tests BEFORE and AFTER any dependency updates\n- If snapshots change, investigate why and get user confirmation\n- CSS output is validated by the Rust `pandacss_stylesheet` insta snapshots plus the `sandbox/codegen` suite\n- CSS output consistency is more important than using latest package versions\n\nRecent Rust parity work (P1-6 / P2-7) tightened TS alignment — treat these as CSS contracts when reviewing diffs:\n\n- **Eager compound variants** — emitted by default at build time (`emit_eager_compounds`); runtime combo classes still\n apply for dynamic usage.\n- **`smartCompoundVariants`** — opt-in via `optimize.smartCompoundVariants: true`; narrows compound CSS to selected\n variant combos instead of emitting every permutation.\n- **Grouped `@media` emit** — rules that share `@media` / `@supports` wrapper prefixes are tree-grouped\n (`pandacss_stylesheet::grouped`) before writing CSS.\n- **Modern breakpoint syntax** — responsive conditions normalize to `@media (width >= Nrem)` via\n `pandacss_shared::to_rem` (px/em → rem; rem/%/vh pass through).\n\n### Testing Workflow\n\n**Always run tests from the project root:**\n\n```bash\n# ✅ Correct\npnpm test packages/cli\npnpm test packages/config\n\n# ❌ Incorrect\ncd packages/cli && pnpm test\n```\n\n**Key test commands:**\n\n```bash\npnpm test # Run tests for specific package/file\npnpm test packages/cli # Test one package\npnpm build # Build all packages\npnpm build:fast # Fast build without type definitions\n```\n\n### Package Management\n\n**Use `--ignore-scripts` for dependency updates:**\n\n```bash\npnpm install --ignore-scripts\npnpm update --ignore-scripts\n```\n\n**When updating CSS processing dependencies:**\n\n1. Update package.json versions\n2. Run `pnpm install --ignore-scripts`\n3. Run `cargo nextest run -p pandacss_stylesheet` and `sandbox/codegen` to verify CSS output unchanged\n4. Check the affected bundler integrations and sandbox projects\n5. Create changeset if changes affect users\n\n### Dependency Strategy\n\n- **PostCSS integration**: `@pandacss/postcss` integrates the Rust compiler with PostCSS; it does not own CSS emission\n- **lightningcss**: used in compiler compatibility tests, not in the Rust emission pipeline. Full CSS-aware optimization\n remains an open follow-up; see `design-notes/stylesheet.md`\n- **Workspace packages**: the `@pandacss/*` packages (cli, compiler, config, types, etc.) must stay in sync\n\n## Common Workflows\n\n### Making Code Changes\n\n1. Read relevant source files in `/packages//src/`\n2. Understand the change impact (does it affect CSS output?)\n3. Make changes\n4. Run tests: `pnpm test packages/`\n5. If tests fail, investigate and fix (don't just update snapshots)\n6. Create changeset for user-facing changes\n\n### Before committing\n\n**Always run the quality checks that match your diff before creating a git commit.** CI will run them anyway; catching\nfailures locally avoids broken PR checks and fix-up commits.\n\nRun from the repo root:\n\n| If you changed… | Run before commit |\n| ---------------------------------------------------------------- | -------------------------------------------------------------------- |\n| `crates/**`, `packages/compiler/**`, `packages/compiler-wasm/**` | `pnpm rust:fmt` and `pnpm rust:clippy` (Rust Quality CI) |\n| Rust engine / NAPI / `transformSource` behavior | `pnpm test:compiler` (rebuilds the `.node`, then compiler Vitest) |\n| TypeScript packages under `packages/**` | `pnpm test ` |\n| CSS output (Rust stylesheet emit) | `cargo nextest run -p pandacss_stylesheet` + `sandbox/codegen` first |\n\nFor broader pre-PR validation (not required on every commit): `pnpm rust:check`, `pnpm rust:test`, `pnpm typecheck`,\n`pnpm build:fast`.\n\nDo not commit with known failing fmt, clippy, or test output in the areas you touched.\n\n### Updating Dependencies\n\n1. Check current versions in package.json\n2. Research latest compatible versions\n3. Update package.json files\n4. Run `pnpm install --ignore-scripts`\n5. **Run CSS output checks first**: `cargo nextest run -p pandacss_stylesheet` + `sandbox/codegen`\n6. If snapshots change, investigate the root cause\n7. Run broader suite: `pnpm rust:test` (and `pnpm test ` for TS)\n8. Create changeset documenting the update\n\n### Creating Changesets\n\n```bash\n# Changesets are in .changeset/ directory\n# Create a new file: .changeset/.md\n```\n\n**Format:**\n\n```markdown\n---\n'@pandacss/package-name': patch|minor|major\n---\n\nBrief description of the change and its impact.\n\n- Detail 1\n- Detail 2\n```\n\nKeep changesets **concise**: one or two sentences on user-visible impact. Skip root-cause essays, long before/after\nexamples, and implementation detail — that belongs in the PR or commit message. Changesets are user-facing copy, so\nfollow [`TONE_OF_VOICE.md`](TONE_OF_VOICE.md).\n\n**Changeset types:**\n\n- `patch`: Bug fixes, dependency updates, non-breaking changes\n- `minor`: New features, backwards-compatible changes\n- `major`: Breaking changes\n\n## Communicating Issues & Fixes\n\nExplain to someone who knows Panda, not the internals. Default to short.\n\nPlain words over jargon. If a term only makes sense after reading the source, define it in half a sentence or drop it.\nThe reader should understand what broke and why without opening a file.\n\n**Shape** — four lines, in this order:\n\n- **Symptom** — what the user sees. \"`boxSize=\"4\"` emitted `box-size` instead of `width`/`height`.\"\n- **Cause** — one sentence. \"Replayed atoms skip the transform pass.\"\n- **Fix** — one sentence. \"Recompute on the consumer, which already has the callback.\"\n- **Confidence** — what you verified, what you assumed, what's still open.\n\n**Rules:**\n\n- Lead with the symptom. Never open with the code path.\n- One number or name per claim (`5 duplicate copies`, `schemaVersion 5`, a commit sha). Not \"much faster\".\n- Separate \"I verified this\" from \"I'm inferring this\". A traced code path is not a tested result.\n- Put caveats inline, not in a footer the reader never reaches.\n- A follow-up question is not a request for more detail. Answer what was asked.\n\n**Draw it when prose gets long.** If the explanation needs more than ~4 sentences, or crosses more than two hops,\nreplace the prose with a diagram:\n\n```\nlibrary consumer\n css({ boxSize: '4' }) build info: atom(boxSize, 4)\n │ │\n ▼ ▼\n transform() → { width, height } hydrate → transform skipped\n │ │\n ▼ ▼\n .size_4 { width; height } ✅ .size_4 { box-size } ❌\n```\n\nASCII in the terminal, mermaid in markdown docs. The diagram replaces the prose; it doesn't accompany it.\n\n## Important Files & Patterns\n\n### Configuration Flow\n\n1. User config → `packages/config/` (`loadConfig`, `bundleConfig`, snapshot)\n2. Config types/hooks → `packages/types/src/config.ts`\n3. Resolved config → `@pandacss/compiler` (NAPI) → Rust `pandacss_config` → `pandacss_system`\n4. Codegen + CSS emission happen inside the Rust engine (`crates/*`)\n\n### CSS Processing Flow (v2, Rust)\n\n1. Source scan + extraction → `crates/extractor` (Oxc)\n2. Style usage → atomic rules → `crates/encoder`\n3. Native CSS emission → `crates/stylesheet` (replaces the old PostCSS/lightningcss optimize path)\n4. Orchestration → `crates/pandacss_compiler`; project state and caches → `crates/pandacss_project`\n\n### Adding a new styled-system function\n\nA new factory in generated `styled-system` (`css`, `cva`, `sva`, `viewTransition`, …) is not a codegen-only change. Wire\nevery stage that sees call sites, or extract / transform / CSS emit will miss them. Use `viewTransition` or `cva` as a\nreference.\n\n| Stage | Where | What to do |\n| ----------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Allowlist / `importMap` | `pandacss_system` extractor config + `normalizeImportMap` | Add the call name under the right `MatchCategory`. New entrypoint → new `importMap` key + matcher; shared barrel → extend an existing category (like `viewTransition` on the css allowlist). |\n| Types | `packages/types` (+ codegen types if mirrored) | Public options / return types. |\n| Codegen | `pandacss_codegen` artifact + `css/index` barrel | Emit the factory. Reuse helpers (`toHash`, `memo`, …). Skip the artifact for syntaxes that don't support it. |\n| Hash contract | `pandacss_shared` | If runtime class names must match Rust emit, share one serialize/hash — don't fork two algorithms. |\n| Extract / encode | `pandacss_project` parse arm | Turn matched calls into project IR. |\n| Usages | `pandacss_project` usages walk | Visit style slots so unused-keyframe / unused-token pruning still sees them. |\n| Transform | `pandacss_transform` | Rewrite static calls. Leave the runtime import for dynamic ones. Clean up dead imports when fully inlined. |\n| Stylesheet | `pandacss_stylesheet` (+ orchestration in `pandacss_compiler`) | Emit CSS. Add insta snapshots. |\n| Design note | `design-notes/` + index | API shape, non-goals, pipeline. |\n| Tests | crate tests + `sandbox/codegen` when user-facing | Extract, transform (rewrite + dead import), stylesheet, codegen artifact, sandbox. |\n| Changeset | `.changeset/` | Short user-facing copy when the API ships. |\n\nCodegen alone ships a runtime function that Panda never extracts or emits CSS for. Extract/emit without transform leaves\nthe factory call in the bundle. Full path: allowlist → types → codegen → extract → usages → transform → stylesheet →\ntests → design note.\n\n### Test Fixtures\n\n- Rust: integration tests live in `crates//tests/`; see `design-notes/rust-testing.md`\n- TS: `sandbox/codegen` validates generated styled-system output across frameworks\n\n## Debugging Tips\n\n### Understanding Test Failures\n\n**Snapshot mismatches:**\n\n- Compare expected vs received CSS output carefully\n- Look for media query ordering, selector merging, or whitespace changes\n- Identify which dependency update caused the change\n- Check Rust stylesheet changes and any downstream bundler CSS processing\n\n**Build failures:**\n\n- Check TypeScript errors in `packages/*/src/`\n- Run `pnpm build:fast` for faster iteration without type checking\n- Use `pnpm typecheck` for type-only validation\n\n### Finding Code\n\n**Use search tools strategically:**\n\n- Grep for function names, class names, or specific strings\n- Check both `/src/` and `/__tests__/` directories\n- Look in `/packages/types/src/` for type definitions\n- Config options are defined in `packages/types/src/config.ts`\n\n## Watch Out For\n\n1. **Circular dependencies**: Be careful when adding imports between core packages\n2. **Browser compatibility**: Changes to browserslist affect CSS transformation\n3. **CSS processing ownership**: Rust emits Panda CSS; bundlers may apply their own CSS processing afterward\n4. **Workspace protocol**: Internal packages use `workspace:*` in dependencies\n5. **Multiple package.json**: Each package has its own, plus root package.json\n6. **Sandbox warnings**: Even if main packages are fine, check sandbox projects for warnings\n7. **Extraction is Rust/Oxc now**: `ts-morph`/`ts-evaluator` were removed with the v1 node pipeline. Extraction runs\n through `@pandacss/compiler` (Oxc) — don't reintroduce ts-morph assumptions.\n8. **MCP stdio lifecycle**: keep it minimal. The SDK transport keeps the process alive via `stdin`; on disconnect just\n exit (see `exitOnDisconnect` in `packages/mcp/src/server.ts` — stdin `end`/`close` + `SIGINT`/`SIGTERM`/`SIGHUP`,\n matching popular servers like context7). Do **not** add `await new Promise(() => {})` keep-alive, or heavy\n `uncaughtException`/EPIPE guards — no reference/shadcn/context7 server does that.\n9. **PostCSS plugin edits the parsed `Root` in place**: never re-parse `root.toString()`. Rules inlined from `@import`\n keep their own `source`, which bundlers use to rebase `url()`s and build source maps.\n\n## Package Relationships\n\n```\n@pandacss/cli (panda CLI)\n ├─ @pandacss/compiler (NAPI → Rust engine; extraction, codegen, CSS emission)\n ├─ @pandacss/config (config load / bundle / snapshot)\n ├─ @pandacss/types\n ├─ @pandacss/vite (bundler integration)\n └─ @pandacss/postcss (PostCSS plugin)\n\n@pandacss/dev\n ├─ . (browser-safe config helpers)\n ├─ /node (config loading + compiler APIs)\n └─ /cli (command runners)\n\n@pandacss/compiler (v2, NAPI)\n └─ crates/* (Rust workspace, all `pandacss_*`-prefixed)\n ├─ pandacss_extractor (Oxc parsing + scan_imports + match_imports)\n ├─ pandacss_literal (host-neutral extracted value IR)\n ├─ pandacss_encoder, pandacss_recipes, pandacss_tokens, pandacss_system, pandacss_project, pandacss_transform\n ├─ pandacss_stylesheet (native CSS emission), pandacss_compiler (CSS/codegen orchestration), pandacss_config\n ├─ packages/compiler/crate (compiler_napi cdylib — native NAPI)\n └─ packages/compiler-wasm/crate (compiler_wasm cdylib — browser wasm-bindgen)\n```\n\n## CLI (`@pandacss/cli`)\n\nThe `panda` command lives in `packages/cli/`. It uses **citty** for routing and **zod** for flag validation.\n\n**Subagent** (`.claude/agents/cli-design-expert.md`): embeds the full CLI design contract (human-first help, output,\nerrors, flags, interactivity, scripting). Invoke **`cli-design-expert`** for new subcommands, flag changes,\nerror-message work, or help/usage reviews — no need to consult external CLI guides separately.\n\n**Key files:**\n\n- `packages/cli/src/cli-main.ts` — dispatcher; bare `panda` runs the full build\n- `packages/cli/src/args.ts`, `schema.ts` — shared flags\n- `packages/cli/src/commands/` — subcommands\n- `packages/cli/src/output.ts`, `diagnostics.ts`, `result.ts` — streams and exit codes\n\n**Panda CLI conventions:**\n\n- Default `panda` (no subcommand) runs the full build\n- Shared flags: `--cwd`, `--config` / `-c`, `--json`, `--format`, `--log-level`, trace flags\n- Exit codes: `0` success, `1` failed, `2` usage, `3` internal (`ExitCode` in `result.ts`)\n\n**Before committing CLI changes:** `pnpm test packages/cli`\n\n## Rust / Oxc Engine\n\nPanda 2.0 replaced the `ts-morph` + `ts-evaluator` compiler with a Rust/Oxc engine. JS-facing APIs stay stable; Rust\nships behind `@pandacss/compiler`.\n\n**Read first** before touching Rust:\n\n- [`crates/RUST_GUIDE.md`](crates/RUST_GUIDE.md) — coding standards, review checklist, PR review output format, and Rust\n subagent index. Consult this when writing or reviewing Rust code; use `AGENTS.md` (this file) for commands and\n workflows.\n- `design-notes/README.md` — index of durable Rust architectural decisions (crate layering, extraction pipeline, literal\n evaluator, project lifecycle, NAPI boundary, performance budget, scope and boundaries, publish namespace). **Skim the\n index on the first Rust task in any session and consult the specific note before any change in that area.** When you\n change the underlying design, update the matching note in the same PR.\n- `design-notes/rust-testing.md` — full Rust testing strategy (consolidated harness, insta workflow, fast iteration).\n\n**Subagents** (`.claude/agents/`): `cli-design-expert` (CLI UX — see [CLI section](#cli-pandacsscli)), `rust-engineer`\n(implement), `rust-reviewer` (read-only review), `oxc-extractor-architect` (extraction/Oxc), `rust-perf-analyst`\n(benchmarks / `PERF(port):` flips).\n\n### Toolchain\n\n- Rust pinned to `1.93.0` via `rust-toolchain.toml` (matches Oxc 0.130 MSRV).\n- Oxc crates: `oxc_allocator`, `oxc_ast`, `oxc_diagnostics`, `oxc_parser`, `oxc_span` at `0.130.0`.\n- Test deps: `insta` (inline YAML snapshots) + `indoc` (dedented multi-line source fixtures).\n\n### Commands\n\n**Workspace-wide (pre-PR / CI):**\n\n```sh\npnpm rust:check # cargo check --workspace --locked\npnpm rust:test # cargo nextest run --workspace --locked (+ doc tests)\npnpm rust:test:cargo # cargo test --workspace --locked (fallback without nextest)\npnpm rust:fmt # cargo fmt --all --check\npnpm rust:clippy # cargo clippy --all-targets --locked -- -D warnings\npnpm bench:rust-spike # TS baseline benchmark\npnpm --filter @pandacss/compiler build:native # build the NAPI .node artifact\npnpm --filter @pandacss/compiler test # Vitest against the current .node (may be stale)\npnpm test:compiler # build:native then compiler Vitest (use after Rust/NAPI/transform changes)\n```\n\n**Bench / legacy comparison tests:**\n\n- Benchmarks that compare v2 against legacy Panda must run the **legacy JS side** against the published npm packages,\n not local workspace `packages/*` sources. Keep legacy deps in `bench/package.json` pinned to npm versions (for example\n `@pandacss/node`, `@pandacss/extractor`, `@pandacss/token-dictionary`), and keep v2-only packages such as\n `@pandacss/compiler`, `@pandacss/compiler-wasm`, and `@pandacss/config` on `workspace:*`.\n- Do not run bench comparison scripts with `--conditions source`; published npm packages do not ship `src/index.ts`. Use\n the `pnpm --filter=./bench