Create stories template with best practices by flacoman91 · Pull Request #484 · cfpb/design-system-react

flacoman91 · 2026-02-09T14:58:20Z

I've looked at the other stories in our project and created a basic example devs can work off of when starting off a new component.

github-actions · 2026-02-09T15:00:16Z

PR Preview Action v1.8.1
🚀 View preview at https://cfpb.github.io/design-system-react/pr-previews/pr-484/
Built to branch `gh-pages` at 2026-02-10 19:36 UTC. Preview will be ready when the GitHub Pages deployment is complete.

natalia-fitzgerald

@flacoman91
Nice work! Here are some initial suggestions on the templates.

docs/storybook/ComponentOverviewTemplate.mdx

src/components/ComponentTemplate/ComponentTemplateOverview.mdx

natalia-fitzgerald · 2026-02-09T19:37:38Z

src/components/ComponentTemplate/ComponentTemplateOverview.mdx

+  </li>
+  <li>
+    <Paragraph>
+      You want to describe usage rules, do/don&apos;t guidance, or accessibility


All usage guidelines should all live in the CFPB Design System itself and not in the DSR. If we are referring to something more specific here, for example, React implementations then we can specify.

natalia-fitzgerald · 2026-02-09T19:38:08Z

src/components/ComponentTemplate/ComponentTemplateOverview.mdx

+  </li>
+</List>
+
+<Heading type='4'>Related stories</Heading>


Suggested change

<Heading type='4'>Related stories</Heading>

<Heading type='4'>Component variant</Heading>

natalia-fitzgerald · 2026-02-09T19:53:35Z

src/components/ComponentTemplate/ComponentTemplate.stories.tsx

+ * - Keep stories focused on behavior/appearance; avoid test-only props.
+ * - Use args for the "Default" story and reuse them in variants.
+ * - Add a minimal set of variants that reflect real usage.
+ * - Add the link to the component's documentation page in https://cfpb.github.io/design-system/components/


Suggested change

* - Add the link to the component's documentation page in https://cfpb.github.io/design-system/components/

* - Add the link to the component's CFPB Design System documentation page in https://cfpb.github.io/design-system/components/

natalia-fitzgerald · 2026-02-09T20:07:58Z

@flacoman91
Are all of these accounted for in the stories template? You don't need to repeat this checklist in there but we could link to it. And, I do want to make sure that the way we've set it up is consistent with the bullets below:

Introduction text has been copied from the CFPB Design System page for the component
Link to the CFPB Design System component page has been added (e.g., Source: https://cfpb.github.io/design-system/components/banner-notification)
Each CFPB Design System component variant is implemented as a separate story
Story name is written in sentence case (eg., Radio Button => Radio button)
Component and variant naming is consistent with the CFPB Design System BUT does not repeat the name of the parent component for variants (eg., Button => Primary instead of Button => Primary button )
The order of the stories matches between the DS and the DSR
(same component names, same placeholder text, etc.)
The components have the same sample text between the DS and the DSR

flacoman91 · 2026-02-09T22:48:46Z

@flacoman91 Are all of these accounted for in the stories template? You don't need to repeat this checklist in there but we could link to it. And, I do want to make sure that the way we've set it up is consistent with the bullets below:

Introduction text has been copied from the CFPB Design System page for the component

Link to the CFPB Design System component page has been added (e.g., Source: https://cfpb.github.io/design-system/components/banner-notification)

Each CFPB Design System component variant is implemented as a separate story

Story name is written in sentence case (eg., Radio Button => Radio button)

Component and variant naming is consistent with the CFPB Design System BUT does not repeat the name of the parent component for variants (eg., Button => Primary instead of Button => Primary button )

The order of the stories matches between the DS and the DSR
(same component names, same placeholder text, etc.)

The components have the same sample text between the DS and the DSR

The first 2 items, i added in the component.tsx file since that is how that info gets injected in the storybook file.

The rest I added this in the stories template.

natalia-fitzgerald

@flacoman91
I know this is still a work in progress. I made some suggestions, particularly for the stories and overview docs to make this look more like a template for what the final pages should look like (in terms of their content blocks). I think the guidance is good but I would prefer that we hide it outside of the content that will show up on the pages.

natalia-fitzgerald · 2026-02-09T23:47:19Z

src/components/ComponentTemplate/ComponentTemplateOverview.mdx

+  </li>
+  <li>
+    <Paragraph>
+      All usage guidelines should all live in the CFPB Design System itself and not in the DSR. If we are referring to something more specific here, for example, React implementations then we can specify.


This blurb applies to how we handle DSR component documentation more broadly. It could be moved to the component template stories level.

src/components/ComponentTemplate/ComponentTemplateOverview.mdx

natalia-fitzgerald · 2026-02-10T00:02:29Z

src/components/ComponentTemplate/ComponentTemplateOverview.mdx

+  </li>
+  <li>
+    <Paragraph>
+      All usage guidelines should all live in the CFPB Design System itself and not in the DSR. If we are referring to something more specific here, for example, React implementations then we can specify.


Suggested change

All usage guidelines should all live in the CFPB Design System itself and not in the DSR. If we are referring to something more specific here, for example, React implementations then we can specify.

natalia-fitzgerald · 2026-02-10T00:07:58Z

src/components/Component/component.stories.tsx

+import type { Meta, StoryObj } from '@storybook/react-vite';
+import ComponentTemplate from './ComponentTemplate';
+
+// Best practice checklist:


At a later date we should bring together the verification checklist, this checklist, and any other user documentation checklists and determine where the different content should live so that we are only maintaining it in one place.

We have this place: https://cfpb.github.io/design-system-react/?path=/docs/guides-introduction--overview. Maybe that would be the place to put these types of process lists. Templates like these could link back out to that page https://cfpb.github.io/design-system-react/?path=/docs/guides-introduction--overview. And then this template could just be a content template for the page type. Not something we need to figure out yet.

Actually, I think this is a nicer approach, rather than linking to the introduction page - https://govuk-react.github.io/govuk-react/?path=/docs/docs-contributing--docs](#484 (comment))

natalia-fitzgerald · 2026-02-10T00:11:49Z

src/components/ComponentTemplate/ComponentTemplate.stories.tsx

+};
+
+export const WithCustomRender: Story = {
+  name: 'Custom render',


What is the use case for custom render?

It's just another story example for the page. We can remove it.

natalia-fitzgerald · 2026-02-10T00:17:42Z

src/components/ComponentTemplate/ComponentTemplate.stories.tsx

+const meta: Meta<typeof ComponentTemplate> = {
+  // TODO: Update to your component's category and name.
+  title: 'Templates/Component Template',
+  component: ComponentTemplate,


Can we change the heading on this page to "Component name" (sentence case)?

<h1 class="sbdocs-title sb-unstyled css-1006lt">Component name``

natalia-fitzgerald · 2026-02-10T00:27:33Z

src/components/Component/component-overview.mdx

Screenshot of what this page should look like (pulled from Checkboxes example)

natalia-fitzgerald

@flacoman91 - A few additional suggestion included here.

Also, if we plan to show the templates in actual UI we should update the menu items to whatever names we want to use to refer to each of these templates (rather than having the menu items pull from the first heading on each template page). Or do we plan to remove these from view once we complete the review process?

natalia-fitzgerald · 2026-02-10T01:53:30Z

src/components/ComponentTemplate/ComponentTemplateOverview.mdx

+</Paragraph>
+
+<Paragraph>
+  The only use case for this format is for when we have components that live under a single parent where the types (or variants) have their own states. This template should be used very rarely.


Suggested change

The only use case for this format is for when we have components that live under a single parent where the types (or variants) have their own states. This template should be used very rarely.

src/components/ComponentTemplate/ComponentTemplateOverview.mdx

natalia-fitzgerald · 2026-02-10T02:21:58Z

This is a nice approach to how/where to document the contribution guidelines: https://govuk-react.github.io/govuk-react/?path=/docs/docs-contributing--docs. They created a section within the storybook documentation itself for "Documentation."

natalia-fitzgerald

@flacoman91
What do you think of this naming for the files to make it simpler:

src/components/templates

Component.stories.tsx
Component.test.tsx
Component.tsx
ComponentGroup.mdx

I don't know where to put this but when the ComponentTemplate.stories (Component.stories.tsx) template is used with the ComponentTemplateOverview.mdx (ComponentGroup.mdx) we do not include the CFPB Design System component description on the stories page. In these use cases the component description from the CFPB Design System only lives on the ComponentTemplateOverview.mdx (ComponentGroup.mdx) page.

natalia-fitzgerald · 2026-02-10T02:25:54Z

src/components/Component/component.test.tsx

Is this one the unit test?

Yes, its just a basic test. We should also note that devs should aim for 100% coverage (or whatever threshold)

Is this test the same one that is mentioned in the verification checklist?

"Verify component unit tests are implemented and passing - 85% or greater (ex: yarn vitest ComponentName)"

If so I'd like to link to this template from the checklist. For the naming is "Component.test.tsx" specific enough? As in are there component tests and unit tests or component unit tests? This is clearly not my area of expertise, I am asking for the sake of consistent language between the way we refer to these things in the checklist and the template naming (and so that we use the naming that makes the most sense to developers like you).

yes. same test

src/components/ComponentTemplate/ComponentTemplateOverview.mdx

natalia-fitzgerald · 2026-02-10T02:30:45Z

src/components/Component/component.tsx

+/**
+ * Copy the component description from the CFPB Design System page for the component in the component file JSDoc block (autodocs uses it).
+ * Add the link to the component's CFPB Design System documentation page below
+ *
+ * Source: https://cfpb.github.io/design-system/components/[Component-Name]
+ */


Does this text belong here or does it only belong on the stories template page?

We can put a reminder on the stories template page to remind users to update this info.

I would only add this information here in the JSDocs. Autodocs pulls the component description from the component’s JSDoc consistently across all stories and consumers. If you have this info in the storybook, devs don't see it appear in the IDE intellisense feature.

If you want the IDE to actually show the component details when you're coding, you want this info here. This way it will appear in both the IDE and in the stories in storybook.

It looks like the way we have it declared in other components are set up are a little inconsistent.

natalia-fitzgerald · 2026-02-10T02:31:54Z

src/components/Component/component.tsx

+   * Label text for the component.
+   */
+  label: string;
+  /**
+   * Optional helper text shown below the label.
+   */
+  helperText?: string;


Here we should indicate that the sample text we use in these components should match the CFPB Design System component page example.

I added this in the stories template since that is what determines how you view it in storybook.

@natalia-fitzgerald

add the design system link, add mdx file add component example adding test file update move template update text update name update template Apply suggestion from @natalia-fitzgerald Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> Apply suggestion from @natalia-fitzgerald Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> Apply suggestion from @natalia-fitzgerald Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> Apply suggestion from @natalia-fitzgerald Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> Apply suggestion from @natalia-fitzgerald Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> Apply suggestion from @natalia-fitzgerald Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> Apply suggestion from @natalia-fitzgerald Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> Apply suggestion from @natalia-fitzgerald Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> Apply suggestions from code review Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> Apply suggestion from @natalia-fitzgerald Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> Apply suggestion from @natalia-fitzgerald Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> Apply suggestion from @natalia-fitzgerald Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> Apply suggestion from @natalia-fitzgerald Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> fixing formatting remove template Apply suggestion from @natalia-fitzgerald Co-authored-by: Natalia Fitzgerald <77348967+natalia-fitzgerald@users.noreply.github.com> remove p rename file to kebab

flacoman91 · 2026-02-10T18:05:26Z

This is a nice approach to how/where to document the contribution guidelines: https://govuk-react.github.io/govuk-react/?path=/docs/docs-contributing--docs. They created a section within the storybook documentation itself for "Documentation."

I like this and the contribution guide section!

flacoman91 · 2026-02-10T18:52:03Z

@natalia-fitzgerald we already have a guides section at the top with introduction. we can add the template there as well as any other contribution guidlines?

natalia-fitzgerald · 2026-02-10T21:22:41Z

@natalia-fitzgerald we already have a guides section at the top with introduction. we can add the template there as well as any other contribution guidelines?

@flacoman91
I see the top section as broader than the templates we are talking about here. What would you think of creating two folder groups? I haven't thought about this in too much detail so I haven't mapped out. But, since it does seem like we will need more documentation it would be good to consider a structure that could start to address the different needs.

Folder: Getting started

Positioned at the top (would replace "Guides" title with "Getting started"
Audience: Designers, developers, general public
Purpose: Welcome visitors to the DSR
Could include: Introduction (could call this one "Welcome" (what is the DSR, links to DS, GitHub repo), How to install the project, etc. (TBD - for now it would just be the existing welcome page)

Folder: Contributing

Positioned at the bottom
Audience: Developers (and Natalia)
Purpose: Provide guidance and templates for contributing and anything else that would be useful to a developer that wants to contribute (TBD)
Could include: Templates (Component, Story, etc.), Component verification checklist, etc.

It's possible that if we build this structure we will have to modify it later but I think having a broad folder at the top that serves as the front door and a narrowly focused folder at the bottom for contributing might be a good start?

natalia-fitzgerald reviewed Feb 9, 2026

View reviewed changes

natalia-fitzgerald requested changes Feb 10, 2026

View reviewed changes

flacoman91 force-pushed the rad-stories-template branch from cff2526 to 35934ac Compare February 10, 2026 01:11

natalia-fitzgerald reviewed Feb 10, 2026

View reviewed changes

natalia-fitzgerald requested changes Feb 10, 2026

View reviewed changes

flacoman91 force-pushed the rad-stories-template branch from 7765e90 to bb0012e Compare February 10, 2026 18:03

flacoman91 force-pushed the rad-stories-template branch from bb0012e to 69145a3 Compare February 10, 2026 18:04

reorder template and sidebar

127d7f9

	<Heading type='4'>Related stories</Heading>
	<Heading type='4'>Component variant</Heading>

	* - Add the link to the component's documentation page in https://cfpb.github.io/design-system/components/
	* - Add the link to the component's CFPB Design System documentation page in https://cfpb.github.io/design-system/components/

Conversation

flacoman91 commented Feb 9, 2026

Uh oh!

github-actions bot commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2026-02-10 19:36 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

natalia-fitzgerald left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

natalia-fitzgerald commented Feb 9, 2026

Uh oh!

flacoman91 commented Feb 9, 2026

Uh oh!

natalia-fitzgerald left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

natalia-fitzgerald left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

natalia-fitzgerald commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

natalia-fitzgerald left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

flacoman91 commented Feb 10, 2026

Uh oh!

flacoman91 commented Feb 10, 2026

Uh oh!

natalia-fitzgerald commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

github-actions bot commented Feb 9, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-02-10 19:36 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

natalia-fitzgerald commented Feb 10, 2026 •

edited

Loading

natalia-fitzgerald commented Feb 10, 2026 •

edited

Loading