skills/chakra-ui__chakra-ui
1
0
Fork 0
mirror of https://github.com/chakra-ui/chakra-ui.git synced 2026-09-14 16:43:45 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
@chakra-ui/react@3.36.1
chakra-ui__chakra-ui/CLAUDE.md
T
Segun Adebayo f26e863add fix: cva normalize
2025-09-30 17:49:38 +01:00

9.2 KiB
Raw Permalink Blame History

Claude's Learning Document - Chakra UI

Last Updated: September 30, 2025

Project Overview

Chakra UI is a comprehensive React component system for building accessible, high-quality web applications and design systems. It emphasizes speed, accessibility, and works seamlessly with modern frameworks like Next.js (including RSC support).

Project Structure

Root Directory

chakra-ui/
├── packages/           # Core packages
├── apps/              # Applications (www docs, mcp server)
├── sandbox/           # Testing environments
├── scripts/           # Build and utility scripts
├── .changeset/        # Changesets for versioning
└── package.json       # Root package configuration

Key Packages

  1. packages/react - Main React component library

    • Core system implementation
    • Styled-system utilities
    • Component recipes
    • Type definitions

  2. packages/cli - CLI tools for Chakra UI

    • Type generation
    • Token management

  3. packages/charts - Chart components

  4. packages/panda-preset - Panda CSS preset for Chakra

Apps

  1. apps/www - Documentation website (https://chakra-ui.com)
  2. apps/mcp - MCP server for AI integrations
  3. apps/compositions - Component compositions examples

Sandbox Environments

Multiple sandbox projects for testing in different environments:

  • next-app/, next-pages/ - Next.js testing
  • vite-ts/, vite-jsx/ - Vite testing
  • remix-ts/ - Remix testing
  • react-router/ - React Router testing
  • storybook-ts/ - Storybook testing
  • shadow-dom/ - Shadow DOM testing

Styled System Architecture

The styled-system is the heart of Chakra UI's styling engine. Located in packages/react/src/styled-system/:

Core Files

  1. system.ts - Main system creation and configuration

    • Creates the Chakra system instance
    • Integrates tokens, breakpoints, conditions, and utilities
    • Provides CSS-in-JS functionality

  2. cva.ts (Class Variance Authority) - Recipe creation

    • Handles variant-based styling
    • Processes base styles, variants, and compound variants
    • Recent Fix: Now properly handles bracket syntax for responsive styles in recipes

  3. sva.ts (Slot Variance Authority) - Multi-slot recipe creation

    • For components with multiple parts (slots)
    • Each slot can have its own variants

  4. token-dictionary.ts - Token management

    • Token resolution and transformation
    • Semantic token handling
    • Color palette expansion

  5. breakpoints.ts - Responsive breakpoint system

    • Converts breakpoint names to media queries
    • Handles array syntax for responsive values

  6. conditions.ts - Conditional styling

    • Pseudo-selectors (:hover, :focus, etc.)
    • Data attributes
    • Media queries

  7. utility.ts - Utility function management

    • Property transformations
    • CSS property mappings

  8. calc.ts - CSS calc() utilities

    • Mathematical operations in CSS

Style Resolution Flow

  1. User defines styles (tokens, recipes, variants)
  2. normalize() processes raw style objects
  3. Breakpoint arrays [value1, value2] → responsive object {base: value1, sm: value2}
  4. Tokens get resolved from token dictionary
  5. Conditions get applied (media queries, pseudo-selectors)
  6. CSS output is generated with proper layering

Recent Work: Recipe Bracket Syntax Fix

Problem

Array/bracket syntax for responsive styles wasn't working correctly in recipe variants:

const recipe = system.cva({
  variants: {
    variant: {
      primary: {
        color: ["red", "green"], // ❌ Wasn't converting to breakpoints
      },
    },
  },
})

Solution

Enhanced the normalization process in the recipe system to handle bracket syntax properly. The fix ensures that:

  1. Base styles support bracket syntax
  2. Variant styles support bracket syntax
  3. Compound variants support bracket syntax
  4. Mixed bracket and object syntax works correctly

Modified Files

  • packages/react/src/styled-system/breakpoints.ts
  • packages/react/src/styled-system/calc.ts
  • packages/react/src/styled-system/conditions.ts
  • packages/react/src/styled-system/cva.ts
  • packages/react/src/styled-system/sva.ts
  • packages/react/src/styled-system/system.ts
  • packages/react/src/styled-system/token-dictionary.ts
  • packages/react/src/styled-system/utility.ts
  • packages/react/src/utils/entries.ts

Test Coverage

Created comprehensive tests in packages/react/__tests__/recipe.test.ts:

  1. ✅ Bracket syntax in recipe variants (original issue)
  2. ✅ Bracket syntax in base styles
  3. ✅ Object syntax as control test
  4. ✅ Multiple properties with bracket syntax
  5. ✅ Multiple breakpoints (3+ values)
  6. ✅ Compound variants with bracket syntax
  7. ✅ Mixed bracket and object syntax
  8. ✅ Partial breakpoint values
  9. ✅ Multiple variant options with bracket syntax

Changeset

Created .changeset/fix-recipe-bracket-syntax.md documenting the fix for release notes.

Build Scripts

Core Commands

pnpm build              # Build all packages
pnpm build:fast         # Fast build (no type checking)
pnpm dev                # Watch mode for all packages
pnpm test               # Run Vitest tests
pnpm typecheck          # TypeScript type checking

Token Generation

pnpm build:tokens       # Generate TypeScript types from tokens
pnpm build:tokens-dev   # Generate tokens locally

Package Management

pnpm react              # Run commands in @chakra-ui/react
pnpm www                # Run commands in docs site
pnpm mcp                # Run commands in MCP server

Quality Assurance

pnpm lint               # ESLint
pnpm format:check       # Prettier check
pnpm format:write       # Prettier format

Release Management

pnpm version            # Create version with changesets
pnpm release            # Publish to npm
pnpm version:dev        # Create dev snapshot version
pnpm release:dev        # Publish dev version

Key Technologies

  • React 19.1.1 with Server Components support
  • TypeScript 5.8.3 for type safety
  • Vite 7.0.0 for bundling and dev server
  • Vitest 3.2.4 for testing
  • Panda CSS preset for styling
  • Changesets for version management
  • Rollup for package bundling
  • Storybook 9.1.8 for component development

Testing Philosophy

  • Unit tests with Vitest
  • Accessibility tests with vitest-axe
  • Component tests with @testing-library/react
  • Integration tests in sandbox environments
  • Storybook for visual testing

Key Design Principles

  1. Accessibility First - WCAG compliant components
  2. Type Safety - Full TypeScript support
  3. Performance - Optimized style resolution
  4. Developer Experience - Intuitive APIs
  5. Composability - Build complex UIs from simple primitives
  6. Responsive - Mobile-first design patterns
  7. Themeable - Customizable design tokens

Current Git Status

Staged Files (Recent Work)

  • .changeset/fix-recipe-bracket-syntax.md - Changeset for recipe fix
  • packages/react/__tests__/recipe.test.ts - New test suite
  • Multiple styled-system files (modified for bracket syntax support)

Recent Commits

  • 96edd4393 - docs: password input example
  • 5b2bc851f - fix(www): update showcase navigation
  • c58b20530 - docs: ai rules
  • e59f66e19 - docs: update focus ring
  • 451209e75 - fix(table): ensure stickyHeader works with outline variant

Learning Insights

Responsive Style Patterns

Bracket Syntax (Array)

color: ["red", "green", "blue"]
// Maps to: base=red, sm=green, md=blue

Object Syntax

color: { base: 'red', sm: 'green', md: 'blue' }

Both are equivalent and should work interchangeably throughout the system.

Recipe System

CVA (Class Variance Authority) - Single component styling

const button = system.cva({
  base: {
    /* base styles */
  },
  variants: {
    /* variants */
  },
  compoundVariants: [
    /* combinations */
  ],
  defaultVariants: {
    /* defaults */
  },
})

SVA (Slot Variance Authority) - Multi-part component styling

const card = system.sva({
  slots: ["root", "header", "body", "footer"],
  base: {
    /* styles per slot */
  },
  variants: {
    /* variants per slot */
  },
})

Token System

  • Semantic tokens reference base tokens
  • Color palettes auto-expand (50-950 scales)
  • Tokens can use CSS variables
  • Token dictionary handles resolution and transformation

Next Steps / Areas to Explore

  1. Understanding the component architecture in packages/react/src/components/
  2. Deep dive into the Panda CSS integration
  3. MCP server capabilities for AI integrations
  4. Documentation generation system
  5. CLI tooling for scaffolding and code generation
  6. Performance optimization strategies
  7. Build pipeline and bundle optimization

This document serves as a living knowledge base for Claude to maintain context about the Chakra UI project structure, recent changes, and architectural decisions.

Reference in New Issue View Git Blame Copy Permalink