Contributing
Making suggestions
The design system exists in GitHub to encourage collaborative work. If something can be better, it should be made better.
Content recommendations go through the Web Content Managment Committee, all other recommendations go through Web Development.
If comfortable with GitHub, make a pull request with details for why the change should be made.
Writing for the design system
These guidelines are borrowed from the wonderfully written principles at Vue.js.
- A feature does not exist until it is well documented.
- Respect people’s cognitive capacity. When people start reading, they begin with a limited amount of brain power, and when they run out, they stop learning.
- Cognitive capacity is deplated faster by complex sentences.
- Break concepts down into digestible pieces and mind the flow of the document to more slowly deplete cognitive capacity.
- Read the documentation from other’s perspective. Avoid the “curse of knowledge”, where something may seem obvious but is not. Good documentation meets people where they are.
- Describe the problem first, then the solution. Before demonstrating how a feature works, explain why it exists.
- While writing, ask questions. Especially if they might seem “dumb”.
- Be involved in feature discussions. Harness documentation-driven development.
Testing requirements
All code must be tested against the following environments. All HTML, CSS, and JS techniques must have 98% coverage based on caniuse.com using the past full semester’s statistics from the main website (or the Health Sciences Library website for HSL).
All code must function or meaningfully and gracefully degrade on these platforms using the listed tool combinations.
Screen reader combinations from WebAIM's Screen Reader User Survey published 22 February 2024.
Last updated: 19 May 2025
Desktop combinations
- Windows 11 + Chrome
- Windows 11 + Chrome + NVDA
- Windows 11 + Edge
- Windows 11 + Edge + JAWS
- Windows 11 + Firefox + NVDA
- Mac + Safari
- Mac + Safari + VoiceOver
- Mac + Chrome
Mobile
- iPhone iOS + Safari
- iPhone iOS + Safari + VoiceOver
- iPad + Safari
- Samsung Android + Samsung Internet
- Samsung Android + Chrome
- Samsung Android + Chrome + TalkBack