How to Use ExampleDesignSystem

Section 1 of 5

What is in the repository

Technical

Repository: puddnsnacks-hub/ExampleDesignSystem (private). The site, this guide included, is published at xds.puddnsnacks.com. The design-system/ folder mirrors the hosted design-system page file for file; everything else exists to view, document or rebuild it.

ExampleDesignSystem/
├── design-system/              the design system, as published
│   ├── README.md               brand book: the usage rules
│   ├── tokens.json             every token (g and s colors, type, spacing, size, motion …)
│   ├── tokens.css              compiled from tokens.json; never edit by hand
│   ├── choosing.md             which component, by the user's goal
│   ├── laws.md                 every system rule, one sentence each
│   ├── design-system.json      index of the hosted page: title, asset records
│   ├── components/
│   │   ├── bundle.css          component tier (--c-*) and every component
│   │   ├── bundle.js           behavior: window.XDS
│   │   └── <Name>/            README.md guide + preview.html specimen
│   ├── fonts/                  14 WOFF2 files
│   └── assets/                 Icons (41), Logos (2), Photography (4)
├── gallery/                    every preview as an openable page
├── How-To-Docs/                this guide
└── tools/
    ├── compile_tokens.py       tokens.json → tokens.css
    ├── build_gallery.py        previews → gallery/
    └── build/                  regenerates design-system/ from the XDS V4 source

What each kind of file is for
File	Read by	Edited by
`tokens.json`	Tools, the hosted page, AI builders	People, then `compile_tokens.py`
`tokens.css`, `bundle.css`, `bundle.js`	Browsers	Generated; do not edit
`components/<Name>/README.md`	People and AI builders	Generated from the component registry
`README.md`, `choosing.md`, `laws.md`	People and AI builders	People

Counts: 69 components in 11 families, 15 page templates, 256 color tokens in three themes (Light, Dark surface, Alternate pack), 24 type styles.

Plain language

What is all this, and which parts should I care about? Learn more

What

A design system is a shared kit for building web pages: the colors, type, spacing and ready-made pieces (buttons, cards, forms) every page uses. A repository, or "repo," is the folder that kit lives in on GitHub, with a full history of every change. The design-system folder is the kit itself. The other folders let you see it (gallery), learn it (this guide) and rebuild it (tools).

Why

Keeping the kit in one place means every page draws from the same source. Change the link color once and every page that uses the kit gets the new color. Without it, each team copies values by hand, and the copies slowly drift apart.

How

Open gallery/index.html to see every piece working.
Read design-system/README.md for the rules of use.
Open a piece's folder in design-system/components for its guide.
Leave the generated files (tokens.css, bundle.css, bundle.js) alone; they are rebuilt from the sources.

Analogy: it's a restaurant's recipe binder. The binder is the design system, the photos in it are the gallery, and the kitchen notes on how the binder is printed are the tools. Cooks follow the binder; nobody rewrites the printed copies by hand.

Section 2 of 5

Load the system on a page

Technical

Load three files in this order. The script is optional: every component renders without it.

<link rel="stylesheet" href="design-system/tokens.css">
<link rel="stylesheet" href="design-system/components/bundle.css">
<script src="design-system/components/bundle.js" defer></script>

Every page starts from the same shell. .xds-page on <body> sets the ground, ink, focus ring and antialiasing once.

<body class="xds-page">
  <a class="xds-skip-link" href="#main">Skip to main content</a>
  <!-- gov-banner, site-alert (when there is one), header -->
  <main id="main" tabindex="-1">
    <section class="xds-ground">
      <div class="xds-layout" data-kind="container">
        <button class="xds-button" data-variant="primary" data-size="md">Apply now</button>
      </div>
    </section>
  </main>
  <!-- footer -->
</body>

Classes begin xds-; variants are data-* attributes; parts are __part classes.
XDS.init(root) wires markup injected after load. XDS.toast(message, { status, title, sticky }) and XDS.modal.open(id) are the page-facing calls.
Icons come from the sprite bundle.js inserts: <svg class="xds-icon" data-size="md" aria-hidden="true"><use href="#xds-search"></use></svg>.
Fonts load from tokens.css; keep design-system/fonts/ beside it.

Plain language

How does a web page actually start using the design system? Learn more

What

A web page is a text file of HTML: labeled boxes of content. On its own it looks plain. The three lines at the top point the page at the design system's files: tokens.css holds the values (colors, sizes), bundle.css holds the look of every piece, and bundle.js adds behavior such as menus that open and close. A "class" is the label that tells a box which piece it is, such as xds-button.

Why

Pointing at shared files instead of copying them means a page always gets the current version. The order matters because each file builds on the one before: the look needs the values, and the behavior needs the look.

How

Put the three lines in the page's <head>, in that order.
Give the <body> the label xds-page.
Add pieces by copying their markup from each component's guide, then changing the words.
Pick a variant by changing an attribute, for example data-variant="secondary" for a quieter button.

Analogy: it's like a new apartment. The three lines connect the utilities: water first, then power, then the internet. Once they're connected, every room you furnish already works.

Section 3 of 5

Build a page

Technical

The page model
Layer	Markup	Rule
Ground	`section.xds-ground[data-ground]`	A section. Carries the color edge to edge, holds content 32 from the window (16 at compact), no vertical padding.
Container	`.xds-layout[data-kind="container"]`	Sits in a ground, no fill, content 24 from the color, components 16 apart.
Paper	`.xds-paper[data-surface]`	A component with its own fill and paired stroke, inside a container.
Component	`.xds-*`	Always in a container, never directly on a ground.

Choose a component by the user's goal: design-system/choosing.md. It also lists what the system deliberately lacks (no carousels, no dark mode, no rounded corners outside the conversation family).
Start from a template: design-system/components/<Name>Template/ holds 15 full pages (shell, landing, program, article, newsroom, data, form, grant, search, emergency, assistant …).
Dark is a variant, never a page mode: a dark section is data-ground="dark", and each dark-capable component inside carries data-surface="dark". Light-only components (forms, tables, alerts, the conversation family) stay light.
Brand packs: data-theme="alt" on <html> swaps the four brand ramps; status colors never change.
One h1 per page, as its first heading. No horizontal scrolling: wrap, fold or cut.

Plain language

How do I put a page together without breaking the rules? Learn more

What

Every page is a stack of bands. A band (a "ground") sets the background color across the full width. Inside each band, a "container" keeps the content a set distance from the edges. The pieces, such as buttons and cards, sit inside containers. A "template" is a finished example page you can copy.

Why

Fixed nesting keeps spacing identical from page to page, so pages feel like one site even when different people build them. The system also measures the space between bands for you, so nobody has to guess.

How

Find the template closest to the page you need in the gallery's Templates group, and copy its markup.
Replace the words and images; keep the bands, containers and pieces.
If you need a piece the template lacks, look up the user's goal in choosing.md and copy that piece's markup from its guide.
For a dark band, mark the band dark and mark each piece inside it dark too.

Analogy: it's packing moving boxes. The truck is the page, each box is a band, the packing paper is the container's margin, and the dishes are the pieces. Dishes never ride loose in the truck.

Section 4 of 5

Tokens: the three tiers, and changing a value

Technical

Token tiers
Tier	Prefix	Holds	Lives in	Bound by
Global	`--g-`	Literal values: color ramps, scales, families	`tokens.json` (colors), `bundle.css` (the rest)	The semantic tier only
Semantic	`--s-`	Meaning, with a light and a dark-surface value	`tokens.json`	Page CSS
Component	`--c-`	The contract each component binds (1,752 tokens)	`components/bundle.css`	Components only

Change a value:

# 1. edit the value in design-system/tokens.json
# 2. regenerate the compiled files and the gallery
python3 tools/compile_tokens.py
python3 tools/build_gallery.py
# 3. check the gallery in Light, Dark surface and Alternate pack, then commit

Never write a color, size, radius or font literal in page CSS; bind --s-*. If no token fits, report the gap.
A semantic color's dark-surface value is stored twice: the Dark surface theme in tokens.json and the data-surface="dark" scope (section 3) in bundle.css. Change both together.
Every text color's usage note in tokens.json states its measured contrast; keep 4.5:1 (3:1 for icons and large text).

Plain language

What is a token, and why are there three kinds? Learn more

What

A token is a named value, such as "the link color" or "the space between two cards." There are three layers of names. The bottom layer is the raw paint chips: every shade, numbered. The middle layer gives each job a name, such as "body text" or "page background," and points at a chip. The top layer says which job each part of each piece uses.

Why

Names by job let you change meaning safely. If body text should be a shade darker, you point "body text" at a different chip, and every piece that uses body text follows. The middle layer also holds a second answer for dark backgrounds, so a piece knows its dark colors without anyone deciding them one piece at a time.

How

Find the token in tokens.json and change its value.
Run the two commands shown above to rebuild.
Open the gallery and look at the pieces that use it, in all three themes.
Commit the change with a sentence saying what changed and why.

Analogy: it's a paint store. The chips on the wall are the bottom layer; "kitchen walls" and "front door" on your shopping list are the middle layer. Repaint the front door by crossing out one chip number on the list, not by visiting every door.

Section 5 of 5

Work with the system on GitHub

Technical

Change something

git clone https://github.com/puddnsnacks-hub/ExampleDesignSystem.git
cd ExampleDesignSystem
git switch -c darken-link-color
# edit, then: python3 tools/compile_tokens.py && python3 tools/build_gallery.py
git add design-system gallery
git commit -m "Darken the link color one step"
git push -u origin darken-link-color

Open a pull request from the branch on GitHub; merge into main after review. main is the released state.

Release a version

git switch main && git pull
git tag v2.1.1 -m "Link color one step darker"
git push origin v2.1.1

Use it in another project

git submodule add https://github.com/puddnsnacks-hub/ExampleDesignSystem.git vendor/ExampleDesignSystem
# link vendor/ExampleDesignSystem/design-system/tokens.css, components/bundle.css, components/bundle.js
git submodule update --remote          # pull a newer version later

Host the gallery and this guide

The site lives in a separate public repository, puddnsnacks-hub/ExampleDesignSystem-site, served by GitHub Pages at xds.puddnsnacks.com. The source repository stays private. After a change is merged into main:

python3 tools/publish_site.py            # copies index.html, documentation/, gallery/, How-To-Docs/, design-system/ and pushes
python3 tools/publish_site.py --dry-run  # counts what would change, pushes nothing

Never edit the site repository by hand; each publish replaces it. The domain is a CNAME record (xds → puddnsnacks-hub.github.io) at the domain registrar. Without the site, open index.html from a local clone.

Keep the hosted design-system page in step

design-system/ mirrors the hosted page's files (project/…). After a merge, republish the changed files there; icons and photos stay as uploaded assets named in design-system.json. To regenerate everything from the XDS V4 source, see tools/build/README.md.

Plain language

How do changes get from my computer to everyone else? Learn more

What

GitHub keeps the master copy of the repository online. "Clone" makes your own copy. A "branch" is a private draft where you make a change. A "commit" saves a step with a note. A "pull request" asks others to review your draft before it joins the master copy. A "tag" stamps a version number on a moment in history so other projects can ask for exactly that version.

Why

Drafts and reviews keep a half-finished change from reaching every page that uses the system. Version numbers let a project stay on a known version until it is ready to move up.

How

Clone the repository once.
For each change, make a branch, edit, rebuild, and commit with a clear note.
Push the branch and open a pull request on GitHub; ask a teammate to review it.
After it merges, tag a new version if other projects should pick it up.
To update the public site, run the publish script. Everything in the site is public; the source stays private.

Analogy: it's a shared cookbook at a library. You borrow a copy, write your edits on sticky notes, and hand them to the librarian. Only after a second reader agrees do the notes go into the book, and each printing gets an edition number.