Contributing to the Clinical Design System

Overview

Clinical decision support teams are expected, whenever possible, to use the VA Clinical Design System components, patterns, tokens, and utility classes that are published in this documentation site and Storybook. This allows for efficient design and coding practices while maintaining consistency of the user experience.

If existing components or patterns will not work to address needs, teams should contribute new components, patterns, or revisions to existing by going through the process outlined below.

This process works best if started during the design phase so all teams impacted including the Clinical Design System can plan for the work. Anyone can contribute code, design, and documentation. Collaboration from teams is what makes the Clinical Design System great!

Bug severity scale

P0 — Critical

Definition

Breaks clinical workflow or introduces risk to patient safety. Violates accessibility compliance at P0 or P1 level. No workaround exists. Must be hotfixed immediately.

Examples

Header component fails to load patient context
Form input is not accessible by keyboard
Issue prevents clinicians from completing a CDS task, and there is no work around available
Security vulnerability ranked as critical or high
Any defect that causes significant data loss or exposes PII
Core feature regression that blocks use of a production system

Turnaround

ASAP (current release) — requires immediate action due to impact on clinical workflow, patient safety, or blocking functionality.

Release expectation: Hotfix in current release.

Expectations

DS team investigates immediately
App team may roll back or hotfix
- A follow-up ticket is opened to review the hotfix with the contributing team. If additional design or functionality needs are found, new tickets will be created; otherwise, the ticket is closed.
Contribute a PR if possible

P1 — High

Definition

Breaks a primary function or core design system use case, possibly with limited or no workaround. Impacts production apps or major workflows.

Examples

Focus lost when activating a button with keyboard
Core token mismatch causing unreadable text
Prevents upgrade of shared libraries (e.g., React)
Security vulnerability ranked as medium
Accessibility defect causing a major barrier but not full block

Turnaround

Within 1 sprint (not to exceed 2 sprints) — urgent, should not roll into long-term backlog.

Release expectation: Off-cycle or next scheduled release.

Expectations

Teams collaborate to determine fix timing
Workarounds explored while fix is in progress
Provide PR if capacity allows

P2 — Medium

Definition

Noticeable issue with a clear workaround; causes UX inconsistency or degraded experience but does not block workflow.

Examples

Incorrect padding or spacing on a common component
Minor color contrast deviation from threshold
Workaround available but adds rework or delays
Security vulnerability ranked as low

Turnaround

2+ sprints — scheduled in a future sprint or release window.

Release expectation: Addressed in upcoming planned release.

Expectations

Workaround used while fix is scheduled
Teams may choose to contribute fix via PR

P3 — Low

Definition

Cosmetic or minor performance issue that does not affect functionality or trust. Fix can wait for a future release.

Examples

Alignment off by a few pixels
Outdated documentation example
Minor visual inconsistencies not affecting usability

Turnaround

Backlog / Future Consideration — addressed during backlog grooming or maintenance cycles.

Release expectation: Included in maintenance or minor version release.

Expectations

No immediate fix required
Track for inclusion in future maintenance work

Accessibility and security note

Accessibility issues follow the 508 rubric and are mapped to this same scale:

P0–P1 for blocking or severe violations
P2 for moderate impact with workaround
P3 for minor or cosmetic issues

Security vulnerabilities should be triaged by severity (critical → low) to match the same prioritization.

Bug severity scale — table version

Severity	Definition	Examples	Turnaround & Release Expectation	Expectations
P0 — Critical	Breaks clinical workflow or introduces risk to patient safety. Violates accessibility compliance at P0 or P1 level. No workaround exists.	Header component fails to load patient context; Security vulnerability critical/high; Loss of patient data.	ASAP (current release) — Hotfix required.	Investigate immediately; Rollback or hotfix; Contribute PR.
P1 — High	Breaks a primary function or core design system use; limited / no workaround. Impacts production apps.	Focus lost with keyboard; Core token mismatch; Security vulnerability medium.	Within 1 sprint (not to exceed 2) — Off-cycle or next scheduled release.	Collaborate on fix timing; Explore workaround; Contribute PR if possible.
P2 — Medium	Noticeable issue with workaround; UX inconsistency but not blocking.	Padding / spacing off; Minor color contrast issue; Security vulnerability low.	2+ sprints — Planned future release.	Use workaround; Contribute PR optional.
P3 — Low	Cosmetic or minor issue; no impact on usability.	2 px alignment issue; Outdated doc example.	Backlog / Future Consideration — Planned future release.	No immediate fix required; Track for backlog.

Have questions?

After you’ve reviewed all of the above and still have a question, sign up for design office hours on Tuesdays or dev office hours on Thursdays, after your issue has been added. The Clinical Design System team can guide you in your contribution and your question may help improve the guidance on this page.