Work in progress. This guide is a proposal under active review (PR #1) — pages, spec, and structure are still changing and nothing here is final or adopted yet.
The codified IRS online look — built on the U.S. Web Design System with the IRS palette and masthead — packaged so a person or an AI assistant can scaffold a new, on-brand IRS page in one pass.
It is page-first: the unit of work is a whole page, not a component in isolation. No build step, no framework — plain HTML and one stylesheet.
| Path | What it is |
|---|---|
DESIGN.md |
The spec: principles, page anatomy, tokens, type, blocks, recipes, checklist. |
CONTRIBUTING.md |
The rules: accuracy to IRS.gov, no PII, generated screenshots, banner flag. |
AGENTS.md |
How to build a page from this system (for AI assistants and humans). |
index.html |
The gallery — every base page, shown whole. |
css/irs.css |
The canonical stylesheet. Link it and use the documented classes. |
base/ |
The official IRS.gov surfaces as they exist in production, rendered in the system. Copy the closest one to start a page. |
prototypes/ |
Speculative concept explorations, clearly disclaimed — not planned or actual IRS systems. |
assets/ |
Shared assets (IRS logo). |
irs-gov-homepage.html— the IRS.gov homepage: utility bar, search, primary nav, account promo, top task tiles, news, full footer columns.your-account.html— the account landing: Individual / Business / Tax Pro accounts, sign in or create account via ID.me identity verification.wheres-my-refund.html— refund status: availability windows, checking with or without an account, timelines, hotlines, delay reasons.online-account.html— the signed-in Individual Online Account home: balance, refunds, payments, tax records, notices, authorizations, profile.
Base pages mirror what is live in production on IRS.gov — content,
navigation, and copy stay accurate; when IRS.gov changes, the base page
changes. Speculative concepts live under prototypes/, each
footed with a concept disclaimer.
Every page carries the full USWDS banner markup, but it renders only on real
.gov properties: pages set data-gov-banner="off" on <html> (the banner
asserts a page IS a government website — showing it anywhere else would imply
the page is one). Real .gov deployments flip it to "on". Documentation
screenshots force it on to show full page anatomy.
cp base/wheres-my-refund.html my-feature.html
# open my-feature.html in a browser; edit the title, crumb, h1, and mainThen fill main from the blocks documented in DESIGN.md, keep the chrome and
the banner-toggle script, and run the checklist. That's it.
Every page is captured mobile/desktop and dark/light, plus a
before/after pair (all in docs/screenshots/,
regenerated with node tools/screenshots.mjs).
Before / after — the same page without vs. with the design system:
| Before (no system) | After (irs.css) |
|---|---|
 |
 |
Light / dark — the IRS.gov homepage (dark is an explicit data-theme="dark" opt-in; pages render light in any OS theme, matching production):
| Light | Dark |
|---|---|
 |
 |
Mobile — Where's my refund at 390px, light & dark:
| Mobile light | Mobile dark |
|---|---|
 |
 |
- Square corners (4px on buttons/tiles only); circular for indicators.
- Source Sans 3, IRS blue/navy, USWDS government banner on every page.
- Bold dark labels, plain values; 16px UI text at weight 500.
- Use tokens, not raw hex. Link the stylesheet, don't fork it.
All example data is illustrative — never commit real taxpayer data or PII.