Getting Started

Everything you need to set up the Civic Design System locally — from cloning the repo to previewing the site.

Requirements

• Node.js 18.x or higher
• npm 8.x or higher
• A text editor (VS Code recommended)
• A terminal

Quick Start

# 1. Clone the repository
git clone https://github.com/michaelasaro/civic-guide.git
cd civic-guide

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Start the development server
npm run serve

Open http://localhost:3000 to view the documentation site.

Guided Tour

New to this project? The repo includes a CodeTour that walks you through the entire build system step by step, assuming no prior knowledge. It explains what each file does, how they connect, and why things are set up the way they are.

To start the tour:

1. Install the CodeTour extension for VS Code
2. Open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows)
3. Type CodeTour: Start Tour and select "How the Build Works"

The tour is stored in .tours/ and ships with the repo, so anyone who clones it gets access.

Available Scripts

Typical development workflow: Run npm run serve in one terminal and npm run watch:styles in another. Every time you save a style change, the CSS rebuilds automatically.

Project Structure

civic-guide/
├── src/                          # Source files
│   ├── styles/                   # Sass source files
│   │   ├── index.scss            # Main entry point (3 layers)
│   │   ├── _bridge.scss          # Connects your settings to USWDS
│   │   ├── _packages.scss        # Choose which USWDS components to include
│   │   ├── custom-styles.scss    # Your custom CSS overrides
│   │   └── uswds-settings/       # Design token settings
│   │       ├── _colors.scss      # Brand colors and palettes
│   │       ├── _typography.scss  # Fonts, sizes, weights
│   │       ├── _spacing.scss     # Margins, padding, grid
│   │       ├── _components.scss  # Component-specific settings
│   │       ├── _utilities.scss   # Utility class configuration
│   │       └── _general.scss     # Paths, focus styles, global settings
│   ├── fonts/                    # Custom web fonts
│   └── images/                   # Custom images (logos, hero, branding)
│
├── site/                         # Documentation website
│   ├── pages/                    # Content pages (HTML)
│   ├── page-templates/           # Layout templates
│   ├── images/                   # Site images
│   ├── styles/                   # Site-specific CSS
│   └── scripts/                  # Site-specific JavaScript
│
├── dist/                         # Build output (generated)
│   ├── civic/                    # Your customized theme
│   │   ├── styles/               # civic.css, civic.min.css, sourcemaps
│   │   ├── fonts/                # Custom fonts
│   │   └── images/               # Custom images
│   └── uswds/                    # USWDS assets (CSS, JS, fonts, icons)
│
├── .tours/                       # CodeTour guided walkthroughs
├── .browserslistrc               # Browser targets for autoprefixer
├── gulpfile.js                   # Build configuration
├── server.js                     # Development server
└── package.json                  # Dependencies and scripts

How the Build Works

The build compiles your Sass source into production-ready CSS in 5 steps:

1. Sass compilation — Reads index.scss, follows all imports, produces raw CSS + sourcemap
2. Autoprefixing — Adds vendor prefixes (-webkit-, -ms-) for browser compatibility
3. Writes civic.css — Full, readable CSS with sourcemap for debugging
4. Minification — Compresses the CSS (removes whitespace, shortens colors)
5. Writes civic.min.css — Compressed CSS with sourcemap for production

Browser targets are defined in .browserslistrc (same as USWDS: > 2%, last 2 versions, not dead).

The Three-Layer Architecture

Styles are loaded in order through index.scss:

Layer 1: BRIDGE          Your settings → passed to USWDS core
Layer 2: PACKAGES        USWDS components (you choose which ones)
Layer 3: CUSTOM STYLES   Your CSS overrides (loaded last, wins over everything)

Customizing the Theme

Changing Settings

All USWDS settings (colors, fonts, spacing, etc.) are pre-written in two places — just uncomment to activate:

1. Find the setting in src/styles/uswds-settings/ (e.g., _colors.scss)
2. Uncomment it and change the value
3. Uncomment the matching line in src/styles/_bridge.scss
4. Run npm run build

Example: Changing the primary color

// In src/styles/uswds-settings/_colors.scss — uncomment and set your color:
$theme-color-primary: #4D8157;

// In src/styles/_bridge.scss — uncomment the matching line:
$theme-color-primary: colors.$theme-color-primary,

Every button, link, and primary-colored element updates automatically.

Settings Categories

Choosing Which Components to Include

By default, all USWDS components are included. To reduce CSS file size, comment out components you don't use in src/styles/_packages.scss:

// Comment out a component you don't need:
// @forward "usa-tooltip/src/styles";

// Keep the ones you use:
@forward "usa-button/src/styles";
@forward "usa-header/src/styles";

Components are grouped by purpose (Layout, Page Structure, Navigation, Content, Forms, etc.) with descriptions of what each one provides.

Adding Custom CSS

For styles that can't be achieved with design tokens, add CSS to src/styles/custom-styles.scss. It loads last, so it overrides anything from USWDS.

Alternative Build Option

For users familiar with the official USWDS workflow, the standard compile functions are also available:

npx gulp init          # First-time setup
npx gulp compile       # Compile Sass + icon sprite
npx gulp watch         # Watch for changes
npx gulp copyAll       # Copy all USWDS assets
npx gulp update        # Update after USWDS upgrade

Browser Support

Browser targets are defined in .browserslistrc, matching USWDS targets:

• Browsers with > 2% global usage
• Last 2 versions of each browser
• No discontinued browsers

In practice: Chrome, Firefox, Safari, Edge (latest versions), and most mobile browsers.

Dependencies