Lyse
Design systems drift. Lyse measures it.
The local, deterministic health score for your design system — audit, explain, and hand the fixes to your coding agent, locally or in CI.
Quickstart
AI coding agents ship UI fast — and hardcode #3b82f6 where color.brand.primary exists, reinvent <Button>, and skip stories. Lyse audits the drift they (and humans) introduce, scores it 0–100, and hands the fixes back to the same agent.
npx -y @lyse-labs/lyse@latest
That's it — no config, no prompts, your Health Score in seconds.
Optional: calibrate
lyse init detects your framework, writes .lyse.yaml, and optionally wires the MCP server for your AI agent.
npx -y @lyse-labs/lyse@latest init
Commands
lyse audit # rerun the audit (text, JSON, or SARIF)
lyse handoff # audit, then hand the findings to your coding agent to fix (Claude Code / Cursor / Codex)
lyse init --scaffold # generate missing AI-readiness files (llms.txt, AGENTS.md)
lyse init --migrate-tokens # convert legacy {value,type} token JSON to DTCG ({$value,$type})
lyse explain X # rationale + examples for a rule
lyse mcp setup # wire MCP into Cursor / Claude Code / Codex
lyse manifest # print the versioned, graph-derived DS Machine Manifest for agents/CI
lyse add ci-gate # install the diff-first CI gate (.github/workflows/lyse.yml)
lyse baseline write # record accepted findings to .lyse/baseline.json (commit it)
lyse share # copy a Markdown summary to your clipboard
lyse manifest (also served over MCP as get_ds_manifest) publishes a
stable, versioned contract describing the design system — tokens,
component contracts, zone summary, extraction status — for coding agents,
MCP clients, and CI. Built without running an audit, so it never affects
the Health Score. Schema and versioning policy in
docs/architecture/manifest.md.
Trust boundary. By default, lyse handoff launches your coding agent with its permission prompts bypassed so it can apply fixes unattended — only run it on repositories you trust. It confirms before spawning (Continue? [y/N], skipped under --yes or non-interactively); pass --review to keep the agent's own per-action permission prompts instead.
Diff-first workflow
Existing drift shouldn't block a PR. Run lyse baseline write once to record the accepted findings + scores to .lyse/baseline.json, commit it, then wire lyse add ci-gate (or run lyse audit --scope new yourself). CI gates only on new drift — a finding absent from the baseline, or a Health Score axis that regressed — never on the backlog. Finding identity is stable across reformatting (file + rule + normalized value, not line numbers), so a whitespace-only commit produces zero new findings. Re-run lyse baseline write whenever you deliberately accept new state.
What it audits
A Health Score (0–100) across 6 axes — tokens, a11y, components, stories, ai-surface, ai-governance — from deterministic static rules. Each axis is an opportunity-weighted clean-adoption ratio (scoring-v3); axes need 30+ opportunities to count. CMMI-style maturity tier (Foundational → Autonomous) mapped from the score. No LLM, no network, fully local by default. The previous severity-weighted formula stays reachable for one minor release via --score-model v2 — scores are not comparable across the two. Full formula and per-rule docs in docs/.
Token drift is judged against your scale, not a built-in one: every hardcoded value is resolved against the token scales Lyse derives from your repo (Tailwind config, *.tokens.json, CSS custom properties, SCSS variables) and classified exact / near / novel / unresolved. A value on your own scale is not drift; a value close to a token is reported with its candidate; a value unlike anything is reported but not claimed as drift; an expression Lyse cannot judge statically is not reported at all and is counted in meta.abstentions.
The optional render layer (lyse audit --render) runs additional checks against a pre-built Storybook (storybook-static/ or a URL): tokens/rendered-token-fidelity (CSS custom property drift) and a11y/runtime-axe (axe-core a11y violations). Both are experimental and do not affect the Health Score.
lyse explain --score also reports an AI-Governance Maturity Level (L0–L5, by presence of AI affordances — marker components, AI tokens, interaction patterns, governance docs). Deterministic by default; an optional LLM tier reads semantic affordances for the harder cases.
Privacy
lyse audit is static-only by default: nothing leaves your machine. The optional LLM precision filter is opt-in (--llm, LYSE_LLM=1, or explicit llm.provider config) and BYOK — having the claude CLI installed does not enable it silently, and the default audit never prompts for it. Telemetry is opt-in only (a one-time prompt shown after your first report, default declines). See PRIVACY.md.
More
© 2026 Lyse Labs.
