@devries-cameron20 / composio-1 / commits / 0d4383c4f
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

fix(docs): isolate product theme from next-themes storage, switcher link fixes (#4349)

## Summary Applies the top findings from a multi-reviewer code review of #4335 (which merged before these could land on the PR branch). Four validated findings, all small and behavior-preserving outside the fixes themselves: - **Cross-tab theme fight (P1):** #4335 routed the product-derived theme through next-themes' shared `theme` localStorage key -- written by the root layout's inline head script on every hard load and by `setTheme` on every client switch. next-themes listens for cross-tab storage events on that key, so two docs tabs on different products (Platform dark / For You light) silently repaint each other with no self-heal (the provider effect's deps are `[product, setTheme]`, so the flipped tab never corrects). The product theme is derived state, not a preference: this PR applies it directly to the document element (`applyProductTheme`) and passes `forcedTheme: initialTheme` from the server-resolved product so hydration cannot flip a stale stored value. No `theme` localStorage writes remain anywhere. - **theme-color meta (P2):** the two `prefers-color-scheme`-keyed metas meant mobile browser chrome mismatched the forced page theme (white chrome over dark Platform pages for light-OS users). Now a single meta keyed to the product theme. - **Switcher current-option href (P2):** the popover option marked `aria-current="page"` resolved to the product landing route, so middle-click, hover status bar, and copy-link all pointed at the wrong URL. It now hrefs the current pathname. - **Explore-card aria-label (P3):** `aria-label` replaced the link's accessible name, so the product description inside the card was not announced. Dropped; heading + description now form the name. ## Changes - `docs/app/layout.tsx` -- inline script no longer writes localStorage (pre-paint class priming unchanged); single product-keyed `theme-color` meta; `forcedTheme: initialTheme` on `RootProvider`. - `docs/components/docs-product-context.tsx` -- `setTheme`/`useTheme` removed; new `applyProductTheme` used in the product effect and the flushSync commit. - `docs/components/product-switcher.tsx` -- `destination = isCurrent ? pathname : docsProductDestination(...)`. - `docs/components/home-surfaces.tsx` -- Explore-card `aria-label` removed. - `docs/tests/static/product-navigation.test.ts` -- pins the new invariants (`applyProductTheme`, `forcedTheme: initialTheme`, and a negative assertion that `localStorage.setItem('theme'` stays out). ## Testing - `bun test tests/static/` -- 541 pass / 0 fail - `bun run types:check` -- clean - `bun run lint` -- only pre-existing warnings (`home-surfaces.tsx:102` `no-img-element` is in `ForYouVisual`, untouched) - Worth a manual check: two tabs on different products no longer repaint each other (static tests cannot prove cross-tab storage isolation) ## Notes - Docs-only change; no changeset required. - Review context: follow-up to #4335. Remaining review findings (navigation state-machine races, theme-scope design call, decision record) are tracked separately.

Alberto Schiabel committed Sep 4, 2026 at 17:32 UTC 0d4383c4f74ec0b58372d3666d740845b6ec3077
6 files changed +44 -13
docs/app/layout.tsx
+5 -3
@@ -88,11 +88,10 @@ export default async function Layout({ children }: LayoutProps<'/'>) {
88 <head>
89 <script
90 dangerouslySetInnerHTML={{
91 - __html: `try{localStorage.setItem('theme','${initialTheme}')}catch{}document.documentElement.classList.remove('light','dark');document.documentElement.classList.add('${initialTheme}');document.documentElement.style.colorScheme='${initialTheme}'`,
91 + __html: `try{document.documentElement.classList.remove('light','dark');document.documentElement.classList.add('${initialTheme}');document.documentElement.style.colorScheme='${initialTheme}'}catch{}`,
92 }}
93 />
94 - <meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)" />
95 - <meta name="theme-color" content="#131211" media="(prefers-color-scheme: dark)" />
94 + <meta name="theme-color" content={DOCS_PRODUCTS[initialProduct].themeColor} />
95 <script
96 type="application/ld+json"
97 dangerouslySetInnerHTML={{
@@ -132,9 +131,12 @@ export default async function Layout({ children }: LayoutProps<'/'>) {
131 <ProductTransitionLoader />
132 <Analytics />
133 <PostHogProvider>
134 + {/* DocsProductProvider owns the rendered theme; useTheme().resolvedTheme is not a product-theme signal. */}
135 <RootProvider
136 theme={{
137 defaultTheme: 'system',
138 + forcedTheme: initialTheme,
139 + storageKey: 'composio-docs-theme',
140 attribute: 'class',
141 enableSystem: true,
142 hotKey: false,
docs/components/docs-product-context.tsx
+21 -6
@@ -12,7 +12,6 @@ import {
12 } from 'react';
13 import { flushSync } from 'react-dom';
14 import { usePathname, useRouter } from 'next/navigation';
15 -import { useTheme } from 'fumadocs-ui/provider/base';
15 import {
16 classifyDocsProduct,
17 DOCS_PRODUCTS,
@@ -47,6 +46,23 @@ function writeProductCookie(product: DocsProduct): void {
46 document.cookie = serializeDocsProductCookie(product);
47 }
48
49 +/**
50 + * The product theme is derived state, not a user preference: apply it directly
51 + * to the document element instead of routing it through next-themes' shared
52 + * `theme` localStorage key, whose cross-tab storage events would repaint other
53 + * tabs that are viewing the other product.
54 + */
55 +function applyProductTheme(product: DocsProduct): void {
56 + const { theme, themeColor } = DOCS_PRODUCTS[product];
57 + const root = document.documentElement;
58 + root.classList.remove('light', 'dark');
59 + root.classList.add(theme);
60 + root.style.colorScheme = theme;
61 + document
62 + .querySelector('meta[name="theme-color"]')
63 + ?.setAttribute('content', themeColor);
64 +}
65 +
66 export function DocsProductProvider({
67 initialProduct,
68 children,
@@ -56,7 +72,6 @@ export function DocsProductProvider({
72 }) {
73 const pathname = usePathname();
74 const router = useRouter();
59 - const { setTheme } = useTheme();
75 const [persistedProduct, setPersistedProduct] = useState(initialProduct);
76 const [pendingProduct, setPendingProduct] = useState<DocsProduct | null>(null);
77 const pendingNavigation = useRef<{
@@ -68,8 +83,8 @@ export function DocsProductProvider({
83 const product = pendingProduct ?? inferredProduct ?? persistedProduct;
84
85 useEffect(() => {
71 - setTheme(DOCS_PRODUCTS[product].theme);
72 - }, [product, setTheme]);
86 + applyProductTheme(product);
87 + }, [product]);
88
89 const persistProduct = useCallback((nextProduct: DocsProduct) => {
90 writeProductCookie(nextProduct);
@@ -108,7 +123,7 @@ export function DocsProductProvider({
123 flushSync(() => {
124 setPersistedProduct(nextProduct);
125 setPendingProduct(nextProduct);
111 - setTheme(DOCS_PRODUCTS[nextProduct].theme);
126 + applyProductTheme(nextProduct);
127 });
128 if (href !== pathname) router.push(href);
129 };
@@ -167,7 +182,7 @@ export function DocsProductProvider({
182 commitNavigation();
183 }
184 },
170 - [pathname, router, setTheme],
185 + [pathname, router],
186 );
187
188 const value = useMemo(
docs/components/home-surfaces.tsx
-1
@@ -40,7 +40,6 @@ function IntentCard({ intent }: { intent: HomeIntent }) {
40 return (
41 <article className="grid overflow-hidden border border-fd-border bg-fd-card shadow-[0_1px_0_rgba(15,15,15,0.04)] md:grid-cols-[minmax(0,1fr)_calc(50%-0.75rem)]">
42 <ProductSelectionLink
43 - aria-label={`Explore ${intent.product} docs`}
43 className="relative overflow-hidden border-b border-fd-border bg-fd-background p-5 pb-40 no-underline transition-colors hover:bg-fd-accent/20 focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-fd-ring sm:p-6 sm:pb-44 md:min-h-72 md:border-b-0 md:border-r md:pb-6"
44 href={DOCS_PRODUCTS[intent.productId].landingRoute}
45 product={intent.productId}
docs/components/product-switcher.tsx
+3 -1
@@ -78,7 +78,9 @@ export function ProductSwitcher({ placement = 'sidebar' }: { placement?: 'nav' |
78 {DOCS_PRODUCT_ORDER.map((productId, index) => {
79 const option = DOCS_PRODUCTS[productId];
80 const isCurrent = productId === product;
81 - const destination = docsProductDestination(pathname, productId);
81 + const destination = isCurrent
82 + ? pathname
83 + : docsProductDestination(pathname, productId);
84 return (
85 <div key={productId}>
86 {index > 0 && <div aria-hidden="true" className="mx-2 my-1 h-px bg-fd-border" />}
docs/lib/home-navigation.ts
+3
@@ -30,6 +30,7 @@ interface DocsProductConfig {
30 switcherDescription: string;
31 landingRoute: string;
32 theme: 'light' | 'dark';
33 + themeColor: '#131211' | '#ffffff';
34 routePrefixes: readonly string[];
35 sidebar: readonly ProductSidebarGroup[];
36 home: Omit<HomeIntent, 'productId' | 'product'>;
@@ -61,6 +62,7 @@ export const DOCS_PRODUCTS = {
62 switcherDescription: 'Connect your apps to AI clients.',
63 landingRoute: '/docs/agent-plugins',
64 theme: 'light',
65 + themeColor: '#ffffff',
66 routePrefixes: [
67 '/docs/agent-plugins',
68 '/docs/claude-code-plugin',
@@ -107,6 +109,7 @@ export const DOCS_PRODUCTS = {
109 switcherDescription: 'Build agents with the Composio SDK.',
110 landingRoute: '/docs/quickstart',
111 theme: 'dark',
112 + themeColor: '#131211',
113 routePrefixes: [
114 '/docs/quickstart',
115 '/docs/providers',
docs/tests/static/product-navigation.test.ts
+12 -2
@@ -21,12 +21,14 @@ describe('Docs product navigation', () => {
21 switcherDescription: 'Connect your apps to AI clients.',
22 landingRoute: '/docs/agent-plugins',
23 theme: 'light',
24 + themeColor: '#ffffff',
25 });
26 expect(DOCS_PRODUCTS.platform).toMatchObject({
27 product: 'Platform',
28 switcherDescription: 'Build agents with the Composio SDK.',
29 landingRoute: '/docs/quickstart',
30 theme: 'dark',
31 + themeColor: '#131211',
32 });
33 });
34
@@ -162,9 +164,17 @@ describe('Docs product navigation', () => {
164 expect(switcherSource).toContain('href="/"');
165 expect(sharedLayoutSource).toContain('slots: { navTitle: ProductNavTitle }');
166 expect(sharedLayoutSource).toContain('themeSwitch: { enabled: false }');
165 - expect(contextSource).toContain('setTheme(DOCS_PRODUCTS[product].theme)');
167 + expect(contextSource).toContain('applyProductTheme(product)');
168 + expect(contextSource).toContain('.querySelector(\'meta[name="theme-color"]\')');
169 + expect(contextSource).toContain("?.setAttribute('content', themeColor)");
170 expect(contextSource).toContain('window.setTimeout(finish, 1500)');
167 - expect(rootLayoutSource).toContain("localStorage.setItem('theme','${initialTheme}')");
171 + expect(rootLayoutSource).toContain('forcedTheme: initialTheme');
172 + expect(rootLayoutSource).toContain("storageKey: 'composio-docs-theme'");
173 + expect(rootLayoutSource).toContain(
174 + 'content={DOCS_PRODUCTS[initialProduct].themeColor}',
175 + );
176 + expect(contextSource).not.toContain("localStorage.setItem('theme'");
177 + expect(rootLayoutSource).not.toContain("localStorage.setItem('theme'");
178 expect(rootLayoutSource).toContain('hotKey: false');
179 });
180 });