Component roadmap: Phase 1 (v1.0) vs future work

[abbybowman]

Tracks which components ship in HDS Core v1.0 and what's deferred. Cross-references HDS Figma guidance, USWDS components, and HDS Core SCSS files.

Guiding principles

HDS Core v1.0 is a CSS/Sass theme layer on USWDS. Phase 1 covers components that are already styled in CSS and need Storybook documentation, plus a small set of new components that are essential for an MVP v1.0 launch.

Utility classes: HDS Core introduces minimal utility classes beyond USWDS. Currently: .hds-print-visible (opt-in print visibility for elements hidden by default in print, e.g., critical site alerts).

JavaScript: HDS Core ships no custom JS. Components that use USWDS JS (accordion, banner, date picker, modal, tooltip, etc.) work out of the box when uswds.js is loaded. Components needing custom JS are deferred or ship as CSS-only shells with a note.

Navigation terminology: HDS Figma, USWDS, and HDS Core use overlapping names for navigation components. See DESIGN.md § Navigation Component Mapping for the canonical terminology reference.

Phase 1 — Ship in v1.0

Done: Styled in CSS and documented in Storybook

Component	HDS Guidance	USWDS Equiv	Stories
Accordion	Accordion.pdf	Accordion	✅ Guidance + Playground
Blockquote	Blockquote.pdf	—	✅ Guidance + Playground
Breadcrumb	Breadcrumbs.pdf	Breadcrumb	✅ Guidance + Playground
Button (CTA, Secondary, Outline)	Buttons.pdf	Button	✅ Guidance + Playground
Checkbox	Checkbox.pdf	Checkbox	✅ Guidance + Playground
Form (composed)	—	Form, Validation	✅ Stories (Guidance and final QA check TODO pre-1.0)
Icon Button	Buttons.pdf	—	✅ Guidance + Playground
Intro Text	—	Prose (.usa-intro)	✅ Guidance + Playground
In-Page Navigation	Navigation.pdf	In-page navigation	✅ Guidance + Playground
Link	Links.pdf	Link	✅ Guidance + Playground
List	List.pdf	List	✅ Guidance + Playground
Pagination	Pagination.pdf	Pagination	✅ Guidance + Playground
Primary Arrow Button	Buttons.pdf	—	✅ Guidance + Playground
Radio Button	Radio Buttons.pdf	Radio buttons	✅ Guidance + Playground
Select	Text and Select Fields.pdf	Select	✅ Guidance + Playground
Site Alert	Banners.pdf	Site alert	✅ Guidance + Playground
Table	—	Table	✅ Guidance + Playground
Text Input	Text and Select Fields.pdf	Text input, Textarea	✅ Guidance + Playground

Form controls (Checkbox, Radio, Select, Text Input) share _form.scss. List and Table have bare element fallbacks in base/_elements.scss. All other components follow the _component-name.scss convention.

All foundation pages are complete — see Storybook sidebar for the full list.

Close: Already styled in CSS, needs Storybook stories and testing

Component	SCSS File	HDS Guidance	USWDS Equiv	Notes
Prose	—	—	Prose	Stories done. Full HDS styling blocked on build pipeline migration (see GitHub Discussion).

Needs CSS + Storybook stories (essential for v1.0)

Component	HDS Spec	USWDS Equiv	Notes
Chip	Chips.pdf	—	Visually and typographically identical to Topic Tag (Inter 12px semibold, sentence case, outline box) but with NASA Blue border and X dismiss icon. Used for removing applied filters in search/gallery. Needs custom JS for dismiss — CSS-only styling ships in v1.0, dismiss behavior deferred. Build alongside Tag component with shared text mixin.
Tag	Tags.pdf	Tag	Three distinct tag types in HDS Figma with different typography and interaction: Content Tag (Inter 12px bold, uppercase, non-interactive, icon + label), Topic Tag (Inter 12px semibold, sentence case, interactive — navigates to topic page, outline box), Urgent Label (DM Mono 12px, wide letterspacing — deferred). Topic Tags share text treatment with Chips — build with shared mixin. Major naming conflict: USWDS .usa-tag serves a different purpose.

Phase 2 — Post-v1.0 (future contributors / phases)

Navigation (Header, Footer, Secondary Navigation) is the top Phase 2 priority; it's the highest-complexity, highest-impact component set remaining after v1.0.

Architecture review: Five pre-1.0 architecture decisions are under discussion with adopting teams (see GitHub Discussion). Outcomes may reshape Phase 2 priorities — particularly selective USWDS loading, JavaScript strategy, and USWDS migration compatibility.

High priority: Essential components needing design + build

Many of these are already styled in the HDS Core WordPress theme and/or on production flagship sites, and just need to be reviewed for best practices/compatibility and ported in.

Component	HDS Spec	USWDS Equiv	Notes
Navigation (Header/Footer/Secondary Nav)	Navigation.pdf	Header, Footer	_navigation.scss exists (Phase 2 stub). Includes Global Navigation (Murphy Bed menu, dropdowns, logo link, NASA TV), Secondary Navigation (horizontal bar beneath header with breadcrumb/title scroll swap, light/dark themes, optional dropdown menus), and Footer. The vanilla WP HDS theme had 4 nav variants (agency/explore/external/internal) each with header + footer. Needs custom JS for Murphy Bed menu, scroll effects, and hover interactions. HIGH COMPLEXITY — top Phase 2 priority.
Banner (government)	—	Banner	_banner.scss exists (Phase 2 stub) — inherited styles are not fully HDS-themed. No HDS Figma design. USWDS default works acceptably with HDS theming (colors and fonts apply automatically). Needs creative director review before HDS-specific styling. Uses USWDS JS for expand/collapse. Not the same as HDS Figma "Banners" — see Site Alert.
Cards	Cards.pdf	Card	USWDS base + HDS layout. Every content site needs cards. Vanilla WP HDS theme has markup that could be helpful. No JS needed.
Date Picker	Date Picker.pdf	Date picker	USWDS base + HDS theming. Uses USWDS JS.
Dialogs & Modals	Dialogs & Modals.pdf	Modal	USWDS base + HDS theming. Uses USWDS JS.
Dropdown Menus	Dropdown Menus.pdf	Combo box / Select	Complex interaction. USWDS JS covers combo box; HDS-specific menu patterns may need custom JS. Required for Pagination filter variant and Table of Contents mobile collapse.
File Upload	File Upload.pdf	File input	USWDS base + HDS theming. Uses USWDS JS.
Grid Utilities	—	Grid	_grid-utilities.scss exists. Responsive reverse, horizontal lists. Refinements to the core USWDS grid, which works fine for v1.0. No JS needed.
Search Inputs	Search Inputs.pdf	Search	USWDS base + HDS theming. No JS needed (search submission is application logic, not component JS).
Sliders	Sliders.pdf	Range slider	USWDS base + HDS theming. Uses USWDS JS.
Table of Contents	Table of Contents.pdf	—	HDS component. Multi-column link grid at top of page (2-col or 3-col) with directional arrow affordances (↓ anchor, → internal, ↗ external). Collapses to dropdown on small/medium screens — needs custom JS for mobile dropdown. Minimum 5 rows. Not a duplicate of In-Page Navigation (sticky sidebar with scroll spy) or Secondary Navigation (site-section bar beneath header).
Toggles	Toggles.pdf	—	Needs custom JS (no USWDS equivalent).
Tooltips & Popovers	Tooltips & Popovers.pdf	Tooltip	USWDS base + HDS theming. Uses USWDS JS.

Med priority: Components with narrower use cases

Component	HDS Spec	USWDS Equiv	Notes
Avatars & Badges	Avatars & Badges.pdf	—	No USWDS equivalent. Mostly relevant to NASA.gov profiles and author bylines. No JS needed.
Captions	Captions.pdf	—	.hds-caption class already exists and works. Phase 2 scope: Storybook story + credit line variant at end of caption. No JS needed.
Status Indicator	Status Indicator.pdf	—	No USWDS equivalent. Primarily relevant to mission status on NASA.gov. No JS needed.
Stepper	Stepper.pdf	Step indicator	USWDS base + HDS theming. No JS needed.

Med priority: Deferred aspects of v1.0 components with broad use cases

When an aspect of a Phase 1.0 component needs more time and attention post-1.0 to implement properly (and/or requires creative director review), we track it as a task in GitHub Issues or as an Idea in GitHub Discussions. Priorities shaped by community upvotes.

Item	Task/Discussion	Notes
Utility Text Buttons	#5	Accordion open/close with text labels. HDS Figma shows text + icon utility buttons.
New and Renamed Icons	#3	Needs creative director review. Some HDS Figma icons don't match current sprite names.
Pagination: responsive simplified	#11	Auto-switch bounded/unbounded → simplified on small viewports via CSS media queries. Both markup variants in DOM, toggle visibility.
Icon Button: hover/disabled/focus	#12	Figma values confirmed. Currently implemented only in _pagination.scss (pagination arrows). _icon-button.scss needs matching implementation for all roles. See DESIGN.md § Creative Director Review for blue/midtone palette questions.
Icon Button: size audit	#13	Figma defines 6 sizes (XS–XXL, 16–36px). HDS Core has 3. --lg is 40px but Figma XXL is 36px. SVG padding (24×24 vs Figma 20×20) affects glyph-to-container ratio. Accordion chevron circle (24px / 1.5em) also needs this --md size. See DESIGN.md § Creative Director Review.
Primary arrow button sizes	#9	Figma shows 6 sizes (14–36px). HDS Core ships default only. Needs creative director review.
Extended palette utility classes	—	$hds-extended-palette map exists in _hds-tokens.scss but $global-color-palettes expects palette name strings, not a Sass map. Needs research into USWDS 3.x custom color registration API.
Alert: Historical Content Notice	—	Neutral informational alert (Carbon 05 bg, dark text) positioned between header and page body. Maps to usa-alert not usa-site-alert. Uses archive icon. See Figma CSS specs in session notes.
Table: mobile variants	#27	Mobile/stacked layouts (.usa-table--stacked, .usa-table--stacked-header) untested with HDS overrides. Figma also shows different text sizes for small vs M-XL viewports. Needs testing, likely CSS fixes, and creative director review for mobile typography.
Form: composed review	—	Error side border (USWDS adds left border on .usa-form-group--error, Figma doesn't show it) and error inline icon (red circle exclamation present in Figma, absent in USWDS). Next session TODO.
Select: custom chevron	—	Replace USWDS default double-arrow with HDS arrow-chevron-down. Requires palette-aware SVG approach or custom dropdown component.
Select: custom dropdown panel	—	Figma shows styled dropdown with rounded corners and blue active highlight. Requires JavaScript — native <select> can't be styled.

Low priority: Deferred aspects of v1.0 components

Item	Task/Discussion	Notes
Accordion: bordered variant	—	USWDS .usa-accordion--bordered is not restyled by HDS. Pending creative director review. See DESIGN.md § Accordion.
Accordion: hover state	—	HDS Figma does not specify hover for accordion heading row. Pending Figma research on full-row hover patterns. See DESIGN.md § Accordion.
Pagination: filter variant	#10	Requires Dropdown Menu component. HDS Figma spec shows rows-per-page filter. See DESIGN.md § Filter Variant.
Play Buttons & Media Controls	#7	Overlay, fullscreen, NASA TV badge. Uses hds-buttons/interactive-*.svg fixed-color graphics.
Site Alert: dismiss button	—	Needs custom JS. HDS Figma shows ✕ close button on banners. USWDS site alert has no built-in dismiss.
Site Alert: "Live!" badge	—	Composed pattern with badge label + CTA link. HDS Figma shows this on red/blue announcement banners.
Social Buttons	#6	Platform-specific branded circles. Currently only --social role exists with gray styling.
Table: palette-aware backgrounds	#26	Tables use fixed white/Carbon 90 backgrounds regardless of surrounding palette. Needs creative director review. See DESIGN.md § Table.
Table: advanced features	—	Tabs, actions bar, filter panel, search, download, print, accordion mobile layout, fixed first column. Complex composed patterns.
Checkbox/radio size	—	Figma 18px, USWDS 20px. Forced via CSS. $theme-input-select-size can't express 2.25 units. Monitor for side effects.
Form: floating label	—	Figma shows label-as-placeholder that moves above field on focus. Requires JavaScript.
Disabled help text	—	Figma dims to Carbon 40 (2.85:1 contrast, fails WCAG). HDS Core keeps readable. Flagged for creative director review.

Low priority: Unstyled components

USWDS components not listed above (Alert, Button group, Card, Collection, Combo box, Character count, Date range picker, Icon list, Identifier, Input mask, Input prefix/suffix, Language selector, Memorable date, Process list, Side navigation, Summary box, Time picker) work with HDS theming but have no HDS-specific designs. Use USWDS defaults.

HDS Figma components with no USWDS equivalent are deferred. Needs custom JS: Audio Player, Carousel Thumbnails, Countdown, Filters & Sorts, Live Event Ticker, Loaders (complex variants), Quick Facts Carousel, Scroll Hint, Tabs, Video Player. CSS-only: Gallery Thumbnails, Image with Caption, Sign Ups & Subscribe, Social Media, Vitals.