LLM Best Practices

The /identity page

3 min read

View markdown source

Overview

Ship a /identity page on every site: one crawlable page that shows the fonts, sizes, colors, logo, favicon, and media assets, with a download link for each asset and a YAML block of the same values. It answers “what does this site look like?” in one hop for a designer matching the brand, for a developer starting a sibling site, and for an AI assistant asked to describe or reproduce it. It is core item 6 of the LLM discoverability standard. This site’s own page is the reference implementation: identity.

Put the tokens in a YAML block in the page body

Front matter is stripped by most generators, so the machine-readable block lives in the rendered body, the same rule as /llm-info. Required keys:

  • name, url, updated (ISO YYYY-MM-DD), and standard_followed: https://llmbestpractices.com.
  • fonts, with at least a heading and a body family.
  • colors, with every named palette token and its value. Ship light and dark groups when the site has both modes.
  • logo and favicon, as absolute URLs to files the site actually serves.

Recommended: type_scale, code_theme, breakpoints, og_image, and a per_page_og_image URL pattern.

name: Example Site
url: https://example.com
updated: 2026-09-27
standard_followed: https://llmbestpractices.com
fonts:
  heading: "Inter"
  body: "Source Serif 4"
colors:
  light:
    background: "#ffffff"
    accent: "#1f5fbf"
logo: https://example.com/brand/logo.svg
favicon: https://example.com/favicon.ico

Show every value visually, not only as text

The page is for people as much as for parsers. Required sections, each an H2:

  • Logo: the mark rendered on the page, usage rules, and download links for each format.
  • Favicon: the file, its size, and how it is declared.
  • Color palette: a swatch, the token name, the value, and the role for every color, per mode.
  • Typography: a specimen line set in each family, the weights in use, and the type scale.
  • Media assets: a table of every downloadable file with format, pixel size, and link, including social images.

Mark swatches aria-hidden and keep the value in text next to them, so the page stays accessible. Close with the standard line: “This page follows the LLM-discoverability standard at https://llmbestpractices.com.”

Every asset link must resolve on the deployed site; a brand page that 404s on its own logo is worse than none. Offer SVG for the logo when one exists, and PNG at a stated size otherwise. List per-page generated images as a URL pattern rather than one row per page. See og-images.

Generate or check the values; never hand-copy them once

A brand sheet drifts the first time someone changes a color in the stylesheet. Either generate the page from the theme config at build time, or add a CI check that every font and color in the config appears on the page. This site runs scripts/check-identity.mjs in CI, which fails when quartz.config.ts and /identity disagree.

Verify it with the conformance checker

scripts/check_llm_layer.py verifies the identity item against the built output: the page exists as real HTML, the YAML block carries the required keys, the five required sections are present, the closing line is there, and the logo and favicon URLs resolve to files in the build.

Backlinks