> For the complete documentation index, see [llms.txt](https://docs.civictheme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.civictheme.io/playbook/govcms/02-sub-theme-setup.md).

# Setting Up Your Sub-Theme

This chapter walks through the sub-theme that was generated during installation and gets your local development environment ready. By the end, you will understand the sub-theme directory structure, have the build system running, and be able to view components in Storybook.

**CivicTheme must never be modified directly. Unless exceptional circumstances which must be logged in your project documentation as updates will wipe out these changes**

Your sub-theme inherits everything from CivicTheme and is where all custom work happens — overriding components, adding new ones, and adjusting styles. The build system merges your sub-theme's components with the base theme's components at compile time, so your overrides take priority automatically.

## Prerequisites

See the [sub-theme reference](/development/drupal-theme/sub-theme.md#prerequisites).

## Step 1: Understand the sub-theme directory structure

The sub-theme creation script generates a complete project scaffold. Understanding this structure is essential before making any changes. The key directories you will work in most are `components/`, `assets/`, `templates/`, and the two variable files (`variables.base.scss` and `variables.components.scss`).

The full directory structure, library system, and placeholder asset replacement are documented in the [sub-theme reference](/development/drupal-theme/sub-theme.md).

## Step 2: Understand the build system

The build system is a custom Node.js script (`build.js`) that compiles your sub-theme's SCSS, JavaScript, and assets. It is not webpack or gulp — it is purpose-built for CivicTheme's component architecture. The essential commands are:

```bash
npm run build          # Full build (assets + Storybook static site)
npm run dist           # Compile assets only (faster, no Storybook)
npm run dist:watch     # Watch mode (recompiles on file changes)
npm run lint           # Lint SCSS and JavaScript
```

The build pipeline, output files, and configuration are documented in the [build system reference](/development/drupal-theme/systems/build.md).

## Step 3: Run Storybook

Storybook provides an interactive development environment where you can view, test, and document components in isolation — without needing a running Drupal site.

Start the development server:

```bash
npm run storybook
```

This runs `npm run dist` first to compile assets, then starts the Storybook dev server with file watching. Both the asset compilation and Storybook will watch for changes and hot-reload automatically.

## Step 4: Verify the development workflow

Run through this checklist to confirm your development environment is working:

* [ ] `npm run dist` completes without errors
* [ ] `npm run dev` starts storybook and watches for changes
* [ ] Components display correctly in Storybook with interactive controls
* [ ] Changes to a component's `.scss` file are reflected after running `npm run dist`
* [ ] The Drupal site displays your sub-theme correctly with the compiled assets
* [ ] `npm run lint` runs without errors

## Troubleshooting

If you encounter build, Storybook, or cache issues, see the troubleshooting section in the [sub-theme reference](/development/drupal-theme/sub-theme.md#troubleshooting).

## Next step

With your sub-theme set up and the development workflow verified, the next step is to configure your site's visual identity — colors, header, footer, and other theme settings.

Continue to [Chapter 3: Configuring Colors and Theme Settings](/playbook/govcms/03-colors-and-settings.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.civictheme.io/playbook/govcms/02-sub-theme-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.