SpecLens UI

SpecLens UI turns team UI standards into executable, accountable, baseline-aware semantic governance rules.

It is not a visual diff platform, accessibility engine, design system portal, or monitoring platform. It is a lightweight governance runner that attaches to real E2E scenarios and reports UI conformance issues with evidence, ownership, and baseline status.

Current Status

• Stages 1-7 are implemented and covered by scripts/core-smoke.mjs plus the real project pilot.
• Dev runtime check is implemented through speclens-ui dev-check for local dev server pages.
• Stage 7 was validated against E:\Work\admin-list\apps\admin-pro-health with 3 real routes, baseline, CI handoff check and retrospective output.

Core Capabilities

• Rule runner with rule level override and rule options.
• Stable issue fingerprint, required issue evidence and baseline classification.
• JSON, Markdown, JUnit and CI summary reports.
• CI exit strategy, defaulting to new-errors.
• Playwright-compatible adapter and scenario runner.
• Dev runtime CLI that opens local dev pages in a real browser and writes scenario results, reports and baseline status.
• Built-in MVP UI governance rules.
• Presets, custom rules and accountable suppressions.
• Pilot JSON Schema output for manifest, scenario-results and review records.
• Pilot manifest template and validation for 3-page business project trials.
• Pilot scenario-results serialization for E2E runner handoff.
• Pilot aggregation API for 3-page business project trials.
• Pilot readiness check CLI for manifest, scenario results, report and review records.
• Pilot retrospective generation from reports and validated review records.
• speclens-ui pilot-init CLI for generating a pilot manifest.
• speclens-ui pilot-validate CLI for pilot plan/input readiness checks.
• speclens-ui pilot-check CLI for validating pilot handoff artifacts before CI or retrospective.
• speclens-ui pilot-report CLI for CI report generation from serialized scenario results.
• speclens-ui pilot-retro CLI for retrospective Markdown generation.

CLI

Initialize local guard settings in a business project:

speclens init

Smart integration

Use recommendations before editing config:

speclens init --recommend
speclens init --recommend --json

Use diagnostics when local setup fails:

speclens doctor
speclens doctor --json

init --recommend prints scenario candidates only. It never writes .speclens/config.mjs. doctor diagnoses setup health. It does not install dependencies, start dev servers, or repair config.

Run watch mode to monitor file changes and check UI in real-time:

speclens dev --watch

Run one-time check for the local dev server:

speclens check --base-url http://127.0.0.1:5173

Run one local development page in a real browser:

speclens-ui dev-check \
  --project my-admin \
  --base-url http://127.0.0.1:5173 \
  --url /overview \
  --headed

Run a multi-page dev runtime config:

speclens-ui dev-check \
  --config .speclens/speclens.dev.config.mjs

Use --update-baseline only when intentionally accepting the current dev runtime result as baseline.

Performance budgets

Heavy design-review checks can be bounded with performance:

export default {
  ruleProfile: 'design-review',
  performance: {
    ruleTimeoutMs: 5000,
    maxIssuesPerRule: 50,
    maxElementsPerRule: 5000,
    governanceTopN: 100,
  },
}

Built-in heavy design rules cooperate with these budgets inside browser-side DOM scans. If a rule truncates, reports include telemetry so reviewers know the result was bounded.

Generate JSON Schema for external validation:

speclens-ui pilot-schema \
  --name scenario-results \
  --out .speclens/schemas/scenario-results.schema.json

Create a pilot manifest:

speclens-ui pilot-init \
  --project my-business-app \
  --out .speclens/speclens-pilot.json

Validate pilot manifest before E2E implementation:

speclens-ui pilot-validate \
  --manifest .speclens/speclens-pilot.json \
  --min-scenarios 3

Validate pilot input before report generation:

speclens-ui pilot-validate \
  --input .speclens/scenario-results.json \
  --min-scenarios 3 \
  --require-owners

Generate report artifacts and CI exit code:

speclens-ui pilot-report \
  --input .speclens/scenario-results.json \
  --project my-business-app \
  --baseline .speclens/baseline.json \
  --out .speclens/reports \
  --ci-strategy new-errors

Check pilot handoff artifacts before CI or retrospective:

speclens-ui pilot-check \
  --manifest .speclens/speclens-pilot.json \
  --input .speclens/scenario-results.json \
  --report .speclens/reports/speclens-report.json \
  --reviews .speclens/pilot-review-records.json \
  --min-scenarios 3 \
  --require-owners

Generate retrospective Markdown:

speclens-ui pilot-retro \
  --report .speclens/reports/speclens-report.json \
  --reviews .speclens/pilot-review-records.json \
  --out .speclens/reports/speclens-retrospective.md

Use --update-baseline only when intentionally accepting the current pilot result as baseline.

Documentation

• 落地方案
• 项目边界
• 架构设计
• 规则系统
• E2E 接入
• Baseline 与报告
• 任务清单
• MVP 验收
• 阶段 7 试点执行手册
• 开发运行时检查
• 本地 UI 运行时守门工具 (Local Dev Guard)
• 本地 UI 守门工具详细功能设计与任务清单

Verification

npm run build
npm run smoke

The smoke script validates core rules, baseline, reporters, Playwright adapter, dev runtime check, extension points, suppression, pilot manifest, pilot JSON Schema output, pilot scenario-results serialization, CI summary, pilot report artifacts, pilot retrospective generation, review record validation, and the dev-check, pilot-schema, pilot-init, pilot-validate, pilot-check, pilot-report and pilot-retro CLI commands.