IRS Online Design Guide: the spec and the official base pages - #1
Merged
Conversation
Establishes the design guide as a small, build-free system optimized for
scaffolding whole pages (not just components):
- css/irs.css canonical stylesheet: tokens, base, government banner, masthead,
nav, buttons, cards, fields, read rows, alerts, wizard steps,
footer. USWDS-based with the IRS palette; square corners, 4px
buttons, Source Sans 3.
- DESIGN.md the spec: principles, page anatomy, tokens, type, building
blocks, page recipes, and a per-page checklist.
- AGENTS.md how an AI or human scaffolds a page from the system.
- templates/ whole-page starting points: base-page, account-dashboard,
task-wizard.
- assets/ IRS logo.
- README.md overview + quick start.
All example data is illustrative; no PII.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… + render tool - css/irs.css: prefers-color-scheme dark theme (brand chrome stays IRS blue, content surfaces invert) - tools/screenshots.mjs: Playwright render of every template across mobile/desktop x light/dark, plus an unstyled-vs-styled before/after pair - docs/screenshots/: 14 committed PNGs - DESIGN.md/AGENTS.md/README.md: screenshots now required for every change; README embeds a representative set Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…item Balances/amounts/body text are never red; red is reserved for error-alert accents (.alert.error left rule / icon).
…flag sync
- prototypes/: three polished pages showing the system on real surfaces —
IRS.gov homepage (omnibar front door), Online Account (IOLA role switch),
Where's My Refund (timeline tracker). Self-contained, fictional data,
official-repo disclaimers.
- index.html: root gallery presenting pages in context first, templates second.
- CONTRIBUTING.md: no PII, generated screenshots never stale, banner flag,
prototypes/ is polished-only, keep the index fresh.
- Gov banner flag: data-gov-banner on <html> ("off" everywhere off .gov —
the banner asserts a page IS a government website; "on" only on real .gov
deployments). Hide rule ships in css/irs.css; screenshots force it on to
document full page anatomy.
- Icons: no emoji, no glyph icons — templates converted to the inline-SVG
16-grid set (landmark, lock, chevrons, check); .ic class in css/irs.css.
- DESIGN.md: principles 5 + 8 updated, prototypes section, checklist items.
- Screenshots regenerated: 28 + before/after pair, incl. the new pages.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
slavingia
changed the title
Restructure per review: drop templates/ and prototypes/ — the repo now ships base/, the official IRS.gov surfaces as they exist in production, rendered in the design system. Base pages are the starting points (copy the closest one); speculative concepts live in the prototypes gallery repo. - base/irs-gov-homepage.html — utility bar (Help/News/Tax Pros, Español, Sign in, Create account), header search, real primary nav (File, Pay, Refunds, Credits & Deductions, Forms & Instructions, Report Fraud), account promo, the six production task tiles, news cards, and the real footer columns (Our agency / Know your rights / Resolve an issue / Related sites). - base/your-account.html — the account landing: Individual / Business / Tax Pro cards with production capability lists, "Sign in or create account", and the ID.me identity-verification note. - base/wheres-my-refund.html — availability windows (24 hours / 3 days / 4 weeks), check with or without an account, refund timelines, IRS2Go and hotlines, delay reasons — all mirroring irs.gov. - Padding fixes: nav.tabs scrolls instead of overflowing narrow screens; masthead wraps under 600px; homepage utility strip wraps cleanly. Mobile pages now render at exactly 390px with no horizontal overflow. - index.html, DESIGN.md, CONTRIBUTING.md, AGENTS.md, README.md rewritten around base/; screenshots regenerated (16 + before/after pair). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
slavingia
changed the title
Collaborator
Author
|
IRS logo is too small |
Collaborator
Author
|
we should have a login style nav that's just logged out view with blue-on-white sign in button and then omnibar / search in hero below that |
Collaborator
Author
|
this should all work natively with GitHub pages right? |
- IRS logo: assets/irs-logo.svg viewBox was 0 0 652 652 with the lockup
occupying only a third of it — cropped to the artwork (20 218 602 207)
so the logo renders at its real size; seal sized 44px in a 76px
masthead.
- Logged-out header: masthead now carries "Create account" and a
blue-on-white Sign in button (.masthead .signin in irs.css); duplicate
sign-in links removed from the utility strip. Where's my refund gets
the same button.
- Hero omnibar: search moved out of the masthead into the navy hero
("How can we help you?" + full-width omnibar). The account promo
moved to a card at the top of main.
- All screenshots regenerated; mobile pages still exactly 390px wide.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The core search interaction, built to the ARIA combobox pattern:
- Popular tasks on focus; substring filtering across titles plus
plain-language/form-number keys ("1040-x", "cant pay") with the
matched span bolded; category kickers per suggestion.
- Keyboard: arrow up/down (wrapping), Enter navigates, Esc closes
(preventDefault — search inputs natively clear on Esc and the input
event would reopen the panel), click-outside closes, mousedown
selects before blur.
- aria-expanded / aria-controls / aria-activedescendant / role=option
wired throughout; suggestions defined once as a data array.
- Verified end-to-end with Playwright: focus shows Popular (5), "refund"
filters to 1 with <b>refund</b> highlighted, ArrowDown+Enter navigates
to wheres-my-refund.html, Esc closes keeping the value, "1040-x"
surfaces the amended-return task.
- tools/screenshots.mjs now captures the open-panel state (4 new shots:
desktop/mobile × light/dark); DESIGN.md documents the pattern as a
building block.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- base/online-account.html — the signed-in IOLA account home, grounded in the production feature list (irs.gov "Online account for individuals"): account balance by year, refunds status with tracker link, payments (schedule up to 365 days, 5-year history, payment plan), tax records (transcripts, W-2/1095-A/1099s, audit status), notices with paperless/email options, authorizations (POA/TIA, e-sign), and profile readrows (address, notifications, IP PIN). Signed-in chrome: persona in masthead, account tabs, fictional data disclaimed in sub and footer. - index.html: uniform card thumbnails (fixed-height, object-fit cover from the top) so cards no longer leave uneven voids; h1 no longer crowds the masthead; new gallery card for the account view. - Screenshot tool covers the new page (24 shots + before/after); all mobile shots verified at exactly 390px. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Two Safari-visible bugs, both fixed in the shared files so every page gets them: - Logo rendered gigantic in Safari, overlapping the masthead label: cropping the logo's viewBox earlier left the SVG with no intrinsic width/height, which WebKit can't size via height:100%/width:auto. assets/irs-logo.svg now declares width=602 height=207, and .logo .seal img uses an explicit 44px height. - Pages followed the OS dark theme, but production IRS.gov is light-only: the dark palette in css/irs.css is no longer under @media (prefers-color-scheme: dark) — it now applies only with an explicit data-theme="dark" on <html>, and :root sets color-scheme:light. Pages render light in any OS theme; the screenshot tool sets the attribute so dark-capability shots remain. Verified in WebKit with a dark OS theme across all five pages: logo 128x44, white body background, no horizontal overflow, no JS errors. Screenshots regenerated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Page titles were cramped under the nav on every page: main.wrap now carries 36px top padding in css/irs.css (one fix for all pages); per-page mt-3 compensations removed and .crumb top margin dropped. - Public nav gains a "Home" tab matching the logged-in IOLA pattern — active on the homepage, linking back from Your account and Where's my refund. - "Sign in or create account" CTAs now land in the base IOLA view (online-account.html): homepage promo card, Where's my refund "Check in your account", and the Individual Account card on the chooser. Masthead "Sign in" still routes through the Your account chooser, whose Individual card continues into IOLA. - Flow verified in-browser: homepage CTA → IOLA; masthead Sign in → chooser → Individual → IOLA; wmr CTA → IOLA; Home tab → homepage. Screenshots regenerated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…nifier - Janky button alignment: cards inside .grid/.grid-3 are now flex columns and a direct-child .btn pins to the card bottom (margin-top:auto in css/irs.css) — CTAs align across a row no matter how much content sits above. On Where's my refund the About link moved above the button so both cards end flush. Verified via bounding boxes: wmr buttons y=617/617, chooser y=488/488/488. - Omnibar: removed the Search submit button; a muted magnifying-glass SVG sits left of the input, focus ring moves to the whole bar (:focus-within). Enter still submits/selects. - Screenshots regenerated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
IOLA's visible copy called its own data fictional ("All values shown
are fictional example data" in the sub and footer) — removed; the page
reads as the real product. Example values are shown, never labeled
(the no-PII guarantee lives in CONTRIBUTING.md, not in page copy).
Guarded against regression: scripts/check_fourth_wall.py (ported from
the prototypes gallery, extended with fictional/example-data/design-
guide patterns and no mock-data allowances) scans every base/ page;
.github/workflows/checks.yml runs it on every push and PR. The root
index.html gallery is exempt — describing the pages is its job.
CONTRIBUTING.md documents the rule. Screenshots regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The "Do more with an IRS account" card under the hero is gone — the masthead Sign in button and the top-task tiles carry those paths. Screenshots regenerated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…hero copy Placeholder text disappears on input and fails contrast — the example queries now live in the hero paragraph, which stays visible while typing. The input keeps its aria-label; the autocomplete's Popular suggestions on focus cover discovery. Screenshots regenerated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The gray utility bar above the masthead is gone; Español moves into the masthead next to Create account / Sign in so the language toggle survives. Page opens banner → masthead → nav, same as the other base pages. Screenshots regenerated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A bit less air between the nav and page titles, still clear of the chrome. One shared rule, applies to every page. Screenshots regenerated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Collaborator
Author
|
Feedback addressed, all pushed:
Also since the last review: the signed-in Individual Online Account view ( 🤖 Generated with Claude Code |
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Publishes the IRS Online Design Guide as a small, build-free, page-first system. The unit is a whole page, not a component in isolation — and the pages shipped are the official IRS.gov surfaces, rendered in the design system. Built on USWDS with the IRS palette and masthead.
No templates, no speculative concepts (those live in the prototypes gallery repo). You start a new page by copying the closest base page.
Contents
base/— the official surfaces, accurate to production IRS.gov:irs-gov-homepage.html— logged-out masthead (Español · Create account · blue-on-white Sign in button), the real primary nav with a Home active tab, and a hero omnibar with working autocomplete (ARIA combobox: popular tasks on focus, substring filtering with bolded matches, ↑/↓/Enter/Esc, no placeholder — example queries live in visible hero copy). Real task tiles, news, and the production footer columns.your-account.html— the account chooser: Individual / Business / Tax Pro cards with production capability lists and the ID.me identity-verification note.wheres-my-refund.html— availability windows, check with or without an account, timelines, hotlines, delay reasons.online-account.html— the signed-in Individual Online Account home: balance by year, refunds, payments, tax records, notices, authorizations, profile. Sign-in CTAs across the repo land here, so the whole flow clicks through: homepage → chooser → IOLA.index.html— the gallery, one card per base page.DESIGN.md/CONTRIBUTING.md/AGENTS.md— the spec, the rules, and the how-to.css/irs.css— the canonical stylesheet (tokens, chrome, blocks,.icicons, opt-in dark palette).scripts/check_fourth_wall.py+.github/workflows/checks.yml— CI enforces that base pages read as real IRS products (no "prototype/demo/fictional data" in visible copy).tools/screenshots.mjs+docs/screenshots/— 28 committed PNGs covering every page, including the open-autocomplete state.Policies worth calling out
data-gov-banner="off"; real .gov deployments flip it to"on". Screenshots force it on to document full anatomy.data-theme="dark"opt-in (screenshots capture it).Screenshots
IRS.gov homepage — hero omnibar, and the autocomplete open:
The signed-in flow — account chooser → Individual Online Account:
Where's my refund? — mobile light, and the before/after pair:
(All 28 in
docs/screenshots/; regenerate withnode tools/screenshots.mjs.)How to use
cp base/wheres-my-refund.html my-feature.html # then edit title, crumb, h1, and mainKeep the chrome (banner markup + toggle + flags, masthead, footer), fill
mainfrom documented blocks, use tokens not raw hex, capture screenshots, run the checklist.🤖 Generated with Claude Code