Merge pull request #9240 from department-of-veterans-affairs/update-u…

…x-how-we-work-doc

Updates to UX team's "How We Work" pages

VAMobile/documentation/docs/UX/How-We-Work/building-screens-figma.md

@@ -10,10 +10,10 @@ sidebar_position: 6
 ## Step 1: Create your frame
 
 1. Create a frame at 360 x 760.
-2. In the assets panel, search “template” and drag the appropriate template (home, health, benefits, payments) into the frame.
-3. After adding the template to the frame, you can then select that template layer, which will give you options in the design panel on the right-hand side of the screen. In this panel, you can select the sub-template (feature, subtask, etc.).
+2. In the assets panel, search “template” and drag the template into the frame.
+3. After adding the template to the frame, you can then select that template layer, which will give you options in the design panel on the right-hand side of the screen. In this panel, you can select the category (home, health, benefits, payments) and template type (feature, subtask, etc.).
 
-![Screenshot of the design panel in Figma](/img/figma/design-panel.png)
+![Screenshot of the design panel in Figma](/img/figma/figma-screen-template-properties.png)
 
 ## Step 2: Add your content
 
@@ -32,10 +32,13 @@ _Note: You can always go back and make changes to the content component that you
 
 After you’ve created all of the shipped screens in light mode, you may need to create dark mode versions of your screens. 
 
-1. To create dark mode versions, select all of your light mode layers and duplicate them (on Mac, you can hold down options and click + drag to duplicate). _We recommend visually grouping light mode versions together and dark mode versions together._
+1. To create dark mode versions, select all of your light mode layers and duplicate them (on Mac, you can hold down option and click + drag to duplicate). _We recommend visually grouping light mode versions together and dark mode versions together._
 2. We recommend adding light and/or dark mode to each of your frame names within your shipped file. For example, you may name one of your light mode frames “Profile / Landing / Light” and the dark mode frames  “Profile / Landing / Dark”.
-3. After you have duplicated your light mode versions, you’ll need to change the color mode. You can adjust the mode by selecting the template layer within each dark mode frame and selecting “dark” from the Mode option in the design panel on the right-hand side.
-4. You will also need to update each of your components within your content area to dark mode. The easiest way to do this is to select each component layer within the “Layers” panel on the left (you may have to click the option to “See All Layers”). You’ll want to look for the “Content” layer and may have to go several layers deep within this layer to find your individual component layers. Then, select “Dark” in the mode area within the design panel. 
+3. After you have duplicated your light mode versions, you’ll need to change the color mode. You can adjust the mode by clicking the change variable mode icon and switching each library to "Dark" (see screenshot below).
+
+![Change variable mode icon in Figma](/img/figma/figma-change-variable-mode-icon.png)
+
+4. You may also need to update some of your components within your content area to dark mode. The easiest way to do this is to select each component layer within the “Layers” panel on the left (you may have to click the option to “See All Layers”). You’ll want to look for the “Content” layer and may have to go several layers deep within this layer to find your individual component layers. Then, select “Dark” in the mode area within the design panel. 
     1. Figma is not without glitches and will sometimes return your component to its default settings when switching the color mode. When this happens, sometimes resetting the component will fix it. You can do this by clicking the icon with 3 dots (“...”) in the design panel. Click the icon and select “Reset all changes” (see screenshot below). If this doesn’t work, you may have to update each component manually.
 	2. When using the “Text Area” and “Default List” components, you may have to update each row within the component to dark mode vs. updating the entire component at one time. This will often prevent the content from restoring to default.
 

VAMobile/documentation/docs/UX/How-We-Work/designing-ui.md

@@ -5,7 +5,7 @@ sidebar_position: 3
 
 ## UI best practices
 
-- **Use [components](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/ComponentsSection/) already available** in the system.
+- **Use [components](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/Flagship%20design%20library/Components/Overview) already available** in the system.
 - Use [Balsamiq](https://balsamiq.cloud/s4uw4la/pnnwuqv) 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](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/Flagship%20design%20library/Templates/ScreenTypes) to use.
@@ -17,25 +17,21 @@ sidebar_position: 3
 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 [VA Mobile App Design Library](https://www.figma.com/file/QVLPB3eOunmKrgQOuOt0SU/VA-Mobile-Design-Library?node-id=1028%3A3927) and** avoid detaching it in your working file**.
+    - 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](https://www.figma.com/design/Zzt8z60hCtdEzXx2GFWghH/%F0%9F%93%90-Component-Library---Design-System---VA-Mobile?m=auto&node-id=0-1&t=eKUAt5IA4XlJEuk5-1) and/or the [VA Mobile App Design Library](https://www.figma.com/file/QVLPB3eOunmKrgQOuOt0SU/VA-Mobile-Design-Library?node-id=1028%3A3927) and** avoid detaching it in your working file**.
 - **Rare: Using existing component(s) with some updates**
     - If you believe the existing component needs to be changed, add the component from the [VA Mobile App Design Library](https://www.figma.com/file/QVLPB3eOunmKrgQOuOt0SU/VA-Mobile-Design-Library?node-id=1028%3A3927) and **detach it for ideation**.
-        - If components have been changed, have them reviewed by the [Component Committee](https://docs.google.com/document/d/1rgNpTvUjZR6E2Z6vfSrxLxvXt7Zxq1Jq6kw6TCDJbBk/edit?pli=1#bookmark=id.pv64bxlp7e6c) before finalizing your design.
         - Once approved, work with the [Design Librarian](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/How-We-Work/design-librarian/) to add it to the library.
 - **Caution: Making a new component**
     - If a design requires a new component, try using [Balsamiq](https://docs.google.com/document/d/1rgNpTvUjZR6E2Z6vfSrxLxvXt7Zxq1Jq6kw6TCDJbBk/edit?pli=1#heading=h.7jcyyrw27o8y), 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](https://docs.google.com/document/d/1pC-Pyc_HDZMtHb17XRND_57u7H8I3IDATUDGgGxFZAg/edit#heading=h.iwlf7nqnidb).
-    - You will be invited to a meeting and will review the component and the documentation with the Component Committee. _Note: These do not have to be high fidelity designs._
+    - When you’re ready, prep documentation for the component by following [how to document components](https://department-of-veterans-affairs.github.io/va-mobile-app/design/About/Contributing%20to%20the%20design%20system/writing-component-documentation).
     - Once approved, work with the [Design Librarian](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/How-We-Work/design-librarian/) to add it to the library.
 
 
 ### Best practices in Figma
 
-- Follow the rules around [where we work in Figma](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/How-We-Work/where-we-work#ui-library-and-feature-designs---figma). Generally, most of your work will be done in the [working file](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/How-We-Work/where-we-work#categoryname) for the category your feature is in.
- When starting a new feature, work with the [Design Librarian](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/How-We-Work/design-librarian/) to create a new working file.
-- Every working file should include a **Cover** and **Readme** page in your file.
-    - Readme page orients people to your file and the work in general. It should contain project info, important links, team members, etc.
-- In your working file, **avoid creating local components**.
+- Follow the rules around [where we work in Figma](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/How-We-Work/where-we-work). 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
@@ -45,68 +41,76 @@ There are a few paths that can be taken when updating existing features or creat
 
 ## 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 the FE team will need.
+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](https://www.figma.com/design/CZcnWfQOwtLqPm4WA5paYG/VADS-Web-Annotation-Kit?node-id=415-1135&t=AA1kuENFcAY6o5JH-1).
+    - _Note: There is a [mobile / iOS version of the annotation kit](https://www.figma.com/design/MWuEixKG2VG90fBwqSBvZS/TESTING---VADS-iOS-Annotation-Kit?t=XiMx6pFh9fDRwHz9-0) 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 
-See: [Determining Navigation & Information Architecture Placement for New VA Mobile App Features](https://docs.google.com/document/d/1XQcYxnCifloaBFNKL2C9JNS7KIj6wEhb4VokPGxBZU8/edit), [VA Mobile app: Detailed sitemap (future state 9-30-22](https://app.mural.co/invitation/mural/adhoccorporateworkspace2583/1655989910332?sender=u28718b63c8993f515e0b2240&key=6f96be43-72c9-4ae6-b529-a2941eb14ba9) 
+   - See: [Determining Navigation & Information Architecture Placement for New VA Mobile App Features](https://docs.google.com/document/d/1XQcYxnCifloaBFNKL2C9JNS7KIj6wEhb4VokPGxBZU8/edit) and [VA Mobile app: Detailed sitemap (future state 9-30-22](https://app.mural.co/invitation/mural/adhoccorporateworkspace2583/1655989910332?sender=u28718b63c8993f515e0b2240&key=6f96be43-72c9-4ae6-b529-a2941eb14ba9) 
 2. Update category screens, if needed
 3. Document intended flow
 4. Defined back labels and screen title
 
 
 ### Reviews
 
-1. Present at Show and Tell or have a peer review your work
-2. Complete an accessibility review, if needed
-3. Receive sign-off from content designer on all copy
-4. Review components with [Design Librarian](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/How-We-Work/design-librarian)
+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](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/How-We-Work/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](https://www.figma.com/file/myVAkBM6nrpt3iC39RyjXz/%F0%9F%A7%B0-FigmaFileWorkflow---Resource---VAMobile?node-id=344%3A279&t=jC6U9HEvK543P9i4-1) 
 3. Check with Product about when work will be handed off
-3. Plan to attend FE handoff meeting to answer any questions
+3. 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 Zenhub) in a timely manner and communicate with the front-end team (engineers and product manager) to collaborate on refinements.
+ - 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](#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, and content QA (aka UX QA) completed before release.
+- 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 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.
+    - 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](https://adhoc.slack.com/archives/C02F8TLNSGY/p1666966698246379).)
+    - For using real test users/data, see this [Slack thread on logging in as a test user](https://adhoc.slack.com/archives/C02F8TLNSGY/p1666966698246379).
     - 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](https://github.com/department-of-veterans-affairs/va-mobile-app/issues/4009)) and a content bug ([4121](https://github.com/department-of-veterans-affairs/va-mobile-app/issues/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
-- For major features, team members should expect to work with the [Design Librarian](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/How-We-Work/design-librarian) and the Product team to prepare app store content.
+- For major features, team members should expect to work with the [Design Librarian](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/How-We-Work/design-librarian) and the Product team to prepare the [app store content](https://didactic-robot-p9wpqpp4wwh99w-3000.app.github.dev/va-mobile-app/docs/Operations/Updating%20the%20App%20Stores).
 
 
 ## Moving/Publishing Work
 
+### Library updates
+
+- When the design work is complete and is approved for launch, work with the [Design Librarian](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/How-We-Work/design-librarian) to implement any needed updates into the [Flagship Library](https://www.figma.com/design/QVLPB3eOunmKrgQOuOt0SU/Flagship-Library---%F0%9F%93%90-Resource---VA-Mobile?m=auto&node-id=719-1428&t=FZCBblfdhmL0HUbe-1).
+
 ### Move work to shipped file
 
-- When the design is live in the app, the [Design Librarian](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/How-We-Work/design-librarian) will work with you to create a shipped file as outlined in the [Figma file workflow](https://www.figma.com/file/myVAkBM6nrpt3iC39RyjXz/%F0%9F%A7%B0-FigmaFileWorkflow---Resource---VAMobile?node-id=344%3A279&t=jC6U9HEvK543P9i4-1).
+- When the design is live in the app, work with the [Design Librarian](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/UX/How-We-Work/design-librarian) to create a shipped file as outlined in the [Figma file workflow](https://www.figma.com/file/myVAkBM6nrpt3iC39RyjXz/%F0%9F%A7%B0-FigmaFileWorkflow---Resource---VAMobile?node-id=344%3A279&t=jC6U9HEvK543P9i4-1).