llm-browser/frontend/DESIGN.md

LLM Browser — Agent View (Northstar design system)

Audience & purpose

A validator tool for people who publish sites for LLM agents: enter a domain, see exactly what a text-only agent sees. Three surfaces per inspection: rendered markdown, the llms.txt family (raw + parsed), and the agent-readiness checks. Shared with the Northstar showcase app (routes, primitives), so all components come from src/components/ui.

Visual character

Inherited from the host system: lab()-based tokens, quiet surfaces, mono for machine output (URLs, raw files, source), sans for prose. Nothing on the agent-view page introduces new colours — every shade is a token or a color-mix() of one, so dark/light parity is automatic.

Layout

• Single-column app pattern: form card → status header → tabbed results.
• ?url=<domain> in the address bar is the source of truth for what is being inspected; link clicks rewrite it (the agent loop), so any view is a link.
• Tabs: Markdown (rendered), Source (raw markdown + copy), llms.txt (one card per candidate path: /llms.txt, /llms-full.txt, /.well-known/llms.txt), robots.txt, Meta (definition list), Checks (badge + label + detail rows).

Component patterns

• Status: Badge variants carry state — positive/ok, primary/warn, destructive/error, secondary/info. No extra colours for severities.
• File cards: Card + CardHeader, status badge, absolute URL in mono, parsed doc first, raw content in a <details> below.
• Markdown output renders through src/components/markdown/MarkdownView (React elements, no HTML injection); links are intercepted and re-enter the viewer instead of navigating away.
• Empty, loading (Skeleton), and error states are explicit — an inspection can fail at the network, the site, or validation, and each gets its own copy.

Accepted decisions

• The light theme's --destructive stays at the default red (lab(48.4493% 77.4328 61.5452)): its brighter variant failed the 4.5:1 pair with --destructive-foreground. Dark keeps the brighter red (passes on dark surfaces). Theme rules in src/tokens.css use explicit selectors only (no :not([data-theme='light']) fallback) so tooling resolves them cleanly.
• Agent-view styles live in src/App.css under "Agent view"; they override .markdown-body's article metrics (.agent-doc) and add link, list, table, quote and code styling the showcase never needed.
• Severity mapping: ok→positive, info→secondary, warn→primary, error→destructive. Uppercase mono badges in the checks list.