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 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.

Last updated: 14 August 2019

Desktop combinations

• Windows 10 + IE 11
• Windows 10 + Edge + JAWS
• Windows 10 + Edge + Narrator (?)
• Windows 10 + Edge
• Windows 10 + Firefox + NVDA
• Windows 10 + Chrome
• Mac + Safari
• Mac + Safari + VoiceOver
• Mac + Chrome

Mobile

• iPhone iOS + Safari
• iPhone iOS + Safari + VoiceOver
• Samsung Android + Samsung Internet
• Samsung Android + Chrome
• Samsung Android + Chrome + TalkBack