Definition of done for a story

[gfellerph]

With more people working on the Design System Documentation, it might be a good idea to write up a definition of done for stories.

To gather some input, what makes a good story in your opinion? Please comment in this issue what you think a story needs before it can be considered as done.

[gfellerph]

• Component docs
  • Short introduction
  • Canvas for showcasing
  • Controls for the showcase
  • Variants if applicable (e.g. group of component or small example in context)
  • Instructions for installation
  • Controls
  • Possibility to re-create all variants (good for debugging because they can be set via query params and a reproduction can be linked)
  • Accessibility hints for relevant controls like disabled state or hidden labels
  • Testing
  • Cross browser testing of the docs
  • Testing in High Contrast mode
  • Approval by UX for the story
  • For more complex widgets: screen reader testing (at least nvda)

[alizedebray]

• Accessibility
  • aria-hidden="true" or span.visually-hidden labels for all icons
• Docs
  • No key attributes in code snippets
  • No nested p's (beware of .lead and .alert)
  • LinkTo with both kind and story attributes
  • div.hide-col-default wrapper for Controls component on CSS only docs
  • No dark code blocks
• Naming convention
  • Docs file: [component].docs.mdx
  • Story file: [component].stories.tsx
  • Demo story file: [component].demo.stories.tsx
  • Snapshot story file: [component].snapshot.stories.tsx

[oliverschuerch]

@gfellerph Your proposal seems to be very complete in my opinion.

Testing the high contrast mode could be automated eventually with a cypress plugin and snapshot tests: https://github.com/ling1726/cypress-forced-colors

Try emulating the high contrast mode in chrome by yourself:

• Open the Command Menu: ctrl + shift + P (or cmd + shift + P on mac).
• Type "rendering" and press Enter .
• In the Rendering panel, scroll down to the Emulate CSS media feature forced-colors and activate it from the drop-down.
• You can switch also prefers-color-scheme to test light/dark mode.

[oliverschuerch]

@alizedebray

• I would change "No key attributes in code snipptes" to "No react related attributes in code snippets" (e.g. className, htmlFor, key, etc.)
• We could decide to use the linkTo directive instead of the LinkTo Storybook block, this would give us more freedom in creating the link: https://storybook.js.org/addons/@storybook/addon-links.
• Add [component].styles.scss and [component].module.scss for style and scss export files to the naming conventions.
• Add [component].blocks.tsx for custom mdx helper blocks to the naming conventions.
• Everything else looks just fine!

[alizedebray]

@oliverschuerch My point on LinkTo was more about the story attribute which was not needed with Storybook 6 but has to be added with Storybook 7.

No problem using the linkTo directive although it needs to be investigated as I had to replace it in the Heading docs (you can see in the PR #1673 preview that "check out heading utilities" doesn't show a link).

[alizedebray]

• Use mapClasses utility function wherever we had classes formated using [*].filter(c => c && c !== 'null').join(' ')

[imagoiq]

Quick note about tsx, I think this issue is linked: https://github.com/swisspost/design-system/issues/1774

[oliverschuerch]

@gfellerph Is this ticket still needed or should we add a docs page about it? Could it be done by the PiBs Guys?

[gfellerph]

@oliverschuerch, this should rather go into the contribution.md file, but can also be a PIBS task.

[davidritter-dotcom]

I have another small thing that could be in a definition of done: We should also add the sourceState="shown" attribut to the first canvas if the code is not too long.

[imagoiq]

Some other thoughts:

In https://nicsteenhout.substack.com/p/accessibility-specific-tech-requirements, how can we specify the requirements and to which level? It's quite complex with WCAG and different screen readers.

Adobe Spectrum has a public checklist for design (only design unfortunately): https://spectrum.adobe.com/page/button/#Design-checklist .

[b1aserlu]

• Component docs

  • Short introduction
  • Canvas for showcasing
  • Controls for the showcase
  • Variants if applicable (e.g. group of component or small example in context)
  • Instructions for installation

• Controls

  • Possibility to re-create all variants (good for debugging because they can be set via query params and a reproduction can be linked)
  • Accessibility hints for relevant controls like disabled state or hidden labels

• Testing

  • Cross browser testing of the docs

  • Testing in High Contrast mode

    • Try emulating the high contrast mode in chrome by yourself:
      • Open the Command Menu: ctrl + shift + P (or cmd + shift + P on mac).
      • Type "rendering" and press Enter .
      • In the Rendering panel, scroll down to the Emulate CSS media feature forced-colors and activate it from the drop-down.
      • You can switch also prefers-color-scheme to test light/dark mode.

  • Approval by UX for the story

  • For more complex widgets: screen reader testing (at least nvda)

• Accessibility

  • aria-hidden="true" or span.visually-hidden labels for all icons

• Docs

  • No react related attributes in code snippets (e.g. className, htmlFor, key, etc.)
  • No nested p's (beware of .lead and .alert)
  • When using LinkTo use both kind and story attributes
  • div.hide-col-default wrapper for Controls component on CSS only docs
  • Add the sourceState="shown" attribute to the first canvas if the code is not too long.

• Naming convention

  • Docs file: [component].docs.mdx
  • Story file: [component].stories.ts
  • Demo story file: [component].demo.stories.tsx
  • Snapshot story file: [component].snapshot.stories.ts
  • style file [component].styles.scss
  • SCSS export file [component].module.scss
  • Custom mdx helper blocks [component].blocks.tsx

• General Coding Rules

  • Use already existing utilities instead of custom solutions. For example use mapClasses utility function instead of [*].filter(c => c && c !== 'null').join(' ')