# mui/pigment-css architecture

> Architecture diagram of the GitHub repository mui/pigment-css, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mui/pigment-css
- Repository: https://github.com/mui/pigment-css

## Overview

##### Project Type and Purpose
- This project is an open-source, monorepo-based library that implements a zero-runtime CSS-in-JS solution.
- Its purpose is to provide a build-time CSS extraction mechanism along with helper APIs (such as styled components, css, keyframes, global styles, theming, and the sx prop) for managing and composing styles in React applications. There are also integration plugins for popular frameworks (Next.js, Vite) and utilities for processing themes and dynamic style rules.
- The README gives plenty of usage instructions (getting started, theming, RTL support, etc.), and the file tree shows numerous packages, apps (examples/demos), docs, and workflows—indicating a multi-package ecosystem for both core functionality and integrations.

##### File Structure (High-Level Breakdown)
- Root Level:
- Configuration files (.eslintrc, .circleci, .github workflows, tsconfig, webpack config, etc.) for code quality, CI/CD, and build processes.
- Multiple documentation files (CHANGELOG, README, HOW_PIGMENT_CSS_WORKS.md, CONTRIBUTING).
- Scripts folder for building, testing, releasing, and other automation.
- Monorepo Management:
- Files like lerna.json, pnpm-workspace.yaml indicate use of Lerna and pnpm workspaces to manage multiple packages.
- Key Directories:
- apps: Contains demo applications (local UI libraries, Next.js app, Vite app) that showcase integration. They demonstrate how to set up Pigment CSS with corresponding bundlers.
- packages: Contains all the independent modules such as:
- pigment-css-core – the fundamental logic for CSS extraction and style processors.
- pigment-css-react – React-specific helpers including styled components, sx prop, and theming.
- pigment-css-nextjs-plugin, pigment-css-vite-plugin, pigment-css-unplugin – integration plugins for popular frameworks.
- pigment-css-theme, pigment-css-utils, eslint-plugin-material-ui – additional functionality and utilities.
- docs: Contains documentation sources (likely compiled to a docs site) with MDX files and code examples.
- examples: Provides additional demo projects (Next.js, Remix, Vite, Webpack) in various languages (TS and JS) to demonstrate Pigment CSS usage.

##### Key Components and Their Relationships
- Core Libraries (in packages):
- pigment-css-core holds the build-time CSS extraction, tooling, and processing logic.
- pigment-css-react builds on the core and exposes the main APIs (css, styled, keyframes, etc.)
- Integration Plugins:
- pigment-css-nextjs-plugin and pigment-css-vite-plugin wrap the Pigment CSS functionality for specific bundler configurations.
- There is also a pigment-css-unplugin that likely helps integrate with other environments.
- Example Applications:
- In the apps and examples directories, there are demo applications (e.g., pigment-css-next-app, pigment-css-vite-app) which integrate these packages into full-stack or client-only apps.
- Documentation & Developer Experience:
- The docs folder, along with a comprehensive README, provides usage instructions and guides (including theming, RTL support, and API usage details).
- CI/CD pipelines (configured in .github/ and .circleci/) ensure quality, testing, and coverage.

##### Architectural Patterns and Design Principles
- Monorepo Structure: The project is split into multiple interdependent packages managed via Lerna and pnpm. This separation enhances modularity and reusability.
- Build-Time Extraction: Unlike typical runtime CSS-in-JS libraries, Pigment CSS extracts styles during build time – this is central to the design and influences how plugins are structured.
- Plugin Integration: Separate integrations for Next.js, Vite, etc., indicate the use of adapter patterns to plug into different bundler ecosystems.
- Theming and Variants: The API design (variants, sx prop, etc.) shows an emphasis on statically analyzable styles while still permitting dynamic behavior via CSS variables.
- CI/CD and Testing: With multiple workflows and test directories for each package, the project emphasizes automated quality assurance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Manager Subgraph
    subgraph "Monorepo Manager"
        Lerna["lerna.json"]:::monorepo
        Pnpm["pnpm-workspace.yaml"]:::monorepo
    end

    %% Core Libraries Subgraph
    subgraph "Core Libraries"
        CoreCore["pigment-css-core"]:::core
        CoreReact["pigment-css-react"]:::core
        CoreTheme["pigment-css-theme"]:::core
        CoreUtils["pigment-css-utils"]:::core
    end

    %% Integration Plugins Subgraph
    subgraph "Integration Plugins"
        PluginNext["pigment-css-nextjs-plugin"]:::plugin
        PluginVite["pigment-css-vite-plugin"]:::plugin
        PluginUn["pigment-css-unplugin"]:::plugin
    end

    %% Example Applications Subgraph
    subgraph "Example Applications"
        NextApp["Next.js App Demo"]:::example
        ViteApp["Vite App Demo"]:::example
    end

    %% Documentation & CI/CD Nodes
    Docs["Documentation & Guides"]:::docs
    CICD["CI/CD Workflows"]:::devops

    %% Relationships between subgraphs and nodes
    %% Monorepo influences Core Libraries
    Lerna -->|"manages"| CoreCore
    Pnpm  -->|"manages"| CoreCore

    %% Internal Core Libraries relationships
    CoreTheme -->|"provides theme to"| CoreReact

    %% Core Libraries used by Integration Plugins
    CoreCore -->|"provides extraction"| PluginNext
    CoreReact -->|"provides runtime APIs"| PluginNext

    CoreCore -->|"provides extraction"| PluginVite
    CoreReact -->|"provides runtime APIs"| PluginVite

    CoreCore -->|"provides extraction"| PluginUn
    CoreReact -->|"provides runtime APIs"| PluginUn

    %% Integration Plugins used by Example Applications
    PluginNext -->|"integrates in"| NextApp
    PluginVite -->|"integrates in"| ViteApp
    PluginUn -->|"supports"| NextApp
    PluginUn -->|"supports"| ViteApp

    %% Documentation guides usage of Example Apps
    Docs -->|"guides usage of"| NextApp
    Docs -->|"guides usage of"| ViteApp

    %% CI/CD supports Core Libraries and Integration Plugins
    CICD -->|"tests/builds"| CoreReact
    CICD -->|"tests/builds"| PluginNext

    %% Click Events for Component Mapping
    click Lerna "https://github.com/mui/pigment-css/blob/master/lerna.json"
    click Pnpm "https://github.com/mui/pigment-css/blob/master/pnpm-workspace.yaml"
    click CoreCore "https://github.com/mui/pigment-css/tree/master/packages/pigment-css-core"
    click CoreReact "https://github.com/mui/pigment-css/tree/master/packages/pigment-css-react"
    click CoreTheme "https://github.com/mui/pigment-css/tree/master/packages/pigment-css-theme"
    click CoreUtils "https://github.com/mui/pigment-css/tree/master/packages/pigment-css-utils"
    click PluginNext "https://github.com/mui/pigment-css/tree/master/packages/pigment-css-nextjs-plugin"
    click PluginVite "https://github.com/mui/pigment-css/tree/master/packages/pigment-css-vite-plugin"
    click PluginUn "https://github.com/mui/pigment-css/tree/master/packages/pigment-css-unplugin"
    click NextApp "https://github.com/mui/pigment-css/tree/master/apps/pigment-css-next-app"
    click ViteApp "https://github.com/mui/pigment-css/tree/master/apps/pigment-css-vite-app"
    click Docs "https://github.com/mui/pigment-css/tree/master/docs"
    click CICD "https://github.com/mui/pigment-css/tree/master/.github/workflows"

    %% Styles
    classDef monorepo fill:#ffcccc,stroke:#000,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#000,stroke-width:2px;
    classDef plugin fill:#ccccff,stroke:#000,stroke-width:2px;
    classDef example fill:#ffffcc,stroke:#000,stroke-width:2px;
    classDef docs fill:#ccffff,stroke:#000,stroke-width:2px;
    classDef devops fill:#ffccff,stroke:#000,stroke-width:2px;
```
