How cagov/design-system works
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.