lyse

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

• CHANGELOG.md — release history
• docs/ — full documentation, rule pages, architecture
• CONTRIBUTING.md — how to add a rule or fix a bug
• LICENSE / COMMERCIAL.md — dual AGPLv3 / commercial
• SECURITY.md — vulnerability reports

© 2026 Lyse Labs.