Components
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
- 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
- Colors: The tag color options will match semantic color meanings with alerts decided in ADR 001.
- Spacing and size: The size and the spacing of the tags will remain the same as the current tag already in the VADS.
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.- 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
- 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
- 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
- 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
- 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
- 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