Spike & Implementation: Migrate Component Library from Storybook to Lookbook

Background

Our component library is currently documented in Storybook, which is not native to Django. This has resulted in components living in a separate repository, disconnected from the actual components used in the application. The core risk here is drift — as the application evolves, there is no guarantee that what is documented in Storybook reflects what is actually being rendered in production. This creates confusion for developers, slows down onboarding, and undermines the reliability of the component library as a source of truth.

Lookbook, as a native Django solution, resolves this by co-locating component previews directly within the application, ensuring documentation and implementation are always in sync.

Spike Objectives

Before committing to a full migration, a spike is required to:

• Assess the current state of components in Storybook and map them to their counterparts in the application
• Validate that Lookbook can support our existing component patterns and requirements
• Identify any components that may require refactoring as part of the migration
• Estimate the effort required for a full migration
• Document a recommended migration approach for the team

Implementation

Following the spike, the implementation should:

• Migrate all existing Storybook components into Lookbook, co-located with their application counterparts
• Deprecate the Storybook repository upon successful migration
• Ensure all component previews are accurate and reflect the current production state
• Update developer documentation to reflect the new workflow

Definition of Done

• Spike findings documented and shared with the team
• All components successfully migrated to Lookbook
• Storybook repository deprecated
• No orphaned or undocumented components remaining