Review your app

View as Markdown

Your coding agent reviews the running application in a browser and captures evidence for each finding. Before creating browser tests, run the design review. In addition to visual quality, it checks accessibility (WCAG 2.1 AA) and testability, including whether the page provides the semantic information required by assistive technologies and automated tests.

Run a design review

Start with a design review of accessibility and testability:

/shiplight review design — focus on accessibility and testability

The focus text is optional. Without it, the design review includes accessibility, testability, visual quality, and responsive behavior. Add --thorough or --quick to set the depth. Run /shiplight review without a review type to answer a few questions about your application and receive a prioritized plan across the available review areas.

Accessibility is testability

Browser tests identify elements by accessible name, just as users do: "Click the Create button" or "Fill in the Email field." When buttons, fields, and sections have appropriate labels, roles, and ARIA attributes, tests can identify the intended element reliably.

Missing accessible names affect both users and tests. A screen reader cannot describe an unlabeled icon button, and a test may have to locate it by its position in the page structure. That locator can break when the layout changes.

The review identifies elements that cannot be located by name, including unnamed buttons, unlabeled inputs, and controls with ambiguous text. Each finding includes a specific recommendation, such as adding a label or ARIA attribute. When no semantic option is appropriate, it may recommend a data-testid as a fallback.

This improves your tests in three ways:

• More accurate — Tests identify the intended element even when the same text appears more than once.
• More stable — Tests that use accessible names are less affected by redesigns and layout changes than tests that depend on page structure. This also reduces locator repair during runs (why).
• More accessible — The same changes improve the experience for users of assistive technologies.

The design review also covers responsive behavior across breakpoints, visual consistency, typography, and internationalization readiness.

Review the report

The review creates shiplight/reports/design-review-{date}.md. The report includes a score for each category and findings organized by severity. Each finding cites the relevant standard, such as a WCAG criterion, Material Design guidance, or APCA, and includes evidence and a confidence score. The report omits heuristic findings with less than 50% confidence.

Each finding includes two ways to address the issue:

• File-level fix guidance — The current value, proposed change, and explanation of how the change meets the standard.
• A YAML regression test — A test created through create-yaml-tests to prevent the issue from returning.

Review other areas

The same command supports reviews for security, privacy, compliance, resilience, performance, seo, and geo. Run a specific review, such as /shiplight review security, or use /shiplight review --all to combine every applicable area into one report.

When to run a review

• Before creating a test suite — Identify stable semantic information that tests can use.
• When fix repeatedly repairs the same locators — Find and correct the underlying testability problem instead of continuing to update tests.
• Before a launch or demonstration, or when a designer is unavailable — Evaluate the interface against objective, measurable criteria.