Branching Out: Create & maintain your own design system

A guide for starting your own design system. This project is hosted on netlify:

• https://drupal-govcon-2025.bixal.com/
• https://drupal-govcon-2025.netlify.app/

The repo for the code exercises can be found here.

Project Structure

Inside this project, you'll see the following folders and files:

.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   ├── docs/
│   │   ├──── guides/
│   │   ├────── 01-intro.md
│   │   ├────── 02-uswds-foundation.mdx
│   └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json

Starlight looks for .md or .mdx files in the src/content/docs/ directory. Each file is exposed as a route based on its file name.

Images can be added to src/assets/ and embedded in Markdown with a relative link.

Static assets, like favicons, can be placed in the public/ directory.

Working with Git

Naming Branches

Use the project prefix, the GitHub issue number, and a brief summary of the changes.

feature/dg2025-{ISSUE_NO}-{BRIEF_DESCRIPTION}

Example

feature/dg2025-20-font-size

Reviewing Pull Requests

There aren't strict requirements or anything process related, but you might see PR comments like:

**suggestion**: Consider a visual for plain language. Suggestions are non-blocking.

**issue**: This change seems to have affected deploys.

**issue (non-blocking)**: I found a separate issue while reviewing, let's fix on follow-up.

These follow conventional comment guidelines. They help make PR comments clearer and show what comments are blocking and which aren't.

Updating Content

Illustrations

Illustrations are from https://undraw.co/illustrations, using Bixal Blue #152D6B.

Referencing sites

When referencing sites for further reading, use the following format:

{TITLE} | {DOMAIN}

Example

[Design Principles | USWDS](https://designsystem.digital.gov/design-principles/)

Navigation

To update the Guide sidebar navigation go to: astro.config.mjs

Theming docs

Starlight comes with these customizable theming props, they're listed in props.css | GitHub.

Example

Here's how you can apply them to components:

{/* 02-uswds-foundation.mdx */}

<Icon name="approve-check" color="var(--sl-color-green)" class="inline-icon" />

Commands

All commands are run from the root of the project, from a terminal:

Command	Action
npm install	Installs dependencies
npm run dev or npm start	Starts local dev server at localhost:4321
npm run format:check	Checks code formatting
npm run format:fix	Fixes code formatting issues
npm run build	Build your production site to ./dist/
npm run preview	Preview your build locally, before deploying
npm run astro ...	Run CLI commands like astro add, astro check
npm run astro -- --help	Get help using the Astro CLI

Additional resources

• Starlight’s documentation
• Astro documentation
• Astro Discord server