The challenge

After successfully launching Coiled's new Next.js website with updated branding and design, the team wanted to ensure their documentation site at docs.coiled.io maintained the same level of polish and brand consistency.

The existing PyData Sphinx theme, while functional, didn't reflect Coiled's modern brand identity or provide the cohesive experience users expected when moving between the marketing site and documentation.

Key challenges included:

• Brand inconsistency: The documentation looked disconnected from the main website
• Generic appearance: The standard PyData theme didn't differentiate Coiled's docs from other projects
• Mobile experience: The responsive behavior needed improvement to match modern expectations

Our approach

Design collaboration and requirements gathering

Working closely with Coiled's designer, we began by cataloging all the Sphinx components that would need custom styling—from basic typography and navigation elements to complex interactive components like tabs and code blocks.

We defined the technical constraints of working within Sphinx's templating system and identified opportunities where we could enhance the user experience while respecting the framework's limitations.

Custom Sphinx theme development

Rather than building a completely new theme from scratch, we strategically extended the PyData Sphinx theme to leverage its solid foundation while implementing Coiled's custom design:

Core customization areas:

• Typography system: Implemented Coiled's font hierarchy and spacing
• Color palette: Applied the brand's color system throughout all components
• Layout foundation: Prepared the structural elements (sidebars, topbar, footer) for the site
• Navigation design: Created a custom navbar that echoes the main website
• Component styling: Redesigned cards, buttons, tables, and admonitions using modular CSS architecture for maintainability

Advanced component implementation:

• Responsive sidebar: Three-level navigation that collapses gracefully on mobile
• Code block enhancements: Improved syntax highlighting and copy functionality
• Interactive elements: Tabs, dropdowns, and expandable sections
• API documentation styling: Clean, scannable parameter descriptions

Iterative development process

The project followed an agile approach with regular check-ins and reviews:

• Week 1-2: Theme architecture and core component development
• Week 3-4: Advanced components
• Week 5-6: Feedback, testing and final polish

The project stayed within the estimated budget through careful scope management:

• Priority-based implementation: Core components first, enhancements second
• Design pragmatism: Balanced ideal design with Sphinx limitations
• Future-proofing: Built foundation for potential theme upgrades

The outcome

The custom Sphinx theme successfully unified Coiled's digital brand presence:

• Brand consistency: Seamless visual transition between marketing site and documentation.

• Enhanced user experience: Modern, responsive design that works well across devices.

• Maintainable codebase: Clean, documented theme architecture for future updates.

Tech stack