{"owner":"chakra-ui","repo":"panda","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# Claude Code 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** with workspace support.\n\n## Key Architecture\n\n### Monorepo Structure\n\n```\n/packages/          # Core packages published to npm\n  /core/           # CSS processing, rule generation, optimization (PostCSS/LightningCSS)\n  /node/           # Node.js APIs, config resolution, file watching\n  /cli/            # CLI tool (@pandacss/dev package)\n  /parser/         # Static analysis and extraction\n  /generator/      # Code generation for styled-system\n  /fixture/        # Shared test fixtures and utilities\n  /postcss/        # PostCSS plugin\n  /preset-*/       # Design system presets\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/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 Optimization**: Uses PostCSS (default) or LightningCSS (optional) for CSS processing\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- The test `packages/core/__tests__/atomic-rule.test.ts` is the primary CSS output validator\n- CSS output consistency is more important than using latest package versions\n\n### Testing Workflow\n\n**Always run tests from the project root:**\n\n```bash\n# ✅ Correct\npnpm test packages/core\npnpm test packages/parser\n\n# ❌ Incorrect\ncd packages/core && pnpm test\n```\n\n**Key test commands:**\n```bash\npnpm test <path>              # Run tests for specific package/file\npnpm test packages/core       # Test all core package tests\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```bash\npnpm install --ignore-scripts\npnpm update <package> --ignore-scripts\n```\n\n**When updating PostCSS or browserslist-related packages:**\n1. Update package.json versions\n2. Run `pnpm install --ignore-scripts`\n3. Run `pnpm test packages/core` to verify CSS output unchanged\n4. Check for browserslist warnings in sandbox projects\n5. Create changeset if changes affect users\n\n### Dependency Strategy\n\n- **PostCSS ecosystem**: Coordinate updates across all PostCSS plugins to avoid CSS output changes\n- **browserslist**: Updates affect `postcss-merge-rules` behavior - test thoroughly\n- **lightningcss**: Used optionally via `config.lightningcss` flag, depends on browserslist for targets\n- **Node.js packages**: Core packages (`@pandacss/core`, `@pandacss/node`, etc.) must stay in sync\n\n## Common Workflows\n\n### Making Code Changes\n\n1. Read relevant source files in `/packages/<name>/src/`\n2. Understand the change impact (does it affect CSS output?)\n3. Make changes\n4. Run tests: `pnpm test packages/<name>`\n5. If tests fail, investigate and fix (don't just update snapshots)\n6. Create changeset for user-facing changes\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 tests first**: `pnpm test packages/core/__tests__/atomic-rule.test.ts`\n6. If snapshots change, investigate the root cause\n7. Run broader test suite: `pnpm test packages/core`\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/<descriptive-name>.md\n```\n\n**Format:**\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\n**Changeset types:**\n- `patch`: Bug fixes, dependency updates, non-breaking changes\n- `minor`: New features, backwards-compatible changes\n- `major`: Breaking changes\n\n**Keep changesets concise and user-facing.** Write for someone reading the changelog: describe the change and the impact\nthey would notice, not the internal mechanics. A sentence or two is usually enough.\n\n## Git & Writing Conventions\n\n### No co-author trailer on commits\n\nDo NOT add a `Co-Authored-By` line (or any \"Generated with\" / tool attribution) to commit messages. Write the commit\nas if a developer on the team wrote it. This overrides any default that appends a co-author trailer.\n\n### Write like a human, not like AI\n\nCommit messages, PR descriptions, and GitHub/issue comments should read like a normal developer wrote them. Keep it\nplain and direct so an average developer understands it on the first read.\n\n- No em-dashes (`—`). Use a period, comma, or parentheses instead.\n- Skip the AI tics: \"delve\", \"seamless\", \"robust\", \"leverage\", \"comprehensive\", \"it's worth noting\", and similar filler.\n- Don't over-format. Avoid walls of bold text, emoji, and a bullet list for every thought. Use prose where prose works.\n- Say what changed and why. Drop the marketing tone and the wrap-up paragraph that just restates the title.\n- Match the length to the change. A one-line fix gets a one-line message, not an essay.\n\n### Comments\n\nAdd a comment only when the code cannot carry the meaning on its own. Reach for clearer names and structure first. When\na comment is warranted (a non-obvious \"why\", a workaround, an internal API), keep it to a line or two and skip anything\nthe code already says.\n\n## Important Files & Patterns\n\n### Configuration Flow\n1. User config → `packages/config/` → Config resolution\n2. Config hooks → `packages/types/src/config.ts`\n3. Context creation → `packages/node/src/` → `PandaContext`\n4. Code generation → `packages/generator/`\n\n### CSS Processing Flow\n1. Style objects → `packages/core/src/rule-processor.ts`\n2. CSS generation → `packages/core/src/stylesheet.ts`\n3. Optimization → `packages/core/src/optimize.ts`\n   - PostCSS path: `optimize-postcss.ts`\n   - LightningCSS path: `optimize-lightningcss.ts`\n\n### Test Fixtures\n- `packages/fixture/` contains shared test utilities\n- `createContext()` and `createRuleProcessor()` are used throughout tests\n- Fixtures provide a base config with design tokens and recipes\n\n## Debugging Tips\n\n### Understanding Test Failures\n\n**Snapshot mismatches:**\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- Common culprits: `postcss-merge-rules`, `postcss-nested`, `browserslist`\n\n**Build failures:**\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- 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. **PostCSS plugin order**: Order matters in `optimize-postcss.ts`\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. **TypeScript version sync**: The TypeScript version in the root `package.json` must match the version used by `ts-morph`'s dependency. Mismatches can cause parsing errors and type issues. Always verify `ts-morph` compatibility when updating TypeScript.\n\n## Package Relationships\n\n```\n@pandacss/dev (CLI)\n  ├─ @pandacss/node (core runtime)\n  │   ├─ @pandacss/core (CSS processing)\n  │   ├─ @pandacss/parser (static analysis)\n  │   ├─ @pandacss/generator (codegen)\n  │   └─ @pandacss/config (config resolution)\n  └─ @pandacss/postcss (PostCSS plugin)\n\n@pandacss/core\n  ├─ postcss (CSS processing)\n  ├─ lightningcss (optional, faster CSS processing)\n  ├─ browserslist (browser targets)\n  └─ postcss-* plugins (optimization)\n```\n\n## Useful References\n\n- **Main documentation**: `/website/` (documentation source)\n- **Type definitions**: `packages/types/src/` (comprehensive types)\n- **Integration examples**: `/sandbox/` (real-world usage)\n- **Test patterns**: `packages/fixture/` and `packages/core/__tests__/`\n\n## Best Practices for AI Assistants\n\n1. **Always read before writing**: Understand existing patterns before making changes\n2. **Test incrementally**: Run tests after small changes, not just at the end\n3. **Preserve CSS output**: When in doubt, prioritize CSS output stability\n4. **Use workspace knowledge**: Remember this is a monorepo - changes may affect multiple packages\n5. **Document breaking changes**: If CSS output must change, explain why clearly\n6. **Check sandboxes**: Don't just test main packages - verify sandbox projects too\n\n## Emergency Rollback\n\nIf a change breaks things:\n```bash\ngit checkout packages/          # Revert package.json changes\npnpm install --ignore-scripts   # Restore dependencies\npnpm test packages/core         # Verify tests pass\n```\n\n---\n\n**Last Updated**: 2025-01-17\n**Project Version**: 1.4.2\n"},"files":{"CLAUDE.md":"# Claude Code 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** with workspace support.\n\n## Key Architecture\n\n### Monorepo Structure\n\n```\n/packages/          # Core packages published to npm\n  /core/           # CSS processing, rule generation, optimization (PostCSS/LightningCSS)\n  /node/           # Node.js APIs, config resolution, file watching\n  /cli/            # CLI tool (@pandacss/dev package)\n  /parser/         # Static analysis and extraction\n  /generator/      # Code generation for styled-system\n  /fixture/        # Shared test fixtures and utilities\n  /postcss/        # PostCSS plugin\n  /preset-*/       # Design system presets\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/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 Optimization**: Uses PostCSS (default) or LightningCSS (optional) for CSS processing\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- The test `packages/core/__tests__/atomic-rule.test.ts` is the primary CSS output validator\n- CSS output consistency is more important than using latest package versions\n\n### Testing Workflow\n\n**Always run tests from the project root:**\n\n```bash\n# ✅ Correct\npnpm test packages/core\npnpm test packages/parser\n\n# ❌ Incorrect\ncd packages/core && pnpm test\n```\n\n**Key test commands:**\n```bash\npnpm test <path>              # Run tests for specific package/file\npnpm test packages/core       # Test all core package tests\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```bash\npnpm install --ignore-scripts\npnpm update <package> --ignore-scripts\n```\n\n**When updating PostCSS or browserslist-related packages:**\n1. Update package.json versions\n2. Run `pnpm install --ignore-scripts`\n3. Run `pnpm test packages/core` to verify CSS output unchanged\n4. Check for browserslist warnings in sandbox projects\n5. Create changeset if changes affect users\n\n### Dependency Strategy\n\n- **PostCSS ecosystem**: Coordinate updates across all PostCSS plugins to avoid CSS output changes\n- **browserslist**: Updates affect `postcss-merge-rules` behavior - test thoroughly\n- **lightningcss**: Used optionally via `config.lightningcss` flag, depends on browserslist for targets\n- **Node.js packages**: Core packages (`@pandacss/core`, `@pandacss/node`, etc.) must stay in sync\n\n## Common Workflows\n\n### Making Code Changes\n\n1. Read relevant source files in `/packages/<name>/src/`\n2. Understand the change impact (does it affect CSS output?)\n3. Make changes\n4. Run tests: `pnpm test packages/<name>`\n5. If tests fail, investigate and fix (don't just update snapshots)\n6. Create changeset for user-facing changes\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 tests first**: `pnpm test packages/core/__tests__/atomic-rule.test.ts`\n6. If snapshots change, investigate the root cause\n7. Run broader test suite: `pnpm test packages/core`\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/<descriptive-name>.md\n```\n\n**Format:**\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\n**Changeset types:**\n- `patch`: Bug fixes, dependency updates, non-breaking changes\n- `minor`: New features, backwards-compatible changes\n- `major`: Breaking changes\n\n**Keep changesets concise and user-facing.** Write for someone reading the changelog: describe the change and the impact\nthey would notice, not the internal mechanics. A sentence or two is usually enough.\n\n## Git & Writing Conventions\n\n### No co-author trailer on commits\n\nDo NOT add a `Co-Authored-By` line (or any \"Generated with\" / tool attribution) to commit messages. Write the commit\nas if a developer on the team wrote it. This overrides any default that appends a co-author trailer.\n\n### Write like a human, not like AI\n\nCommit messages, PR descriptions, and GitHub/issue comments should read like a normal developer wrote them. Keep it\nplain and direct so an average developer understands it on the first read.\n\n- No em-dashes (`—`). Use a period, comma, or parentheses instead.\n- Skip the AI tics: \"delve\", \"seamless\", \"robust\", \"leverage\", \"comprehensive\", \"it's worth noting\", and similar filler.\n- Don't over-format. Avoid walls of bold text, emoji, and a bullet list for every thought. Use prose where prose works.\n- Say what changed and why. Drop the marketing tone and the wrap-up paragraph that just restates the title.\n- Match the length to the change. A one-line fix gets a one-line message, not an essay.\n\n### Comments\n\nAdd a comment only when the code cannot carry the meaning on its own. Reach for clearer names and structure first. When\na comment is warranted (a non-obvious \"why\", a workaround, an internal API), keep it to a line or two and skip anything\nthe code already says.\n\n## Important Files & Patterns\n\n### Configuration Flow\n1. User config → `packages/config/` → Config resolution\n2. Config hooks → `packages/types/src/config.ts`\n3. Context creation → `packages/node/src/` → `PandaContext`\n4. Code generation → `packages/generator/`\n\n### CSS Processing Flow\n1. Style objects → `packages/core/src/rule-processor.ts`\n2. CSS generation → `packages/core/src/stylesheet.ts`\n3. Optimization → `packages/core/src/optimize.ts`\n   - PostCSS path: `optimize-postcss.ts`\n   - LightningCSS path: `optimize-lightningcss.ts`\n\n### Test Fixtures\n- `packages/fixture/` contains shared test utilities\n- `createContext()` and `createRuleProcessor()` are used throughout tests\n- Fixtures provide a base config with design tokens and recipes\n\n## Debugging Tips\n\n### Understanding Test Failures\n\n**Snapshot mismatches:**\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- Common culprits: `postcss-merge-rules`, `postcss-nested`, `browserslist`\n\n**Build failures:**\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- 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. **PostCSS plugin order**: Order matters in `optimize-postcss.ts`\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. **TypeScript version sync**: The TypeScript version in the root `package.json` must match the version used by `ts-morph`'s dependency. Mismatches can cause parsing errors and type issues. Always verify `ts-morph` compatibility when updating TypeScript.\n\n## Package Relationships\n\n```\n@pandacss/dev (CLI)\n  ├─ @pandacss/node (core runtime)\n  │   ├─ @pandacss/core (CSS processing)\n  │   ├─ @pandacss/parser (static analysis)\n  │   ├─ @pandacss/generator (codegen)\n  │   └─ @pandacss/config (config resolution)\n  └─ @pandacss/postcss (PostCSS plugin)\n\n@pandacss/core\n  ├─ postcss (CSS processing)\n  ├─ lightningcss (optional, faster CSS processing)\n  ├─ browserslist (browser targets)\n  └─ postcss-* plugins (optimization)\n```\n\n## Useful References\n\n- **Main documentation**: `/website/` (documentation source)\n- **Type definitions**: `packages/types/src/` (comprehensive types)\n- **Integration examples**: `/sandbox/` (real-world usage)\n- **Test patterns**: `packages/fixture/` and `packages/core/__tests__/`\n\n## Best Practices for AI Assistants\n\n1. **Always read before writing**: Understand existing patterns before making changes\n2. **Test incrementally**: Run tests after small changes, not just at the end\n3. **Preserve CSS output**: When in doubt, prioritize CSS output stability\n4. **Use workspace knowledge**: Remember this is a monorepo - changes may affect multiple packages\n5. **Document breaking changes**: If CSS output must change, explain why clearly\n6. **Check sandboxes**: Don't just test main packages - verify sandbox projects too\n\n## Emergency Rollback\n\nIf a change breaks things:\n```bash\ngit checkout packages/          # Revert package.json changes\npnpm install --ignore-scripts   # Restore dependencies\npnpm test packages/core         # Verify tests pass\n```\n\n---\n\n**Last Updated**: 2025-01-17\n**Project Version**: 1.4.2\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# Claude Code 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** with workspace support.\n\n## Key Architecture\n\n### Monorepo Structure\n\n```\n/packages/          # Core packages published to npm\n  /core/           # CSS processing, rule generation, optimization (PostCSS/LightningCSS)\n  /node/           # Node.js APIs, config resolution, file watching\n  /cli/            # CLI tool (@pandacss/dev package)\n  /parser/         # Static analysis and extraction\n  /generator/      # Code generation for styled-system\n  /fixture/        # Shared test fixtures and utilities\n  /postcss/        # PostCSS plugin\n  /preset-*/       # Design system presets\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/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 Optimization**: Uses PostCSS (default) or LightningCSS (optional) for CSS processing\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- The test `packages/core/__tests__/atomic-rule.test.ts` is the primary CSS output validator\n- CSS output consistency is more important than using latest package versions\n\n### Testing Workflow\n\n**Always run tests from the project root:**\n\n```bash\n# ✅ Correct\npnpm test packages/core\npnpm test packages/parser\n\n# ❌ Incorrect\ncd packages/core && pnpm test\n```\n\n**Key test commands:**\n```bash\npnpm test <path>              # Run tests for specific package/file\npnpm test packages/core       # Test all core package tests\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```bash\npnpm install --ignore-scripts\npnpm update <package> --ignore-scripts\n```\n\n**When updating PostCSS or browserslist-related packages:**\n1. Update package.json versions\n2. Run `pnpm install --ignore-scripts`\n3. Run `pnpm test packages/core` to verify CSS output unchanged\n4. Check for browserslist warnings in sandbox projects\n5. Create changeset if changes affect users\n\n### Dependency Strategy\n\n- **PostCSS ecosystem**: Coordinate updates across all PostCSS plugins to avoid CSS output changes\n- **browserslist**: Updates affect `postcss-merge-rules` behavior - test thoroughly\n- **lightningcss**: Used optionally via `config.lightningcss` flag, depends on browserslist for targets\n- **Node.js packages**: Core packages (`@pandacss/core`, `@pandacss/node`, etc.) must stay in sync\n\n## Common Workflows\n\n### Making Code Changes\n\n1. Read relevant source files in `/packages/<name>/src/`\n2. Understand the change impact (does it affect CSS output?)\n3. Make changes\n4. Run tests: `pnpm test packages/<name>`\n5. If tests fail, investigate and fix (don't just update snapshots)\n6. Create changeset for user-facing changes\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 tests first**: `pnpm test packages/core/__tests__/atomic-rule.test.ts`\n6. If snapshots change, investigate the root cause\n7. Run broader test suite: `pnpm test packages/core`\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/<descriptive-name>.md\n```\n\n**Format:**\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\n**Changeset types:**\n- `patch`: Bug fixes, dependency updates, non-breaking changes\n- `minor`: New features, backwards-compatible changes\n- `major`: Breaking changes\n\n**Keep changesets concise and user-facing.** Write for someone reading the changelog: describe the change and the impact\nthey would notice, not the internal mechanics. A sentence or two is usually enough.\n\n## Git & Writing Conventions\n\n### No co-author trailer on commits\n\nDo NOT add a `Co-Authored-By` line (or any \"Generated with\" / tool attribution) to commit messages. Write the commit\nas if a developer on the team wrote it. This overrides any default that appends a co-author trailer.\n\n### Write like a human, not like AI\n\nCommit messages, PR descriptions, and GitHub/issue comments should read like a normal developer wrote them. Keep it\nplain and direct so an average developer understands it on the first read.\n\n- No em-dashes (`—`). Use a period, comma, or parentheses instead.\n- Skip the AI tics: \"delve\", \"seamless\", \"robust\", \"leverage\", \"comprehensive\", \"it's worth noting\", and similar filler.\n- Don't over-format. Avoid walls of bold text, emoji, and a bullet list for every thought. Use prose where prose works.\n- Say what changed and why. Drop the marketing tone and the wrap-up paragraph that just restates the title.\n- Match the length to the change. A one-line fix gets a one-line message, not an essay.\n\n### Comments\n\nAdd a comment only when the code cannot carry the meaning on its own. Reach for clearer names and structure first. When\na comment is warranted (a non-obvious \"why\", a workaround, an internal API), keep it to a line or two and skip anything\nthe code already says.\n\n## Important Files & Patterns\n\n### Configuration Flow\n1. User config → `packages/config/` → Config resolution\n2. Config hooks → `packages/types/src/config.ts`\n3. Context creation → `packages/node/src/` → `PandaContext`\n4. Code generation → `packages/generator/`\n\n### CSS Processing Flow\n1. Style objects → `packages/core/src/rule-processor.ts`\n2. CSS generation → `packages/core/src/stylesheet.ts`\n3. Optimization → `packages/core/src/optimize.ts`\n   - PostCSS path: `optimize-postcss.ts`\n   - LightningCSS path: `optimize-lightningcss.ts`\n\n### Test Fixtures\n- `packages/fixture/` contains shared test utilities\n- `createContext()` and `createRuleProcessor()` are used throughout tests\n- Fixtures provide a base config with design tokens and recipes\n\n## Debugging Tips\n\n### Understanding Test Failures\n\n**Snapshot mismatches:**\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- Common culprits: `postcss-merge-rules`, `postcss-nested`, `browserslist`\n\n**Build failures:**\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- 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. **PostCSS plugin order**: Order matters in `optimize-postcss.ts`\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. **TypeScript version sync**: The TypeScript version in the root `package.json` must match the version used by `ts-morph`'s dependency. Mismatches can cause parsing errors and type issues. Always verify `ts-morph` compatibility when updating TypeScript.\n\n## Package Relationships\n\n```\n@pandacss/dev (CLI)\n  ├─ @pandacss/node (core runtime)\n  │   ├─ @pandacss/core (CSS processing)\n  │   ├─ @pandacss/parser (static analysis)\n  │   ├─ @pandacss/generator (codegen)\n  │   └─ @pandacss/config (config resolution)\n  └─ @pandacss/postcss (PostCSS plugin)\n\n@pandacss/core\n  ├─ postcss (CSS processing)\n  ├─ lightningcss (optional, faster CSS processing)\n  ├─ browserslist (browser targets)\n  └─ postcss-* plugins (optimization)\n```\n\n## Useful References\n\n- **Main documentation**: `/website/` (documentation source)\n- **Type definitions**: `packages/types/src/` (comprehensive types)\n- **Integration examples**: `/sandbox/` (real-world usage)\n- **Test patterns**: `packages/fixture/` and `packages/core/__tests__/`\n\n## Best Practices for AI Assistants\n\n1. **Always read before writing**: Understand existing patterns before making changes\n2. **Test incrementally**: Run tests after small changes, not just at the end\n3. **Preserve CSS output**: When in doubt, prioritize CSS output stability\n4. **Use workspace knowledge**: Remember this is a monorepo - changes may affect multiple packages\n5. **Document breaking changes**: If CSS output must change, explain why clearly\n6. **Check sandboxes**: Don't just test main packages - verify sandbox projects too\n\n## Emergency Rollback\n\nIf a change breaks things:\n```bash\ngit checkout packages/          # Revert package.json changes\npnpm install --ignore-scripts   # Restore dependencies\npnpm test packages/core         # Verify tests pass\n```\n\n---\n\n**Last Updated**: 2025-01-17\n**Project Version**: 1.4.2\n","category":"root","tokens":2485}]}