PDS Storybook

Pure Design System Storybook showcase with live configuration capabilities.

This is the reference Storybook implementation demonstrating all features of the Pure Design System, including:

- 🎨 Live Configuration - Real-time design system updates via embedded configurator
- 🔍 Smart Search - Natural language queries for tokens and components
- 📚 Comprehensive Stories - All tokens, primitives, components, patterns, and enhancements
- 🎯 Best Practices - Organized by design system standards

Features

$3

Click the PDS Configurator button in the Storybook toolbar to open a configuration panel (via pds-drawer[position=bottom]) that includes:

- Full pds-config-form with simple/advanced modes
- Real-time preset switching
- Color, typography, spacing customization
- Export configuration as JSON
- Instant application to all visible stories

$3

Click the search icon in the toolbar to query the design system using natural language:

- "what is the focus border color on inputs?"
- "button hover states"
- "how to create a card layout?"

Powered by the PDS query system from pds-query.js.

$3

Stories are organized following design system best practices:

#### Foundations
Design tokens and core elements:
- Colors - Scales (50-900), semantics, themes
- Typography - Font families, sizes, weights, modular scale
- Spacing - Spatial rhythm, progression
- Icons - Icon system with sprite

#### Primitives
Basic UI building blocks:
- Buttons - Variants, sizes, states, icon buttons
- Forms - Inputs, selects, textareas, validation
- Cards - Surface containers
- Badges - Pills and badges
- Alerts - Notification styles

#### Components
Web Components ():
- pds-icon - SVG sprite icons
- pds-drawer - Slide-out panels
- pds-tabstrip - Accessible tabs
- pds-upload - File upload with preview
- pds-toaster - Toast notifications
- pds-richtext - Rich text editor (prefers #showdown import map; set format="markdown" to submit Markdown)
- pds-form - JSON Schema forms
- pds-splitpanel - Resizable panes
- pds-scrollrow - Horizontal scroll

#### Patterns
Layout patterns and utilities:
- Layout - Grid, flex, containers
- Utilities - Spacing, borders, effects
- Border Effects - Gradients, glows

#### Enhancements
Progressive enhancements for semantic HTML:
- Dropdowns -

- Toggles -
- Range Sliders - Enhanced
- Required Fields - Auto-asterisks

Development

$3

bash

npm install





$3



Auto-generate stories from PDS ontology and demo component:

bash

npm run generate-stories





This reads:

-

src/js/pds-core/pds-ontology.js

 - Component metadata

-

src/js/pds-configurator/pds-demo.js

 - Demo HTML sections



And outputs to

stories/

 organized by groups.



$3

bash

npm run storybook





Opens at http://localhost:6006



$3

bash

npm run build-storybook





Outputs to

storybook-static/

$3

bash

npm run storybook:dev





Generates stories then starts Storybook.



Architecture



$3



This Storybook runs PDS in live mode:

javascript

// .storybook/preview.js

await PDS.start({

  mode: 'live',

  preset: 'default',

  autoDefine: {

    baseURL: '/assets/pds/components/',

    predefine: ['pds-icon', 'pds-drawer']

  }

});





Benefits:

- Styles generated at runtime

- Instant design updates

- Full access to

PDS.compiled

 object model

- Automatic font loading



> ⚠️ Important: Programmatic Component Access

>

> Components loaded via

autoDefine (except those in predefine

) are registered asynchronously. When accessing component methods programmatically in stories or utilities:

>

>

javascript

> // Always wait for the component to be defined

> await customElements.whenDefined('pds-toaster');

> const toaster = document.querySelector('pds-toaster');

> toaster.toast('Message');

>



>

> Components in the

predefine array (pds-icon, pds-drawer) are available immediately after PDS.start()

 completes.



$3



Custom Storybook addon at

.storybook/addons/pds-configurator/

:



Manager Side (

Tool.js

):

- Toolbar button to open configurator

- Search/omnibox for queries

- Event bus communication



Preview Side (

preview.js

):

- Creates

with



- Listens to

pds:design:updated

 events

- Calls

PDS.applyDesign()

 and forces remount



$3

scripts/generate-stories.js

 automatically creates stories by:



1. Parsing

pds-ontology.js

 for component metadata

2. Extracting HTML from

pds-demo.js

 sections

3. Generating CSF3 stories with controls

4. Organizing by groups (foundations/primitives/components/patterns/enhancements)



Customization:

Edit the generator to add new story groups or customize templates.



Story Controls



Each story includes argTypes for interactive customization:

javascript

argTypes: {

  preset: {

    control: 'select',

    options: ['default', 'ocean-breeze', 'midnight-steel', ...]

  },

  primaryColor: {

    control: 'color'

  },

  secondaryColor: {

    control: 'color'

  }

}





Controls trigger

PDS.applyDesign()

 to update the live configuration.



Integration with Consumer Projects



See

packages/pds-storybook-cli

 for CLI tool to integrate PDS into existing Storybook instances.



Configuration



Modify

.storybook/preview.js

 to change:



- Initial preset

- Auto-loaded components

- Theme management

- Global styles application



Files



packages/pds-storybook/

├── .storybook/

│   ├── main.js                      # Storybook configuration

│   ├── preview.js                   # PDS initialization

│   └── addons/

│       └── pds-configurator/        # Custom addon

│           ├── register.js          # Manager registration

│           ├── Tool.js              # Toolbar UI

│           ├── preview.js           # Preview logic

│           └── constants.js         # Event constants

├── scripts/

│   └── generate-stories.js          # Story generator

├── stories/

│   ├── getting-started.md           # Welcome page (imported from project root)

│   ├── foundations/                 # Token stories

│   ├── primitives/                  # Primitive stories

│   ├── components/                  # Component stories

│   ├── patterns/                    # Pattern stories

│   └── enhancements/                # Enhancement stories

└── package.json





Contributing



Stories are auto-generated but can be manually edited. After editing:



1. Test changes:

npm run storybook



2. Regenerate if needed:

npm run generate-stories



3. Commit both generator and generated files



Publishing



This package is private and not published to npm. It serves as:



1. Reference implementation

2. Development environment

3. Story template source for CLI



The CLI (

@pure-ds/storybook`) copies stories from here to consumer projects.

License

ISC

PDS Storybook

Features

$3

- Toggles -
- Range Sliders - Enhanced
- Required Fields - Auto-asterisks

Development

$3

bash

npm install





$3



Auto-generate stories from PDS ontology and demo component:

bash

npm run generate-stories





This reads:

-

src/js/pds-core/pds-ontology.js

 - Component metadata

-

src/js/pds-configurator/pds-demo.js

 - Demo HTML sections



And outputs to

stories/

 organized by groups.



$3

bash

npm run storybook





Opens at http://localhost:6006



$3

bash

npm run build-storybook





Outputs to

storybook-static/

$3

bash

npm run storybook:dev





Generates stories then starts Storybook.



Architecture



$3



This Storybook runs PDS in live mode:

javascript

// .storybook/preview.js

await PDS.start({

  mode: 'live',

  preset: 'default',

  autoDefine: {

    baseURL: '/assets/pds/components/',

    predefine: ['pds-icon', 'pds-drawer']

  }

});





Benefits:

- Styles generated at runtime

- Instant design updates

- Full access to

PDS.compiled

 object model

- Automatic font loading



> ⚠️ Important: Programmatic Component Access

>

> Components loaded via

autoDefine (except those in predefine

) are registered asynchronously. When accessing component methods programmatically in stories or utilities:

>

>

javascript

> // Always wait for the component to be defined

> await customElements.whenDefined('pds-toaster');

> const toaster = document.querySelector('pds-toaster');

> toaster.toast('Message');

>



>

> Components in the

predefine array (pds-icon, pds-drawer) are available immediately after PDS.start()

 completes.



$3



Custom Storybook addon at

.storybook/addons/pds-configurator/

:



Manager Side (

Tool.js

):

- Toolbar button to open configurator

- Search/omnibox for queries

- Event bus communication



Preview Side (

preview.js

):

- Creates

with



- Listens to

pds:design:updated

 events

- Calls

PDS.applyDesign()

 and forces remount



$3

scripts/generate-stories.js

 automatically creates stories by:



1. Parsing

pds-ontology.js

 for component metadata

2. Extracting HTML from

pds-demo.js

 sections

3. Generating CSF3 stories with controls

4. Organizing by groups (foundations/primitives/components/patterns/enhancements)



Customization:

Edit the generator to add new story groups or customize templates.



Story Controls



Each story includes argTypes for interactive customization:

javascript

argTypes: {

  preset: {

    control: 'select',

    options: ['default', 'ocean-breeze', 'midnight-steel', ...]

  },

  primaryColor: {

    control: 'color'

  },

  secondaryColor: {

    control: 'color'

  }

}





Controls trigger

PDS.applyDesign()

 to update the live configuration.



Integration with Consumer Projects



See

packages/pds-storybook-cli

 for CLI tool to integrate PDS into existing Storybook instances.



Configuration



Modify

.storybook/preview.js

 to change:



- Initial preset

- Auto-loaded components

- Theme management

- Global styles application



Files



packages/pds-storybook/

├── .storybook/

│   ├── main.js                      # Storybook configuration

│   ├── preview.js                   # PDS initialization

│   └── addons/

│       └── pds-configurator/        # Custom addon

│           ├── register.js          # Manager registration

│           ├── Tool.js              # Toolbar UI

│           ├── preview.js           # Preview logic

│           └── constants.js         # Event constants

├── scripts/

│   └── generate-stories.js          # Story generator

├── stories/

│   ├── getting-started.md           # Welcome page (imported from project root)

│   ├── foundations/                 # Token stories

│   ├── primitives/                  # Primitive stories

│   ├── components/                  # Component stories

│   ├── patterns/                    # Pattern stories

│   └── enhancements/                # Enhancement stories

└── package.json





Contributing



Stories are auto-generated but can be manually edited. After editing:



1. Test changes:

npm run storybook



2. Regenerate if needed:

npm run generate-stories



3. Commit both generator and generated files



Publishing



This package is private and not published to npm. It serves as:



1. Reference implementation

2. Development environment

3. Story template source for CLI



The CLI (

@pure-ds/storybook`) copies stories from here to consumer projects.

License

ISC