Carbon Gatsby Theme
Led development of gatsby-theme-carbon during IBM’s migration to Carbon v10 and the new IBM Design Language. Instead of building separate sites, I partnered with design to deliver a unified Gatsby theme that now powers an ecosystem of both internal and external IBM websites.
Summary
As development lead, created gatsby-theme-carbon to unify IBM's design ecosystem under a single, reusable Gatsby theme. Built during the Carbon v10 and IBM Design Language migration, the theme now powers hundreds of internal and external repositories and enables teams to launch IBM Design Language-compliant sites in hours rather than months. Partnered closely with designers to ensure the theme properly expressed design principles while creating sustainable architecture for content authors and developers.
Background
The Challenge: With the launch of Carbon v10 and the new IBM Design Language, IBM needed to rebuild both the Carbon Design System website and the IBM Design Language website. Building these separately would have duplicated effort and risked inconsistency across IBM's design presence. Meanwhile, teams across IBM struggled to create sites that properly reflected the IBM Design Language without dedicated development resources.
The Opportunity: Gatsby's theme system provided a way to encapsulate all configuration and implementation details into a reusable package. This meant we could build once and enable dozens of teams to launch consistent, high-quality sites with minimal technical overhead.
My Role: As development lead, I owned the technical architecture and implementation strategy while partnering closely with Carbon designers to ensure the theme properly expressed the IBM Design Language across different use cases.
Approach
Theme Architecture & Gatsby Integration:
- Built on Gatsby's theme composition system, allowing teams to shadow (override) components while maintaining core functionality
- Implemented MDX-first content strategy, enabling content authors to write in Markdown with embedded React components
- Created flexible component shadowing system that balanced consistency with customization needs
Design System Integration:
- Integrated Carbon React components as the foundation while building theme-specific patterns for common website needs
- Ensured automatic adherence to IBM Design Language principles through built-in typography, spacing, and color systems
- Created documentation site architecture that worked for both technical and brand-focused content
Content Author Experience:
- Designed MDX-based content system that allowed non-technical team members to create rich, interactive pages
- Built sidebar navigation system that is easily configurable for designers, developers or content editors
Scalability & Maintenance:
- Established versioning strategy that allowed theme updates to propagate across all dependent sites
- Built theme with plugin architecture to support different site needs (documentation, marketing, events)
- Created starter templates and comprehensive documentation to reduce onboarding friction
Challenges
Technical Complexity Across Team Skills: The theme needed to serve both highly technical developers building documentation sites and content creators with minimal coding experience. Balancing powerful customization capabilities with simple content authoring required careful API design and extensive testing with both user types.
IBM Design Language Translation: Converting IBM Design Language principles from print and brand guidelines into flexible web patterns was challenging. Each component needed to work across different content types while maintaining consistent brand expression. This required close collaboration with designers to validate that the theme truly captured the intended design language.
Cross-Team Coordination: As the theme gained adoption, managing feedback and feature requests from multiple teams required careful prioritization. Each team had specific needs, but changes needed to benefit the broader ecosystem without breaking existing implementations.
Outcomes
Adoption & Scale:
- Powers hundreds of internal and external repositories according to GitHub dependency tracking
- Serves as foundation for major IBM design properties including IBM Design, Carbon Design System, IBM Design Language, and IBM Design Research
- Receives ~1,127 weekly npm downloads demonstrating active community usage
Developer & Content Author Efficiency:
- Teams report migrating entire sites to the theme "in a matter of hours" versus months for custom development
- Content creators can launch new sites without dedicated development resources
- Testimonials highlight ability to focus on content rather than technical implementation
Design Consistency:
- Automatic compliance with IBM Design Language across all implementing sites
- Shared component library ensures visual solidarity across IBM's design ecosystem
- Theme-managed configuration eliminates common implementation inconsistencies
Technical Foundation:
- Created reusable model for design system-driven website themes
- Established patterns for MDX-based content management that other teams have adopted
- Built sustainable update mechanism where core improvements benefit entire ecosystem automatically