Tag - 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 - Define the meaning for colored tags

• Date raised: February 25, 2025
• Decision date: April 8, 2025

Context

An experimental design request was submitted and approved by the Design System Council to add different color variations for the tag component. One of the main concerns raised was addressing the colors that would be added so that each color has specific meaning and intent. A discovery was conducted to audit the existing use of color in the design system, review how other design systems were using color, and make sure the colors aligned to our current use of color in the design system.

Decision

We will only apply colors to tags that align with the current alert color meanings in the VA Design System:

• Status (Default): Used to show the status of a process.
• Informational: Used to provide helpful information or something that warrants a user’s attention. Not used for negative consequences.
• Success: Used to indicate success.
• Warning: Used to warn a user, such as when there are negative consequences, or when something has gone wrong.
• Error: Used when there is a problem or something destructive is about to occur.

Consequences

Applying colors to tags can introduce a few different interaction issues that will need testing:

• Colors can make tags look more like buttons.
• Making sure the colors are applied appropriately can be challenging. Guidance will need to be added and tied to alerts.
• Color can communicate a priority when we don’t mean it to.

ADR 002 - Tag styles

Superseded by ADR 012, which redesigned the visual treatment of the va-tag-status.

• Date raised: December 5, 2025
• Decision date: May 25, 2025

Context

Tags can come in a variety of styles and we needed to finalize a final design for the colored tag options. Several different design routes were considered, including the original experimental design (with borders and varied sizes) and the mobile design (with large border radius and a border).

Decision

1. Colors: The tag color options will match semantic color meanings with alerts decided in ADR 001.
2. Spacing and size: The size and the spacing of the tags will remain the same as the current tag already in the VADS.
3. Border: Both the mobile and the experimental design included borders, but looking at the mockups with tags in context, we decided that the border makes the tags look more like buttons. So to avoid any confusion with buttons we will be removing the border.
4. Icon: To make the tags accessible we need to make sure that color is not the only way that the tag conveys status. We will include the same icon used in the alert to convey the meaning of the tag beyond color.

Consequences

Currently, we only have a single tag color. Going forward we will have a variety of options for teams to choose depending on the status of the tag. It is challenging to foresee all the different ways the tags will be used. This could have consequences if the colored tags options are used in ways we did not account for.

ADR 003 - Accessible colors

Superseded by ADR 012, which redesigned the visual treatment of the va-tag-status.

• Date raised: May 25, 2025

Context

The tag background must meet 3:1 color contrast against the page background.

• The colored background of the tag carries semantic meaning (warning, error, success) and is not decorative, so it functions as a “graphical object” under WCAG.
• WCAG 1.4.11 (non-text contrast) sets a minimum 3:1 contrast between any meaningful graphical element and its adjacent background so that users with low vision can reliably perceive the shape and color cue.
• USWDS also recommends 3:1 contrast on tags.

Decision

The team recommends adding a border to the tag to achieve the 3:1 ratio contrast. The other option is to use a solid color that creates the 3:1 ratio.

Consequences

Adding a border may make the tags look like buttons. Usability testing would help us understand if users think these are buttons.

See ADR 006 for the resolution of this decision.

ADR 004 - Uppercase text

Superseded by ADR 008, which reversed this decision, and changes all status tags to use Sentence case text.

• Date raised: May 25, 2025

Context

During a tag usage audit, we identified teams using tags with sentence case instead of the standard uppercase format. Teams cited improved readability and accessibility as their primary motivations for this deviation.

Tags with uppercase are a good choice for:

• Visually distinguishing tags from buttons
• Drawing attention to the tag to make them more noticeable and easily scannable

Tags with uppercase are not a good choice for:

• Long strings of text because it reduces readability and can harm accessibility
• When the tone should be conversational or friendly

Decision

Maintain alignment with USWDS tag component standards by continuing to use uppercase text for tags. This approach preserves design system consistency and alignment with the USWDS tag component while leveraging the functional benefits of uppercase formatting for short-form, categorical content.

Consequences

• Current tag implementation may not accommodate all existing use cases optimally
• Some teams may need to evaluate whether tags are the appropriate component for their specific content needs

See ADR 006 for the superseding decision on case.

ADR 005 - Icon size update

Superseded by ADR 012, which redesigned the visual treatment of the va-tag-status.

• Date raised: October 2, 2025
• Decision date: October 2, 2025

Context

Originally, the icon size was going to match the font size (16.96px) for consistency. However, the smallest token size in USWDS is 24px, and designers identified that a larger size would improve legibility and better align with the design system.

Decision

Increase the icon size for status tags to 24px × 24px.

Consequences

• Positive: Improved legibility and alignment with USWDS token standards
• Negative: The new icons increase the overall size of the tag, making them more prominent, which may be too much for some use cases
• Risks: Minimal; potential layout adjustments may be required in tight spaces

ADR 006 - Tag color alignment

Superseded by ADR 012, which redesigned the visual treatment of the va-tag-status.

• Date raised: October 2, 2025
• Decision date: October 2, 2025

Context

The original plan was to align tag colors with Alert component colors. During review, the team discovered that the mobile team is creating a “blue sky” version of status tags with a different palette. Aligning with mobile ensures cross-platform consistency.

Decision

Update tag colors to align with the mobile blue sky status tag palette.

Consequences

• Positive: Visual consistency across web and mobile platforms; alignment with ongoing mobile design efforts
• Negative: Divergence from alert colors may reduce direct color association with alert messages. The new palette is darker and more solid, which may make tags look like buttons and potentially confuse users
• Risks: Moderate; if users attempt to click tags as buttons, we may need to revisit color choices

ADR 007 - Text weight

Superseded by ADR 012, which redesigned the visual treatment of the va-tag-status.

• Date raised: October 2, 2025
• Decision date: October 2, 2025

Context

The mobile blue sky designs used a semibold font weight, which is not supported in our type system. Readability was a concern for smaller status tags.

Decision

Use bold font for all status tag text.

Consequences

• Positive: Improves readability and provides a close match to the intended semibold weight
• Negative: Bold text may appear slightly heavier than intended, but impact is minimal
• Risks: Combined with darker colors, bold text might feel visually heavy in some use cases

ADR 008 - Sentence case

• Date raised: October 2, 2025
• Decision date: October 2, 2025

Context

Some tags may be longer than 1–2 words. Using all caps or title case reduces readability and scanability for longer text.

Decision

Adopt sentence case for all status tag text.

Consequences

• Positive: Easier to read and scan, especially for longer phrases
• Negative: Inconsistent with other components that may use all caps for emphasis (the original tag component)
• Risks: Users may perceive sentence case as less “badge-like” compared to all caps

ADR 009 - Warning tag color

• Date raised: October 2, 2025
• Decision date: October 2, 2025

Context

All status tags were originally mapped to the alert color token scale. However, the warning tag needed special consideration to avoid confusion when used with the Critical Action component.

Decision

Map the warning status tag to the critical alert color token.

Consequences

• Positive: Ensures visual and semantic cohesion between Critical Action alerts and status tags when displayed together
• Negative: Creates a strong connection between the Critical Action and the status tag that may not be desirable in all situations
• Risks: Potential confusion if users expect warning and critical states to remain visually distinct

ADR 010 - Dark mode

• Date raised: October 10, 2025
• Decision date: October 14, 2025

Context

The current Status Tag component designs are optimized for light mode only, with semantic colors chosen for visibility and WCAG contrast compliance on light backgrounds. To be fully integrated as a Mobile app component we would need to add color options for dark mode.

There is ongoing discovery work to merge the mobile app and the VADS tokens into a single place for cohesive colors between the two platforms.

Decision

Defer implementation of dark mode support until the tokens for Mobile app and web have been completed. This will prevent duplication of work and create a more cohesive and consistent color experience when the color combinations can be looked at as a whole.

Consequences

• Positive: Ensures visual and semantic cohesion between the mobile app and web
• Negative: The mobile app might need to use the Status Tags before dark mode can be implemented, causing visual differences
• Risks: Potential divergence if dark mode can’t be implemented in time

ADR 011 - Neutral status

Date Accepted: August 2026

Context

The existing status tag options (informational, warning, success, error) all convey urgency or meaning. Teams needed a status for states that don’t need that level of attention, like an inactive or default state.

Decision

Add a Neutral status option using a gray color palette. Documentation guidance uses the default. Screen readers will announce the status as “Info”, same as the Info status tag.

Consequences

• Positive: Gives teams an option for status states that don’t need the visual weight of the other semantic colors
• Negative: A neutral status should be used in rare occasions so it might add more complexity to when you would use it.
• Risks: Initially we didn’t not create a ‘default’ tag as it conflicts the base tag component and doesn’t align with currently defined semantic meanings. Teams should really scrutinize if a neutral status is right for their product.

ADR 012 - Status tag redesign

• Date accepted: August 2026

Context

As part of a Tiger Team initiative in the summer of 2026, the va-tag-status component was redesigned by an outside team.

This update aligns with their other redesign efforts including:

• Lighter colors
• Rounded corners
• Smaller fonts
• Smaller icons

Decision

This change has been approved as part of a Tiger Team initiative in the summer of 2026.

You can see all of the diffs in this PR

Consequences

• Positive: Because this is an existing component, teams will get these updates for free from the component lilbrary.
• Negative:
• Risks: The new design departs from intentional decisions made in the original design, including rounded corners and a smaller icon size. The rationale for those decisions is documented in previous ADRs. Once the redesigned VA.gov authenticated experience launches, we will need to evaluate whether these changes introduce confusion or other usability issues for Veterans.

ADR 013 - Font size and big variant

This decision applies to both the va-tag and va-tag-status components.

• Date raised: September 2, 2026
• Decision date: September 14, 2026

Context

ADR 012 set the va-tag-status font size to --vads-font-size-sm (15px) as part of the summer 2026 Tiger Team redesign, following Kaizen’s documentation at the time. Matt Dingee later instructed the Kaizen team not to use font sizes smaller than the base size (16px), and to use font sizes smaller than base very sparingly. On September 14, 2026, direction changed again: the team decided to keep the default font size at --vads-font-size-sm to align with the U.S. Web Design System (USWDS) Tag component, and to follow USWDS’s lead by adding a big variant instead.

Decision

1. Keep the default font size for va-tag and va-tag-status at --vads-font-size-sm, aligning with USWDS.
2. Add a big variant (matching USWDS’s usa-tag--big modifier) that uses the base body font size, --vads-font-size-body-default.
3. Guidance: Use the big variant when a tag communicates a page-level status or label. Use the default size when a tag appears inline, within a container like a Card, or when multiple tags appear on the same page.

Consequences

• Positive: Aligns va-tag and va-tag-status with USWDS conventions, giving teams a way to increase visual weight for page-level tags without changing the default, more compact size used in lists, tables, and cards.
• Negative: Introduces a second size option that teams need to choose between, adding a small amount of decision-making overhead.