Code for America MarComms Design System


Overview

This design system helps our team build websites that look and feel consistent with our brand. It's built with SCSS and web components, using modern CSS features like container queries and custom properties. The system includes design tokens, reusable components, and layout utilities.

Features

- Design Tokens: Consistent spacing, colors, typography, and layout values
- Responsive Grid: Flexible 12-column grid with CSS gap support
- Web Components: Reusable components built with Lit
- Layout Utilities: Stack, cluster, grid, and section patterns

Installation

``bash
npm install @codeforamerica/marcomms-design-system
`

Usage

$3

Import all styles:

`scss
@import '@codeforamerica/marcomms-design-system/src/styles.scss';
`

Or import specific parts:

`scss
@import '@codeforamerica/marcomms-design-system/src/core/tokens';
@import '@codeforamerica/marcomms-design-system/src/core/grid';
@import '@codeforamerica/marcomms-design-system/src/core/layout';
`

$3

Import all components:

`javascript
import '@codeforamerica/marcomms-design-system';
`

Or import specific components:

`javascript
import '@codeforamerica/marcomms-design-system/src/components/card.js';
import '@codeforamerica/marcomms-design-system/src/components/button.js';
`

Development

$3

- Node.js 20+
- npm

$3

`bash


Clone the repository

git clone https://github.com/codeforamerica/marcomms-design-system.git
cd marcomms-design-system

Install dependencies

npm install

Start development server

npm run develop

Start Storybook

npm run storybook
`

$3

- npm run build - Build production assets
- npm run develop - Watch and build development assets
- npm run storybook - Start Storybook development server
- npm run build-storybook - Build static Storybook
- npm run chromatic - Deploy to Chromatic for visual testing

Design tokens

The system includes design tokens for:

- Spacing: Layout and component spacing scales
- Colors: Brand colors, grayscale, and semantic colors
- Typography: Font families, sizes, and line heights
- Layout: Grid breakpoints and container sizes

Browser support

- Modern browsers (>0.2% usage)
- No Internet Explorer support
- Progressive enhancement for older browsers

Documentation

- Storybook: View live documentation
- Chromatic: Visual testing and component library

Release process

This project automatically creates new versions and publishes them:

$3

- Auto Versioning: Version numbers are created based on your commit messages
- NPM Publishing: New versions publish to NPM automatically when you merge to main
- GitHub Actions: Builds, tests, and publishes everything without manual work

$3

Use these commit message formats to control version changes:

`bash
feat: add new card component # New feature (1.0.0 → 1.1.0)
fix: resolve button spacing issue # Bug fix (1.0.0 → 1.0.1)
feat!: redesign grid system # Breaking change (1.0.0 → 2.0.0)
docs: update README examples # No version change
`

$3


1. Pull Request: Creates a preview build for review
2. Merge to Main: Starts the release process
3. Version Check: Looks at your commits to decide the new version number
4. NPM Release: Publishes the new version to @codeforamerica/marcomms-design-system
5. Documentation Update: Updates the live Storybook site

$3

- Built files ready to use in /dist
- Source files for custom setups in /src`
- Documentation and package info

Maintainer

Fritz Jooste
Lead Front-end Developer, MarComms Team
fjooste@codeforamerica.org