feat(docs): add dark/light mode icon support for variants

[devin-ai-integration]

Add dark/light mode icon support for variants

This PR implements runtime support for dark/light mode icons in the documentation platform, enabling icons to automatically adapt to the user's theme preference.

What was the motivation & context behind this PR?

User requested the ability to specify different icons for dark and light modes in docs.yml. Previously, the icon field only supported a single string value that would display the same in both themes. Now it supports both:

• Simple format: icon: "icon-name" (uses same icon for both themes)
• Themed format: icon: { dark: "icon-dark", light: "icon-light" } (different icons per theme)

This is a runtime-only implementation without schema changes. The FDR API schema still defines icon as optional<string>, but the frontend now accepts objects at runtime.

Changes Made

Updated both processIcon implementations (in packages/fern-docs/bundle/ and packages/fern-docs/components/):

1. Added ThemedIcon interface and isThemedIcon() type guard
2. Refactored icon processing into processIconString() helper function
3. Added logic to detect themed icons and render both variants with Tailwind's dark:hidden / hidden dark:inline-block classes
4. Maintained backward compatibility - simple string icons still work

How has this PR been tested?

⚠️ Not yet tested with actual documentation - This requires:

1. Creating a test docs.yml with themed icons
2. Verifying icons display correctly in both light and dark modes
3. Testing with all icon formats (file:, inline SVG, font icons)
4. Confirming CSS classes work in all rendering contexts (sidebar, navigation, etc.)

Local verification completed:

• ✅ Code passes pnpm format and pnpm check
• ✅ Both processIcon implementations updated identically
• ⏳ CI checks pending

Important Review Items

High Priority:

1. Schema mismatch: Icon field is still typed as string in FDR SDK but now accepts objects at runtime. Should we update the schema or document this as unsupported/experimental?
2. CSS compatibility: Will dark:hidden and hidden dark:inline-block work correctly in all contexts where icons are rendered?
3. Type safety: Is the isThemedIcon() type guard comprehensive enough to prevent invalid inputs?

Medium Priority:
4. Edge cases: What should happen when both dark/light are empty strings or both undefined?
5. Testing strategy: How should we test this before merging? Local docs.yml? E2E tests?
6. Documentation: Should we document this feature for users, or keep it undocumented until schema is updated?

---

Devin Session: https://app.devin.ai/sessions/cf2b0ed912fe454cbdc13b764952c786
Requested by: Kapil Gowru (@kgowru)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[vercel]

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

Project	Deployment	Preview	Updated (UTC)
dev.ferndocs.com	Ready	Preview	Nov 2, 2025 8:05pm
fern-dashboard	Ready	Preview	Nov 2, 2025 8:05pm
fern-dashboard-dev	Ready	Preview	Nov 2, 2025 8:05pm
ferndocs.com	Ready	Preview	Nov 2, 2025 8:05pm
preview.ferndocs.com	Ready	Preview	Nov 2, 2025 8:05pm
prod-assets.ferndocs.com	Ready	Preview	Nov 2, 2025 8:05pm
prod.ferndocs.com	Ready	Preview	Nov 2, 2025 8:05pm

1 Skipped Deployment

Project	Deployment	Preview	Updated (UTC)
fern-platform	Ignored		Nov 2, 2025 8:05pm