[Exploration] Storybook organization

[natalia-fitzgerald]

The goal of this issue is to explore ways of organizing/structuring the CFPB React component library in Storybook.

Task

• Gather structure/organization examples of other Storybook component libraries
• Share approaches with the Design Engineering team
• Make a decision about how we would like to structure/organize the content

Storybook libraries

• https://design.va.gov/storybook/
• https://trussworks.github.io/react-uswds/
• https://govuk-react.github.io/govuk-react/
• https://react.carbondesignsystem.com

[natalia-fitzgerald]

Exploration 1:

Here's an example from the Storybook website.

It seems like a pretty simple approach:

• The page/tab we now label "Overview" would be labeled "Docs"
• Each variation/type would be a "Story"
• They do not show overt visuals of the different states on the page.
• Following on the "Buttons" example our Stories would be
  • Primary
  • Secondary
  • Disabled
  • Destructive
  • Printed
  • Super
  • Full-width
  • Group
  • Static icon (may be covered by the pagination component)
  • Animated icon (confirm use case for SBL)

[meissadia]

Things I like about each Storybook configuration

• Carbon
  • All stories are on a single page, though I also like the ability to focus/modify a single variant at a time (like our current implementation)
  • Groupings (Components vs Elements)
• USWDS
  • Ability to toggle between Canvas/Docs
  • GOVUK
  • Their Welcome page gives nice context on how to use the library
  • Their grouping (Form, Typography, Navigation, Layout)
• VA
  • How to use Storybook
  • Additional guidance in the component's Overview header

[natalia-fitzgerald]

GOV.UK

• Content is broken up into categories that include form, typography, page and layout, and navigation
• Categories are not in alphabetical order (so what is the ordering logic?)
• Types within categories are alphabetized

Welcome

Example Application

FORM

Button Checkbox Date field Error summary Error text Fieldset File upload Form group Hint text Input field Input Label text Label Multi choice Radio Search box Select Textarea

TYPOGRAPHY

Caption Details Document Footer Metadata Heading Inset text Lead paragraph List item Ordered list Paragraph Phase banner Table Tag Unordered list Warning text

PAGE & LAYOUT

Footer GlobalStyle Grid col Grid row Main Page Panel Section break Top nav

NAVIGATION

Back link Breadcrumbs Link Pagination Related items Skip link Tabs

UTILITY

Loading box Visually hidden Icons

DOCS

Accessibility API Contributing

USWDS

• Components is a very large bucket of alphabetized components

Welcome

DESIGN TOKENS

Swatches

Page Templates

Authentication Pages Documentation Pages Landing Page Not Found Page

Components

Accordion Alert Banner Breadcrumb Button Button groups Card CharacterCount Checkbox Collection Combo box Date input Date picker Date range picker Dropdown File input Footer Form controls Form elements Form templates Grid Header Icon list Icons Identifier Input prefix or suffix Modal Pagination ProcessList Radio buttons Range slider Search Select Side navigation SiteAlert Step Indicator Summary box Table Tag Text input Textarea Tooltip Typography Validation

CFPB Design System

• Sections are sometimes not meaningful, for example “Lists and tables” section contains Lists and Tables pages

Foundation

BASICS

Color Grid

TYPOGRAPHY

Fonts Headings Paragraphs

BRAND SYMBOLS

Logo Seal

GRAPHICS

Iconography

Components

ALERTS

Banner notification Notifications

BEHAVIOR

Expandables Summaries

FORM ELEMENTS

Buttons Checkboxes Dropdowns and multiselects Fieldsets Helper text Labels and legends Links Radio buttons Range sliders Text inputs

LISTS AND TABLES

Lists Tables

Patterns

INTERACTION PATTERNS

FORMS

Designing forms E-mail signup forms

NAVIGATION

Filterable list control panels Pagination

TRANSITIONS

Transition patterns

LAYOUT PATTERNS

INTRODUCTIONS

Heroes Text introductions Item introductions

FEATURED CONTENT

Cards Featured content module Wells Taglines

MAIN CONTENT

Info unit groups Interactive charts

Pages

Landing pages Sublanding pages Browse pages Learn pages Filterable list pages Document detail pages Story pages

Development

ATOMIC

Atomic components

LAYOUT

Base images Blocks Column dividers Main content and sidebars

UTILITIES

Helper classes and mixins Media queries Variables

[natalia-fitzgerald]

CFPB Design System - Mapped to GOV.UK

• This is an attempt at mapping the CFPB DS to more of a UK.gov approach. I have placed an * next to content that is either missing from our library or has some other inconsistency
• There is a question of how best to break things up into separate components (For example Text input and text area are in the same DS section. Should they be separated into individual components?
• If we added a category called "Elements" what would you put in there from the CFPB DS list posted here
• I think that a large part of the component library will relate to forms. It seems like we have the option of showing all of the form combinations on a component by component basis, isolate the variables as their own component. We should discuss what would be most useful for developers.

Welcome

Example Application

Form

Checkboxes Buttons Date field (date picker) Dropdowns and multiselects Error summary Error text Fieldsets File upload Form group (USWDS + UK) Form templates (USWDS) Helper text (this is called hint text in USWDS and UK) Labels and legends Alerts -- Notifications -- (this contains in page notifications, inline notifications and form level alerts - should probably be broken up differently for our context) Radio buttons Text fields/inputs (Text input and text area input - should we break these apart?) Search box

Navigation

Breadcrumbs Links Pagination Related links

Page and Layout

Cards “Divider”* (horizontal rule) Footer Grid Header Heroes Item introductions Megamenu Text introductions Wells Taglines

Typography

Headings Icon list (USWDS) Icons Inset text Lead paragraph List item Ordered list Paragraph Table Tag Unordered list

[meissadia]

My attempt at grouping the pieces of the CFPB DS in a more cohesive way

* = Not Implemented @ = Does it belong in DSR?

Design Guidance*@

Links to documentation or things that do not have an associated implementation

• Accessibility
• Data Visualization
• Equity-centered Design
• Print
• Patterns
  • Designing Forms
  • Pages*@
    • Should these be implemented as Layout components?
  • Transitions

Content

Components to structure and style content

• Text
  • Heading
  • Paragraph
    • Body
    • Lead
    • Subheading
  • HelperText
  • Label
• Graphics & Media
  • Chart*?
  • Icon
  • Images*
    • Image*
    • Figure*
  • Video*
• Featured Content
  • Banner/Tagline
  • Cards*
  • Expandable
  • FeaturedModule*
  • Info Units*@
  • Introductions
    • IntroHero (Hero)
    • IntroText*
    • IntroItem*
  • Notification
  • Summaries*
  • Well
• Structured Content
  • List
  • Table

Layout

Components to structure pages

• Block*
• Divider
  • RowDivider (Divider)
  • ColumnDivider*
• Footer
• Grid
• Header (PageHeader)
• Page Layouts
  • MainWithSidebar
  • MainWithLeftSidebar
  • MainWithBleedbar
• Navigation
  • Link
  • Navbar
  • SkipNav
  • Pagination

User Inputs

Components to gather user input (not always in a Form? ex. Login button used as Nav element)

• Button
• Checkbox
• Dropdown
• EmailSignup*
• Fieldset*
• FilterPanel*
• Radio*
• Range*@
• Text
  • InputText
  • AreaText*
  • DateText*
  • InputTextWithButton*
  • InputTextWithButtonInside*

Utilities

Tools to assist with common dev tasks

• Color*
• Helper classes and mixins*
• Media queries*@
• Variables*@

[meissadia]

General emphasis on matching heading levels between custom overviews <=> Auto generated

• How can we customize the auto generated heading levels?
  • Need to make all overviews custom?
  • Can we remove the Stories section label from auto pages?
  • How would that affect the page heading hierarchy?
  • Could we change the headings used for, what are currently, nested sections?