Skip to content

AGENTS.md

Latest commit

 

History

History
57 lines (48 loc) · 3.2 KB

AGENTS.md

File metadata and controls

57 lines (48 loc) · 3.2 KB
Raw

Building IRS pages (for AI assistants and humans)

This repo is set up so you can scaffold a new, on-brand IRS page in one pass. Read this, then read DESIGN.md. Both are short on purpose.

The loop

  1. Pick the closest base page in base/ and copy it — never start from a blank file:
    • irs-gov-homepage.html — landing/hub: search, nav, promo, tiles, footer columns.
    • your-account.html — choice/sign-in: cards with capability lists + CTAs.
    • wheres-my-refund.html — content/tool: prose, key/value cards, CTAs.
  2. Keep the chrome. Leave the government banner, masthead, footer, and the banner-toggle script as they are. Only change the masthead .ctx label, the nav.tabs items, and the <title>. Keep data-gov-banner="off" on <html> — the banner renders only on real .gov deployments (it asserts the page IS a government website; see DESIGN.md principle 5).
  3. Fill main from the documented blocks (.card, .field, .alert, .readrow, .shell+.steps). Don't invent new components or new CSS when a block already exists — compose the existing ones.
  4. Use tokens, not hex. var(--irs-blue), var(--line), etc. If you reach for a raw color, you're probably drifting off-system.
  5. Capture screenshots with node tools/screenshots.mjs and commit them under docs/screenshots/ — always before/after, mobile/desktop, and dark/light. The look is the deliverable; reviewers judge it visually.
  6. Run the checklist at the bottom of DESIGN.md before you're done.

Hard rules

  • Link the stylesheet, don't fork it. Reference css/irs.css; don't paste a modified copy of the system's CSS into the page. New page-specific styles, if truly unavoidable, go in a small <style> block and should still use tokens.
  • Square by default. Containers, panels, cards, inputs: no border-radius. Buttons and small square tiles: 4px. Circular only for genuine indicators.
  • One h1.page per page. Plain-language copy. Readable measure for prose.
  • No new dependencies. No frameworks, no build step, no JS beyond the banner toggle unless the feature genuinely needs interaction.
  • Mock data only in examples. Never put real taxpayer data or PII in a template or example page.
  • Icons are inline SVG only. 16-grid, currentColor, stroke-width:1.6, the .ic class — never emoji or text glyphs (› ⌄ ✕ ✓) as icons.
  • base/ stays accurate to production. Base pages mirror what is live on IRS.gov — content, navigation, and copy. Speculative concepts belong in prototypes/, always footed with the concept disclaimer — never in base/.

What "done" looks like

A single HTML file that opens directly in a browser, passes the DESIGN.md checklist, links css/irs.css, and is built entirely from documented blocks — so it already looks like IRS and the next person (or model) can extend it the same way.

Extending the system

If a genuinely new, reusable pattern is needed: add the class to css/irs.css, document it in DESIGN.md (with a token-based rule), and show it in a template. Keep additions small, square, and token-driven so the system stays coherent.