brandmd

brandmd is a command-line tool that turns any live website into a machine-readable design specification. It renders the page, observes how it is actually styled, and writes the result as DESIGN.md, the format defined by the open @google/design.md spec: YAML frontmatter holding typed tokens for colors, typography, rounded corners, spacing and components, followed by prose sections such as Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components and Do's and Don'ts. Generated files are intended to validate clean under the official @google/design.md lint command. The motivation is that AI coding agents produce generic interfaces when they lack the project's colors, fonts, spacing and component conventions. Placing DESIGN.md in a project root gives agents such as Claude Code, Cursor, Gemini CLI, Codex and Google Stitch that context up front. A single invocation, for example running npx brandmd against a URL and writing DESIGN.md, is enough; no manual authoring of the spec is required. Extraction is local. The tool launches a headless browser via Playwright, scrolls to trigger lazy-loaded content, dismisses cookie banners and overlays, reads CSS custom properties from :root (including media queries), and collects computed styles from visible elements. It then clusters similar colors, derives a spacing scale and base grid unit, identifies border radii and shadow styles, and recognises component patterns such as buttons, cards and inputs. Typography detection is role-aware, preferring display over heading over body fonts while skipping monospace, fallback and icon fonts. No LLM calls or API keys are involved in the default path. Several output shapes are offered alongside the default DESIGN.md: raw JSON tokens for scripts and toolchains, CSS custom properties, a Tailwind v4 @theme block, and a self-contained HTML brand guide with swatches, type specimens, spacing visualisation and shadow examples. Multiple URLs can be passed to merge tokens across pages, with frequencies normalised per page so a button-heavy documentation page cannot outvote a homepage. An optional dark flag extracts dark-theme tokens using prefers-color-scheme. An optional vision flag uses a Gemini API key to add illustration style, photography mood and copywriting voice cues read from a screenshot. An agent flag additionally writes Cursor rules and skill files into both the universal .agents/skills path and the Claude Code skills directory, so the brand context is picked up without manual wiring. brandmd itself is also distributed as an installable Agent Skill, and a companion repository provides ready-made brand skills for Tailwind CSS, shadcn/ui, Vercel, Mintlify and Anthropic. The tool is deliberately fail-closed. Block pages, access-denied responses, login walls and pages with too little evidence cause a refusal with exit code 2 in every format and no artifact is written, so a poor capture cannot overwrite a good DESIGN.md; an override flag forces output but marks the artifact in each format. Writes are transactional, using temporary files and rename with rollback. Exit codes distinguish success, operational or validation errors, refusals, and drift detected by the check subcommand. A check subcommand compares a deployed page against a committed DESIGN.md for design drift, comparing colors by semantic role rather than as an unordered set of hex values, and failing builds on lost or repainted roles and changed primary or secondary fonts. The documentation is candid about its limits: component drift is reported but does not fail a build, secondary font changes can pass unnoticed, and dynamically changing pages can produce spurious major changes, so results should be reproduced before being trusted. A separate diff subcommand compares two DESIGN.md files and produces a markdown report of shared and unique colors, typography, spacing, radii and per-component differences, along with a what-to-copy synthesis. A gallery of example outputs from Stripe, Linear, GitHub, Vercel, Notion, Cursor, Anthropic, Figma, Supabase, Raycast and others is included in the repository. The project is MIT licensed.