CRAFT-1833: Documentation App - miscellaneous changes

[misama-ct]

Documentation App Revamp

Note

While many many files changed, everything is neatly compartmentalized. There is a single component change in nimbus (the Tabs component), apart from that it's only documentation changes in nimbus. Everything related to the document parsing lives now in a separate package. If you can run the docs-app locally (pnpm nimbus:init & pnpm start:docs) and file-changes in mdx-files propagate to the frontend then I'd consider this success.
To see the new TabsView, check out the Button component.

Overview

Comprehensive revamp of the Nimbus documentation system with improved architecture, better performance, and enhanced developer experience.

---

Key Changes

1. New Build Package (@commercetools/nimbus-docs-build)

Standalone documentation build system with:

• MDX parsing with multi-view support (.mdx, .dev.mdx, .a11y.mdx, .guidelines.mdx)
• TypeScript type extraction via react-docgen-typescript
• Route manifest and search index generation
• Incremental builds with caching (~60% faster)
• Content validation and SEO generation

2. Enhanced Build Pipeline

• MDX Hot Module Replacement: Live preview of documentation edits
• Advanced Code Splitting: Route-based and vendor chunking
• Optimized Dependencies: Smart bundling and compression
• Asset Optimization: Image and font organization

3. Improved Navigation & UX

New Components:

• DocMetadata - Document presentation with lifecycle states
• ColorThemeMenu - Dynamic theme selection with preview
• ViewTabs - Multi-view documentation navigation
• ErrorBoundary - Graceful error handling
• AppFrame - Unified layout structure

Navigation Enhancements:

• Breadcrumb context with copy link functionality
• Enhanced TOC with hash navigation
• Sidebar scroll restoration
• Smooth hash navigation and scroll-to-anchor

4. Enhanced Tabs Component

• Added variant prop with "line" (default) and "pills" options
• Refactored styling to use compound variants with box shadows
• Improved recipe organization for better maintainability
• Enhanced Storybook stories with comprehensive interaction tests
• Added controlled mode with selectedKey and onSelectionChange props

5. Developer Experience

• Real-time MDX content updates with HMR
• Per-route data invalidation
• Improved error handling and validation
• Better build performance with caching

---

Examples

Multi-View Documentation (Button Component)

button.mdx         → Main overview
button.dev.mdx     → Developer implementation
button.a11y.mdx    → Accessibility standards
button.guidelines.mdx → Design guidelines

Build Performance

• Build time: ~60% faster
• HMR: Near-instant MDX updates
• Bundle: Optimized with route-based splitting

---

Breaking Changes

None - Fully backward compatible

All changes are additive or internal refactoring:

• New Tabs variant prop is optional (defaults to "line" which matches previous behavior)
• Internal build scripts refactored (no consumer impact)
• Documentation file structure changes (internal only)

---

Architecture Changes

Before

• Monolithic build scripts
• Manual MDX parsing in app
• Limited caching
• Complex routing logic

After

• Standalone @commercetools/nimbus-docs-build package
• Build-time documentation generation
• Intelligent caching system
• Simplified routing with static modules

---

Checklist

• New build package created and tested
• Multi-view documentation support
• HMR for MDX files
• Navigation components refactored
• Tabs component enhanced (backward compatible)
• Button documentation improved with multiple views
• Code splitting optimized
• Error boundaries added
• Unused code removed
• All tests passing

[changeset-bot]

🦋 Changeset detected

Latest commit: c651915

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@commercetools/nimbus-docs-build	Patch
@commercetools/nimbus-icons	Patch
@commercetools/nimbus	Patch
@commercetools/nimbus-i18n	Patch
@commercetools/nimbus-tokens	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
nimbus-documentation	Ready	Preview	Comment	Nov 7, 2025 9:06am
nimbus-storybook	Ready	Preview	Comment	Nov 7, 2025 9:06am

[valoriecarli]

this is looking amazing, but you already know that. ive left a couple of things that we can follow up on at a later time, and like @ByronDWall brought up, i think its time we start thinking of adding tests to this beauty.
thank you!

[valoriecarli]

just putting this here to keep everything in one place

Where the Header is 🤩 on the Implementation tab, its now doing a thing on the adjacent Overview tab for both DateRangePicker & DateRangePickerField

[misama-ct]

just putting this here to keep everything in one place

Where the Header is 🤩 on the Implementation tab, its now doing a thing on the adjacent Overview tab for both DateRangePicker & DateRangePickerField

This is a matter of changing the component-name.mdx & component-name.*slug*.mdx files.

If there are multiple mdx-files for a component, the Tabs are displayed and a "Meta"-Section (title, descirption, lifecycleState & tags) is displayed on top of them on every tabbed page. The displayed information comes from the frontmatter section of the component-name.mdx file (also used and displayed by the search).

[jaikamat]

Looks like it's in a great place