Update Contributing guideline about orbit

[honzatmn]

I wrote down something that we used in past for our front-end components. I am not sure about "visual consistency" section to have in there from the start (as it is mostly just for designers) but if we go open source with our design system, we should include visual quality checklist too, linked to our guidelines.

From design POV:
[ ] Visual consistency
↳ [ ] Colors are used according the color guidelines
↳ [ ] Typography respects visual hierarchy
[ ] Responsive behavior
↳ [ ] Component can work stand-alone, it responsively reflects width of it’s parent element
↳ [ ] Content is resilient to any length (what does happen if we put longer label or no label at all?)
[ ] Accessibility sub-checklist
↳ [ ] All touch targets are at least 40x40px in size
[ ] Design tokens are used as values for properties (as soon as they are defined)

From front-end POV:
[ ] Accessibility sub-checklist
↳ [ ] It has proper HTML markup (

for paragraphs, for headers, etc).
↳ [ ] Non-text elements have alternative text
[ ] It’s properly documented, which means:
↳ [ ] Implemented to Storybook
↳ [ ] It’s crystal clear how to use without further knowledge
↳ [ ] Any special behavior is documented
[ ] Front-end tests are created (don’t know how to write this in proper dev language)

[VaclavSir]

[ ] Accessibility sub-checklist
↳ [ ] It has proper HTML markup (

for paragraphs, for headers, etc).

I would be more specific:

• UI components either use semantic elements (<p>, <input> etc.), or they are marked with ARIA attributes (eg. <span role="checkbox" aria-checked="false"> etc.)

↳ [ ] Non-text elements have alternative text

• ... if they hold an important information for the user.

↳ [ ] Any special behavior is documented

Agree, but it should be said where to document it. I would vote for the Storybook, preferably using the Info Addon.

[ ] Front-end tests are created (don’t know how to write this in proper dev language)

I think devs don't know yet either. I would omit this point from the contribution guide until we decide how to create these tests.

[VaclavSir]

Some other points from the front-end dev's PoV:

• Markup is as minimal as possible (avoid unnecessary spans and divs)
• All components are annotated using Flow
• Suppression of ESLint or Flow checks should be avoided

[fallion]

↳ [ ] Any special behavior is documented
Agree, but it should be said where to document it. I would vote for the Storybook, preferably using the Info Addon.

I agree Info Addon and use show markup feature.

[honzatmn]

It would be cool if we added at least basic ARIA attributes from the start, didn't even hoped for that.

Also, I agree with more specificity if possible and I really like the point with minimal markup as possible. 👍All other points are fine by me, not that I know what "Flow" is.

About documentation: we will have special documentation site for everything else (from documented visual style and design guidelines to detailed specification how to use ... anything, actually). It will be definitely linked to Storybook, so anyone can see the React component and play with it there. It would be great if in Storybook was a link back to documentation site, for start. The main reason for separate documentation site is that our requirements for documentation are now far behind what Storybook can offer and it's won't be just about documentation for components.