Skip to content

Storybook stories as examples ​

A component can come with stories: ready-made states of it, such as "a warning with a title" or "a card with a text and a button". Storybook shows them, and Frame offers them as examples in the Blocks panel. One piece of YAML serves both.

The same as a video.

Examples under a component in the Blocks panel

What it does ​

Frame reads the stories that the Storybook addon for Drupal SDC reads. Open the arrow next to a component in the Blocks panel: its stories are listed with the tag example, with their name, and their description as a tooltip. Drag one onto the page. Frame adds the component with the values of the story, and fills its slots with the content of the story.

A card added from an example, with its text and button

An example is a starting point. The block you get is an ordinary block: nothing links it to the story, and changing the story later does not change it.

Where a story lives ​

In the component.yml, under thirdPartySettings.sdcStorybook:

yaml
thirdPartySettings:
  sdcStorybook:
    disabledStories: [old]
    stories:
      with_button:
        name: With a button
        description: A card with a text and a button.
        props:
          heading: Cook with a local chef
        slots:
          content:
            - 'Dough by hand, sauces from scratch.'
            - type: component
              component: 'my_theme:button'
              props: { label: Sign up, url: /contact }

Or in a file of its own, {component}.{story}.story.yml, in the folder of the component or below it. It has the keys of one story, without the nesting:

yaml
# components/alert/stories/alert.success.story.yml
name: Success
props:
  tone: success
  text: '<p>See you on Saturday.</p>'

The key of a story is its key in stories, or the part of the file name between the component name and .story.yml. When both places have a story with the same key, the one in the component.yml is used. disabledStories hides stories by key; all hides every one. name is the label, description the tooltip. The other keys of a story (parameters, globals, library_wrapper) are for Storybook, and Frame ignores them.

What goes in a slot ​

A slot is a text, a node or a list of them. Frame maps the nodes that it has an equivalent for.

NodeIn Frame
a textthe text component, as a paragraph (a text that starts with < is HTML as it is)
type: markupthe text component, with the markup
type: element (html_tag)the text component, with <tag attributes>value</tag>; only text inside, no scripts or event handlers
type: componentthe component, from the story named in story (by key or name), then its own props and slots; the rest starts as a new block does
type: image, type: icon, nodes of your ownleft out: Frame has no image from a URL, and the icon is a prop of a component

Frame never stops for a story it cannot use. What it leaves out (a prop or slot the component does not have, a node it has no equivalent for, a component that is not available) is a warning in the log of the browser, Frame examples: ..., with the component and the story. frame check lists the same.

Default values ​

A new block, a story and a preview start from the same value of a prop, in the order of the Storybook addon:

  1. the value in the story,
  2. default in the schema,
  3. the first of examples in the schema.

Frame used the first example before default; if a component has both and you want the example, remove the default.

Examples, presets, the library and templates ​

What it isLinked afterwards
Examplea story of a component: values and content, as a starting pointno
Presetone look (styling) for the blocks of a kindyes
Librarya block with its content, reused as it isyes
Templatea whole page that new pages start fromno

Stories are not presets: a preset is styling only, and the stories are content.

One YAML for Storybook and Frame ​

The component files of a theme can serve both tools:

  • Props and slots (the schema, default, examples, variants) are read by both.
  • Stories are written once and used by both: Storybook shows them, Frame offers them as examples.
  • Design tokens in {theme}.tokens.yml, icons in {theme}.icons.yml and html_cva() in a template are features of Drupal core. The addon draws them in Storybook and Drupal draws them on the page, in Frame too; there is nothing to repeat. See Design tokens, Icons and Variants with html_cva().
  • What only Frame reads (x-builder-*, thirdPartySettings.frame_editor) is ignored by Storybook, and what only Storybook reads (parameters, globals, library_wrapper, tags) is ignored by Frame. Both live under thirdPartySettings, which Drupal leaves to other tools.

Check the YAML ​

bash
node web/themes/contrib/frame/bin/frame.mjs check            # in your theme folder
node web/themes/contrib/frame/bin/frame.mjs check components/card --strict

frame check reads every *.component.yml and *.story.yml below the folder (or the file) and prints what it finds, one line each: the file, where in it, and what to change. It checks:

  • the file against the schema for component files of Drupal core (the one in the core/ folder around the theme, else a copy that comes with Frame), and that prop and slot names can be Twig names;
  • the keys Frame reads: x-builder-* and thirdPartySettings.frame_editor, with a hint for a misspelled one ("did you mean x-builder-widget?"), widgets, x-builder-show-when, accepts, a default that the type or the enum does not allow;
  • the stories: their keys, props and slots against the component, and their nodes.

The output for a card with a misspelled key, a wrong default, and stories that do not fit:

text
$ frame check components
warning components/card/card.component.yml: props.properties.heading.x-builder-widgit is not a key Frame reads: did you mean "x-builder-widget"?
warning components/card/card.component.yml: props.properties.tone.default is not one of the values the prop allows (info, warning).
warning components/card/card.component.yml: thirdPartySettings.sdcStorybook.stories.warn.props.title is not a prop of the component: Frame and Storybook ignore it.
warning components/card/card.component.yml: thirdPartySettings.sdcStorybook.stories.warn.slots.content[0] has the type "image": Storybook draws it, Frame leaves it out of an example.
warning components/card/stories/card.broken.story.yml: nam is not a key of a story: did you mean "name"?

0 errors, 5 warnings.

An error means Drupal or Frame cannot use the file; the command ends with exit code 1. A warning means it works but probably not as meant; --strict makes it an error too. Add it to the scripts of your theme ("check": "node ../../contrib/frame/bin/frame.mjs check") or to the CI.

What Frame does not take from the addon ​

Feature of the addonIn Frame
Stories in the YAML and in *.story.ymlexamples
Story nodes component, element, markup, a textmapped
Story nodes image, icon, custom nodesleft out with a warning
disabledStorieshonoured
Defaults: story, default, examplesthe same order
Mock data from the schema (json-schema-faker)no: Frame starts a prop empty without default or examples; give the props that matter one
validateframe check
parameters, globals, tags, library_wrapper, Controls, the sidebarStorybook only
Namespaces, dependencyMap, libraries from a CDNStorybook only: Drupal loads the libraries on a real page
Icon API, design tokens, html_cva(), form_statefeatures of Drupal; used as they are, not by the stories

Limitations ​

  • Only the components of the theme and its base themes have examples, as only those are in the Blocks panel.
  • A component that the theme replaces (replaces) is offered as the replacement, with the stories of the replacement only. Copy the stories into it when you replace one.
  • A story that names a component that is not offered by the theme is left out.
  • Examples of a field, a view or a block of Drupal do not exist.