Add guide for writing stories

[jamie-lynch]

What is the purpose of this change?

This PR adds a document which sets out a guide for writing stories to help ensure consistency and best practice.

Background

This document is being added during the migration of API docs from theguardian.design into Storybook. I have written this up whilst working on #902 so that PR is a good example of the guidelines in action.

I'm adding it now so that as we continue with the migration and find even more ways to improve the documentation we can record these explicitly for the future, but also so that we can have the discussion around best practice for stories in one place, rather than split across multiple PRs throughout the migration.

[SiAdcock]

If we're not passing default args via the NoValue.args = {...} pattern, is it useful to spread the args into the component like this? Is it doing anything?

[jamie-lynch]

It's not, good point. The only thing that we need is to pass an arg into the function so that Storybook generates the source for the docs page. We could instead do:

export const NoValue = (_: MyComponentProps) => (
  <MyComponent label="Label"/>
)

[SiAdcock]

Oh wow, that's unusual. So if you don't specifically define an argument, the docs don't get generated? You couldn't simply do:

export const NoValue = () => (
  <MyComponent label="Label"/>
)

?

[jamie-lynch]

Correct - for example:

With Args

export const LegendSupportingTextLight = (args: RadioGroupProps) => (
	<RadioGroup
		{...args}
		name="colours"
		label="Select your preferred colour"
		supporting="You can always change it later"
	>
		{radiosOneSelected.map((radio, index) =>
			React.cloneElement(radio, { key: index }),
		)}
	</RadioGroup>
);

or

export const LegendSupportingTextLight = (_: RadioGroupProps) => (
	<RadioGroup
		name="colours"
		label="Select your preferred colour"
		supporting="You can always change it later"
	>
		{radiosOneSelected.map((radio, index) =>
			React.cloneElement(radio, { key: index }),
		)}
	</RadioGroup>
);

Without Args

export const LegendSupportingTextLight = () => (
	<RadioGroup
		name="colours"
		label="Select your preferred colour"
		supporting="You can always change it later"
	>
		{radiosOneSelected.map((radio, index) =>
			React.cloneElement(radio, { key: index }),
		)}
	</RadioGroup>
);

[sndrs]

storybook must be able to introspect useful info from you explicitly giving the args type, even if you don't use it?

[jamie-lynch]

Are we happy with this then?

export const LegendSupportingTextLight = (_: RadioGroupProps) => (
	<RadioGroup
		name="colours"
		label="Select your preferred colour"
		supporting="You can always change it later"
	>
		{radiosOneSelected.map((radio, index) =>
			React.cloneElement(radio, { key: index }),
		)}
	</RadioGroup>
);

[sndrs]

how about a rule where we don't use emotion in stories? if you need to style things, you can use the style prop, but maybe best is show things unstyled? that's the raw component being demoed then. e.g.

[jamie-lynch]

how about a rule where we don't use emotion in stories? if you need to style things, you can use the style prop, but maybe best is show things unstyled? that's the raw component being demoed then. e.g.

Hmm... I thought I agreed with this but then I had a play with the Link stories and I'm not sure. I think there are good cases for using styles to improve the story but I'm not sure that having style objects in the rendered output is a good thing. For starters, it makes it easy to copy and paste something that (I don't think) we'd recommend.

[sndrs]

is it useful though to style the demo? i feel like that should show us what you get out the box, rather than an example of using it?

[jamie-lynch]

is it useful though to style the demo? i feel like that should show us what you get out the box, rather than an example of using it?

Yeah, maybe for the Demo it should always just be the component on it's own. I'll update the recommendations to include that.

I'd argue that some of the styling is useful for stories that are used for visual regression testing as it can test them in context or test multiple instances of the component in one story. I've posted a couple more ideas for how to improve those code blocks in the Improve storybook code blocks card on the backlog. Plus we can add a recommendation to minimise styling in stories.

[sndrs]

that's a good point – maybe we just don't want code for the chromatic examples? only the demo with the knobs?

[sndrs]

love it!

[SiAdcock]

Amazing work, thanks @sndrs and @jamie-lynch 💎