Storybook Stories

File Structure

stories/templates/[ComponentName]/ ├── basic.js Base template, args, and parameters ├── additional.stories.js Additional story variants └── additional.mdx Documentation for additional stories

File Concatenation

basic.js is automatically concatenated with additional.stories.js at load time. Do NOT import from basic.js in additional.stories.js — Template , args , and parameters are already in scope.

basic.js Pattern

import { html } from "lit"; import { ifDefined } from "lit/directives/if-defined.js";

export const Template = args => html <sgds-component ?prop=${args.prop} attribute=${ifDefined(args.attribute)}></sgds-component>;

export const args = { prop: true, attribute: "value" }; export const parameters = {};

additional.stories.js Pattern

import { html } from "lit";

// Template is in scope via concatenation — no import needed

export const Dismissible = { render: Template.bind({}), name: "Dismissible", args: { dismissible: true, show: true }, parameters: {}, tags: ["!dev"] };

For complex stories, define a local template inline:

const ShowMoreTemplate = args => html <sgds-system-banner show id="banner" dismissible> <sgds-system-banner-item>Long content...</sgds-system-banner-item> </sgds-system-banner> <script> document.querySelector("#banner").addEventListener("sgds-show-more", () => modal.show()); </script>;

export const ShowMore = { render: ShowMoreTemplate.bind({}), name: "Show More", args: {}, parameters: {}, tags: ["!dev"] };

See reference/examples.md for full real-world component examples.

DRY Rules

The folder name is the namespace. Strip it from filenames and export names.

File Naming

stories/utilities/border/ ✅ color.stories.js ❌ border-color.stories.js ✅ radius.stories.js ❌ border-radius.stories.js

stories/utilities/spacing/gap/ ✅ static.stories.js ❌ gap-static.stories.js ✅ form.stories.js ❌ form-gap.stories.js

stories/utilities/spacing/padding/ ✅ static.stories.js ❌ padding.stories.js ✅ layout.stories.js ❌ layout-padding.stories.js

Storybook Title

// ✅ Folder path already provides context export default { title: "Utilities/Border/Color" }; export default { title: "Utilities/Spacing/Gap/Form" };

// ❌ Repeats the category export default { title: "Utilities/Border/Border Color" }; export default { title: "Utilities/Spacing/Gap/Form Gap" };

Export Names

// In stories/utilities/border/color.stories.js // title path already contains "Border" export const Grayscales = ... // ✅ not BorderGrayscales export const Primary = ... // ✅ not PrimaryBorder

Story Naming Conventions

• Export name: PascalCase (NoClampAction )

• Display name: Title Case ("No Clamp Action" )

• Be descriptive, not generic — avoid Story1 , Story2

Commands

Command Purpose

pnpm storybook

Preview stories

pnpm run build:storybook

Production build