Determine component health factors
Purpose
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.
By using a multifaceted approach, we can gain a better sense of the overall health of each component. We understand that subjectivity is a natural factor in the process and that the goal isn't a health score or fixed data point, but an evidence-based impression of a component's status at given point in time.
Why track health?
- We've tried tracking status based on "completeness," but completeness isn't easily attainable, and a component can still be complete while not satisfying many factors. (See &6 (closed) for challenges related to being complete.)
- Health is positive and more qualitative than quantitive.
- 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 SUS.
- Health is a better indicator for infrastructure, which is how we should think about the design system.
Desired outcome
In addition to bring more alignment between the UI kit, GitLab UI, and Pajamas, this would provide a simple way to scan component criteria and be able to make decisions about:
- Using the component
- Prioritizing component work
Health criteria:
Criteria | Definition |
---|---|
Design | Fulfills design requirements |
Development | Fulfills functional requirements |
Accessibility | Satisfies WCAG success criteria, has passing automated tests, and has passed manual evaluations |
Documentation | Has supporting examples (stories) and guidelines that prescribe details about variants, implementation, content, and use |
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
How to evaluate the criteria
There will be an epic for each component with child issues for each of the four criteria listed below.
A completed task indicates that this part of the evaluation has been completed and doesn't relate to the resulting status.
Design
A design evaluation ensures that the design specs are up to date, can be used as a reference for development when necessary, and that the component is useable in Figma to create accurate design and prototyping artifacts.
Tasks
-
Check the GitLab.org project for open issues tagged with the component label that address missing or incomplete design requirements. Create a new thread with links to relevant issues. -
Check to see if the component's design specs in the Pajamas UI Kit 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. Report your findings in a new thread and note if there's anything that seems to be missing. -
Insert the component from the component library into a test file in Figma and experiment with the options in the properties panel. Repeat this for each variant and answer the following questions in a new thread: - Do the component configuration options in the properties panel work as expected?
- Is there anything that seems to be missing or is confusing?
- If applicable, can you update content and swap variants and states without items resetting?
- Does the property naming look correct?
-
Review your findings as a whole, and in a "summary" thread assign a single status to the component and explain your reasoning. -
Have your findings reviewed by a member of the Foundations design team. -
Create any additional followup issues needed that would help resolve findings that impact the component's health (be sure to use the component label) and add them to the linked items section. -
Add the status to the design section of the epic description. -
Close the issue.
Development
A development evaluation ensures that components are functionally complete and have accurately translated design specs into code.
- 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 the design specs are also present in GitLab UI stories
- Check the GitLab.org project for open issues that address component needs
- If using an anchor tag in user-generated content, ensure sanitization & proper
rel
attribute (consider using thesafe_link
directive)
Accessibility
An accessibility evaluation ensures that a component 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
Documentation
A documentation evaluation ensures that a component 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
Considerations
- While health works for components, completeness may still be applicable to foundational things like color and typography. Lack of completeness in those areas reduces health for any part of the system that relies on them.
- Existence in a particular form (UI kit, code, etc.) isn't sufficient, because existence itself isn't a good measurement. If it exists, however, then it can be evaluated by the criteria above.
- Adoption or usage count on its own doesn't indicate health. For example, a component may be included, but then extended incorrectly. Likewise, a component may be used a number of times for a purpose it wasn't intended for. However, by combining adoption with health we could assess overall impact in a separate effort.
Component status/health examples
- https://primer.style/guides/status
- https://www.duetds.com/components/
- https://www.delldesignsystem.com/updates/component-status/
- https://thumbprint.design/components/overview/
- https://www.supernova.io/blog/how-to-track-your-design-systems-health-with-supernova
- https://userlane.supernova-docs.io/latest/components/overview-iLsbd7kI