storybook.md

What it gives?

• Visual documentation

  • Discoverability (Easier to find existing components. Potentially works for designers too. As a result, we are saving time because we are not doing the same thing again and again)
  • Regression (Breaking design or API changes will be reflected)
  • Describes component API (And edge cases)
  • Hints to intended usage

• Faster design delivery (than having component embedded into the page)

  • Early design feedback
  • Tangible (Can be used as an Acceptance Criteria)
  • Divide a component as much as you like (component === Jira ticket)
  • Might result in faster delivery generally

• Playground (do not afraid to add state to your stories and turn them into micro apps)

  • When a component is built from scratch, allows experimenting with visual representation and internal API (don't build in your head)
  • When component is ready, allows experimenting with integration (Interaction with other components, API sanity check, drafts for future components)
  • Can I imagine another usage context for this component? Does component API allow to express this context?
  • Knobs do the thing (Expose movable parts, encourage people to play)

• Testing (Storybook Driven Development may be surprisingly similar to TDD)

  • Encourages low coupling (Double checking integration points)
  • Encourages easy mocking (We want to use the same mocking tools in specs and stories)
  • Exposes and specifies behavior (Which good tests do)
  • Is this thing accessible? And if I switch it to another state? (You can rerun accessibility test, which might fail at one specific state. Button with kind FAILURE doesn't have enough color contrast, but kind NORMAL is ok, as an example)

Why it is easy to add? Why it doesn't take but saves time?

• It's like a function call (It's cheap, you provide arguments and enjoy the result)
• This should not be a separate ticket, this should help you with your current ticket

Why it can be hard to add, time-consuming and frustrating?

• Apollo
• useQuery and useMutation to be more specific. They are hard to mock, describing data variants (and behavior tied to data) can be too verbose and probably will be skipped. Devs do it only for the great purpose of "This code must be tested, at all costs! (Well, at least that branch)"

Can we do something about it?

• Yes
• Don't use useQuery and useMutation
• Create abstractions over ApolloClient that allow you to mock data, not the way this data is obtained (It should be obtained via simple method call).