Pre-1.0 architecture decisions: input needed from adopting teams

[abbybowman]

Context

HDS Core is a Sass/CSS theme layer on USWDS 3.x. The approach so far for the pre-1.0 buildout has been to keep standard USWDS markup, override styles with HDS values, and ship no custom JavaScript. This has worked well for individual components — buttons, tables, accordions, forms, links, and lists all restyle cleanly with the same .usa-* markup.

As we push into composed components (Prose, Navigation, Cards) and palette-aware content blocks, we're hitting limitations in the "override everything" approach:

• Specificity battles. USWDS component CSS loads its own typography, colors, and spacing via internal mixins. HDS overrides must match or exceed that specificity. Some components (Prose, composed forms) require reverse-engineering USWDS source to find the right selectors, and the override code is sometimes longer than writing the component from scratch.
• Dead code. We load all ~70 USWDS component packages but only theme ~18. The rest ship unused CSS that inflates bundle size and creates potential style conflicts.
• Build tooling. @uswds/compile locks us to Gulp 4, which has 11 known dependency vulnerabilities. There's no Gulp 5 compatible version and @uswds/compile has limited active maintenance.
• Prose is the immediate example. .usa-prose applies its own heading, list, table, and margin styles via internal USWDS mixins. HDS needs different values for all of these. Overriding them requires ~150 lines of CSS that duplicate our existing styles at higher specificity and must stay in sync whenever the base styles change.

Before we lock in the v1.0 architecture, we want your input on five decisions that would be disruptive to change after teams start building against a 1.0 release.

---

1. Selective USWDS loading, drop @uswds/compile and Gulp?

Current state: styles.scss loads the entire USWDS library (@forward "uswds" = all ~70 component packages), then _hds-components.scss overrides individual components. Build uses Gulp 4 via @uswds/compile.

Proposed: Replace monolithic USWDS loading with selective @use = only load the ~18 component packages HDS actually themes. Components where HDS overrides are more complex than the component itself (Prose is the current example) get replaced with HDS implementations. Replace Gulp 4 with direct sass CLI and npm scripts.

What this changes for adopters: Nothing in the output CSS; same classes, same HTML markup. Build pipeline is internal to HDS Core. Adopter integration (Sass import or pre-compiled CSS link) stays identical.

Benefits:

• Composed components like Prose can be written clean instead of fighting USWDS specificity
• Smaller CSS bundle (skip ~50 unused USWDS component stylesheets)
• Eliminates Gulp 4 dependency vulnerabilities
• Clear inventory of exactly which USWDS packages HDS depends on (important context given USWDS's current maintenance trajectory)

Risks:

• USWDS packages may have internal cross-dependencies that surface when other packages aren't loaded. Requires testing to verify the selective set compiles cleanly.
• We diverge from USWDS's documented build process, so we own debugging any compilation issues rather than relying on @uswds/compile support.
• If a future USWDS update changes a package we selectively load, we discover it in isolation rather than as part of a tested monolith. (Mitigated by pinning USWDS version and reviewing changelogs before updating.)

Discussion q's:

• Any objections? Are any teams planning to import HDS Core in a way that would depend on the full USWDS component library being present in the output CSS?

---

2. Global bare-element styling on or off by default?

Current state: Bare HTML elements (<h1>, <a>, <table>, <ul>) receive no HDS styling unless they're inside a USWDS component wrapper (.usa-prose, .usa-table) or the adopter enables $theme-global-content-styles: true in their Sass configuration. This is a USWDS flag that defaults to false.

The tradeoff:

false (current default)	true
Bare elements are unstyled — safe for apps that don't want opinionated defaults	Every bare element on the page gets HDS typography, colors, and spacing
CMS/markdown content needs .usa-prose wrapper to look correct	CMS content looks correct without wrappers
More setup work for content-heavy sites	Could cause unexpected styling on app UI that uses bare elements for non-content purposes

Discussion q's:

• How will your site generate content? Will you wrap CMS output in .usa-prose?
• Do you expect bare <h1> and <a> elements to be HDS-styled by default, or do you prefer opting in per-section?
• If your team is migrating an existing USWDS site, what is the current setting?

---

3. Class naming for HDS-authored components: .usa-* or .hds-*?

Current state: HDS uses .usa-* class names when the component maps 1:1 to USWDS (same markup, different styles). Components with no USWDS equivalent use .hds-*.

The question: If Decision 1 is approved and HDS starts writing its own implementations of components like Prose (instead of overriding the USWDS version), should those keep the .usa-* class name or use a new .hds-* name?

.usa-prose (keep)	.hds-prose (rename)
Drop-in — existing USWDS markup works with no changes	Explicit that this is an HDS component, not vanilla USWDS
Easier migration from vanilla USWDS sites	Avoids confusion when HDS behavior differs from USWDS docs
Risk: adopters may expect USWDS-documented behavior	Risk: migration requires find-and-replace across templates

Discussion q's:

• How much existing USWDS markup do your current sites have?
• Would a class name change be a one-time find-and-replace, or a significant effort?

---

4. JavaScript strategy for HDS Core

Current state: HDS Core ships zero custom JavaScript. Interactive components (accordion, banner, modal, tooltip, in-page navigation, date picker) work via uswds.js — a single ~100KB bundle that initializes all USWDS JS components on the page.

The problem: Several Phase 2 HDS components require JavaScript that USWDS doesn't provide:

• Navigation: Murphy Bed menu, scroll effects, hover interactions
• Dropdown menus (custom styled — not native <select>)
• Mobile table of contents collapse
• Toggles
• Site alert dismiss button

These are core components for nasa.gov and mission sites — not edge cases.

Options:

Approach	Pros	Cons
Keep uswds.js + add hds.js bundle	Simple, familiar pattern	Two JS bundles, potential initialization order issues
Per-component ES modules	Tree-shakeable, modern	More complex integration for non-bundler sites
Web components (<hds-dropdown>)	Framework-agnostic, encapsulated	Larger architecture shift, SSR considerations
Vanilla JS with data-* init (same pattern as USWDS)	Consistent with USWDS pattern teams already know	Manual initialization, same limitations as current USWDS approach

Discussion q's:

• Are you loading uswds.js as a single bundle, or using a framework adapter like react-uswds?
• What JS bundler/framework does your site use (if any)?
• What's your Content Security Policy situation? (Affects viable JS patterns.)
• Would your team contribute JS implementations for shared components?

---

5. USWDS migration compatibility: how faithful do we need to be?

Current state: A core design goal has been that existing USWDS sites can adopt HDS Core with minimal markup changes — add the HDS CSS and .usa-button, .usa-accordion, .usa-table elements restyle automatically. This has worked well for the components shipped so far. Most are pure CSS overrides with no HTML changes required.

The tension: As we move into more complex components, we're finding cases where HDS needs different markup than USWDS for the same component class. Examples so far:

• HDS ordered lists need role="list" for accessibility when using HDS's custom numeral styling (USWDS doesn't require this)
• Phase 2 navigation will likely have different markup structure than USWDS header/footer

Some future components may have similar requirements that we can't predict yet.

The question: Where on this spectrum should HDS Core target?

Approach	What it means
Full drop-in	Any .usa-* markup from a vanilla USWDS site works without HTML changes. HDS visual differences are CSS-only.
Mostly drop-in	Most components work without changes. A documented shortlist of components requiring one-time HTML updates (add an attribute, change a wrapper, etc.).
Migration guide	HDS Core provides its own recommended markup patterns. A migration guide documents what to change from vanilla USWDS. Existing markup may partially work but isn't guaranteed.

Discussion q's:

• How much existing USWDS markup do your sites have?
• What's a reasonable amount of one-time migration effort?
• Are there specific components where drop-in compatibility is critical, vs. components where you'd accept HTML changes with clear documentation?

---

How to weigh in

We're scheduling a meeting next week (March 30-Apr 3) to discuss. If you can't attend, please comment here with your team's constraints, preferences, and questions.