# cagov/design-system architecture

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

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

## Overview

##### Project Type & Purpose
- The project is a design system – a collection of reusable web components (e.g., accordion, back-to-top, site header, etc.) and supporting documentation.
- It is intended to provide a consistent, accessible, and performant set of components for government websites (e.g., covid19.ca.gov, cannabis.ca.gov) and supports iterative development.
- Components are individually versioned and published to npm, then pushed to a CDN for use on client sites.

##### Key Directories & Their Role
– /components:
- Contains individual components with their own package.json, build (rollup) configurations, source code (JavaScript, Sass/CSS, HTML templates) and unit tests.
- Each component package goes through build steps, prepublish scripts, and gets published to npm and the CA CDN.

– /docs:
- Contains content for the design system website including markdown pages, layouts (using 11ty templates), CSS (Sass and other dependencies), and JavaScript.
- This site showcases the components and provides guidance, documentation, and examples.

– Configuration & CI/CD Files:
- GitHub workflows (in .github/workflows) for deployment, validation (linting, tests, accessibility), and PR previews.
- Playwright configuration for end-to-end testing and accessibility checks.
- ESLint configuration and Husky pre-commit hooks to run unit tests on components.
- Build scripts (e.g., rollup.config.js) within each component to compile assets.

##### Main Components of the Architecture
a. Component Library:
- Each component (e.g., accordion, back-to-top, page-alert, etc.) is developed, tested, built, and versioned independently.
- They undergo automated unit tests (using Open Web Components recommendations) and have their own documentation (README, use-cases).

b. Documentation Site:
- The /docs directory holds the site’s content (pages, templates, assets) generated using 11ty.
- It is the public-facing face of the design system, providing examples, guidelines, and additional pages.

c. Build & Automation Pipeline:
- Build Scripts: Rollup is used in many component directories to bundle JavaScript and compile Sass/CSS into /dist folders.
- CI/CD: GitHub Actions workflows automate tests, deploy to AWS (staging/production), and validate pull requests (using axe for accessibility and Playwright for end-to-end tests).
- Prepublish Hooks: In each component’s package.json, scripts ensure that tests pass and build artifacts (in /dist) are updated before publishing.

d. Testing Framework:
- Unit tests for individual components are run via npm commands and pre-commit hooks.
- End-to-end tests are run using Playwright which also includes accessibility checks (axe) to ensure compliance.

e. External Integrations:
- Published components are made available via npm and written to a CDN.
- The design system site itself is served locally with a static server (via http-server) during development to avoid conflicts with test runners.

##### Relationships & Interactions
– Components are developed in isolation but share common practices and infrastructure (e.g., testing, build steps). They interact with:
- The documentation site where their examples and usage details are auto-generated from markdown files and component READMEs.
- The CI/CD pipeline, where commits trigger pre-commit tests (via Husky) and end-to-end tests with Playwright.
– The build system links source code (src) to final distributed artifacts (dist) that are published to npm and the CDN.
– GitHub workflows coordinate deployments, PR previews, and automated validations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Component Library and its individual components
    CL_LIB["Component Library"]:::dev
    subgraph "Components"
        direction TB
            ACC["Accordion (src,test,dist)"]:::dev
            BTS["Back-to-Top (src,test,dist)"]:::dev
    end

    %% Documentation Site
    DS["Documentation Site (11ty,markdown)"]:::dev

    %% CI/CD Pipeline with its sub-components
    subgraph "CI/CD Pipeline"
        direction TB
            GHW["GitHub Workflows"]:::automation
            PRE["Pre-commit Hooks"]:::automation
    end

    %% Testing Framework
    subgraph "Testing Framework"
        direction TB
            UT["Unit Tests"]:::test
            E2E["End-to-End Tests (Playwright,axe)"]:::test
    end

    %% External Publishing
    EP["External Publishing (npm,CDN,AWS)"]:::external

    %% Relationships & Data Flow
    CL_LIB -->|"autogen"| DS
    CL_LIB -->|"commit_triggers"| GHW
    CL_LIB -->|"commit_triggers"| PRE
    GHW -->|"run_tests"| UT
    GHW -->|"run_tests"| E2E
    PRE -->|"verify"| UT
    GHW -->|"deploy_artifacts"| EP

    %% Click Events
    click CL_LIB "https://github.com/cagov/design-system/tree/main//components"
    click ACC "https://github.com/cagov/design-system/tree/main//components/accordion"
    click BTS "https://github.com/cagov/design-system/tree/main//components/back-to-top"
    click DS "https://github.com/cagov/design-system/tree/main//docs"
    click GHW "https://github.com/cagov/design-system/tree/main//github/workflows"
    click PRE "https://github.com/cagov/design-system/tree/main//.husky/pre-commit"
    click E2E "https://github.com/cagov/design-system/blob/main//playwright.config.mjs"

    %% Styles
    classDef dev fill:#a6cee3,stroke:#1f78b4,stroke-width:2px;
    classDef automation fill:#b2df8a,stroke:#33a02c,stroke-width:2px;
    classDef test fill:#fb9a99,stroke:#e31a1c,stroke-width:2px;
    classDef external fill:#fdbf6f,stroke:#ff7f00,stroke-width:2px;
```
