storybook: Addon-docs: StoryDescription is not shown for first story

@shilman @domyen - There are a couple of thoughts I had regarding this:

1. None of the examples in the Storybook website follow this pattern, including the Tasks example in the official tutorial. If I have a HeaderWithLink and HeaderWithoutLink, there isn’t really a primary story. Therefore, I’m not sure if this is the default pattern to follow.
2. At the very least, I don’t think we should exclude the primary story from the list of stories that follow below. It seems an odd UX experience to have story #1 on top and (n-1) stories below that.

If the encouraged pattern is to have a BaseButton or BaseHeader configurable story, I think the documentation should encourage that from the beginning. Having said that, my contention is that this should not be the default. I’ve found the same issues as @donaldpipowitch and it seems unintuitive for most cases.

Thank you!

Apologies for the late reply everyone 🙏. There seem to be two issues here:

StoryDescription is missing from the primary story (the one at the top) of the DocsPage. I agree that this is an oversight. My strawman is to put the description (only) here.

The idea of “Primary” stories Docs was designed to feature one representative story for each component. This is common practice amongst the design systems we researched like Shopify Polaris, Workday Canvas, and Auth0 Cosmos. But I get that not everyone is going to have the same mental model – that’s why DocsPage is fully customizable.

There are a few things we can do here:

1. Document that the first story == primary docs story. We should have done this in the first place! cc @jonniebigodes can we add this to the new 6.0 docs?
2. Allow people to override the primary story without replacing the DocsPage. Perhaps add a primary parameter at the story level.

I don’t think it makes sense to eliminate the primary story concept because a use case we’d like to support in 6.0 is live adjusting that story via the ArgsTable. I think this behavior with make the primary distinction make a bit more sense.

I don’t know… every time I write stories I stumble over this issue. I think it would be nice if Storybook would not emphasize the first story by default. It should be treated like the other stories and there should be a way to write a more general introduction/description unrelated to a specific story, if needed. But just my opinion. It’s probably too late to get this into v6?

(Update: Workaround for v6-rc:

import {
  Title,
  Subtitle,
  Description,
  Primary,
  Props,
  Stories,
  PRIMARY_STORY,
} from '@storybook/addon-docs/blocks';
import React from 'react';

export const parameters = {
  docs: {
    page: () => (
      <>
        <Title />
        <Subtitle />
        <Description />
-        <Primary />
        <Props story={PRIMARY_STORY} />
-        <Stories />
+        <Stories includePrimary />
      </>
    ),
  },
};

But I still think it is an UX gotcha. 🤔)

I too have been looking for hours for a way to ignore the “primary” story and show all the stories in the docs-page right below the (automatically generated) “Stories” title.

Almost none of my stories makes sense to have a “primary” story.

I want the docs-page to document all the stories, as equal, one after the other

Not sure why the includePrimary is not included in the normal configuration of a jsx file for a story. It seems pretty weird for me to override the full page config to just adding a flag.

Any update on this?

@domyen we can make it work. I’m going to add this to my todo list and i’ll circle back to it shortly.

Sounds good?

@shilman Can you take a look at the PR? Thanks

Was able to find the bug. In DocsPage.tsx

<>
    <Title slot={titleSlot} />
    <Subtitle slot={subtitleSlot} />
    <Description slot={descriptionSlot} />
    <Primary slot={primarySlot} />
    <Props slot={propsSlot} />
    <Stories slot={storiesSlot} />
  </>

The first story is printed by the Primary component and the rest of the stories are printed with the Stories component. In primary component DocStory is called as <DocsStory {...story} expanded={false} withToolbar /> Expanded is set as false here hence it is not printing the title and description. What was the design decision here. A simple fix is passing expanded as true. @shilman What do you think about this fix? Hopefully it does not break anything else. Will run tests to check that. Opening a PR soon.