llm browser

frontend/DESIGN.md

@@ -0,0 +1,45 @@
+# 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.