Add page-scope style comparison (matcher + artifact)

[hungify]

Summary

• Page-scope toMatchFigma calls with styleChecks now run one compareStyles per declared check-point, each against its own baked expectStyle (no live per-checkpoint Figma re-fetch at verify time).
• Added expectStyleToSnapshot() (packages/verify/src/figma-node-style.ts) to bridge the contract's baked ExpectStyle (0-255 RGB + separate alpha, fontSizePx) into the StyleSnapshot shape compareStyles consumes.
• Each resulting issue is tagged with its originating check-point's selector (new optional TopIssue.selector / topIssueSchema.selector field) so multiple check-points stay distinguishable once merged into topIssues.
• Style issues remain non-blocking: merged into topIssues the same way region-scope's existing bake-in is, and done-gate is unaffected since it only blocks on kind === "residual".
• A check-point whose expectStyle never baked at authoring time (failed Figma fetch) is skipped rather than compared against nothing.
• Page-scope contracts with an empty/absent styleChecks behave exactly as before (pixel-only); region-scope's existing single-selector style comparison is untouched.

Closes #27

Test plan

• Unit tests for expectStyleToSnapshot (empty input, each field, color+colorProperty pairing, colorProperty omitted, combined fields) — packages/verify/tests/figma-node-style.test.ts
• Matcher tests — packages/playwright/tests/to-match-figma.test.ts:
  • multiple page-scope check-points, mixed pass/fail, each issue tagged with its own selector
  • check-point missing expectStyle produces no issue
  • empty styleChecks array produces no style issues
  • existing "skips style comparison entirely in page scope (no selector)" test still passes unchanged
• Full repo suite green: verify 186/186, playwright 51/51, cli 73/73, dashboard 47/47, dashboard-server 18/18
• pnpm -r typecheck and oxlint clean

Summary by CodeRabbit

• New Features

  • Added page-scope style checkpoints for validating expected colors, typography, and other supported style properties.
  • Style issues now identify the checkpoint selector that produced them.
  • Added support for converting expected style definitions into comparable snapshots.

• Documentation

  • Documented page-scope style checkpoint usage and non-blocking issue reporting.

• Tests

  • Added coverage for multiple checkpoints, missing expectations, empty configurations, and style conversion.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 909484d2-8fba-4896-801b-55640e5f4512

📥 Commits

Reviewing files that changed from the base of the PR and between 0100a13 and 2c03fce.

📒 Files selected for processing (1)

• packages/playwright/src/matchers/to-match-figma.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds page-scope styleChecks to toMatchFigma. Each checkpoint compares against its baked expected style. Returned style issues include the checkpoint selector and remain non-blocking.

Changes

Page-scope style comparison

Layer / File(s)	Summary
Style conversion and issue contracts packages/verify/src/figma-node-style.ts, packages/verify/src/index.ts, packages/verify/src/types.ts, packages/contracts/src/score.ts	Expected styles convert to StyleSnapshot values. TopIssue and topIssueSchema now support an optional checkpoint selector.
Matcher integration and validation packages/playwright/src/matchers/to-match-figma.ts, packages/playwright/tests/to-match-figma.test.ts, packages/playwright/README.md	The matcher supports page-scope styleChecks, skips checkpoints without expectStyle, tags issues with selectors, and preserves non-blocking behavior. Tests and documentation cover these cases.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 2c03f

The change adds page-scope style diagnostics without altering pixel comparison or merge-gate behavior; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Test as Playwright test
  participant Matcher as toMatchFigma
  participant Converter as expectStyleToSnapshot
  participant Comparator as compareStyles
  participant TopIssues as topIssues
  Test->>Matcher: provide page-scope styleChecks
  Matcher->>Converter: convert checkpoint expectStyle
  Matcher->>Comparator: compare selected element style
  Comparator->>TopIssues: return selector-tagged style issues
  Matcher->>Test: preserve passing pixel comparison

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: adding page-scope style comparison in the matcher and artifact.
Linked Issues check	✅ Passed	The changes implement page-scope checkpoint comparisons, selector-tagged artifact issues, non-blocking behavior, pixel-only fallback, and supporting tests.
Out of Scope Changes check	✅ Passed	All code, type, documentation, and test changes directly support page-scope style comparison and its artifact integration.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/page-scope-style-comparison

---

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR adds page-scope style checkpoint comparisons using baked expectations and tags resulting diagnostics with their originating selectors. It also addresses the previously reported region-routing and matcher-budget issues.

• Converts baked ExpectStyle values into style-comparison snapshots.
• Runs bounded, page-scope checkpoint comparisons and merges their non-blocking issues into score artifacts.
• Extends score schemas and issue types with optional checkpoint selectors.
• Adds matcher and conversion coverage for checkpoint behavior and prior review fixes.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/playwright/src/matchers/to-match-figma.ts	Adds bounded page-checkpoint style comparison and correctly separates page and region behavior without leaving a blocking prior finding.
packages/verify/src/figma-node-style.ts	Adds a focused conversion from baked contract styles to the existing comparison snapshot representation.
packages/contracts/src/score.ts	Extends persisted top issues with an optional selector while preserving compatibility for existing issues.
packages/verify/src/types.ts	Mirrors the optional checkpoint selector in the runtime TopIssue contract.
packages/playwright/tests/to-match-figma.test.ts	Covers page checkpoints, missing expectations, empty checks, and the corrected region fallback behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[toMatchFigma] --> B[Resolve baseline and capture page]
  B --> C[Run pixel comparison]
  C --> D{Region selector present?}
  D -->|Yes| E[Compare region style when Figma style exists]
  D -->|No| F[Compare baked page checkpoints]
  E --> G[Apply remaining timeout budget]
  F --> G
  G --> H[Merge non-blocking style issues]
  H --> I[Attach images and score artifact]

Loading

_{Reviews (5): Last reviewed commit: "Enhance style comparison with page-scope..." | Re-trigger Greptile}