Card - Status - Design decisions

What is an ADR?

We use the ADR (Architecture Decision Record) to structure design decision documentation. Each ADR covers three things: the context that prompted the decision, the decision itself, and its consequences — including trade-offs and any open questions.

ADR 001 - Cards will not support success, warning, or info states

• Date raised: July 17, 2025
• Decision date: July 17, 2025

Context

Many design system components support multiple status states (warning, error, success, and info) that operate similarly to communicate various conditions to users.

Decision

We have decided to limit card status indicators to only the error state. Other status states are not being considered at this time and are not planned for the immediate future.

Consequences

• Teams that want to communicate success, warning, or info states will need to use alternative approaches
• When error states are resolved, teams cannot show a success state directly on the card
• Teams are encouraged to use other alert components in combination with cards to communicate non-error states

ADR 002 - User must be able to resolve the error

• Date raised: July 17, 2025
• Decision date: August 4, 2025

Context

Cards sometimes represent errors caused by API failures or system issues that users cannot directly correct. We want to reserve the card error state specifically for errors that users can take action to resolve.

Decision

Cards displaying an error state must include a visible secondary action link that allows users to correct the error. This action link must be present in all card states (missing, error, and default). The link text may change contextually (for example, from Add to Edit).

Consequences

• Error state cards will always provide users with a clear path to resolution
• Since users need to navigate to a different page to fix the error, the corrective action uses a link element rather than a button
• System-generated errors that users cannot resolve should use different UI patterns

ADR 003 - New Status tag will be used for launch

• Date raised: July 31, 2025
• Decision date: August 4, 2025
• Decision revised: October 16, 2025

Context

The experimental design request specified using a colored tag for the error state. However, colored tags are now available in the VA Design System.

Decision

We will implement the card status using the new status tag style.

Consequences

The status tag is a new component not used by teams at this point. There could be some regressions in the card due to the new tag.

ADR 004 - The error message will be attached to the link when in error mode

• Date raised: July 31, 2025
• Decision date: August 4, 2025
• Decision revised: September 12, 2025

Context

When users tab away from a card in an error state and then return to it via keyboard navigation, we want to ensure they’re still aware that an error needs to be resolved.

Decision

Users will be able to know that there’s an error when they encounter the link.

Accessibility implementation:

Pages containing cards typically do not include form fields (such as text inputs, select menus, or checkboxes).

To ensure error states remain discoverable and perceivable in Browse Mode:

• Error announcements: Error messages use role="alert" to trigger immediate screen reader announcements
• Programmatic associations: Cards use aria-labelledby and aria-describedby to connect headings with error messages
• Semantic structure: Headings inside cards use semantic <h2> tags, enabling navigation via heading shortcuts

This approach ensures screen reader users receive the same information and interaction cues as visual users.

ADR 005 - Existing card will be moved to legacy state in Figma

• Date raised: August 4, 2025
• Decision date: August 6, 2025
• Decision changed: October 16, 2025

Context

To add an error state to the Figma card component, we have two options:

1. Duplicate the existing component structure (preserving legacy design patterns)
2. Issue a new version that improves the component’s construction for future maintenance

Decision

We will issue a new version of the card component to better align with the coded implementation. This involves:

1. Separated concerns: The new card component will have four visual style variants (default border, default error, background, drop shadow)
2. Flexible content: Card content will be either prebuilt options or a flexible option for teams to add custom content

Currently, the component combines content and visual style into single variants. We are separating these concerns to create a more maintainable structure.

We will maintain and support the current card component by renaming it to “Card - Legacy”.

Implementation plan: - Legacy preservation: The current card component will be renamed to “Card - Legacy”

• New default: The improved card component will use the standard “Card” name
• Opt-in adoption: Teams can choose when to migrate to the new design structure
• Error state requirement: Teams wanting to use error states must adopt the new component design

Consequences

• Breaking changes: Teams updating to the new component structure will lose any existing customizations
• Migration effort: Teams will need to plan for updating their card implementations
• Improved maintainability: The separated structure will be easier to maintain and extend
• Communication needed: We need to determine how and when to communicate this change to teams

Open Questions

• How should we communicate this change to affected teams? The current card will be renamed to Card - Legacy.
• Do we want to eventually deprecate the legacy version?

ADR 006 - Card error state component will become Card status

• Date raised: August 31, 2025
• Decision date: October 16, 2025

Context

After discussions with DST Engineers, we realized we should just build the card status as a variant that supports an error state. We have many card statuses across VA.gov.

Decision

We can build a card status variant based on the work done here. Card statuses need a headline and body copy, at a minimum. Items supporting an error state need a tag, an error message, and a link to resolve the error.

A was started and teams were invited to contribute. As of September 12, 2025 no one has.

Consequences

A consequence could be building a status card component that is too restrictive for teams.

ADR 007 - Card status MVP

• Date raised: September 25, 2025
• Decision date: September 25, 2025

Context

In the team’s attempt to make sure any and all possible card status variants could be handled by the first version of this card status, we started churning a bit, and feeling like we would need to account for every possibility.

Decision

Much like the service list item component was created for a specific and limited use case, we can create the new card status variant to meet our initial needs here. To help with this, wireframes were created to help us focus on the elements of a status card.

Consequences

A consequence could be building a status card component that is too restrictive for teams. But, as we can tell for now, this should meet most current use cases. We can expand later.

ADR 008 - Card status will use the action link

• Date raised: January 12, 2026
• Decision date: January 12, 2026

Context

The original design of the card status from the AEDP team used the active link. It was updated to use the action link.

Decision

We will use the action link, not the active link. The link is a call to action, or the primary action the user needs to take. Because we may have multiple cards with primary action links in it, we will use the secondary action link. The active link is used in a collection of links (in this case it’s a collection of cards, not links). We will use the primary action link.

Consequences

Need to make sure we update screenshots in Figma to reflect the new design.

ADR 009 - Card status links will be verbose

• Date raised: January 12, 2026
• Decision date: January 12, 2026

Context

For accessibility reasons, we want to not use as much hidden sr-text, and make sure our link text is as visibly descriptive as we make it for screen reader users. This means that the text links will not just display “Add” or “Edit”, but instead it will say “Add [the thing]” or “Edit [the thing]”.

Decision

We will do this, and it will be written into guidance.

Consequences

The component will not support adding an accessible name to the link. aria-describedby however will be used to manage the error message announcement when the card goes into an error state.