Storybook Application

The Storybook application serves as the primary component library documentation and development environment for Charles Schwab's design system. It provides an isolated environment for developing, testing, and documenting React components used across multiple applications in the monorepo.

Overview

• Application: apps/storybook
• Port: 6006
• Version: 1.0.53
• Framework: Storybook 9.0.13 with Next.js integration
• Build Tool: Vite 5.4.16 with React SWC
• Purpose: Component library documentation and isolated component development

Key Features

• Component Documentation: Interactive documentation for shared UI components
• Isolated Development: Develop components in isolation without application context
• Visual Testing: Preview components in various states and configurations
• Accessibility Testing: Built-in a11y addon for accessibility validation
• Design System Integration: Showcases Charles Schwab design tokens and brand guidelines
• Multi-Package Stories: Aggregates stories from @schwab/ui package components
• Font Integration: Charles Schwab brand fonts (Charles Modern, Schwab Icon Font)

Technical Architecture

Framework Stack

Technology	Version	Purpose
Storybook	9.0.13	Component documentation platform
Vite	5.4.16	Fast build tool and dev server
React	19.1.0	Component library framework
Next.js	15.3.2	Framework integration for Storybook
TypeScript	5.8.2	Type safety and development experience
Tailwind CSS	4.0.17	Utility-first styling system

Core Dependencies

Key dependencies from package.json

{
  "@adobe/react-spectrum": "^3.40.1",
  "@schwab/beacon-design-tokens": "^1.24.29",
  "@storybook/addon-a11y": "^9.0.13",
  "@storybook/addon-docs": "^9.0.13",
  "@storybook/nextjs": "^9.0.13",
  "@storybook/react-vite": "^9.0.13",
  "clsx": "^2.1.1",
  "gsap": "^3.12.7",
  "react-syntax-highlighter": "^15.6.1"
}

Monorepo Integration

The Storybook application integrates with several internal packages:

• @schwab/ui: Primary source of component stories and documentation
• @schwab/twconfig: Tailwind CSS configuration and design tokens
• @schwab/beacon-design-tokens: Charles Schwab design system tokens
• Static Assets: Shares assets from www.schwab.com application

Directory Structure

apps/storybook/
├── .storybook/                # Storybook configuration
│   ├── main.ts               # Main Storybook configuration
│   ├── preview.tsx           # Global preview settings
│   ├── tailwind.css          # Tailwind CSS imports
│   └── importExport/         # Custom addons and panels
│       ├── panel.css         # Panel styling
│       └── register.js       # Addon registration
├── docs/                     # Documentation pages
│   └── foundations/          # Design system foundations
│       ├── colors/           # Color palette documentation
│       ├── typography/       # Typography system
│       └── documentation-template/ # Template for new docs
├── public/                   # Static assets
│   ├── marker.svg           # UI icons and markers
│   ├── test-location.jpg    # Test images
│   └── testdata-meganav.json # Mock data for components
├── fonts/                    # Charles Schwab brand fonts
│   ├── CharlesModern-*.woff # Charles Modern font family
│   └── Schwab-Icon-Font.woff # Schwab icon font
├── storybook-static/         # Build output directory
├── vite.config.ts           # Vite configuration
├── tsconfig.json            # TypeScript configuration
├── tsconfig.node.json       # Node.js TypeScript config
└── fx_controls.ts           # Reusable Storybook control definitions

Configuration Architecture

Storybook Configuration

The main Storybook configuration (main.ts) defines:

.storybook/main.ts key configuration

const config: StorybookConfig = {
  stories: [
    '../../../packages/ui/src/components/**/*.mdx',
    '../../../packages/ui/src/components/**/*.stories.@(js|jsx|mjs|ts|tsx)',
    '../docs/**/*.mdx',
  ],
  staticDirs: ['./../../www.schwab.com/public/nextassets', './../public'],
  addons: [
    '@storybook/addon-a11y',
    '@storybook/addon-docs'
  ],
  framework: {
    name: '@storybook/nextjs',
    options: {},
  }
};

Key configuration features:

• Story Sources: Automatically discovers stories from @schwab/ui package
• Static Assets: Shares assets with www.schwab.com application
• Next.js Integration: Uses Next.js framework for component compatibility
• Accessibility: Built-in a11y testing with addon
• Documentation: MDX support for rich component documentation

Vite Integration

vite.config.ts

export default defineConfig({
  plugins: [react()],
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',
      },
    },
  },
});

Features:

• React SWC: Fast React compilation
• Modern SCSS: Latest SCSS compiler API
• Hot Module Replacement: Instant component updates during development

Development Workflow

Local Development

Development commands

# Install dependencies
pnpm install

# Start Storybook development server on port 6006
pnpm dev

# Alternative Storybook command
pnpm storybook

# Build static Storybook site
pnpm build

# Type checking
pnpm type-check

# Build TypeScript only
pnpm build-tsc

# Preview built site (requires Vite)
pnpm preview

# Start Vite development server
pnpm vite-dev

Component Development Process

1. Create Component: Develop component in packages/ui
2. Write Story: Create .stories.tsx file for component
3. Add Documentation: Include MDX documentation
4. Preview: View component in Storybook at localhost:6006
5. Test: Use accessibility addon for validation
6. Build: Generate static documentation site

Design System Integration

Charles Schwab Fonts

The application configures Charles Schwab brand fonts:

Font configuration in preview.tsx

const charlesModern = localFont({
  src: [
    { path: './../fonts/CharlesModern-Bold.woff', weight: '700' },
    { path: './../fonts/CharlesModern-Regular.woff', weight: '400' },
    { path: './../fonts/CharlesModern-Light.woff', weight: '300' },
    // Additional font variants...
  ],
  display: 'swap',
});

const schwabIcon = localFont({
  src: [
    { path: './../fonts/Schwab-Icon-Font.woff', weight: '700' },
  ],
});

Design Tokens Integration

• Beacon Design Tokens: Charles Schwab's design system tokens
• Tailwind Configuration: Shared Tailwind CSS setup from @schwab/twconfig
• Color System: Documented color palettes and usage guidelines
• Typography: Font sizes, weights, and hierarchy documentation

Story Organization

Story Discovery

Storybook automatically discovers stories from:

1. UI Package Components: packages/ui/src/components/**/*.stories.*
2. Documentation Pages: docs/**/*.mdx
3. Component MDX: packages/ui/src/components/**/*.mdx

Story Structure

Control Definitions

The fx_controls.ts file provides reusable control definitions for consistent story interfaces:

Example control definitions

export const palette = {
  table: { category: 'styles' },
  control: 'select',
  options: [false, 1, 2, 3, 4, 5],
};

export const bleed = {
  table: { category: 'styles' },
  control: 'select',
  options: ['default', 'wide', 'xwide', 'full'],
};

These controls enable:

• Consistent UI: Standardized control interfaces across stories
• Category Organization: Grouped controls by functionality
• Type Safety: TypeScript definitions for control options
• Reusability: Shared control definitions across components

Build and Deployment

Build Process

1. TypeScript Compilation: Component type checking and compilation
2. Story Aggregation: Discovery and compilation of all stories
3. Asset Optimization: Font and image optimization
4. Static Generation: Static HTML/CSS/JS bundle creation
5. Documentation Generation: MDX compilation to HTML

Static Build Output

The build generates a static site in storybook-static/ containing:

• Component Documentation: Interactive component playground
• Design System Guidelines: Foundation documentation
• Asset Files: Optimized fonts, images, and icons
• Search Index: Component and documentation search

Environment Configuration

Navigation Integration

The Storybook includes environment variables for testing navigation components:

Navigation configuration in main.ts

env: (config) => ({
  NEXT_PUBLIC_MEGANAV_BANK_PAGES: '["/bank","/checking",...]',
  NEXT_PUBLIC_MEGANAV_TRUST_PAGES: '["/personal-trust-services",...]',
  NEXT_PUBLIC_MEGANAV_NONAV_PAGES: '["/intelligent-nvidia"]',
})

This enables:

• Navigation Testing: Preview navigation behavior in different contexts
• Page-Specific Behavior: Test components with various page configurations
• Integration Validation: Ensure navigation components work correctly

Accessibility Features

Built-in A11y Testing

• Accessibility Addon: Automated accessibility violation detection
• Color Contrast: Automatic color contrast ratio validation
• Keyboard Navigation: Keyboard accessibility testing
• Screen Reader: ARIA label and role validation
• Focus Management: Focus indicator and tab order testing

Accessibility Documentation

Each component story should include:

• Accessibility Notes: Usage guidelines for screen readers
• Keyboard Interactions: Expected keyboard behavior
• ARIA Attributes: Required ARIA labels and roles
• Color Requirements: Contrast ratio specifications

Testing Strategy

Component Testing

• Isolated Testing: Components tested in isolation from application context
• Visual Regression: Manual visual validation of component states
• Interaction Testing: User interaction simulation and validation
• Responsive Testing: Component behavior across different viewport sizes

Documentation Testing

• MDX Validation: Documentation syntax and rendering validation
• Code Example Testing: Ensure code examples compile and run
• Link Validation: Internal and external link verification

Common Use Cases

Component Development

Example story creation

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from '@schwab/ui';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  parameters: {
    docs: {
      description: {
        component: 'Primary button component for user actions',
      },
    },
  },
};

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Click me',
  },
};

Design System Documentation

Example MDX documentation

# Color System

Charles Schwab's color palette provides a consistent visual foundation.

## Primary Colors

<ColorPalette colors={primaryColors} />

## Usage Guidelines

- Use primary blue for call-to-action buttons
- Reserve red for error states and warnings
- Apply neutral grays for text and backgrounds

Troubleshooting

Common Issues

Issue	Cause	Solution
Port 6006 in use	Previous Storybook process running	Use kill script in dev command
Stories not loading	Incorrect story paths	Check main.ts stories configuration
Font loading issues	Missing font files	Verify font paths in preview.tsx
Build failures	TypeScript errors	Run pnpm type-check
Asset not found	Incorrect static directory	Check staticDirs in main.ts

Development Tips

Performance

Use Storybook's build cache by keeping the .storybook-static directory to speed up subsequent builds.

Font Loading

Charles Schwab fonts are proprietary. Ensure font files are properly licensed and available in the fonts directory.

Integration with Other Applications

Component Library Workflow

Shared Asset Strategy

The Storybook shares static assets with other applications:

• www.schwab.com/public/nextassets: Shared with main website
• Local public/: Storybook-specific assets
• Font files: Brand fonts available to all stories

Future Enhancements

• Visual Regression Testing: Automated screenshot comparison
• Component Performance Testing: Runtime performance monitoring
• Interactive Documentation: Enhanced component playground
• Design Token Automation: Automated token documentation generation
• Multi-Theme Support: Dark mode and alternate theme previews

This Storybook application serves as the central hub for Charles Schwab's design system, enabling consistent component development and comprehensive documentation across the entire monorepo ecosystem.