For designers
Platform Summary
- App is utility-first, “casual, convenient, contextual". It helps Veterans complete actions, not consume content-heavy material. Direct long-form content or research to VA.gov.
- Content is brief and contextual: Keep text short, clear, and actionable. Progressive disclosure is key—avoid over-explaining.
- As required by Rules of Behavior (ROBs), legally required notice must appear in-app as needed (e.g., Overpayments & Copays). Otherwise, direct users to the web.
- Best Practices for platform level features:
- WebView vs Browser—Determine the right modality for your feature before building something new.
- Empty states: Use the pseudo-component consistently. No CTAs, minimal copy, context clues only, no illustrations.
- Accessibility & Compliance: FollowWCAG POUR principles and be 508 compliant. Platform and design system best practices apply.
- Privacy: Homepage anonymizes sensitive info like payments, disability ratings, or other medical information. Detail screens display full content.
Best Practices
1.0 Content Guidance
1.1 Purpose
Ensure in-app copy is actionable, brief, compliant, and consistent with VA Mobile platform principles. Ensure users are able to reach goals regardless of their preferred platform (i.e. mobile app vs. desktop), and that experiences are optimized on a platform-by-platform basis. If someone can't complete a goal or an action in the app then we shouldn't tease them with it, we're focused on making the app as utility focused as possible.
1.2 Principles
- Casual, Convenient, Contextual: Focus on tasks, not information consumption.
- Progressive Disclosure: Give Veterans only what’s necessary at the moment.
- Cross-Platform Adaptation: Mobile copy can differ from Web to match native behaviors, CTAs, and alerts. Data should be consistent across platforms, we identically display quantitative information (ex: times, prescription names, dollar amounts).
- Legal Compliance: Required notices must appear as prescribed by law or VA policy.
1.3 Guidance
- Keep content concise—limit long paragraphs.
- Use clear, simple language—avoid jargon and technical backend references.
- Direct Veterans to VA.gov for research-heavy or content-heavy experiences.
- Maintain privacy—use homepage privacy features as necessary.
Content Categories
| In-App Content | Allowed? | Notes |
|---|---|---|
| Task guidance / instructions | Yes | Short, actionable, use and show contextually |
| Success/failure messaging | Yes | Minimal copy, clear next step |
| Microcopy for clarity | Yes | Supports task completion |
| Confirmation states | Yes | Keep concise |
| Eligibility criteria | Yes | Short, actionable only |
| Legal notices | Yes | Must follow prescribed wording |
| Deep content | No | Use VA.gov, WebView as needed |
| Complex forms | No | Use VA.gov, WebView as needed |
| Long informational text* | No | Use VA.gov, browser preferred |
*Legally required informational text is an exception to this rule. If you’re unsure if your copy meets this specification you can reach out to us via Slack or our attend a Design Critique to get clarity.
2.0 WebView vs Browser
2.1 Purpose
Maintain continuity, security, and task completion across authenticated and public flows. Also see: Rules for Determining UX Modality.
2.2 Principles
- Authenticated flows → WebView: Required for IAL2 secure experiences. Supports pre-filled forms, contextual content, and in-app continuity.
- Public / content-heavy flows → Browser: Better accessibility, larger content, and full native customization via mobile OS level settings.
- Avoid switching channels mid-task, limit tasks to one to two channels max. Do: App → WebView → App. Don’t: Native → WebView → Browser → App, can introduce friction and accessibility issues for some users.
2.3 Guidance
| Scenario | Destination | Notes |
|---|---|---|
| Requires authentication | WebView | Use native OS login & 2FA tools to minimize friction |
| Pre-filled, task-oriented flow | WebView | Keep Veteran in app context |
| Public content | Browser | Ideal for content-heavy pages, legal documents, or complex flows |
| Complex forms | Browser | Supports accessibility and proper UI |
| Not available in-app (VR&E, Mortgage, etc.) | Browser | Default for unsupported features |
3.0 Empty State Guidance
3.1 Purpose
Provide context, reassurance, and psychological safety when there’s no content to display.
3.2 Principles
- Show that content might exist, but currently there isn’t any.
- All systems are functioning correctly; no error implied.
- Context clues explain why the screen is empty (offline, no messages, no appointments).
3.3 Empty State Component
- Minimal layout
- One-line headline
- One-line description
- No CTAs
- No illustrations
- Follows VA copy standards
3.4 Use Cases
| Empty State Type | Allowed? | Notes |
|---|---|---|
| Zero state | Yes | First-time use; no data yet |
| Cleared state | Yes | List emptied after user action |
| No results | Yes | Search/filter empty |
| Contextual | Yes | e.g., “No upcoming appointments” |
| Permission state | No | Do not expose backend systems; redirect to support |
3.5 Copy Rules
- Brief, factual, informative.
- Avoid apologetic tone and technical jargon.
- Progressive disclosure for additional context, outside component if needed (i.e. redirecting users to a tangential experience or leveraging progressive disclosure).
3.0.1 Migration Guide & Decision Tree: Empty States
Goal: Programmatically standardize existing empty states to use Forms MVP component. Steps for XP teams:
- Identify all current empty states.
- Classify type (Zero, Cleared, No Results, Contextual).
- Replace with Forms MVP component.
- Verify copy adheres to VA standards.
- Ensure no CTAs or illustrations.
- Test accessibility and screen-reader experience.
- Get final sign-off from Ryan on UX and final PR sign-off before merging.
4.0 Glossary & Keywords
- Progressive disclosure: Revealing information as needed.
- IA2 / IAL2: Authentication level 2, secure login.
- Forms MVP: Standard empty state pseudo-component.
- Skeleton state: Visual placeholder for future content.
- WebView: In-app browser supporting authenticated flows.
- Browser: External system browser for public or content-heavy flows.
Documentation and resources
Working with the design system
The VA Mobile Design System is the VA Mobile App’s front-end framework. Before getting started, we recommend that you get familiar with the VA Mobile Design System and how you can use it as part of your design process. Each section includes some helpful information:
- Components. Components are the building blocks of the user interfaces. For example, accordions and buttons. Some of these have strict usage guidelines, so please become familiar with them.
Referencing the VA.gov design system
The VA Mobile Design System is an extension of the VA.gov Design System. Additional guidance can be found in each section:
- Content. Our house style guide for VA.gov. Follow the guidelines to help you create a consistent, helpful experience for Veterans.
- Foundation. This section explains VA.gov’s base styles and visual language.
- Patterns. Patterns define how components, content strategy, information architecture, accessibility, and visual design work in tandem to solve Veterans’ needs. Here you will find patterns to ask users for specific pieces of information and how to help a user to complete a task or interaction.
- Templates. Templates, or page layouts, are composed of components within a single page. A layout can contain multiple variations of a component depending on the context.
Design resources
The website displays examples of the various components and patterns in use in the VA Mobile App. You can use your browser’s web inspector to view the specs for each component.
The Design System team also provides a complete Figma library of core components.
Design libraries
The Design System team provides Figma libraries for use by teams.
Add a library to your project
Use libraries to access all design tokens, icons, and components. In Figma, libraries live in the cloud. Thus you do not need to download a library. The Design System team updates the libraries in order to keep it in sync with the va-mobile-library code which contains our React Native web components.
To access and enable the Design Tokens, Icon Library, or Component Library, follow these steps:
- In the Figma menu bar, navigate to Figma > Libraries to open the Libraries modal
- In the modal, find the library file
- Click the “Add to file” button to add the library to your file
Once you’ve loaded the library, you should be able to access everything in it by navigating to Assets > "library file" or Resources > Components > "library file". Note that you cannot edit a library directly. The Design System team manages libraries.
Figma
VA mobile app design teams use Figma to view, share, and collaborate on our work. If you're working on an external Experience Team and need access to our files, you can follow the steps below to be added as a Viewer.
Get added to Figma
- Go to figma.com and create a Figma account
- In the #va-mobile-app-shared-systems channel in Slack, ping a Figma admin.
- Receive the invite via email and accept the invitation.
- Boom, you’re in!
Using Figma
Figma contains a few important features that help teams work together:
- Files (including libraries) live in the cloud, rather than locally on your machine
- You receive library updates automatically (a big advantage of using Figma)
- You can see what everyone else is working on in the VA workspace
- Developers can inspect any element on a page
- You can create a branch of your file at any time
Designers on Experience Teams
Currently, designers on Experience Teams can only be added as Viewers in the VA Mobile App's Figma account. In order to use the Mobile App libraries in the VA.gov Platform team's Figma account, designers should follow the steps below.
- In the VA Mobile App team's Figma account, open the Component Library and/or Flagship Library.
- Find the component you need.
- Copy the component.
- In the VA.gov Platform team's Figma account, open your working file.
- Paste the component into your working file.
If you have questions or need assistance, reach out in the #va-mobile-app-shared-systems channel.
Design Critique Overview & Sign-Up
Design Critique is a collaborative session for sharing in-progress work, exploring ideas, and gathering peer feedback to strengthen design direction, make sure we’re asking and answering the right questions, and ensure usability early on.
Sign up
Use these booking links to schedule time:
- Regularly scheduled (Mondays, Thursdays, and every other Fridays)
- Ad hoc session (As needed, impromptu sessions)
When to Attend
Go to a Design Critique when...
- You’re exploring multiple design directions or…
- You’re testing early hypotheses or low-fidelity wireframes…
- You want to identify risks, gaps, or alternative ideas early.
Tip: One critique leading to one review is the ideal agile flow. When in doubt default to attending critique more often than not and bringing a design multiple times, Design Reviews on the other hand should be a “close to final” step only.
Meeting schedule
Meetings are held up to three times a week. If you’re a member of #va-mobile-app-design, you should receive an automated reminder 15 minutes before each session. A MS Teams join link is included in the reminder.
- Mondays at 08:05AM PT
- Thursdays at 08:05AM PT
- Fridays, biweekly, at 10:05AM PT
- (For 2025, ISO weeks ending in an even number have a session, i.e. W44, W46, etc.)
How to Prepare
- Provide context...
- Be ready to share the problem, user goals, and your hypotheses
- Bring design artifacts...
- Share lo-fi designs or prototypes, don’t over-polish. Overall experience and content should be taken care of before interface decisions are made.
- Be ready to answer questions...
- What do users need to do, what the core function of your new or updated feature(s), what is the full workflow?
- Where will your feature lives in the app? How does this impact navigation, how did you make this decision?
- How will the feature work in dark mode or offline, have you considered mobile constraints or differences?
- Be ready to ask focused questions...
- “Does this flow make sense given in a Mobile context, are there any constraints?”
- “What might we need to change to make this pattern accessible in React Native?”
Desired Outcomes
- Constructive peer and PO level feedback to improve design quality.
- Identified next steps or experiments to validate direction.
Follow up
- Capture feedback—Record notes, decisions, and key insights (async for those who missed it). For critique you can do this via Slack, FigJam, Figma, etc—this is informal and the modality is up to you to decide.
- Prioritize next steps—Not all feedback is equal. Align on what to implement, once aligned Product should post updates to GitHub and update issues, AC and/or Reqs, as needed. For critiques this means talking with your Development and Product team, building context, and aligning on what to do next.
- Close the loop—Designer should make and share updates back to the team in the next session or async post to Slack or GitHub based on your teams communication norms.