Skip to main content

Designing the UI

UI best practices​

  • Use components already available in the system.
  • Use Balsamiq or another lower fidelity tool to ideate
  • If you are working on an existing feature, take a look in the app using demo mode to see how it’s currently working. Figma’s shipped screens are our best examples of how it should look, but there may be some inconsistencies.
  • Consider which screen type to use.
  • Lean on the Design Librarian for support if you aren’t sure where or how to work.

Designing in Figma​

There are a few paths that can be taken when updating existing features or creating new features.

  • Most common: Using existing component(s) with no updates
    • Ideally, we’re using the building blocks we already have when adding new features to the app. If there is an existing component in the library that can be used and does not need to be changed, team members should add the component from the design system's Component Library and/or the VA Mobile App Design Library and avoid detaching it in your working file.
  • Rare: Using existing component(s) with some updates
  • Caution: Making a new component
    • If a design requires a new component, try using Balsamiq, pen and paper, or your favorite low fidelity tool to ideate on ideas.
    • When you’re ready, prep documentation for the component by following how to document components.
    • Once approved, work with the Design Librarian to add it to the library.

Best practices in Figma​

  • Follow the rules around where we work in Figma. Generally, most of your work will be done in the working file for the category your feature is in.
  • Every working file should include a Cover page in your file.
  • In your working file, avoid creating local components unless it is a new component that will ultimately be imported into the Flagship or Component Library.
  • Tagging folks in comments can be a good way to communicate and work async. Try to have longer discussions outside of comments.

Documenting your work​

[TK] - coming up with standards around a11y, design decisions, etc.

Prepping your work for handoff​

Once designs are ready to be handed off to the engineering team, you can review this checklist before handoff to make sure you’ve covered everything that the FE team will need.

Variations​

  1. Determine data organization (e.g. how is a list sorted, does it need filtering, etc)
  2. Create designs with data variations (e.g. examples for lots of data, not much data)
  3. Document and create designs of error states and unhappy paths
  4. Document and create designs of empty states
  5. Consider your design with fonts enlarged or varying screen sizes
  6. Consider dark mode versions of designs
  7. Annotate your design using the VADS Web Annotation Kit.
    • Note: There is a mobile / iOS version of the annotation kit that is still in progress. If you need an annotation that is mobile-specific, you may be able to find it in this kit. If you need something that is not available in either kit, please contact accessibility to determine the best option.

IA/Flows​

  1. Document the IA of your feature & where it lives in the app
  2. Update category screens, if needed
  3. Document intended flow
  4. Defined back labels and screen title

Reviews​

  1. Have a peer review your work
  2. Receive a sign-off from accessibility on the designs and annotations
  3. Receive a sign-off from the content designer on all copy
  4. Review component updates and/or additions with the Design Librarian
    • The Design Librarian will review the updates with the design system team to determine if we will need to coordinate with them on any component updates and/or additions.

Prepping for handoff​

  1. Add Figma links and screenshots of designs (light and dark mode) to appropriate tickets
  2. Create pages for each FE implementation ticket in the working file as outlined in the Figma file workflow
  3. Check with Product about when work will be handed off
  4. Plan to attend a FE handoff meeting to answer any questions

Handing off and following along​

Development Handoff​

  • Team members should expect to do a design walkthrough with engineering as part of the handoff process. In the design walkthrough, team members should be prepared to answer questions related to flow, error/empty states, and design decisions. See prepping your work for handoff above.
  • After the design walkthrough, team members should make any updates to designs, and ensure that appropriate tickets are updated with the intended flow, Figma links, and screenshots.
  • As designs are being implemented by the engineering team, team members should respond to questions (in Slack and/or Zenhub) in a timely manner and communicate with the front-end team (engineers and product manager) to collaborate on refinements.

QA​

  • QA will be QAing AC in tickets throughout the entire development process for a project/feature.
  • Each epic should have visual, interaction, accessibility, and content QA (aka UX QA) completed before release.
  • The exact plan and timing for UX QA can vary across features - you will collaborate with Product and QA to ensure that everyone has the same understanding of what will work best for any given feature. That being said, here are some general guidelines:
    • For large features/features with brand new components, do a round of visual and interaction QA early in development (~when implementation ticket is in PR review).
    • For all features, do visual, interaction, accessibility, and content QA on the 'last needed bug fixes build' for a feature, at the same time that QA is doing their fix verification and regression testing.
    • Use the FE handoff pages in the working file to compare the work.
    • For using real test users/data, see this Slack thread on logging in as a test user.
    • On your testing device, complete a QA of the feature’s happy path.
    • If you need a testing user to reach a particular screen or edge case, you can message a QA engineer in Slack for help.
    • If bugs/issues are found, log a ticket. Here are examples of a UX bug (4009) and a content bug (4121).
  • If you notice that QA engineering is not finding bugs that should have been caught in earlier tickets, let QA know, so they can improve their work.

Launching​

Moving/Publishing Work​

Library updates​

Move work to shipped file​