Give Your Docs Subdomain Its Own Favicon
Your app and your docs usually share one logo, so their tabs look identical. When someone has the dashboard, the API reference, and three guide pages open at once, every tab is the same tiny mark. A coloured outline around the docs icon fixes that in 16 pixels — same brand, obviously different surface.
The problem: docs and app share a mark
Most products put their documentation on a subdomain — docs.yoursite.com — and give it the same favicon as the main app, because it is the same company and the same logo. That is correct for brand, and a real usability tax in the tab bar. A developer reading your guides almost always has the product open in another tab, so they end up with a row of pixel-identical icons and have to read the (truncated) tab titles to find the one they want.
The environment-variant idea solves the neighbouring problem — telling production from staging from local — by tinting or badging the icon per deployment. Docs is a different axis: it is the same environment (production), a different surface. So instead of changing the whole icon, you keep the exact mark and wrap it in a coloured ring. The logo still reads as you; the outline reads as "this is the docs one".
Two axes, two treatments
Environment variants
Which deployment is this?
- Production stays clean; staging and dev get a badge or a colour tint.
- Answers "is this safe to run a destructive command in?"
- Files are prefixed staging- / dev- with matching manifests.
Docs variant
Which surface is this?
- Same production mark, wrapped in a coloured outline.
- Answers "is this the app or the documentation?"
- Files are prefixed docs- with a docs-manifest.json.
Why an outline, and not a whole new icon
A separate docs logo would break recognition — a reader scanning for your brand would skip past it. Recolouring the mark has the same problem and fights your brand guidelines. An outline is the minimal change that survives at 16 pixels: the interior is untouched, so the logo is still instantly yours, and the frame is a strong enough signal on its own that the eye catches it before it reads any text.
It also composes with everything else. The outline sits on top of whatever shape and background you already chose, so a circular icon stays circular inside its frame, and a transparent logo keeps its transparency — only the ring is added.
Choosing the border colour
| Mode | What you get |
|---|---|
| Accent | A hue pulled from the artwork itself, so the ring feels like part of the brand. Best when your logo has a distinct secondary colour to echo. If the dominant colour matches the logo's own background the ring can blend — switch to contrast or white in that case. |
| Contrast | Black or white, whichever reads better against the mark. The safest default for legibility: a dark logo gets a white ring, a light logo gets a near-black one, and the frame is unmistakable at tab size. |
| White | A plain white frame. Clean and neutral, and it reads well against the darker chrome most browsers use around the tab. |
| Custom hex | Pass your own #rrggbb — e.g. your docs site's accent — to match an existing docs design system exactly. |
Generating the docs set
- 1
Turn on the docs variant
In the generator's display options, set Docs Variation to Accent, Contrast, or White. A live preview shows the app tab next to the docs tab so you can judge the outline at real size.
- 2
Download the kit
The zip now includes an outlined copy of every tab icon prefixed docs- (docs-favicon.ico, docs-favicon-32x32.png, docs-apple-touch-icon.png, and so on) plus a docs-manifest.json named "Docs".
- 3
Serve it on the docs host
Drop the docs-* files into the documentation site's static directory and reference them from its <head> — or, if app and docs share one deploy, switch by hostname server-side.
Installing on the docs subdomain
<!-- In the <head> of docs.yoursite.com -->
<link rel="icon" href="/docs-favicon.ico">
<link rel="icon" type="image/png" sizes="32x32" href="/docs-favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/docs-favicon-16x16.png">
<link rel="apple-touch-icon" href="/docs-apple-touch-icon.png">
<link rel="manifest" href="/docs-manifest.json">If the docs site is its own deployment, the docs-* files are simply its normal favicon set — nothing conditional needed.
One deploy for app and docs? Switch by hostname
// Next.js: pick the icon set from the request host.
import { headers } from "next/headers";
export default async function RootLayout({ children }) {
const host = (await headers()).get("host") ?? "";
const prefix = host.startsWith("docs.") ? "/docs-" : "/";
return (
<html>
<head>
<link rel="icon" href={`${prefix}favicon.ico`} />
<link rel="icon" type="image/png" sizes="32x32" href={`${prefix}favicon-32x32.png`} />
<link rel="apple-touch-icon" href={`${prefix}apple-touch-icon.png`} />
<link rel="manifest" href={host.startsWith("docs.") ? "/docs-manifest.json" : "/manifest.json"} />
</head>
<body>{children}</body>
</html>
);
}Reading the host on the server means the right icon ships in the initial HTML — no flash of the wrong favicon.
Docs favicon FAQ
Does the outline hurt brand recognition?
No — that's the whole point of using an outline rather than a new icon or a recolour. The interior mark is untouched, so it reads as your brand at a glance; the ring is an additional signal, not a replacement for the logo.
Will the border still be visible at 16 pixels?
Yes. The frame is sized as a fraction of the icon (about 14% per side) with a one-pixel floor, so even the 16×16 favicon shows a clear ring. Contrast or white borders are the most legible at that size.
Do I need a separate manifest for the docs PWA?
A docs-manifest.json is included, named "Docs …", so if someone installs your documentation as an app it appears distinctly in the launcher. Point the docs host's <link rel="manifest"> at it; if you don't offer an installable docs app you can ignore it.
Can I match my docs design system's exact colour?
Yes. Beyond accent / contrast / white, the generator and the MCP tool accept a custom #rrggbb border colour, so you can echo the exact accent your documentation theme already uses.