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

npm install @codeforamerica/marcomms-design-system

Usage

CSS styles

Import all styles:

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

Or import specific parts:

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

JavaScript components

Import all components:

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

Or import specific components:

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

Development

Prerequisites

• Node.js 20+
• npm

Getting started

# 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

Scripts

• 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:

How it works

• 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

Writing commits

Use these commit message formats to control version changes:

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

What happens when you merge

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

What gets published to NPM

• 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
[email protected]