Developers

Extend the domain icons

The web UI draws a small mark left of a domain name: a brand's logo if we know the brand, a letter otherwise. The brands come from two icon packs, through one generator, from a list that a person curates. This page is how to add a brand or a pack without breaking the rules that make it safe, small, and legal.

The user's view is in Domain icons, the decision and its numbers in ADR-167 on the Decisions page.

How it works

  1. A curated list in ui/scripts/brand-icons.mjs says which domains belong to which brand, and which pack's glyph to use for it.
  2. The generator reads the two packs, minifies the glyph paths, and writes two committed files: brands.ts (a colour, a path, and sometimes a grid size per brand: a lazy chunk) and map.data.ts (the domains and the titles).
  3. The page (DomainIcon.svelte) looks a name up by its longest matching suffix on whole labels. A brand it knows gets its colour as a tile with the glyph on it; any other name gets a monogram in a stable colour; a name of the network itself gets a house; a name the privacy level hid gets nothing.

Nothing is fetched at any point. The tile is drawn from data already in the page.

The rules

RuleWhy
Nothing is fetched. No favicon service, no request to the sites, no image URL. The icon is inline SVG.Every icon request would tell a third party which names are in a person's query log, and the content security policy allows images from 'self' and data: only. The owner declined any such dependency. At privacy level 1 and above the names are hashed, so there is nothing to fetch for anyway.
Two packs, in this order: Simple Icons first, Bootstrap Icons only when Simple Icons has none of the brand's candidates, then a monogram.Simple Icons has the real colour marks. Bootstrap Icons is monochrome, so its glyphs get a brand colour from us. Neither pack has every brand, and a missing brand is a monogram, never a look-alike glyph or a guess.
The list is curated. A brand is on the map because a person listed it with its domains. The generator never adds a pack's whole set.A pack indexes brands, not domains, and no open dataset maps domains to icons. The whole of Simple Icons is 4.8 MiB, which the image cannot afford.
A domain belongs to one brand, matched on whole labels, longest suffix first. A full host may be listed (teams.microsoft.com beats microsoft.com).notnetflix.com is not Netflix. A CDN name belongs to the company that owns the content on it, not to the CDN.
Only CC0, MIT, or Apache-2.0 sources, with their notice in docs/third-party-notices.md.The marks are their owners' trademarks and are shown only to identify the name; the notice says so, and a permissive licence on the artwork does not change that.
The glyph data stays small. It is a lazy chunk (fetched when the first brand tile is drawn), minified to two decimals, and counted in the UI's 400 KiB budget and the image's 15 MiB.See Size and performance budgets. The minifying paid for the second pack: eleven more glyphs and about 15 KiB gzipped less.
The output is committed, and a build needs neither pack. The versions are pinned in the generator, which refuses a different one.A build must not touch the network, and an icon must not change because a package did.

Add a brand

  1. Find the domains it owns. Its own site, its CDN and telemetry names, the hosts you see in your Top domains list. Use a registrable domain (licdn.com) or a full host when one brand under a shared domain needs its own mark.
  2. Check the packs. Is there a Simple Icons slug (look in node_modules/simple-icons or on its site)? If not, is there a Bootstrap Icons name (icons/<name>.svg)? If neither, stop: it stays a monogram.
  3. Add a line to LIST in ui/scripts/brand-icons.mjs: the candidate slugs in order (Simple Icons slugs first, then bi: and a Bootstrap name), then the domains.
    [['microsoftteams', 'bi:microsoft-teams'], ['teams.microsoft.com', 'teams.events.data.microsoft.com']],
    Several lines may use the same glyph (Microsoft's Office, Azure, and Edge names all end in bi:microsoft); the generator stores it once.
  4. For a Bootstrap glyph, add it to BOOTSTRAP: the slug it is stored under, a brand colour as six hex digits, and the title. Pick the colour people know the brand by; the tile chooses a white or a dark glyph by the colour's luminance. The generator checks that the glyph has no evenodd rule (the tile draws every glyph with the default one) and that its paths start with a move.
  5. Run the generator with the pinned packages:
    cd ui
    npm i --no-save simple-icons@16.38.0 bootstrap-icons@1.13.2 svgo@4.1.0
    node scripts/brand-icons.mjs
    --no-save keeps them out of package.json: they are tools for this script, not dependencies of the UI. Point SIMPLE_ICONS_DIR and BOOTSTRAP_ICONS_DIR at installed copies if you keep them elsewhere (svgo is found beside Simple Icons).
  6. Read what it reports: how many brands came from each pack, the glyph data's size raw and gzipped, the brands that are in neither pack, and which of our service presets (presets/services) still have no icon. The gzipped size must not go up for a small addition; if it does, say why.
  7. Review the diff of brands.ts and map.data.ts. A new domain should be there, and nothing else should have moved.
  8. Add the names to the test in ui/tests/e2e/4-icons.spec.ts (it runs without a browser): a name you added and the slug it must map to, and a look-alike that must not.
  9. Look at it in the light and the dark theme at 16 and 20 px. A glyph that is a thin outline can vanish on a tile; a near-black brand flips to a light tile in the dark theme by itself.
  10. Update the docs if the list of missing brands changed (docs/running.md, ADR-167's note), and the roadmap entry.

Add a pack

Adding a pack is a decision, not an edit: write it as an amendment to ADR-167 with the numbers. The second pack's amendment is the template. A pack qualifies when it passes all of these:

  • Licence: CC0, MIT, or Apache-2.0, with the notice text you must reproduce in docs/third-party-notices.md. Not CC BY (it needs per-icon attribution in the page), not "free for personal use".
  • Shape: SVG paths you can put in one <path> with the default fill rule, on a square grid you record (the data carries the grid size when it is not 24).
  • Cost: the glyphs you take, minified, add less than you remove elsewhere, or you show that the lazy chunk stays within the budget. Measure with the generator's report and the UI build.
  • Coverage: it has brands the first pack lacks. Say which.

Then, in the generator: a pinned version and a check for it, a directory variable, a table for anything the pack does not carry (colours, titles), a new candidate prefix like bi:, and a test that its glyphs reach the data. A pack you add must be after the earlier ones in the candidate order, so it never replaces a mark that was already right.

Never: an icon fetched at run time, a favicon service, a raster image, an icon font, or art taken from a company's own site. Each is a privacy, a size, or a licensing problem, and the content security policy blocks the first two.

The checks

What failsWhat it means
The generator exits with "… is installed but … is pinned here"The package version differs from the pin. Install the pinned one, or change the pin and review the whole diff.
The generator throws "BOOTSTRAP has … which no LIST entry uses", or "has no entry for …"The table and the list disagree: a colour without a use, or a bi: name with no colour.
obs_039 the generated data is wholeA mapped brand has no colour, path, or title, or a glyph on the map is unused (it would ship for nothing), or a grid size is not 16.
obs_039 the marks Simple Icons dropped come from the second packA name you expected to map to a Bootstrap glyph does not (the list or the suffix rule), or a first-pack glyph picked up a grid size.
npm run build over 400 KiB, or the image size gateThe data grew more than you planned. See the budgets page.
svelte-checkThe glyph tuple's type changed and a user of it did not.

The files

FileRole
ui/scripts/brand-icons.mjsThe generator: the list, the Bootstrap colours, the pins. Edit this.
ui/src/lib/icons/brands.ts, map.data.tsGenerated and committed. Never edit by hand.
ui/src/lib/icons/DomainIcon.svelte, map.ts, brands.svelte.tsThe tile, the lookup (longest suffix, monogram colour and letter), and the lazy loader.
ui/src/lib/icons/prefs.ts, prefs.svelte.tsThe per-browser choice of style and size (Settings → Account → Domain icons).
ui/tests/e2e/4-icons.spec.tsThe tests that need no browser: the map, the data, the preferences.
docs/third-party-notices.mdThe licence notices. Update it with every pack.

Why does this name still show a letter?

Work down the list; each step rules something out.

  1. Is the style Brand and monogram? Monogram only and Off never draw a brand. It is per person and per browser (Settings → Account → Domain icons).
  2. Is the name hashed? At privacy level 1 and above a name shows as h and 16 hex digits and gets no icon at all.
  3. Is the domain on the map? Search map.data.ts for it. Remember the longest suffix on whole labels: b79c66.us-east-1.prod.service.a2z.com matches a2z.com, but only if a2z.com is listed.
  4. Does the brand have a glyph? The generator prints the brands that are in neither pack. By design those are letters.
  5. Did the chunk load? A failed request for the glyph chunk falls back to letters, with no error. Look at the network tab.
  6. Is the page old? The UI is embedded in the binary: the node must run a build that contains your change.

Worked example: the missing Microsoft logo

A list showed an "M" for teams.events.data.microsoft.com. Simple Icons dropped the Microsoft marks on purpose, so the generator found nothing for the Microsoft lines of the list and those names fell back to a letter. Bootstrap Icons has microsoft and microsoft-teams, so the lines gained a bi: candidate and the two glyphs gained colours. Now teams.events.data.microsoft.com is Teams (its host is listed, so it beats microsoft.com) and vortex.data.microsoft.com is Microsoft. Disney+, Hulu, Minecraft, Adobe, the BBC, Walmart, and AWS are in neither pack and stay letters.