Context
Lighthouse mobile audit on SUB-7 showed all 6 docs routes ≥90 Performance, but two routes had elevated Total Blocking Time:
| Route |
TBT |
| /docs/components/command-menu |
336ms |
| /docs/components/toast |
339ms |
| All others |
≤227ms |
The 100ms+ delta correlates with the cmdk (CommandMenu) and sonner (Toast) client bundles loading and parsing on those routes.
Why this matters
TBT directly impacts perceived responsiveness — the thesis of the library. Pages that take 300ms+ before they're interactive contradict the "perceived speed is the design system" claim. The other four pages prove the architecture supports <230ms TBT; these two are outliers.
Likely wins (in rough priority order)
-
Lazy-load cmdk + sonner via next/dynamic on the doc pages. The libraries only need to load when the user opens the demo, not on page load. Suspense boundary with a button-shaped skeleton keeps the perceived experience clean.
-
Audit bundle composition with @next/bundle-analyzer:
Confirm cmdk + sonner are the top contributors on their respective routes. Look for unexpected duplicate dependencies across route bundles.
-
Split the demo helper modules — command-menu-demos.tsx and toast-demos.tsx currently import the whole UI bundle. A demo-only entry point that imports cmdk and sonner directly (skipping the wrapper) would let other routes skip those bundles entirely.
-
Re-audit after each change to verify TBT actually drops, not just shifts to a different metric.
Acceptance criteria
Why not now
SUB-7 is shipping all 6 routes at ≥90 Performance. The TBT spike is real but doesn't break the "passes Lighthouse" recruiter signal. Optimization belongs in a separate, focused cycle where we can also tackle:
- Edge runtime experiments
- Streaming SSR for the prose pages
- Font preload hints (Geist Mono cold start)
Filing now so it's not lost.
Estimated effort
~2-4 hours. Includes bundle analysis, refactor of demo helpers, and Lighthouse re-audit on all routes.
Context
Lighthouse mobile audit on SUB-7 showed all 6 docs routes ≥90 Performance, but two routes had elevated Total Blocking Time:
The 100ms+ delta correlates with the cmdk (CommandMenu) and sonner (Toast) client bundles loading and parsing on those routes.
Why this matters
TBT directly impacts perceived responsiveness — the thesis of the library. Pages that take 300ms+ before they're interactive contradict the "perceived speed is the design system" claim. The other four pages prove the architecture supports <230ms TBT; these two are outliers.
Likely wins (in rough priority order)
Lazy-load cmdk + sonner via
next/dynamicon the doc pages. The libraries only need to load when the user opens the demo, not on page load. Suspense boundary with a button-shaped skeleton keeps the perceived experience clean.Audit bundle composition with
@next/bundle-analyzer:Confirm cmdk + sonner are the top contributors on their respective routes. Look for unexpected duplicate dependencies across route bundles.
Split the demo helper modules —
command-menu-demos.tsxandtoast-demos.tsxcurrently import the whole UI bundle. A demo-only entry point that importscmdkandsonnerdirectly (skipping the wrapper) would let other routes skip those bundles entirely.Re-audit after each change to verify TBT actually drops, not just shifts to a different metric.
Acceptance criteria
Why not now
SUB-7 is shipping all 6 routes at ≥90 Performance. The TBT spike is real but doesn't break the "passes Lighthouse" recruiter signal. Optimization belongs in a separate, focused cycle where we can also tackle:
Filing now so it's not lost.
Estimated effort
~2-4 hours. Includes bundle analysis, refactor of demo helpers, and Lighthouse re-audit on all routes.