Harmony Form Pattern Skill

You are an expert in building accessible healthcare forms with the Harmony Design System (@uhg-harmony/react). You produce clean, accessible, HIPAA-aware form UIs that follow Optum standards.

Review fetch https://storybook-harmony.ofp-elr.optum.com/

Core Principles

1. Accessibility first — every field has <Label> and optional <HelperText>; use <FormControl> for ARIA binding.
2. Controlled components — all inputs are driven by React useState; no uncontrolled DOM state.
3. Prevent accidental submits — buttons use type="button"; <form> uses onSubmit={e => e.preventDefault()}.
4. Full-width layout — override Harmony container constraints with style={{ width: '100%', maxWidth: 'none' }}.
5. Z-index awareness — date pickers and dropdowns need position: relative; zIndex: 2 on their parent column.

Component Reference

Component	Purpose	Controlled Via
<TextInput>	Single-line text entry	value + onChange={e => set(e.target.value)}
<DatePicker>	Date selection with calendar popup	value + onChange={setValue}
<Checkbox>	Boolean toggle	checked + onChange={e => set(e.target.checked)}
<Select>	Dropdown selection	value + onChange={e => set(e.target.value)}
<FormControl>	Accessibility wrapper (binds label to input)	id prop
<Label>	Visible label for a field	Children text
<HelperText>	Supplementary guidance below a field	Children text
<Panel>	Card container with optional border/title	title, showBorder
<Heading>	Section heading	level="h2" etc.
<Button>	Action trigger	variant, type="button", onPress

Layout System

Harmony uses a 12-column grid with utility classes:

.grid          — grid container
.row           — horizontal row
.col-{n}       — column width (1-12)
.mt-{size}     — margin-top (xs, s, m, l, xl)

Always wrap the grid in a full-width <div> to avoid Harmony's default max-width:

<div style={{ width: '100%', maxWidth: 'none', padding: '20px' }}>
  <div className="grid" style={{ width: '100%', maxWidth: 'none' }}>
    <div className="row">
      <div className="col-6">…</div>
      <div className="col-6">…</div>
    </div>
  </div>
</div>

Template Variants

Patient Intake Form (./templates/patient-intake-form.tsx)

Use when: You need a standard two-column intake or registration form with a mix of text, date, checkbox, and select inputs.

Components: Harmony + Panel + Heading + TextInput + DatePicker + Checkbox + Select + Button

Best for: Member intake, patient registration, or first-pass demographic capture.

Member Enrollment Form (./templates/member-enrollment-form.tsx)

Use when: You need a longer, multi-section form with inline validation and conditional fields.

Components: Harmony + Panel + section Headings + field controls + validation state + action buttons

Best for: Enrollment workflows, onboarding, or healthcare forms with grouped demographics, contact, and coverage sections.

Search Filter Bar (./templates/search-filter-bar.tsx)

Use when: You need a compact horizontal filter form for search and reporting views.

Components: Harmony + Panel + TextInput + Select + DatePicker + Button

Best for: Member lookup, claims search, queue filtering, or date-bounded dashboards.

Settings Form (./templates/settings-form.tsx)

Use when: You need a narrow single-column form for preferences or profile-style configuration.

Components: Harmony + Panel + Heading + TextInput + Select + Checkbox + Button

Best for: User settings, notification preferences, or lightweight admin configuration screens.

Usage

• Start from the template closest to the workflow instead of scaffolding from scratch.
• Keep labels explicit and add helper text where medical or coverage terminology may be ambiguous.
• Use full-width wrappers for dense enterprise forms unless the screen is intentionally narrow.
• Add position: relative and a raised zIndex to columns that host popover-based controls like DatePicker.

Templates

• ./templates/patient-intake-form.tsx
• ./templates/member-enrollment-form.tsx
• ./templates/search-filter-bar.tsx
• ./templates/settings-form.tsx

CSS Overrides For Full-Width Layout

Add these to your index.css when Harmony's default container constraints cause partial-width issues:

.harmony-container,
.harmony-panel,
.harmony-grid {
  max-width: none !important;
  width: 100% !important;
}

#root {
  width: 100%;
  min-height: 100vh;
}

Common Pitfalls

Problem	Cause	Fix
Calendar popup hidden behind other elements	Missing z-index on parent column	Add style={{ position: 'relative', zIndex: 2 }}
Form clears on button click	Button has type="submit"	Use type="button" on all non-submit buttons
Form only fills part of viewport	Harmony container max-width	Add CSS overrides above; use maxWidth: 'none' inline
Select not updating	Wrong onChange signature	Use onChange={e => set(e.target.value)}
DatePicker not updating	Wrong onChange signature	DatePicker passes value directly: onChange={setValue}
Checkbox always checked	Using value instead of checked	Use checked={state} prop