# salesforce/design-system-react architecture

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

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

## Overview

##### Project Type and Purpose
- This is an open-source, presentational React component library (“Design System React”) wrapping the Salesforce Lightning Design System (SLDS).

##### High-Level File-Structure Analysis
- Top-level “components” folder: one subfolder per component (e.g. button, modal, accordion), each containing source (JSX/TS), prop‐type validators, docs, examples, tests.
- “utilities”: shared helper functions, design tokens, samples.
- “scripts”: build/test/publish pipelines (dist.sh, circle-ci hooks, storybook builder, babel transforms).
- “.circleci” & “.github”: CI definitions driving automated tests, code quality checks, and NPM publish.
- Build config files: Babel, Webpack, Jest, Storybook.

##### Key Components
A. Source Code
- Components (React/JSX, CSS class usage)
- Utilities & design tokens
B. Developer Workflow
- Local Dev: Storybook server for live examples
- Tests: Jest unit, Axe accessibility, Storybook snapshot tests
- Build scripts: Babel compile, Webpack bundles
- CI/CD: CircleCI + GitHub Actions
C. Deployment & Consumption
- NPM Registry (package @salesforce/design-system-react)
- Consumers: Any React application

##### Relationships and Data Flows
- Source → Build Scripts → Transpiled Modules & Bundles.
- CI Triggers: commits/PRs → run tests & build → on success → publish to NPM.
- Consumers Import:
- `import {Button} from '@salesforce/design-system-react'` → loads compiled JS module
- `<link>` tags or webpack serve CSS → apply SLDS styles

##### Architectural Patterns and Principles
- Modular Component Pattern: Each React component in its own folder with docs, examples, tests.
- Tree-shaking–friendly ES modules (export individual components).
- Separation of Concerns: source vs. tests vs. docs vs. assets.
- CI-driven quality gates before publishing.

##### Essential Details to Capture
- Components folder structure and role in packaging
- Utilities & design-token pipelines
- CI/CD flow and triggers
- Runtime integration points (React import, CSS link, IconSettings)

## Diagram (Mermaid)

```mermaid
graph TB

subgraph "Development & CI"
  subgraph "Source Code"
    SC1["Components Library"]:::source
    SC2["Utilities & Design Tokens"]:::source
    SC3a["Action Icons"]:::source
    SC3b["Standard Icons"]:::source
    SC3c["Utility Icons"]:::source
    SC3d["Custom Icons"]:::source
    SC3e["Doctype Icons"]:::source
  end
  CI1["GitHub Repo"]:::pipeline
  CI2["CI/CD (CircleCI & GitHub Actions)"]:::pipeline
  T1["Tests (Jest, Axe, Snapshots)"]:::pipeline
  B1["Build & Publish Scripts"]:::pipeline

  SC1 --> B1
  SC2 --> B1
  SC3a --> B1
  SC3b --> B1
  SC3c --> B1
  SC3d --> B1
  SC3e --> B1

  CI1 --> CI2
  CI2 --> T1
  B1 --> T1
  T1 -->|"on success"| CI2
end

subgraph "Package Artifacts"
  TM["Transpiled Modules (/lib)"]:::package
  BD["Bundles (/dist)"]:::package
  NPM["NPM Registry"]:::package

  B1 -->|"babel & webpack"| TM
  B1 -->|"webpack bundle"| BD
  CI2 -->|"npm publish"| NPM
  TM --> NPM
  BD --> NPM
end

subgraph "Runtime Consumption"
  RA["React Application"]:::runtime
  CSS["External SLDS CSS"]:::runtime
  ICONS["Icon Server / Sprite"]:::runtime

  NPM -->|"install & import"| RA
  RA -->|"import CSS"| CSS
  RA -->|"IconSettings iconPath"| ICONS
end

%% Click Events
click SC1 "https://github.com/salesforce/design-system-react/tree/master/components/"
click SC2 "https://github.com/salesforce/design-system-react/tree/master/utilities/"
click SC3a "https://github.com/salesforce/design-system-react/tree/master/icons/action/"
click SC3b "https://github.com/salesforce/design-system-react/tree/master/icons/standard/"
click SC3c "https://github.com/salesforce/design-system-react/tree/master/icons/utility/"
click SC3d "https://github.com/salesforce/design-system-react/tree/master/icons/custom/"
click SC3e "https://github.com/salesforce/design-system-react/tree/master/icons/doctype/"
click B1 "https://github.com/salesforce/design-system-react/blob/master/scripts/dist.sh"
click B1 "https://github.com/salesforce/design-system-react/blob/master/scripts/dist.js"
click B1 "https://github.com/salesforce/design-system-react/blob/master/scripts/prepare-components.js"
click B1 "https://github.com/salesforce/design-system-react/blob/master/scripts/npm-transform.js"
click B1 "https://github.com/salesforce/design-system-react/blob/master/scripts/circle-ci.sh"
click B1 "https://github.com/salesforce/design-system-react/blob/master/scripts/release.js"
click B1 "https://github.com/salesforce/design-system-react/blob/master/scripts/publish-to-git.js"

classDef source fill:#ADD8E6,stroke:#0366d6,color:#000
classDef pipeline fill:#98fb98,stroke:#229954,color:#000
classDef package fill:#FFA500,stroke:#d35400,color:#000
classDef runtime fill:#D8BFD8,stroke:#6C3483,color:#000
```
