Migrate To VADS Components: New Disabilities Form

by Alex Johnson 50 views

Introduction

This document outlines the plan to migrate the New Disabilities page, specifically the new-disabilities/add section, to use the Department of Veterans Affairs Design System (VADS) components. Currently, the page uses custom or "imposter" components that do not align with the standard VADS guidelines. This migration aims to improve consistency, maintainability, and accessibility by replacing these custom components with approved VADS elements. The primary goal is to ensure that the user interface (UI) and components on the New Disabilities page adhere to official VADS guidelines, utilizing only VADS-provided elements. This will standardize the implementation while maintaining consistent functionality and user experience. By adhering to VADS, we ensure a unified and accessible experience for veterans across all VA.gov platforms.

Why is this important? Using VADS components ensures consistency across the VA's digital services, making it easier for veterans to navigate and use the website. Moreover, VADS components are designed with accessibility in mind, helping us meet our commitment to providing inclusive services. This migration will also simplify maintenance and updates, as we can leverage the VADS framework instead of managing custom code. Standardizing the UI with VADS components enhances the user experience by providing a familiar and predictable interface. This consistency helps veterans easily navigate and interact with the form, reducing confusion and improving overall satisfaction. By using VADS, the application becomes more maintainable and scalable, benefiting from the ongoing improvements and updates provided by the VADS team. This ensures that the form remains current with the latest accessibility standards and design best practices. The migration to VADS components also promotes code reuse across different parts of the VA.gov website. This reduces redundancy and streamlines development efforts. By using a centralized design system, the development team can focus on implementing new features and enhancements rather than maintaining custom UI elements.

Problem Severity

This issue is classified as Moderate. While veterans are not blocked from submitting the form, the presence of custom components interrupts the ideal user experience. Addressing this after critical bugs ensures a smoother, more consistent interaction for veterans.

Desired Behavior

The desired outcome is for the page UI and components to strictly follow official VADS guidelines, utilizing only VADS-provided elements. The functionality and user experience should remain consistent with the current implementation, but the underlying code will be standardized for better maintainability and accessibility. This means removing all instances of custom-built UI elements and replacing them with their VADS counterparts. The transition should be seamless from the user's perspective, with no changes to the form's functionality or the steps required to complete it. However, the underlying code will be significantly improved, making it easier to maintain and update in the future. By adhering to VADS, we ensure that the New Disabilities page aligns with the broader VA.gov design standards, providing a consistent and intuitive experience for all users. This also allows us to take advantage of the ongoing improvements and updates to the VADS library, ensuring that the form remains modern and accessible.

Tasks

To achieve the desired behavior, the following tasks need to be completed:

  • Inventory page for custom/imposter components: Conduct a thorough review of the new-disabilities/add page to identify all custom or "imposter" components currently in use. This involves examining the HTML, CSS, and JavaScript code to pinpoint elements that deviate from the VADS standard.
  • Migrate relevant UI to VADS: Replace each identified custom component with its corresponding VADS component. This may involve adjusting the component's properties and configurations to match the existing functionality and appearance.
  • Remove all custom code for old components: After migrating to VADS components, remove all the custom code, styles, and scripts associated with the old components. This step is crucial to ensure that the page relies solely on VADS elements.
  • Refactor tests and styles for VADS: Update the existing tests and styles to reflect the changes made during the migration. This includes updating unit tests to verify the behavior of the new VADS components and adjusting CSS to ensure that the page's appearance remains consistent.

Acceptance Criteria

The primary acceptance criterion is that no custom or "imposter" components remain on the new-disabilities/add page. This will be verified through code reviews, visual inspections, and automated tests to confirm that all UI elements are VADS-compliant.

Definition of Done

To mark this initiative as complete, the following criteria must be met:

  • Meets acceptance criteria: The migrated page must meet the acceptance criteria outlined above, ensuring that no custom components remain.
  • Reviewed and approved by product and/or design: The changes must be reviewed and approved by the product and design teams to ensure that they align with the overall vision and user experience goals.

Engineering Considerations

From an engineering perspective, the following points must be addressed:

  • All tests pass: Ensure that all existing and new tests pass after the migration. This includes unit tests, integration tests, and end-to-end tests to verify the functionality and behavior of the VADS components.
  • New functionality is covered by unit tests: Any new functionality introduced during the migration must be covered by unit tests to ensure its reliability and correctness.
  • Logging and monitoring are implemented (if applicable): If the migration introduces any new logging or monitoring requirements, ensure that these are properly implemented to track the performance and usage of the VADS components.

Code Review & Pull Requests

The code review and pull request process must include the following steps:

  • PR includes Local testing steps: The pull request (PR) must include detailed instructions on how to test the changes locally.
  • PR includes Flipper/testing state details (if applicable): If the changes involve any feature flippers or testing states, these must be clearly documented in the PR.
  • PR includes Author's local proof of submission screenshot: The author of the PR must include a screenshot demonstrating successful local testing of the changes.
  • Copilot review completed and feedback addressed: The code must be reviewed by Copilot, and any feedback or suggestions must be addressed.
  • Internal reviewer approved: An internal reviewer must approve the PR, ensuring that the code meets the required standards and guidelines.
  • Internal reviewer added local proof of submission screenshot: The internal reviewer must also include a screenshot demonstrating successful local testing of the changes.
  • Code functionality verified on Staging after merge: After the PR is merged, the code functionality must be verified on the staging environment to ensure that it works as expected.

Refinement Checklist

Before starting the work, ensure that the following refinement steps have been completed:

  • Added description, tasks, and acceptance criteria
  • Added estimate
  • Labeled with Practice Area (engineer, design, product, data science)
  • Labeled with issue type and characteristics of the ticket (bug, accessibility, request, discovery, documentation, research, content, ux testing, front-end, back-end, datadog, etc.)
  • Added any other relevant project fields (team, OCTO priority...)
  • Added an Epic or Super Epic

By following these steps, we can ensure a smooth and successful migration to VADS components on the New Disabilities page, resulting in a more consistent, maintainable, and accessible user experience for veterans.

In conclusion, migrating to VADS components is crucial for maintaining a consistent and accessible user experience across VA.gov. This initiative ensures that the New Disabilities page aligns with the broader design standards, making it easier for veterans to navigate and interact with the form. By following the outlined tasks and acceptance criteria, we can achieve a seamless transition that improves the overall quality and maintainability of the application. For more information on the Department of Veterans Affairs Design System, visit the VADS official website.