TEST: Component health issue template
Component health evaluation
The purpose of a health evaluation is to determine what factors contribute to the health of a component in the Pajamas Design System, so that we can assess where effort is needed, prioritize work, promote usage, and increase value over time. The scope is limited to Pajamas (Pajamas UI Kit, GitLab UI, Pajamas documentation) and does not include how a component is used or extended in the product.
The evaluation is a collaborative effort between disciplines. Our collective knowledge will increase the quality and value gained from each report.
More details…
Why track health?
- Health is positive and more qualitative than quantitative.
- Health accounts for critical vital signs that lead to stability and performance — things that directly impact UX.
- Health isn't as pass/fail as completeness. A range can better inform appropriate use and predict impact in different use cases.
- Health is more closely correlated to the System Usability Score (SUS).
- Health is a better indicator for infrastructure, which is how we should think about the design system.
Desired outcome
A simple way to scan component criteria and be able to make decisions about:
- Using the component
- Prioritizing component work
Instructions, help, and tips
For evaluators…
Instructions
Initial setup:
-
Title the issue with the component name, for example Health evaluation: componentName
-
Assign evaluator(s) -
Add the component label
For each criteria, at least one evaluator needs to:
- Use the following checklists to evaluate the component
- Create a thread for the criteria to document your findings
- Update the status in the description for the criteria (choose a single status from the list below)
- Update relevant Pajamas (design.gitlab.com) sections
- Create any necessary follow up issues
Completing the evaluation:
-
Ensure that all evaluators have completed the above steps for the criteria they reviewed -
Close this issue
Status options
- Incomplete - Needs attention
- Viable - Critical aspects covered and ready for use, but may not fill all use cases or capabilities
- Complete - All known aspects satisfied
- Deprecated - Component is no longer supported or in use
- * - Used in conjunction with a status to indicate active or planned work
Help and tips
- This is an evaluation, not a test. Use your best judgement and ask for help when needed. Even collectively there are some things we just won't know and that's where we can create followups to find out or come to decisions.
- It can be a challenge to determine where the source of truth may be found. Sometimes designs may be newer than code, and the opposite is true too. Do your best to track determine where feedback is most actionable and appropriate.
- There doesn't have to be complete parity between what's available in the Pajamas UI Kit vs. what's in GitLab UI. There are design instances that don't need to be in code. Likewise, there are controls in GitLab UI that don't need to be part of a component's configurable properties. Focus on the main things like design consistency and a clear representation of states and variants that would need to be used or implemented by a designer or an engineer respectively. Ask yourself if a designer could accurately use the component in a design composition or prototype, or if an engineer could migrate to or implement a component while satisfying UX and accessibility.
- Too much information is better than too little. More details and references in the threads will help us now and in the future to get a better handle on component requirements, capabilities, use, and historical decisions that inform the current state.
- For the accessibility thread in particular, it would be helpful to document the WCAG success criteria referenced, and screen reader and browser combinations used. Information like this will have a compounding effect for future reference and reviews.
Health criteria
Design
Fulfills known design requirements
-
Ensure the Pajamas UI Kit design specs cover all applicable user-facing states and variants. Eric Bailey has a great reference for all the user-facing states. Variants will depend on the component's design and configuration options which may be documented in Pajamas or available in GitLab UI. -
Figma components are available and configurable by inserting from the component library and testing properties -
Review GitLab UI stories to ensure that design specs are accurately implemented and that features present in the Pajamas UI Kit are also present in code -
Check the GitLab.org project for open issues and MRs that address missing or incomplete design requirements
🪧 Status: {status}
Development
Fulfills known functional requirements
-
GitLab UI components have all states, variants, and functionality -
Ensure that all necessary controls exist in GitLab UI -
Review the Pajamas UI Kit to ensure that any variants present in GitLab UI stories are also present in the design specs -
Check for open issues and MRs that address missing or incomplete functional requirements -
If using an anchor tag in user-generated content, ensure sanitization & proper rel
attribute (consider using thesafe_link
directive)
🪧 Status: {status}
Accessibility
Satisfies WCAG success criteria, has passing automated tests, and has passed manual evaluations
-
Satisfies applicable WCAG 2.2 (level AA) success criteria -
Automated test (Cypress) exists and is passing -
Accessibility violations reported by the Storybook accessibility addon in GitLab UI have a followup issue or MR -
Keyboard accessible -
Evaluated with common screen reader and browser combinations (JAWS/Chrome, NVDA/Firefox, VoiceOver/Safari) and issues resolved
🪧 Status: {status}
Documentation
Has supporting examples (stories) and guidelines that prescribe details about variants, implementation, content, and use
-
Documentation page exists in Pajamas and follows component template -
GitLab UI stories align with design specs -
No todos are present -
Documentation present in GitLab UI
🪧 Status: {status}