# workday/canvas-kit architecture

> Architecture diagram of the GitHub repository workday/canvas-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/workday/canvas-kit
- Repository: https://github.com/workday/canvas-kit

## Overview

##### A “Monorepo” container
- That the repository is managed with Lerna, which means each module/package is versioned and managed independently.
- Integration of GitHub Actions (multiple workflow files under the .github/workflows directory) for CI/CD, release, linting, testing, etc.

a. UI Component Modules:
- “modules/react”: This is the heart of the library. Inside, you have multiple packages/subdirectories for individual components (e.g. button, avatar, card, dialog, table, tabs, etc.). Each component package includes implementation (lib/), tests (spec/ and stories/), and documentation demos.
- “modules/labs-react” and “modules/preview-react”: These appear to be experimental or supplementary React packages demonstrating new ideas or previewing upcoming changes.
- “modules/popup-stack”: A specialized module handling popup layering logic.

b. Styles and Theming:
- “modules/styling” and “modules/styling-transform”: These modules provide the utilities to transform and generate CSS/styling rules, convert pixel values to rem, create themes, and perform CSS variable transformations.

c. Documentation and Development Tools:
- “modules/docs”: This module hosts developer documentation, upgrade guides, and technical examples. It is tied in with Storybook configuration (see the .storybook directory and various mdx stories).
- “utils” directory: Contains code generators (“create-component”), custom lint rules, testing helpers, and scripts for dependency checks and publishing. Mark these as auxiliary tools that support the development and maintenance of the library.

d. Non-React or Supporting Modules:
- Modules such as “modules/css” and “modules/labs-css” provide styling assets or CSS-specific utilities.
- “modules/codemod”: Contains scripts designed for upgrading component APIs and code transformations across versions.

##### Relationships and Interactions
- From documentation (modules/docs) and Storybook configurations (in .storybook and “modules/docs/lib”) point out their role in generating developer-facing demos and guides.
- That the utilities in the “utils” folder support tasks like code generation, linting, dependency version checking, and release processes.
- Various test suites (Cypress tests under “cypress”, Jest tests under “jest”) and point them to each module (especially the React component modules) to represent integration with automated testing.
- That GitHub Actions workflows trigger builds, tests, and releases, and are integrated with the overall monorepo structure.

##### Additional Details
- That although many component packages share similar internal patterns (exhibited by the similar folder structure with “lib”, “spec”, “stories”), each package may have its own internal dependencies and use of hooks, theming, and styling utilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Container
    subgraph "Monorepo"
        Lerna["lerna.json"]:::monorepo
        GHactions["GitHub Actions Workflows (.github/workflows)"]:::monorepo
    end

    %% UI Component Modules
    subgraph "UI Component Modules"
        React["modules/react"]:::ui
        Labs["modules/labs-react"]:::experimental
        Preview["modules/preview-react"]:::experimental
        Popup["modules/popup-stack"]:::popup
    end

    %% Styles & Theming
    subgraph "Styles & Theming"
        Styling["modules/styling"]:::styling
        StylingTransform["modules/styling-transform"]:::styling
        Tokens["modules/react/tokens"]:::styling
    end

    %% Documentation & Development Tools
    subgraph "Documentation & Development Tools"
        Docs["modules/docs"]:::docs
        Storybook[".storybook"]:::docs
        Utils["utils/"]:::utils
    end

    %% Non‑React / Supporting Modules
    subgraph "Non‑React / Supporting Modules"
        CSS["modules/css"]:::support
        LabsCSS["modules/labs-css"]:::support
        Codemod["modules/codemod"]:::support
    end

    %% External Integrations
    subgraph "External Integrations"
        External["External Libraries (React, Jest, Cypress, Storybook)"]:::external
    end

    %% Relationships and Interactions
    React -->|"usesTokens"| Tokens
    React -->|"integratesStyling"| Styling
    React -->|"integratesStyling"| StylingTransform

    %% Experimental modules feed into core React components
    Labs -->|"experimentalUI"| React
    Preview -->|"experimentalUI"| React

    %% Popup management for handling overlays in React Components
    React -->|"utilizesPopup"| Popup

    %% Documentation references UI components and Storybook displays demos
    Docs -->|"documents"| React
    Storybook -->|"showcases"| Docs

    %% Utilities support both UI components and documentation
    Utils -->|"supportsDevelopment"| React
    Utils -->|"supportsDevelopment"| Docs
    Utils -->|"supportsDevelopment"| Codemod

    %% Non‑React modules provide additional CSS assets to UI components
    React -->|"incorporatesCSS"| CSS
    React -->|"incorporatesCSS"| LabsCSS

    %% External integrations feed into testing and build pipelines
    External -->|"integratedForTesting"| React

    %% CI/CD pipelines trigger build, test, and release processes across modules
    GHactions -->|"triggersCI"| React
    GHactions -->|"triggersCI"| Docs
    GHactions -->|"triggersCI"| Utils

    %% Codemod scripts update and transform React component codebases
    Codemod -->|"updatesCode"| React

    %% Click Events for Component Mapping
    click Lerna "https://github.com/workday/canvas-kit/blob/master/lerna.json"
    click GHactions "https://github.com/workday/canvas-kit/tree/master/.github/workflows/"
    click React "https://github.com/workday/canvas-kit/tree/master/modules/react"
    click Labs "https://github.com/workday/canvas-kit/tree/master/modules/labs-react"
    click Preview "https://github.com/workday/canvas-kit/tree/master/modules/preview-react"
    click Popup "https://github.com/workday/canvas-kit/tree/master/modules/popup-stack"
    click Styling "https://github.com/workday/canvas-kit/tree/master/modules/styling"
    click StylingTransform "https://github.com/workday/canvas-kit/tree/master/modules/styling-transform"
    click Tokens "https://github.com/workday/canvas-kit/tree/master/modules/react/tokens"
    click Docs "https://github.com/workday/canvas-kit/tree/master/modules/docs"
    click Storybook "https://github.com/workday/canvas-kit/blob/master/.storybook"
    click Utils "https://github.com/workday/canvas-kit/tree/master/utils/"
    click CSS "https://github.com/workday/canvas-kit/tree/master/modules/css"
    click LabsCSS "https://github.com/workday/canvas-kit/tree/master/modules/labs-css"
    click Codemod "https://github.com/workday/canvas-kit/tree/master/modules/codemod"

    %% Style Definitions
    classDef monorepo fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef ui fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px;
    classDef experimental fill:#fff9c4,stroke:#f57f17,stroke-width:2px;
    classDef popup fill:#ffebee,stroke:#c62828,stroke-width:2px;
    classDef styling fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px;
    classDef docs fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef utils fill:#fce4ec,stroke:#ad1457,stroke-width:2px;
    classDef support fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px;
    classDef external fill:#fff3e0,stroke:#ef6c00,stroke-width:2px;
```
