# strapi/design-system architecture

> Architecture diagram of the GitHub repository strapi/design-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/strapi/design-system
- Repository: https://github.com/strapi/design-system

## Overview

##### Project type and purpose
- It’s not a standalone full-stack app; instead it’s an open-source UI toolkit with build, test, versioning, and publishing pipelines.

##### Main architectural components
a. Monorepo root (Yarn v3 workspace + Turbo)
b. Packages
- packages/primitives
c. Documentation site (docs/) – powered by Storybook + Vite, imports design‐system
d. Shared configs & scripts
- ESLint / Prettier / TypeScript configs
- .changeset folder & scripts for versioning
- turbo.json for task orchestration
- scripts/pre-publish.sh, find-release-from-changeset.js
e. CI/CD pipelines (GitHub Actions workflows + custom actions)
f. Test framework (Jest + jsdom mocks)

##### Relationships & data-flow
- The monorepo orchestrator (turbo + Yarn workspaces) runs install, lint, typecheck, test, build, and publish across all packages.
- Each package has its own src/, tests/, tsconfig, and build config (packup or rollup).
- Changesets detect version bumps, custom scripts generate releases, GitHub Actions trigger on PRs, merges, and scheduled jobs (bundle size, chromatic visual tests, release).

##### Architectural patterns & design principles
- Monorepo with shared configs and task orchestration (Turbo + Yarn workspaces).
- Component-driven development (Storybook).
- Semantic versioning and changelog automation (Changesets).
- CI/CD as code (multiple GitHub workflows + custom actions).
- Package encapsulation: each UI module is isolated, tested, and published separately.

##### Technologies / frameworks
- Node.js, Yarn v3 (Plug’n’Play), Turborepo
- React, React-DOM, styled-components
- TypeScript, Jest, Storybook, Vite
- Changesets, Husky (git hooks), ESLint, Prettier
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Root
    subgraph "Monorepo"
        direction TB
        subgraph "Shared Configs & Orchestration"
            direction TB
            TS["tsconfig.json"]:::shared
            ESLint[".eslintrc"]:::shared
            Prettier[".prettierrc"]:::shared
            CommitLint[".commitlintrc.ts"]:::shared
            Changesets[".changeset"]:::shared
            Turbo["turbo.json"]:::shared
            YarnCfg[".yarnrc.yml"]:::shared
            Scripts["scripts/"]:::shared
            JestRoot["jest.config.js"]:::shared
        end

        subgraph "Packages"
            direction TB
            Primitives["packages/primitives"]:::pkg
            Icons["packages/icons"]:::pkg
            StrapiIcons["packages/strapi-icons"]:::pkg
            DesignSystem["packages/design-system"]:::pkg
        end
    end

    %% Dependencies between packages
    DesignSystem -->|"imports"| Primitives
    DesignSystem -->|"imports"| Icons

    %% Docs Site
    Docs["Docs Site (Storybook + Vite)"]:::docs
    Docs -->|"imports"| DesignSystem
    Docs -->|"imports"| Icons

    %% CI/CD
    CI["CI/CD (GitHub Actions)"]:::ci
    CI -->|"runs lint,test,build,bundle-size,chromatic,release"| Monorepo

    %% Publishing Flow
    Changesets -->|"triggers"| Scripts
    Scripts -->|"publishes"| NPM["npm registry"]:::external

    %% Click Events
    click TS "https://github.com/strapi/design-system/blob/main/tsconfig.json"
    click ESLint "https://github.com/strapi/design-system/blob/main/.eslintrc"
    click Prettier "https://github.com/strapi/design-system/blob/main/.prettierrc"
    click CommitLint "https://github.com/strapi/design-system/blob/main/.commitlintrc.ts"
    click Changesets "https://github.com/strapi/design-system/tree/main/.changeset/"
    click Turbo "https://github.com/strapi/design-system/blob/main/turbo.json"
    click YarnCfg "https://github.com/strapi/design-system/blob/main/.yarnrc.yml"
    click Scripts "https://github.com/strapi/design-system/blob/main/scripts/pre-publish.sh"
    click JestRoot "https://github.com/strapi/design-system/blob/main/jest.config.js"
    click Primitives "https://github.com/strapi/design-system/blob/main/packages/primitives/package.json"
    click Icons "https://github.com/strapi/design-system/blob/main/packages/icons/package.json"
    click StrapiIcons "https://github.com/strapi/design-system/blob/main/packages/strapi-icons/package.json"
    click DesignSystem "https://github.com/strapi/design-system/blob/main/packages/design-system/package.json"
    click Docs "https://github.com/strapi/design-system/blob/main/docs/package.json"
    click CI "https://github.com/strapi/design-system/blob/main/.github/workflows/checks.yml"
    
    %% Styles
    classDef pkg fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef docs fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
    classDef shared fill:#eeeeee,stroke:#757575,color:#212121;
    classDef ci fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef external fill:#f3e5f5,stroke:#8e24aa,color:#4a148c;
```
