Planning & Discovery Overview

apps/docs/src/content/docs/pre-planning/overview Click to copy

Copied! apps/docs/src/content/docs/pre-planning/overview

Complete Build Plan & Documentation

Project: Healthcare Content Hub Web Component Library Target: Enterprise healthcare organizations (Drupal integration) Tech Stack: Lit 3.x + Storybook 10.x + Astro/Starlight + TypeScript Purpose: Implementation roadmap and architecture documentation

Executive Summary

This build plan documents the architecture, implementation strategy, and comprehensive documentation system for WC-2026, an enterprise-grade Web Component library designed for healthcare organizations’ public-facing content hubs. The library integrates seamlessly with Drupal CMS while maintaining complete framework independence.

Key Differentiators

Healthcare-First Design
- WCAG 2.1 AA minimum compliance (HHS mandate May 2026)
- WCAG AAA targets for critical components
- High contrast mode and reduced motion support
- Accessible form components with ElementInternals
Drupal-Optimized Architecture
- Zero coupling to Drupal (library is framework-agnostic)
- Component APIs designed for Drupal field structures
- Complete TWIG integration examples
- Minimal Drupal team integration effort
Enterprise-Grade Quality
- 100% TypeScript with JSDoc documentation
- Custom Elements Manifest as single source of truth
- Three-tier design token system (W3C DTCG compliant)
- Comprehensive test coverage (Vitest 4.x Browser Mode)
- Visual regression testing (Chromatic)
Dual Documentation System
- Storybook: Interactive design system, component playground
- Astro/Starlight: Comprehensive guides, tutorials, integration patterns
Latest 2025-2026 Technologies
- Lit 3.x with Reactive Controllers
- Storybook 10.x with Vitest integration
- Terrazzo for W3C DTCG token generation
- Pagefind for unified cross-system search

Project Goals

Primary Objectives

Establish Technical Leadership: Leverage cutting-edge Web Components, Storybook, and Drupal integration patterns
Create Production-Ready Library: Build reusable component library that reduces development time for healthcare content sites
Minimize Integration Friction: Design components and documentation that make Drupal integration effortless
Ensure Healthcare Compliance: Meet WCAG accessibility requirements and industry standards
Enable Design System Adoption: Provide comprehensive documentation for multiple stakeholder types

Success Criteria

Complete architectural documentation reviewed and approved
Component library structure defined with 40+ component specifications
Design token system implemented with light/dark/high-contrast modes
Storybook configured with Lit 3.x integration
Astro/Starlight documentation hub architecture finalized
Component Building Guide completed for front-end developers
Drupal Integration Guide completed for Drupal teams
Testing strategy defined with Vitest 4.x + Chromatic
Architecture decision records documented

Document Index

This build plan consists of 6 comprehensive documents organized by domain:

Core Architecture Documents

02. Architecture & System Design

Author: Principal Engineer Size: ~900 lines Covers:

Overall system architecture (npm workspaces + Turborepo monorepo)
Latest Lit + Storybook integration patterns (2025-2026)
Drupal integration architecture (npm + CDN delivery)
Testing strategy (Vitest 4.x Browser Mode)
3-tier design token system (W3C DTCG compliant)
Build and deployment pipeline
Technology decision log

Key Decisions:

Storybook 10.x with @storybook/web-components-vite
Custom Elements Manifest (CEM) as machine-readable API contract
Vitest 4.x with Browser Mode (Playwright provider)
Style Dictionary 4.x for token generation
Zero Drupal coupling (clean separation boundary)

03. Component Architecture & Storybook Integration

Author: Senior Frontend Engineer Size: 2,183 lines Covers:

Lit 3.x component architecture patterns
Component library structure (40+ components)
Storybook story configuration and variants
TypeScript & JSDoc strategy (100% coverage)
Drupal integration documentation strategy
Testing implementation (unit, integration, E2E, visual)
Accessibility testing (4-level strategy)
Architecture decision records

Key Patterns:

Reactive Controllers over mixins
Form-associated custom elements (ElementInternals)
Context Protocol for theme/i18n
Typed custom events with WcEventDetailMap
Shadow DOM vs. Light DOM decision matrix

03. Design System & Token Architecture

Author: Design System Developer Size: 2,063 lines Covers:

W3C DTCG 2025.10 compliant 3-tier token system
Light/dark/high-contrast mode architecture
CSS architecture for Shadow DOM components
Typography system (Major Third scale, fluid type)
Spacing & layout system (4px grid, container queries)
Healthcare-specific accessibility (WCAG AAA targets)
Storybook and Drupal integration strategies
4-phase implementation roadmap

Key Technologies:

Terrazzo (successor to Cobalt UI) for token generation
OKLCH color space for perceptual consistency
CSS custom properties for theme switching
CSS Shadow Parts for escape-hatch styling

Documentation & Integration Guides

04. Documentation Hub Architecture

Author: Principal Engineer Size: ~1,200 lines Covers:

Astro/Starlight vs. alternatives (rationale)
Two-system strategy (Storybook + Starlight)
Site information architecture (3 audience types)
CEM-powered API documentation generation
Storybook iframe embedding strategy
Unified search (Pagefind with merged indexes)
Content authoring workflow (MDX, TWIG highlighting)
Build & deployment pipeline
Monorepo integration

Key Decisions:

Astro 5.x + Starlight for documentation hub
Pagefind for unified cross-system search
CEM as single source of truth (feeds both systems)
Co-deployment strategy (same domain for CORS)
Cloudflare Pages for hosting

Audience Segmentation:

Component Builders: 10 guide pages
Drupal Teams: 9 guide pages
Designers: 8 guide pages

05. Component Building Guide

Author: Senior Frontend Engineer Size: 2,238 lines / ~82KB Covers:

Drupal-friendly component patterns (attributes, slots, events)
Data structure patterns (flat attributes, JSON handling)
12 complete component specifications with TWIG examples:
- wc-content-card (article teaser)
- wc-article-header (hero banner)
- wc-media (image/video/audio)
- Form components (wc-text-input, wc-textarea, wc-select, etc.)
- wc-nav (navigation with Drupal menu tree)
- wc-hero-banner, wc-accordion, wc-alert
Testing checklist (40+ items)
Anti-patterns to avoid (8 documented patterns)
Component lifecycle & Drupal (AJAX, BigPipe, MutationObserver)
Theming guidelines (CSS custom properties, Shadow Parts)

Target Audience: Front-end developers and designers building Web Components

Key Value: Teaches component builders how to create components that minimize Drupal integration effort

06. Drupal Integration Guide

Author: Design System Developer Size: ~2,100 lines Covers:

Library installation (3 methods: npm, CDN, module wrapper)
TWIG integration patterns (7 patterns)
Node templates (article teaser, article full, landing page, Layout Builder)
Field template integration (overrides, custom field formatters)
Views integration (custom templates, style plugins)
Form integration (Form API, hook_form_alter())
JavaScript behaviors (analytics, AJAX, event delegation)
Theming & customization (CSS custom properties, ::part())
Performance optimization (lazy loading, caching, service workers)
Accessibility checklist (30+ items)
Troubleshooting (5 common issue categories)
Upgrade & maintenance (semver, testing, rollback)
Real-world example (“Regional Health Partners” site)

Target Audience: Drupal developers integrating the Web Component library

Key Value: THE reference guide for consuming the library in Drupal sites

Technology Stack

Core Technologies

Technology	Version	Purpose
Lit	3.x	Web Component framework (5KB runtime)
TypeScript	5.x	Type safety, JSDoc documentation
Storybook	10.x	Component playground, design system
Vitest	4.x	Testing framework (Browser Mode)
Astro	5.x	Documentation site generator
Starlight	0.32+	Documentation theme
Terrazzo	Latest	Design token build tool (W3C DTCG)
npm	10.x	Monorepo package manager

Supporting Tools

Custom Elements Manifest (CEM): Machine-readable component API
Pagefind: Static site search (no Algolia dependency)
Chromatic: Visual regression testing
Playwright: Browser automation for testing
Expressive Code: Syntax highlighting (Shiki-based)
Web Test Runner: Component testing (alternative to Vitest)

Deployment

Cloudflare Pages: Documentation + Storybook hosting (recommended)
Alternatives: Vercel, Netlify, GitHub Pages
CDN: Self-hosted for healthcare production (jsDelivr for prototyping)

Architecture Overview

System Components

wc-2026/
├── packages/
│   └── wc-library/           # Standalone Web Component library (npm package)
│       ├── src/
│       │   ├── components/   # Lit components
│       │   ├── controllers/  # Reactive controllers
│       │   ├── styles/       # Shared styles
│       │   └── tokens/       # Design tokens (generated by Terrazzo)
│       ├── dist/             # Build output (ES2021 modules)
│       └── custom-elements.json  # CEM (generated)
│
├── apps/
│   ├── storybook/            # Storybook design system
│   │   ├── stories/          # Component stories
│   │   ├── .storybook/       # Storybook config
│   │   └── dist/             # Static build (deployed with docs)
│   │
│   └── docs/                 # Astro/Starlight documentation hub
│       ├── src/
│       │   ├── content/
│       │   │   ├── docs/     # Documentation pages
│       │   │   ├── api/      # Auto-generated from CEM
│       │   │   └── tokens/   # Auto-generated from tokens
│       │   └── components/   # Astro components
│       └── public/
│           └── storybook/    # Copied from apps/storybook/dist/
│
└── build-plan/               # This directory
    ├── index.md              # This file
    ├── 02-architecture-and-system-design.md
    ├── 04-documentation-hub-architecture.md
    ├── 05-component-building-guide.md
    └── 06-drupal-integration-guide.md

Data Flow

Source Code (TypeScript + JSDoc)
    ↓
[CEM Analyzer] → custom-elements.json
    ↓
    ├─→ Storybook (autodocs, controls)
    └─→ Starlight (API reference pages)

Design Tokens (DTCG JSON)
    ↓
[Terrazzo] → CSS Custom Properties
    ↓
    ├─→ Lit Components (consume tokens)
    ├─→ Storybook (token visualization)
    └─→ Starlight (token documentation)

Drupal Integration Points

WC Library (npm package)
    ↓
Drupal libraries.yml (asset loading)
    ↓
    ├─→ TWIG Templates (component usage)
    ├─→ Drupal Behaviors (event handling)
    └─→ Theme CSS (token customization)

3-Tier Design Token System

Token Hierarchy

Tier 1: Primitives (Base) - Private, not exported

Raw color palettes (OKLCH)
Base spacing scale (4px grid)
Base typography scale (Major Third 1.250)

Tier 2: Semantic (Decision) - Public API

Surface colors (--hds-surface-primary, --hds-surface-secondary)
Text colors (--hds-text-primary, --hds-text-secondary)
Interactive colors (--hds-interactive-primary-default)
Feedback colors (--hds-feedback-success, --hds-feedback-error)
Spacing tokens (--hds-space-inset-md, --hds-space-stack-lg)
Typography composites (--hds-type-heading-1, --hds-type-body-md)

Tier 3: Component - Component-specific overrides

Button tokens (--wc-button-background, --wc-button-text)
Card tokens (--wc-card-background, --wc-card-border)
Three-level fallback chain: component → semantic → hardcoded

Theme Modes

Light Mode: Default theme
Dark Mode: High contrast, reduced eye strain
High Contrast Light: WCAG AAA+ contrast ratios
High Contrast Dark: WCAG AAA+ contrast ratios

Mode switching via data-theme attribute + CSS custom properties (zero JavaScript).

Component Library Structure

Atomic Design Hierarchy

Atoms (16 components)

Buttons, inputs, icons, badges, avatars, spinners

Molecules (14 components)

Cards, alerts, breadcrumbs, pagination, search bars

Organisms (11 components)

Headers, navigation, footers, sidebars, hero banners

Templates (3 layouts)

Article layout, landing page layout, search results layout

Example Components for Healthcare Content Hub

Component	Purpose	Drupal Mapping
`wc-content-card`	Article teaser	`node--article--teaser.html.twig`
`wc-article-header`	Article hero	`node--article--full.html.twig` (header region)
`wc-media`	Image/video/audio	`field--field-media-*.html.twig`
`wc-nav`	Primary navigation	`menu--main.html.twig`
`wc-text-input`	Form field	`form-element.html.twig` (override)
`wc-alert`	Status messages	`status-messages.html.twig`
`wc-accordion`	FAQ	Paragraph type `paragraph--faq.html.twig`
`wc-hero-banner`	Landing page hero	Paragraph type `paragraph--hero.html.twig`

Testing Strategy

Test Pyramid (Vitest 4.x)

60% Unit Tests (Node environment)

Component logic, utilities, helpers
Fast execution, high coverage

30% Integration Tests (Browser Mode - Playwright)

Component rendering, user interaction
Accessibility tests (expect(el).to.be.accessible())
Real browser environment

10% E2E Tests (Playwright)

Full user flows, cross-component interactions
Visual regression (Chromatic)

4-Level Accessibility Testing

Author-time: IDE linting (ts-lit-plugin)
Story-time: Storybook addon-a11y (axe-core)
CI: Chromatic visual regression + axe tests
Manual: Quarterly screen reader testing (JAWS, NVDA)

Healthcare Compliance

WCAG 2.1 AA (Legally Mandated)

HHS mandate effective May 2026 (US healthcare organizations)
EAA (European Accessibility Act) effective June 2025
Color contrast: 4.5:1 for text, 3:1 for large text
Keyboard navigation for all interactive elements
Screen reader compatibility
Focus indicators
Form labels and error messages

WCAG AAA Targets (Healthcare Best Practice)

Color contrast: 7:1 for text, 4.5:1 for large text
Enhanced focus indicators
44x44px touch targets
Text spacing overrides
Windows High Contrast Mode support
Reduced motion support

Documentation Strategy

Dual System Approach

Storybook = Design System

URL: /storybook/ Purpose: Interactive component playground Features:

Live component demos with controls
Visual regression testing
Accessibility testing (addon-a11y)
Design token visualization
Component source code

Primary Audience: Designers, component builders, QA

Starlight = Documentation Hub

URL: / (root) Purpose: Comprehensive guides and tutorials Features:

Getting started guides
Architecture documentation
Component Building Guide
Drupal Integration Guide
API reference (auto-generated from CEM)
Token reference (auto-generated)
Search (Pagefind)

Primary Audience: Developers (front-end + Drupal), architects, tech leads

Single Source of Truth Principle

CEM feeds both Storybook (autodocs) and Starlight (API pages)
Storybook demos embedded in Starlight via iframe (no duplication)
Token documentation generated from DTCG JSON
Each piece of information has exactly one authoritative home

Implementation Roadmap

Phase 1: Foundation (Weeks 1-2)

Week 1: Project scaffolding

npm workspaces + Turborepo monorepo setup
TypeScript configuration (strict mode)
Lit library package structure
ESLint + Prettier configuration
Git repository initialization
CI/CD pipeline setup (GitHub Actions)

Week 2: Design token system

Terrazzo configuration
3-tier token JSON definitions (light/dark/high-contrast)
Token build pipeline
CSS custom property generation
Token documentation pages

Phase 2: Core Components (Weeks 3-6)

Week 3: Atoms

Button, Link, Badge, Icon
Text Input, Textarea, Checkbox, Radio
Avatar, Spinner, Divider

Week 4: Molecules

Content Card, Alert, Breadcrumb
Pagination, Search Bar
Form components (Select, Radio Group)

Week 5: Organisms

Navigation, Header, Footer
Hero Banner, Accordion
Article Header, Media Component

Week 6: Templates

Article Layout, Landing Page Layout
Search Results Layout

Phase 3: Storybook Integration (Week 7)

Storybook 10.x installation
@storybook/web-components-vite configuration
CEM analyzer integration
Story creation for all components (8 variants each)
Accessibility addon configuration
Theme switcher addon
Design token addon

Phase 4: Testing Infrastructure (Week 8)

Vitest 4.x configuration (Browser Mode)
Unit test suite (60% target coverage)
Integration test suite (30% target coverage)
Playwright E2E tests (10% target coverage)
Chromatic visual regression setup
Accessibility test automation (axe-core)

Phase 5: Documentation Hub (Weeks 9-10)

Week 9: Starlight setup

Week 10: Content authoring

Component Building Guide migration
Drupal Integration Guide migration
Getting started tutorials
Architecture documentation
Token documentation pages
TWIG syntax highlighting

Phase 6: Drupal Integration & Polish (Weeks 11-12)

Week 11: Drupal integration testing

Test Drupal site setup (Drupal 10.3+)
npm package integration
TWIG template creation for key components
JavaScript behaviors for event handling
Theme customization with CSS custom properties
Accessibility testing in Drupal context

Week 12: Polish & launch prep

Final accessibility audit (screen readers)
Performance optimization
Documentation review and polish
Example project creation (“Regional Health Partners”)
Version 1.0.0 release
npm package publication

Architecture Highlights

Key Technical Differentiators

CEM as Single Source of Truth
- Custom Elements Manifest powers both Storybook autodocs and Starlight API pages
- Eliminates manual documentation drift
- JSDoc annotations drive 100% documentation coverage
Healthcare Compliance Leadership
- WCAG 2.1 AA legally mandated (HHS May 2026)
- WCAG AAA targets for competitive advantage
- 4-level accessibility testing strategy
- High contrast mode and reduced motion support
Drupal-First Integration Strategy
- Zero coupling (library is framework-agnostic)
- Component APIs designed for Drupal field structures
- Complete TWIG integration examples in Storybook
- Minimal Drupal team effort (comprehensive integration guide)
Enterprise-Grade Architecture
- W3C DTCG-compliant design tokens (2025.10 spec)
- Vitest 4.x Browser Mode (2-10x faster than Jest)
- Storybook 10.x with native Vitest integration
- Terrazzo for cutting-edge token generation
Dual Documentation System
- Storybook for interactive design system
- Astro/Starlight for comprehensive guides
- Unified search across both systems (Pagefind)
- Audience-specific documentation (builders, Drupal teams, designers)
Latest 2025-2026 Technologies
- Lit 3.x Reactive Controllers (vs. mixins)
- Form-associated custom elements (ElementInternals)
- Shadow DOM CSS Parts for escape-hatch styling
- OKLCH color space for perceptual consistency
- Container queries for responsive components
Production-Ready Testing
- 60/30/10 test pyramid
- Visual regression with Chromatic
- Accessibility automation with axe-core
- Real browser testing (not JSDOM)

Risk Assessment

Technical Risks

Risk	Impact	Mitigation
Storybook 10.x	Low	Now running Storybook 10.2.8 with CSF Factories support
Drupal SSR complexity	Low	Skip SSR initially (progressive enhancement)
Browser compatibility	Medium	Target modern evergreen browsers (Chrome 90+, Firefox 88+, Safari 14+)
Design token tooling maturity	Low	Terrazzo is production-ready (Cobalt UI successor)
Healthcare compliance changes	High	Monitor WCAG 2.2/3.0 developments, build for AAA

Project Risks

Risk	Impact	Mitigation
Timeline pressure	High	Prioritize Phase 1-3, defer advanced features
Scope creep	Medium	Lock component list to 40 components, defer others
Stakeholder alignment	Medium	Documentation serves multiple audiences clearly
Team onboarding	Medium	Prioritize architecture documents and getting started guides

Success Metrics

Project Success

Library published to npm (v1.0.0)
40+ components with 100% JSDoc coverage
80%+ test coverage
All components WCAG 2.1 AA compliant
Documentation hub deployed and searchable
Example Drupal integration site functional

Resources & References

Official Documentation

Specifications

Healthcare Compliance

Build Plan Documents

Architecture & System Design - Principal Engineer
Component Architecture & Storybook Integration - Senior Frontend Engineer
Design System & Token Architecture - Design System Developer
Documentation Hub Architecture - Principal Engineer
Component Building Guide - Senior Frontend Engineer
Drupal Integration Guide - Design System Developer

Next Steps

Immediate

Review all 6 documents - familiarize with every architectural decision
Initialize Git repository - version control for all documents
Set up npm workspace - monorepo structure
Configure TypeScript - strict mode, build pipeline
Generate design tokens - Terrazzo configuration
Create first component - wc-button as proof of concept

Long-Term (Weeks 2-12)

Follow implementation roadmap (6 phases)
Iterate on documentation based on feedback
Build community around the library
Publish version 1.0.0 to npm

Document Version: 1.0 Last Updated: February 13, 2026 Author: Tech Lead Team (Principal Engineer, Senior Frontend Engineer, Design System Developer) Status: Ready for review

Document Change Log

Date	Version	Changes	Author
2026-02-13	1.0	Initial comprehensive build plan created	Tech Lead Team

END OF INDEX