---
id: portfolio.ds.favicon
name: "Favicon"
type: component
status: active
relations: [{"type":"depends_on","target":"portfolio.ds.site-logo"},{"type":"related_to","target":"portfolio.ds.about-design-system"}]
sources: ["packages/design-system/src/components/Favicon.astro","packages/design-system/src/components/DocumentShell.astro","scripts/generate-site-logo-assets.mjs","apps/portfolio-site/public/media/favicon.svg","apps/portfolio-site/src/design-system/docs/favicon.astro","apps/portfolio-site/src/lib/designSystemRegistry.ts"]
catalog: ["apps/portfolio-site/src/design-system/docs/favicon.astro"]
previews: ["apps/portfolio-site/src/design-system/docs/favicon.astro"]
---
# Favicon

## Purpose

Canonical browser-tab icon asset and document-level link component for Post-AI Systems.

`Favicon` derives its mark from the accepted static `Site Logo` geometry, then applies a favicon-specific black-and-white treatment. `DocumentShell` uses the component as the single favicon owner for every public and Design System route.

## Use

- Publish the canonical favicon asset in Design System Media.
- Inspect the single Preview instance at browser-relevant `16 × 16` and `32 × 32` sizes through the Size switcher.
- Emit favicon link metadata from one component for every document rendered through `DocumentShell`.

## Contract

- Keep `scripts/generate-site-logo-assets.mjs` as the only editable geometry source.
- Keep `/media/favicon.svg` as a square SVG with a `512 × 512` viewBox.
- Use a solid `#000000` background and a `#ffffff` mark.
- Inset the complete white mark by `32` SVG units on the `512 × 512` canvas, producing a minimum `1px` safe area at `16 × 16` and `2px` at `32 × 32`.
- Preserve the accepted `Site Logo` proportions, detached cursor and two intentional gaps.
- Keep the favicon static; do not include the Site Logo cursor animation.
- Keep the favicon white-on-black color contract independent from the black-on-transparent Site Logo contract.
- Default the component to `/media/favicon.svg`, `image/svg+xml` and `sizes="any"`.
- Keep the component head-level and free of visible body markup.
- Connect the component once in `DocumentShell`; do not duplicate favicon links in routes or page-level layouts.

## Current Usage

- Every public and Design System document rendered through `DocumentShell`.
- Design System Media preview at `/design-system/media/favicon/`.

## Code Paths

- `packages/design-system/src/components/Favicon.astro`
- `packages/design-system/src/components/DocumentShell.astro`
- `apps/portfolio-site/public/media/favicon.svg`
- `apps/portfolio-site/src/design-system/docs/favicon.astro`
- `scripts/generate-site-logo-assets.mjs`

## Do Not Use

Do not add page-local favicon links or bypass the `Favicon` component with direct document-level markup.

## Accessibility

The standalone SVG has an accessible title and description. The Media Preview identifies both actual-size samples without treating either decorative duplicate as unexplained content.

## Verification

- Regenerate media with `npm run generate:site-logo` and confirm that the favicon output has no drift.
- Confirm the asset has a black background, white mark and no animation declarations.
- Inspect the Preview at `16 × 16` and `32 × 32` and confirm the corresponding `1px` and `2px` minimum safe areas.
- Confirm `/design-system/media/favicon/` and `/media/favicon.svg` return successfully.
- Confirm public and Design System documents contain exactly one favicon link after direct and client-side navigation.
- Run `scripts/design-system-graph --check --no-write`.