Build an AI Design Review Gate

Create a design review gate with Impeccable for your local web page.

Introduction

30 Second Summary

A page can work perfectly while still feeling confusing or difficult to use. Some problems only surface on a smaller screen or when someone leaves the mouse behind.

In this project, you will use Impeccable and Claude Code to build an evidence-based design review gate around one page from an existing web project. The gate combines source, desktop, mobile, usability, and technical evidence while preserving your authority over brand and hierarchy.

What You'll Build

Open one review record to show what automation caught, how your page behaved under real conditions, and which design choices required human judgment.

By the end of this project, you'll have:

A repeatable evidence set that lets you rerun source, desktop, and mobile scans against the same page.
A reviewed design-system context in DESIGN.md that exposes drift from your product's real colors, typography, and shapes.
A clear decision split in DESIGN_REVIEW.md between agent-checkable evidence and choices reserved for human judgment.
Secret Mission: Enable the Claude Code design hook and prove it catches a temporary UI regression automatically.

Are there any prerequisites?

You need an existing web project with one page that runs locally on macOS plus its documented development command. Step 1 covers every unconfirmed tool, while an eligible Claude Code account remains required.

Before We Start

Before any review begins, this is your moment to commit to one page from an existing local web project. Recording its intended local URL or route, main visitor task, and visitor impact keeps every later finding tied to a real goal.

Set Up the Review Workspace

A design review only earns trust when its full workspace works together. A broken runtime can make useful evidence look unreliable.

Node.js supplies the runtime for the review CLI. Google Chrome supplies the rendered page.

Claude Code hosts the review agent. Impeccable supplies the project-level detector.

In this step, get ready to:

Verify the local review toolchain.
Run the selected page at its exact route.
Initialize Impeccable with accurate product context.

Verify Node.js, Claude Code, and Google Chrome

Impeccable requires a supported Node.js runtime. This project uses Node.js v26.13.0 LTS so every later command starts from the same runtime.

Press Cmd+Space to open Spotlight.
Type Terminal into Spotlight.
Press Enter to open Terminal.
Check the installed Node.js plus npm versions by running:

node --version
npm --version

What Do These Checks Prove?

The first command confirms which Node.js runtime executes Impeccable.
The second command confirms that npm is available for package operations.

✔️ I see the required LTS version

Good. Node.js reports v26.13.0. npm also reports an installed version.

ⓧ I see an older Node.js version

Your existing runtime needs an in-place upgrade before the review tools run against the pinned version.

Visit the official Node.js download page.
Select Node.js v26.13.0 LTS.
Run the downloaded macOS installer.
Press Cmd+Space after the installer finishes.
Type Terminal into Spotlight.
Press Enter to open a fresh Terminal window.
Verify the upgraded runtime by running:

node --version
npm --version

What Should You See?

Node.js now reports v26.13.0. npm reports an installed version.

Still Seeing the Older Version?

Close every Terminal window before opening a new one. This refreshes the shell path after the installer finishes.

Ask for help with the runtime path. Share the result in the NextWork community.

ⓧ Command not found

Node.js is missing from your shell. Installing the LTS package also installs npm.

Visit the official Node.js download page.
Select Node.js v26.13.0 LTS.
Run the downloaded macOS installer.
Press Cmd+Space after the installer finishes.
Type Terminal into Spotlight.
Press Enter to open a fresh Terminal window.
Verify the new installation by running:

node --version
npm --version

What Should You See?

Node.js now reports v26.13.0. npm reports an installed version.

Are the Commands Still Missing?

Confirm that the macOS installer completed successfully. Open a completely new Terminal window before repeating the checks.

Ask for help with the missing commands. Share the result in the NextWork community.

Claude Code needs an eligible account before Impeccable can add its review skills to the project.

Check for an existing Claude Code installation by running:

claude --version

What Does This Check Prove?

A version response confirms that the Claude Code command is available in your current shell.

Know Which Account Pays

Claude Code requires an eligible paid plan or a Console account. A Free plan does not include Claude Code.

An active ANTHROPIC_API_KEY makes Claude Code use API billing. Declining API credits keeps this project within subscription usage when your account is eligible.

✔️ I see a Claude Code version

Starting Claude Code opens its interactive session. An unauthenticated installation guides you through browser sign-in.

Start Claude Code by running:

claude

What Does This Command Start?

The command starts the Claude Code session attached to the current Terminal location.

Complete browser sign-in with your eligible account.
Decline API credits if you want to stay within subscription usage.
Close this temporary session by pressing Ctrl+C after authentication succeeds.

Claude Code is now authenticated. The project-specific session comes after Impeccable is installed.

ⓧ Command not found

The stable installer adds Claude Code to macOS. It may ask you to complete browser authentication when you start the command later.

Install the Claude Code stable channel by running:

curl -fsSL https://claude.ai/install.sh | bash -s stable

What Does This Command Do?

The command downloads the official macOS installer. It selects the stable Claude Code channel.

Press Cmd+Space after the installer finishes.
Type Terminal into Spotlight.
Press Enter to open a fresh Terminal window.
Verify the installation by running:

claude --version

What Should You See?

Terminal prints the installed Claude Code version.

Start Claude Code by running:

claude

What Does This Command Start?

The command starts an interactive Claude Code session. An unauthenticated installation guides you through browser sign-in.

Complete browser sign-in with your eligible account.
Decline API credits if you want to stay within subscription usage.
Close this temporary session by pressing Ctrl+C after authentication succeeds.

Is Claude Code Still Unavailable?

Confirm that the installer completed without a network error. Open a new Terminal window so the shell can find the installed command.

Ask for help with the installation. Share the result in the NextWork community.

Google Chrome provides the rendered viewport that later detector checks inspect.

Press Cmd+Space to open Spotlight.
Type Google Chrome into Spotlight.
Press Enter to try opening Google Chrome.

✔️ Google Chrome opens

Google Chrome is ready to display the local page during rendered detector scans.

ⓧ Google Chrome is missing

Installing Google Chrome gives the review workflow a supported browser for rendered checks.

Download Google Chrome from the official Chrome page.
Open the installation file from Downloads.
Follow the macOS installer instructions.
Repeat the Spotlight search for Google Chrome.

Does Chrome Still Refuse to Open?

Confirm that the installation file completed its copy step. Repeat the Spotlight search after closing the installer.

Ask for help with the browser installation. Share the result in the NextWork community.

Your runtime, agent account, and browser are ready. The next check connects them to the selected page.

Run the selected page at its exact route

The development server turns your existing project into a page the browser can reach. A shell environment variable keeps that page's exact URL available to later commands.

Move to your existing web project's top-level folder by running:

cd '[[PROJECT_PATH="path to your existing web project"]]'

What Does This Command Do?

The command places Terminal in the folder that contains your existing web project.

Find the development command in the project's README or package scripts.
Record that command here: your project's documented development command.
Start the development server by running the recorded command:

[[DEV_COMMAND="your project's documented development command"]]

What Should the Server Do?

The server keeps this Terminal tab occupied while it runs. Its output prints a local origin that usually contains localhost plus a port.

Keep this tab running. Stopping the process makes the page unavailable to Impeccable.

Press Command-T to create a second Terminal tab.
Copy the exact local origin printed by the development server.
Append the recorded page route to form the exact review URL.
Replace http://localhost:PORT/path below with that exact review URL.
Export the completed URL by running:

export TARGET_URL='http://localhost:PORT/path'

What Does This Variable Hold?

TARGET_URL holds the precise local page URL for this Terminal tab. The route matters because the review targets one visitor task.

Before you open the page, do you expect the recorded route to load the exact task you chose in Step 0?

Open the exported target URL by running:

open "$TARGET_URL"

What Does This Command Prove?

The command sends the exported URL to your default browser. A successful page load proves that the server origin plus route are reachable.

Google Chrome should show the selected page at its exact route. The content should match the real page you intend to review.

Complete the page's recorded main visitor task in Google Chrome.

You should reach the task's expected result without a routing error. That proves the review target works before any detector scans begin.

Does the Page Fail to Load in Chrome?

Confirm that the first Terminal tab still shows the running development server. Check that TARGET_URL includes the exact route after the port.

If another browser opened, switch to Google Chrome. Paste the exact URL from your export command into Chrome's address bar.

Ask for help with the local route. Share the result in the NextWork community.

Install Impeccable and initialize product context

Why Use the Project-Level CLI?

A browser extension focuses on visual overlays. The project-level CLI keeps repository context plus shared detector settings beside the project.

Hooks remain disabled during the main project. This lets you experience the manual review loop before automating it in the optional challenge.

The pinned installer adds Impeccable 4.8.0 for Claude at project scope. The --no-hooks flag keeps automatic checks disabled.

Return to the second Terminal tab.
Move to the existing web project's top-level folder by running:

cd '[[PROJECT_PATH="path to your existing web project"]]'

Why Return to This Folder?

Project scope attaches the Impeccable installation to the selected repository. Running the installer here keeps the review setup beside the page it governs.

Install the pinned Impeccable project integration by running:

npx impeccable@4.8.0 install -y --providers=claude --scope=project --no-hooks

What Does This Installer Configure?

The package specifier selects Impeccable 4.8.0.
The --providers=claude flag installs the Claude provider integration.
The --scope=project flag keeps the setup inside this project.
The --no-hooks flag leaves automatic checks off.

The installer returns control to Terminal without an installation error. The project now has the pinned Impeccable integration.

Does the Impeccable Install Fail?

Confirm that Node.js still reports v26.13.0. Check that Terminal is inside the selected web project's top-level folder.

Ask for help with the pinned installation. Share the result in the NextWork community.

Start a fresh Claude Code session inside the project by running:

claude

Why Start a Fresh Session?

The fresh session loads the project-scoped Impeccable skills that the installer just added.

Initialize the product context inside Claude Code by entering:

/impeccable init

What Does Initialization Create?

The command writes PRODUCT.md as shared context for future Impeccable reviews.

That context anchors findings to the product's real audience plus task. It also records the platform plus relevant constraints.

You should now see PRODUCT.md in the project. Reviewing it prevents incorrect assumptions from shaping later design feedback.

Ask Claude Code to show PRODUCT.md.
Confirm that the audience matches the real product.
Confirm that the main task matches the selected page.
Confirm that the platform describes the real web experience.
Confirm that the constraints match the current product.
Ask Claude Code to correct each inaccurate detail in PRODUCT.md.

The product context now reflects the page that visitors actually use. Impeccable can ground later reviews in that shared description.

Keep the Claude Code session running in the second Terminal tab.
Press Command-T to create a third Terminal tab.
Move to the existing web project's top-level folder by running:

cd '[[PROJECT_PATH="path to your existing web project"]]'

What Is This Tab For?

The third tab gives you a shell for final command checks while the development server plus Claude Code remain active.

Before you run the final checks, which three signals should prove that the runtime, agent, and detector are ready?

Run the final workspace checks with:

node --version
claude --version
npx impeccable help

What Do the Final Checks Prove?

The Node.js response confirms the pinned runtime remains active.
The Claude Code response confirms the agent command remains available.
The Impeccable help response confirms that the project installation can list its commands.

Node.js prints v26.13.0. Claude Code prints its installed version.

Impeccable prints its command list. Google Chrome still shows the selected page completing its visitor task.

Does a Final Check Fail?

Return to the tool-specific result above that matches the missing command. Confirm that the third Terminal tab is inside the selected project's top-level folder.

Ask for help with the final verification. Share the result in the NextWork community.

Your page now runs inside a verified review workspace. Next, you will capture the context-free source plus viewport baselines.

Capture a Context-Free Baseline

Your reviewed page is already running in Google Chrome. Impeccable can now inspect the repository plus the rendered result.

A context-free baseline records evidence from deterministic checks before DESIGN.md exists. Project-specific drift remains outside this first snapshot.

In this step, get ready to:

Save context-free findings from the actual UI source directory.
Save a rendered desktop baseline at the default viewport.
Save a rendered mobile baseline for cross-scan comparison.

Save the source baseline

The source scan reads your UI files without launching another browser viewport. Saving the findings as JSON gives the baseline a stable format for later comparison.

Return to the Terminal tab at the project root from earlier.
Create the evidence folder by running this command:

mkdir -p review-evidence

What Does This Command Create?

The command creates review-evidence inside your existing project. The -p option keeps the command safe when the folder already exists.

Wait for Terminal to return to the prompt.

A silent return means the evidence folder is ready for the first scan.

Couldn’t Create the Evidence Folder?

Confirm the Terminal tab is at the project root that contains PRODUCT.md.
Check that your macOS account can create files in this project.

If the folder still fails to appear, help me diagnose the folder creation problem.

Check your project file list for a src/ directory.
Replace src/ in the command below with the actual UI source directory if your project uses another location.
Save the context-free source scan by running this command:

npx impeccable detect --json src/ > review-evidence/source-no-design.json

What Does This Scan Capture?

The detect command scans the selected UI source directory for known patterns.

The --json option formats the findings as JSON. The shell redirect saves that output in review-evidence/source-no-design.json.

Confirm review-evidence/source-no-design.json appears in your project file list.

You now have source evidence that intentionally excludes design-system context.

How Should You Read the Exit Code?

Exit code 2 means the scan completed with primary findings.
Exit code 1 means at least one target could not be scanned. Fix the target before continuing.

Is the Source Evidence Missing?

Confirm the source path matches the directory that contains your UI files.
Confirm the Terminal tab is still at the project root.
Rerun the scan after correcting the source path.

For help with the scan target, help me find the correct UI source directory.

Scan the desktop viewport

A rendered viewport lets the detector inspect layout-dependent issues that source files alone cannot reveal. With no viewport override, the URL scan uses 1280x800.

Capture the default desktop viewport in review-evidence/desktop-no-design.json by running this command:

npx impeccable detect --json "$TARGET_URL" > review-evidence/desktop-no-design.json

What Does the Desktop Scan Add?

The URL target makes Impeccable inspect the rendered page at TARGET_URL. This reveals issues that depend on browser layout.

The absence of a viewport option preserves the default 1280x800 desktop dimensions.

Confirm review-evidence/desktop-no-design.json appears in your project file list.

You should now have a second JSON file containing evidence from the running desktop page.

Did the Desktop Scan Fail?

Confirm the development server from earlier is still running.
Confirm TARGET_URL still contains the exact local page URL plus its route.
Confirm the page still loads in Google Chrome.

If the URL scan still cannot reach the page, help me diagnose the rendered desktop scan.

Save the mobile baseline

The mobile scan keeps the same page plus the same detector rules. Its 390x844 viewport exposes findings that depend on a narrow layout.

Capture the mobile viewport in review-evidence/mobile-no-design.json by running this command:

npx impeccable detect --json --viewport 390x844 "$TARGET_URL" > review-evidence/mobile-no-design.json

What Changes in This Scan?

The --viewport 390x844 option renders the existing target at a mobile width plus height. The saved evidence can now be compared with the desktop result.

Confirm review-evidence/mobile-no-design.json appears in your project file list.

Your evidence set now covers source files plus two rendered widths.

Open review-evidence/source-no-design.json in your usual project editor.
Open review-evidence/desktop-no-design.json in your usual project editor.
Open review-evidence/mobile-no-design.json in your usual project editor.
Identify findings that repeat across the source file plus both rendered files.
Identify findings that appear only in the desktop or mobile evidence.

Before you run the final check, do you expect all three evidence files to report a size greater than zero?

Measure the three evidence files by running this command:

wc -c review-evidence/*-no-design.json

What Does This Check Prove?

The wc -c command counts the bytes in every matching baseline file. A positive count confirms that each redirected scan saved output.

You should see a positive byte count beside desktop-no-design.json, mobile-no-design.json, plus source-no-design.json.

Is a File Missing or Empty?

Match the missing filename to its source, desktop, or mobile scan.
Rerun only the corresponding detector command.
Repeat the file-size check after the scan completes.

If a file remains empty, help me diagnose the missing baseline output.

That is your first review dataset complete. The three saved files now preserve source, desktop, and mobile evidence for the real page.

Your baseline now shows what the detector can learn without project design context. Next, you will document the real design system and measure what that context adds.

Load and Prove the Design Context

The context-free JSON evidence shows what Impeccable detects through global rules. It cannot identify drift from your product's own palette or type scale.

A reviewed design system gives the detector that missing context. You will document the real system before proving that its project-specific rules are active.

In this step, get ready to:

Generate a reviewed design-system document from the running page.
Capture design-aware source plus rendered scans.
Prove context loading with a reversible calibration file.

Generate and review DESIGN.md

Generated design context gains authority over future scans. Your review keeps accidental one-off values from becoming product rules.

Switch back to the existing Claude Code session.
Generate the design-system documents from the running page by entering this command:

/impeccable document

What Does This Command Create?

The command records the existing interface's design vocabulary in DESIGN.md.
The YAML frontmatter supports colors.
The frontmatter also supports typography plus rounded values.
The generated companion file at .impeccable/design.json supplies extra detector metadata.

Select DESIGN.md in the project file tree.
Refine DESIGN.md by keeping only intentional colors plus intentional typography plus intentional corner-radius values.
Save DESIGN.md.
Confirm the saved frontmatter contains real colors values.
Confirm the saved frontmatter contains real typography values.
Confirm the saved frontmatter contains real rounded values.

The reviewed frontmatter now describes deliberate product choices. Those values can support project-specific detector findings.

Review the Markdown body against the running page.
Keep the applicable canonical headings from Overview through Do's and Don'ts.
Save the final DESIGN.md.
Confirm .impeccable/design.json exists inside the .impeccable/ directory.
Leave .impeccable/design.json unchanged.

That review gives the detector a trusted vocabulary for the product. The generated companion remains aligned with the document that produced it.

Missing a Design Context File?

Confirm the local page still loads at TARGET_URL.

Confirm the documentation command ran inside the existing project session.

Help me diagnose the missing Impeccable design context files.

Re-run scans with design context

Each new scan must use the same target as its context-free baseline. This keeps design context as the meaningful difference within each pair.

Use the same actual UI source directory that produced review-evidence/source-no-design.json.
Replace src/ in the first command when your baseline used a different UI source directory.
Capture the three design-aware scans by running these commands:

npx impeccable detect --json src/ > review-evidence/source-with-design.json
npx impeccable detect --json "$TARGET_URL" > review-evidence/desktop-with-design.json
npx impeccable detect --json --viewport 390x844 "$TARGET_URL" > review-evidence/mobile-with-design.json

What Do These Scans Capture?

The first command checks the UI source against the reviewed design context.
The second command checks the rendered page at the default 1280x800 viewport.
The third command checks the rendered page at the 390x844 viewport.
Exit code 2 means a scan completed with primary findings.

Confirm review-evidence/source-with-design.json contains JSON output.
Confirm review-evidence/desktop-with-design.json contains JSON output.
Confirm review-evidence/mobile-with-design.json contains JSON output.

You now have a matching design-aware result for every baseline target. Each pair can reveal what project context adds.

Compare review-evidence/source-no-design.json with review-evidence/source-with-design.json.
Compare review-evidence/desktop-no-design.json with review-evidence/desktop-with-design.json.
Compare review-evidence/mobile-no-design.json with review-evidence/mobile-with-design.json.
Note any new design-system-font findings.
Note any new design-system-color findings.
Note any new design-system-radius findings.
Note any new design-system-font-size findings.

How Should You Read the Comparison?

New design-system findings identify values that drift from the documented product vocabulary.

Identical real-page results are valid. They can show that the page already follows the documented system.

Missing Design-Aware Evidence?

Confirm the source target matches the actual UI directory used for the baseline scan.

Confirm the development server still responds at TARGET_URL.

Help me diagnose the missing design-aware scan evidence.

Prove context loading with a calibration

A temporary CSS fixture creates a controlled design-system violation. Scanning the same fixture twice isolates the effect of design context.

Confirm #010203 is absent from DESIGN.md.
Confirm 37px is absent from DESIGN.md.
Choose different absent literals when either value already belongs to the documented system.
Create the temporary calibration file at the project root by running this command:

printf '.review-calibration{color:#010203;border-radius:37px;font-size:37px}\n' > review-calibration.css

What Does This Fixture Test?

The selector contains a color plus two sizes outside the reviewed vocabulary. Both scans receive the same controlled input.

Confirm review-calibration.css exists beside DESIGN.md.
Inspect review-calibration.css to confirm it contains the calibration rule.

The temporary file now gives the detector a known out-of-system target. The real page remains unchanged.

Calibration File Missing?

Confirm the command ran from the project directory that contains DESIGN.md.

The command writes review-calibration.css into the terminal's current directory.

Help me create the calibration file in the correct directory.

Capture the context-free calibration result plus the design-aware calibration result by running these commands:

npx impeccable detect --json --no-design-system review-calibration.css > review-evidence/calibration-no-design.json
npx impeccable detect --json review-calibration.css > review-evidence/calibration-with-design.json

Why Scan the Fixture Twice?

The first scan uses --no-design-system to skip design-system checks for that run. The second scan loads the reviewed design context.

Both results stay under review-evidence/ for a direct comparison.

Confirm review-evidence/calibration-no-design.json contains JSON output.
Confirm review-evidence/calibration-with-design.json contains JSON output.

Both retained files now describe the same temporary rule under two detector modes. That matched input makes the comparison trustworthy.

Calibration Scan Failed?

Confirm review-calibration.css remains at the project root while both scans run.

Treat exit code 2 as completed evidence with primary findings.

Help me diagnose the calibration scans.

Delete the temporary fixture by running this command:

rm review-calibration.css

Why Remove the Fixture?

The fixture exists only to prove context loading. Removing it keeps temporary calibration styles out of the project.

Confirm review-calibration.css no longer exists at the project root.
Confirm DESIGN.md still excludes the temporary calibration literals.

Before you compare the retained files, which result do you expect to contain the extra design-system findings?

Compare the retained calibration evidence by running this command:

diff -u review-evidence/calibration-no-design.json review-evidence/calibration-with-design.json

What Does the Difference Prove?

You should see one or more design-system findings only in the design-aware result. The difference proves that DESIGN.md activates project-specific checks.

The two retained JSON files preserve that proof after the temporary fixture is deleted.

No Design-System Difference?

Confirm the calibration literals are absent from DESIGN.md.

Confirm the first calibration scan includes --no-design-system. Confirm the second scan omits that flag.

Help me diagnose an identical calibration comparison.

That controlled difference completes the proof. Your review stack can now separate global detector findings from project-specific design drift.

Your design context is reviewed plus verified. Next, you will test where deterministic rules stop through real visitor conditions.

Review the Page Under Real Conditions

Your Impeccable evidence now proves that the project design system is loading. That evidence can identify repeatable drift in source files plus rendered layouts.

Now you will use Claude Code with Impeccable to capture a usability critique. A technical audit will expose risks that deterministic scans cannot decide.

A slow mobile simulation in Google Chrome can reveal delayed controls or shifting layouts. Keyboard-only testing can reveal focus problems that a pointer hides.

In this step, get ready to:

Run an Impeccable critique of the exact page URL.
Save a technical audit with P0-P3 priorities.
Test the visitor task under slow mobile plus keyboard-only conditions.

Run the design critique

A critique examines whether the page communicates clearly to its intended visitor. It preserves the code while producing a scored report with strengths plus priority issues.

Return to the Terminal tab that holds TARGET_URL.
Print the exact page URL by running this command:

printf '%s\n' "$TARGET_URL"

What Does This Check Do?

The printf command displays the current value of TARGET_URL without changing it. This gives you the exact route that the running page uses.

You will see the complete local URL in the terminal. Keep that value visible for the critique prompt.

Switch back to the Claude Code session from earlier.
Replace <local URL> in the prompt below with the exact URL printed in Terminal.
Submit the completed critique prompt in Claude Code:

/impeccable critique the page at <local URL>

What Does the Critique Add?

The critique evaluates the page as a visitor experience without editing the interface.
The report scores usability before surfacing strengths plus priority issues.
The full report is archived under .impeccable/critique/ for later review.

Tell Claude Code the page's main visitor task.
Tell Claude Code which parts of the page are intentionally unfinished.
Review the reported strengths.
Review the usability scores.
Review the priority issues.
Review the questions that require product judgment.

That is the first judgment layer captured. The critique now connects each concern to the visitor task that matters.

Confirm the response reports a saved path under .impeccable/critique/.
Ask Claude Code to add ## Design Critique to DESIGN_REVIEW.md.
Ask Claude Code to reference the preserved critique report path in that section.

Did the Critique Stop Early?

Confirm that the development server still serves the printed URL. Keep the exact route in the critique prompt because reviewing a different route produces irrelevant evidence.

Check that the page completes loading in Chrome before retrying the critique.

Help me diagnose an Impeccable critique that cannot review my local page.

Run the technical audit

The critique covers design judgment. The audit examines technical quality across accessibility, performance, theming, responsive behavior, plus implementation integrity.

Remain in the Claude Code session used for the critique.
Run the technical audit against the same page:

/impeccable audit the same page

What Does the Audit Cover?

Accessibility evidence identifies barriers that affect interaction or comprehension.
Performance evidence identifies work that slows the visitor's task.
Theming plus responsive evidence checks behavior across visual modes or viewport sizes.
Implementation integrity evidence checks whether the interface is built consistently.
P0-P3 priorities separate blocking risks from polish.

Ask Claude Code to append the full audit report to DESIGN_REVIEW.md under ## Technical Audit.
Return to DESIGN_REVIEW.md after Claude Code finishes writing the report.
Confirm the audit includes accessibility findings.
Confirm the audit includes performance findings.
Confirm the audit includes theming findings.
Confirm the audit includes responsive behavior findings.
Confirm the audit includes implementation integrity findings.
Confirm the findings use P0-P3 priorities.

The full technical audit is now part of the shared review record. Each issue has a priority that the next step can turn into a decision.

Is the Audit Incomplete?

Confirm that Claude Code audited the same local page used for the critique. A source-only response does not cover the rendered responsive behavior required here.

Ask Claude Code to restore any missing audit dimension before moving on.

Help me complete the technical audit in my review record.

Test slow mobile and keyboard paths

Rendered scenarios expose failures that source analysis cannot reproduce. You will test the same visitor task under a constrained phone simulation plus a keyboard-only desktop path.

What Should You Record?

Focus visibility shows whether the active control remains obvious.
Focus order shows whether the task follows a logical sequence.
Labels show whether each control communicates its purpose.
Blocked interactions show where the visitor cannot continue.
Layout shifts show whether content moves during the task.
Slow-loading feedback shows whether the page explains a delay.

The mobile controls are compact, so taking a moment to locate them is normal.

Switch back to the page in Chrome.
Press Command+Option+I to open Chrome DevTools.
Press Command+Shift+M to open Device Mode.
Set Dimensions to 390 by 844.
Select Low-end mobile from the Throttle list.
Reload the page.
Attempt the page's main visitor task.
Append the slow-mobile observation under ## Human Scenario Checks in DESIGN_REVIEW.md.

What Does Device Mode Prove?

Device Mode approximates a narrow mobile viewport with constrained network plus CPU conditions. This makes layout shifts and delayed feedback easier to observe.

The simulation does not replace testing on a physical phone. Record that limitation with the result.

Keyboard-only testing now checks whether the desktop task remains usable without a pointer. The same task must stay understandable from its focus sequence plus control labels.

Return to the desktop viewport.
Move to the beginning of the page's main task.
Complete the task using only Tab, Shift+Tab, Enter, plus Space.
Switch back to the Claude Code session from earlier.
Ask Claude Code to append the keyboard-only result under ## Human Scenario Checks in DESIGN_REVIEW.md.
Ask Claude Code to include the Device Mode limitation with the slow-mobile observation.

Before you check the record, consider whether both human scenarios will appear beside the full technical audit.

Return to DESIGN_REVIEW.md.
Confirm ## Design Critique references the preserved full critique report.
Confirm ## Technical Audit contains every required audit dimension.
Confirm the technical audit uses P0-P3 priorities.
Confirm ## Human Scenario Checks contains the 390x844 Low-end mobile result.
Confirm the same section contains the keyboard-only task result.
Confirm the mobile observation states that Device Mode is an approximation.

You now have a review that reaches beyond detector output. The record captures technical evidence plus the conditions a real visitor can experience.

Your critique, audit, slow-mobile evidence, plus keyboard result are preserved. Next, you will turn every priority finding into a fix, a human decision, a narrow exception, or a durable design rule.

Turn Findings Into Decisions

Your Impeccable evidence now covers detector results, usability critique, technical audit, and real-condition observations. A raw list still creates noise because no finding has an owner or outcome.

You will use Claude Code to turn that evidence into a decision record. Each priority finding ends with one documented disposition.

In this step, get ready to:

Separate checks an agent can verify from decisions that need human judgment.
Record one narrow exception only when product or brand evidence supports it.
Promote one repeated finding into a reusable design rule before running the final scans.

Separate agent checks from human calls

Deterministic checks can verify repeatable conditions such as token drift or measurable layout behavior. Human judgment remains responsible for brand fit, hierarchy, emotional tone, and context-dependent trade-offs.

How Should the Evidence Split?

Agent-checkable evidence has an observable condition that can be tested again. Detector findings plus keyboard observations often belong here.

Human calls depend on product intent or visitor context. The table preserves both categories without flattening them into one score.

Switch back to the Claude Code session from earlier.
Ask Claude Code to consolidate the detector JSON files, preserved critique, technical audit, and scenario evidence into a table in DESIGN_REVIEW.md.
Specify the table columns as Finding, Evidence Source, Viewport, Priority, Agent Can Verify, Human Decision Required, Decision, and Rationale.
Classify deterministic layout, contrast, source-pattern, token-drift, and keyboard-observation evidence as agent-checkable.
Classify brand fit, hierarchy, emotional tone, and context-dependent trade-offs as human calls.
Require Claude Code to preserve disagreements between evidence sources.
Review every priority row against the original evidence.
Assign every priority finding a disposition of fixed, intentionally excepted, human follow-up, or accepted risk.

You have turned four evidence streams into one decision queue. Every priority row now shows who can verify it plus who has authority over the final call.

Record the narrowest defensible exception

An exception is appropriate only when a real detector value is intentional and supported by product or brand evidence. A value-specific ignore keeps the rest of the rule active.

Choose the path that matches the evidence from your page.

A Real Exception Is Warranted

Use this path when the evidence supports one intentional value-specific finding from the real page.

Choose one actual value-specific finding from the real page.
Copy its exact rule ID from the detector output.
Copy its exact ignore value from the detector output.
Write a reason that cites the supporting product or brand evidence.
Prepare the finding-specific command by replacing each placeholder below with the evidence you copied:

npx impeccable ignores add-value <rule-id> "<value>" --reason "<evidence-backed reason>"

What Does This Command Record?

The add-value form limits the exception to one rule plus one exact value.
The --reason value preserves the evidence behind the decision.
The shared exception is stored in .impeccable/config.json.

Run your customized command in the Terminal tab from earlier.
Record the exception plus its evidence-backed reason in DESIGN_REVIEW.md.

No Exception Is Warranted

A clean review does not need a ceremonial waiver. Keeping the detector active is the defensible decision.

Add No sanctioned exception to the exception status in DESIGN_REVIEW.md.
Record that no ignore was added because the evidence did not justify one.

Return to the Terminal tab where TARGET_URL is exported.
List the current project exceptions by running this command:

npx impeccable ignores list

What Does This Command Confirm?

The list exposes the shared exceptions currently applied by the detector. It gives you a direct check that no broad or fabricated waiver slipped into the review gate.

If you added a justified exception, you should see its finding-specific value plus its reason. If no exception was warranted, you should see no new waiver.

Does the Ignore List Look Wrong?

Compare the listed rule ID plus value with the original detector finding. Remove any draft command that still contains a placeholder before trying again.

Check DESIGN_REVIEW.md for the evidence behind the decision. A missing rationale means the exception is not ready to keep.

Help me review my Impeccable exception for scope and evidence.

Promote a finding into a durable rule

A repeated finding becomes more useful when it shapes future pages. One specific rule in DESIGN.md turns this review into reusable design governance.

Choose one repeated finding or human judgment that should guide future pages.
Ask Claude Code to add one specific do or do-not rule with its rationale to the appropriate canonical section of DESIGN.md.

You should now see one concrete rule in DESIGN.md that another reviewer can apply without repeating this investigation.

Before you run the final scans, which findings do you expect the new decision record to classify as fixed or still active?

Capture the final desktop plus mobile evidence by running these commands:

npx impeccable detect --json "$TARGET_URL" > review-evidence/desktop-final.json
npx impeccable detect --json --viewport 390x844 "$TARGET_URL" > review-evidence/mobile-final.json

What Do the Final Scans Capture?

The first command scans the rendered page at the default desktop viewport.
The second command scans the same page at the 390x844 mobile viewport.
Both commands retain design-system checks because neither scan disables the design context.

When both scans complete successfully, review-evidence/desktop-final.json plus review-evidence/mobile-final.json contain the final JSON evidence. Exit code 2 means the scan completed with findings.

Ask Claude Code to compare review-evidence/desktop-final.json with review-evidence/desktop-no-design.json.
Ask Claude Code to compare review-evidence/mobile-final.json with review-evidence/mobile-no-design.json.
Update DESIGN_REVIEW.md with the final scan comparison.
Review DESIGN_REVIEW.md for the finding-disposition table, agent-checkable split, human-call split, exception status, and final scan comparison.
Review DESIGN.md for the new reusable rule plus its rationale.
Confirm every priority finding ends as fixed, intentionally excepted, human follow-up, or accepted risk.

Strong finish. Your review now converts automated evidence plus human judgment into decisions that future reviewers can inspect and reuse.

Did a Final Scan Fail?

Exit code 1 means at least one target could not be scanned. Confirm the development server is still running at TARGET_URL.

Check that the review-evidence directory still exists. A missing directory prevents the shell from writing the final JSON file.

Help me diagnose my final Impeccable rendered scans.

Secret mission

Make the Review Gate Automatic

Enable the Impeccable hook inside Claude Code. Prove it catches a temporary gradient-text regression without changing the real page.

Clean Up Your Resources

Choose how this local review gate fits your next session. Keeping its files or stopping its server creates no service charge from Impeccable. Active Claude Code use can still count against your plan or Console billing.

Resources you used:

The local development server that provides the page at TARGET_URL.
The shared product context in PRODUCT.md plus the shared design context in DESIGN.md.
The generated files under .impeccable/. These include design.json, config.json, the critique archive, plus the trusted hook state.
The detector evidence under review-evidence/ plus the decisions recorded in DESIGN_REVIEW.md.

Keep everything running

No action needed. Choose this if the page is still under active review.

Keep the local development server running so TARGET_URL remains available for rendered scans.
Keep PRODUCT.md, DESIGN.md, DESIGN_REVIEW.md, plus the evidence files so future decisions retain their context.
Keep the Impeccable hooks enabled so future UI edits receive automatic checks.
Leave the project-local Impeccable installation in place for later design reviews.

Pause - I'll come back to this later

Pause automatic checks plus the development server while preserving every review artifact. Your context, evidence, decisions, plus design rules remain ready for the next session.

Switch back to the Claude Code session from earlier.
Disable automatic Impeccable checks by running:

/impeccable hooks off

What does this command do?

This disables the project's automatic checks. It preserves the design context plus the review evidence you created.

Return to the Terminal tab running your project's documented development command.
Press Control+C to stop the development server.
Refresh TARGET_URL in Google Chrome to confirm the page no longer responds.

That gives you a clean stopping point. The local server plus the automatic design checks are paused while your review record remains intact.

Delete - I don't want to use this again

Deletion is permanent, so this path begins with a repository check. You keep the existing web project's application code while removing only the review artifacts created for this exercise.

Return to the Terminal tab running your project's documented development command.
Press Control+C if the development server is still active.
Inspect the repository changes by running:

git status

What does this check show?

This Git check shows the files that differ from the repository's recorded state. Use it to separate this exercise's artifacts from existing project work before deleting anything.

Confirm that every review path listed below was created solely for this exercise.
Switch back to the Claude Code session from earlier.
Remove the Impeccable hook state by running:

/impeccable hooks reset

What does the reset remove?

The reset removes the project hook configuration, cached hook data, pending state, plus hook entries installed during the Secret Mission. It does not delete your existing application source.

Return to Terminal in the existing web project folder that contains PRODUCT.md plus DESIGN.md.
Remove the generated review artifacts by running:

rm -rf review-evidence DESIGN_REVIEW.md PRODUCT.md DESIGN.md .impeccable/design.json .impeccable/config.json .impeccable/critique

What does this cleanup remove?

This command removes the saved scans, review record, generated context files, design metadata, shared exceptions, plus the critique archive. It leaves the existing application's source files plus the project-local Impeccable installation in place.

Verify the repository state by running:

git status

What should you see?

You should no longer see these paths as present untracked or modified files. If you committed them earlier, Git lists them as deleted until you record or reverse the cleanup.

Still see review artifacts?

Confirm that Terminal is in the folder containing the reviewed web project. Check the path spelling against the resource list before running the cleanup command again.

Ask for help checking the remaining paths without deleting application files.

Cleanup is complete once the generated review paths are absent. Your original web project remains available for future work.

Nice Work!

You did it! You built an evidence-backed design review gate with Impeccable. It catches mechanical UI drift while preserving your authority over product design.

You've learned how to:

Capture repeatable detector evidence for the source code. Capture the same evidence at desktop and mobile widths. Prove design-aware detection with a reversible calibration.
Record the product's intentional design vocabulary in DESIGN.md. Consolidate detector findings in DESIGN_REVIEW.md. Add UX critique evidence. Add technical audit evidence. Preserve slow-mobile observations. Preserve keyboard-only observations.
Apply design governance by assigning every priority finding a final decision. Keep any exception value-specific and evidence-backed. Promote one repeated judgment into a durable design rule.
Secret Mission: Enable the Claude Code design hook. Prove that it catches a temporary gradient-text regression automatically. Confirm that deleting the temporary file clears the finding.

Ready to quiz yourself?