Skip to main content

The ui Directory

This page provides a detailed analysis of the /home/nextjs-web/packages/ui directory, which contains the @schwab/ui package - the centralized React component library used across all Schwab applications.

Package Overview​

Package Name: @schwab/ui
Version: 1.0.0
Type: ES Module
Private: No (can be published)
License: MIT

The ui package is the largest and most complex package in the monorepo, serving as the foundation for all user interface components across Schwab's Next.js applications.

Root Directory Structure​

/home/nextjs-web/packages/ui/
├── .allowlists/           # Exception lists for conformance rules
├── .vercel.approvers      # Deployment approval settings
├── components.json        # Shadcn/ui configuration
├── context.ts            # React context definitions
├── global.d.ts           # TypeScript global type definitions
├── jest.config.json      # Jest testing configuration
├── jest.cicd.config.json # CI/CD specific Jest config
├── node_modules/         # Package dependencies (large)
├── package.json          # Package configuration (310+ lines)
├── src/                  # Source code directory
├── testing.d.ts          # TypeScript testing type definitions
├── tsconfig.json         # TypeScript configuration
└── turbo/               # Turborepo cache directory

Source Code Structure (src/)​

Main Directories​

src/components/ - Core Component Library​

Contains 60+ production-ready React components organized by functionality:

UI Foundation Components:

  • Button/, Link/, Card/, Container/, Divider/
  • Dialog/, Modal/, Sheet/, Popover/, Toast/
  • Table/, Pagination/, Accordion/, Tabs/

Content Components:

  • Heading/, RichText/, Image/, Video/, Audio/, PDF/
  • ArticleTile/, Tile/, Collection/, Deck/, DeckTile/
  • Story/, StoryHeader/, StoryRelatedContent/

Navigation Components:

  • Meganav/, NavContainer/, NavItem/, SearchBar/
  • GlobalFooter/, PageFooter/, Breadcrumbs/

Business-Specific Components:

  • Person/, LockupPerson/, PersonRelatedContent/
  • Topic/, TopicRelatedContent/, SeriesHeader/
  • PatternLandingPage/, CtaPanel/, Marquee/

Utility Components:

  • CaptureQueryParams/, Debug/, VercelEnvOutput/
  • SchwabDataLayer/, ReactPortal/, ZodErrorOutput/

External Integrations:

  • GoogleMaps/, MapMarker/, HighChart/, Icons/
  • SocialLinks/, SocialShare/, Podcast/, PodcastLink/

src/Loaders/ - Data Loading Components​

Specialized components for loading and managing data:

Loaders/
├── CollectionLoader/      # Loads collection data from CMS
├── DynamicCtaLoader/      # Dynamic call-to-action content
├── GlobalFooterLoader/    # Footer content and links
├── MegaNavLoader/         # Navigation structure and content
├── PatternLandingPageLoader/ # Landing page template data
├── PersonLoader/          # Person profile information
├── QuerySetLoader/        # Database query results
├── Search/               # Search functionality and results
├── StoryLoader/          # News and article content
├── TopicLoader/          # Topic-based content aggregation
└── __test_tools__/       # Testing utilities for loaders

Purpose: These loaders abstract data fetching logic and provide consistent interfaces for loading content from various sources (CMS, APIs, databases).

src/utilities/ - Shared Utilities​

Supporting functions and utilities:

utilities/
├── cva/              # Class Variance Authority utilities
├── dictionaries/     # Internationalization and content dictionaries
├── functions/        # General utility functions
├── hooks/           # Custom React hooks
├── services/        # External service integrations
└── shad/            # Shadcn/ui utility functions

src/styles/ - Styling Infrastructure​

Comprehensive styling system:

styles/
├── _breakpoints.scss      # Responsive breakpoint definitions
├── _fonts.scss           # Font family and weight definitions
├── _grid.scss            # CSS Grid system utilities
├── _tailwind-typography.scss # Typography plugin styles
├── _typography.scss      # Typography scale and styles
├── common.module.scss    # Common CSS modules
├── globals.scss          # Global styles and resets
├── scss/                # Additional SCSS modules
└── tailwind-global-transition-styles.scss # Animation transitions

src/fetch-test/ - Testing Infrastructure​

Testing utilities specific to the ui package.

src/jsonld/ - Structured Data​

JSON-LD schema components for SEO and structured data.

src/Ups/ - UX/UI Patterns​

User experience patterns and advanced UI compositions.

Package Configuration​

Path Mapping System​

The package uses extensive path mapping for clean imports:

{
  "imports": {
    "#components/Button": "./src/components/Button/Button.tsx",
    "#components/Card": "./src/components/Card/Card.tsx",
    "#components/Dialog": "./src/components/Dialog/Dialog.tsx",
    // ... 100+ mapped component paths
  }
}

Benefits:

  • Clean import statements: import { Button } from '#components/Button'
  • Refactoring safety - paths can be changed without breaking imports
  • IDE autocomplete support for component discovery

Shadcn/ui Integration​

The package is configured to work with Shadcn/ui:

{
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "../twconfig/src/base/theme.css",
    "cssVariables": true
  },
  "iconLibrary": "lucide"
}

Features:

  • React Server Components support
  • TypeScript first approach
  • CSS Variables for theming
  • Lucide icons integration
  • Integration with @schwab/twconfig package

Component Architecture​

Component Structure Pattern​

Most components follow this structure:

ComponentName/
├── ComponentName.tsx        # Main component implementation
├── ComponentName.server.tsx # Server component variant (if needed)
└── __tests__/              # Component-specific tests
    └── ComponentName.test.tsx

Server vs Client Components​

The package supports both:

  • Server Components (.server.tsx) - for server-side rendering
  • Client Components (.tsx) - for interactive functionality

Testing Strategy​

  • Jest for unit testing
  • Component-specific test files in __tests__/ directories
  • CI/CD specific configurations for automated testing
  • Test tools and utilities in dedicated directories

Key Dependencies​

The package has 310+ lines in package.json, indicating extensive dependencies:

Core Framework:

  • React 19
  • Next.js integration
  • TypeScript support

Styling:

  • Tailwind CSS integration
  • SCSS/Sass support
  • Class Variance Authority (CVA)

Testing:

  • Jest testing framework
  • React Testing Library
  • Testing utilities

External Services:

  • Google Maps integration
  • Chart.js/HighCharts
  • Social media integrations

Usage Across Applications​

The ui package is imported by all applications in the monorepo:

// In any application
import { Button } from '@schwab/ui'
import { Card } from '#components/Card'  // If using path mapping
import { PersonLoader } from '@schwab/ui/Loaders'

Development Workflow​

Working with UI Components​

# Navigate to the ui package
cd /home/nextjs-web/packages/ui

# Run tests
pnpm test

# Watch mode for development
pnpm test:watch

# Type checking
pnpm type-check

# Build the package
pnpm build

Adding New Components​

  1. Create component directory in src/components/
  2. Implement component following existing patterns
  3. Add path mapping in package.json imports
  4. Write tests in __tests__/ directory
  5. Update exports if needed
  6. Document usage patterns

Component Development Guidelines​

  • Server Components first - use .server.tsx when possible
  • TypeScript strict mode - full type safety
  • Responsive design - mobile-first approach
  • Accessibility - WCAG compliance
  • Testing - comprehensive test coverage
  • Documentation - clear usage examples

Integration Points​

With Other Packages​

  • @schwab/utilities - shared utility functions
  • @schwab/twconfig - Tailwind CSS configuration
  • @schwab/schema - type validation
  • @schwab/fetch - data loading in Loader components

With Applications​

  • www.schwab.com - primary consumer of all components
  • client.schwab.com - uses specialized client components
  • storybook - component documentation and testing
  • All applications - foundation for consistent UI/UX

This ui package serves as the design system and component library foundation for Schwab's entire Next.js ecosystem, ensuring consistency, reusability, and maintainability across all applications.