cornhsu-parity 0.11.1 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +246 -174
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -6,249 +6,302 @@
|
|
|
6
6
|
[](https://github.com/HSU-YU-MING/cornhsu-parity/actions/workflows/ci.yml)
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
|
|
9
|
-
**[
|
|
9
|
+
**[Project write-up](https://cornhsu.com/parity) · [GitHub Marketplace](https://github.com/marketplace/actions/parity-design-fidelity-check) · [npm](https://www.npmjs.com/package/cornhsu-parity) · [NuGet](https://www.nuget.org/packages/Cornhsu.Parity) · [繁體中文](README.zh-Hant.md) · MIT**
|
|
10
10
|
|
|
11
11
|
## GitHub Action
|
|
12
12
|
|
|
13
13
|
```yaml
|
|
14
|
-
- uses: HSU-YU-MING/cornhsu-parity@v0.
|
|
14
|
+
- uses: HSU-YU-MING/cornhsu-parity@v0.12.0 # pin exact versions while 0.x; a floating @v1 arrives with 1.0
|
|
15
15
|
with:
|
|
16
|
-
config: parity.config.json #
|
|
17
|
-
target: /pricing #
|
|
16
|
+
config: parity.config.json # optional, defaults to parity.config.json
|
|
17
|
+
target: /pricing # optional, check only this route (omit for all)
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
Fails CI when the gap exceeds the gate threshold, and posts the fidelity report as a PR
|
|
21
|
+
comment that updates in place instead of piling up.
|
|
21
22
|
|
|
22
|
-
>
|
|
23
|
-
>
|
|
24
|
-
>
|
|
23
|
+
> **Design fidelity checking that can actually gate your CI (property-level design QA).**
|
|
24
|
+
> It compares the **real numeric values on both sides** — your Figma file and the actually
|
|
25
|
+
> rendered page — programmatically: "padding is 8px, the design says 12px." Because the
|
|
26
|
+
> output is numbers rather than an impression, it can be a gate: **a PR that drifts from the
|
|
27
|
+
> design turns red**, with the fidelity report posted straight onto the PR.
|
|
25
28
|
|
|
26
|
-
|
|
29
|
+
**Other tools help you *see* design drift. Parity *blocks* it.**
|
|
27
30
|
|
|
28
|
-
|
|
29
|
-
|
|
31
|
+
Most comparable tools (Uiprobe, Loupe, OverlayQA, Floto Design Diff, PixelProof…) do numeric
|
|
32
|
+
comparison these days. The real difference is not "numbers vs. overlays" — it is **whether the
|
|
33
|
+
whole thing can be automated**:
|
|
30
34
|
|
|
31
|
-
| |
|
|
35
|
+
| | Manual spot-check tools<br>(Uiprobe / OverlayQA / Loupe …) | **Parity** |
|
|
32
36
|
|---|---|---|
|
|
33
|
-
|
|
|
34
|
-
|
|
|
35
|
-
|
|
|
36
|
-
|
|
|
37
|
-
|
|
|
38
|
-
|
|
|
37
|
+
| Who runs it | A person opens the tool, clicks around, reads a report | **CI runs it**, nobody has to be present |
|
|
38
|
+
| After a gap is found | File a ticket yourself, or paste the result into the PR | **Exit code blocks the PR** + a bot comment that updates in place |
|
|
39
|
+
| Regression gating | None | **A baseline gates only new/worsened gaps** — projects with existing debt can adopt it today |
|
|
40
|
+
| When there is no Figma file | Unusable | **Snapshot mode**: freeze today's rendering as the baseline so refactors cannot drift |
|
|
41
|
+
| Desktop apps | Not supported | **Electron** (attaches to the live window over CDP) |
|
|
42
|
+
| Price | $39–249 / month (Loupe is free but is a desktop GUI — not automatable) | **Free, MIT** |
|
|
39
43
|
|
|
40
|
-
>
|
|
41
|
-
>
|
|
44
|
+
> Being honest about the boundaries: localhost and authenticated pages are **no longer a
|
|
45
|
+
> differentiator** — Uiprobe and OverlayQA support them too. Neither is "free and open source" —
|
|
46
|
+
> Loupe is also MIT. **What is unique to Parity is the intersection: free × automatable.**
|
|
42
47
|
|
|
43
|
-
##
|
|
48
|
+
## Screenshots
|
|
44
49
|
|
|
45
|
-
|
|
50
|
+
**Report UI (`parity serve --watch`)** — the left column lists every node, matching or not;
|
|
51
|
+
the right side overlays the design boxes and the implementation boxes directly on the real
|
|
52
|
+
screenshot. Click any row to locate it; saving a file triggers a re-scan.
|
|
46
53
|
|
|
47
|
-
|
|
48
55
|
|
|
49
|
-
|
|
56
|
+
**Fidelity report** — each row is a concrete "expected → actual" pair with its severity and a
|
|
57
|
+
suggested fix (including the matching design token). The GitHub Action posts this verbatim as a
|
|
58
|
+
PR comment, updating the same comment rather than adding new ones.
|
|
50
59
|
|
|
51
|
-
|
|
52
61
|
|
|
53
|
-
##
|
|
62
|
+
## At a glance
|
|
54
63
|
|
|
55
64
|
| | |
|
|
56
65
|
|---|---|
|
|
57
|
-
|
|
|
58
|
-
|
|
|
59
|
-
|
|
|
60
|
-
|
|
|
61
|
-
|
|
|
62
|
-
| CI
|
|
63
|
-
|
|
|
66
|
+
| Releases | 22 on NuGet (v0.1.0 → v0.12.0). Pushing a tag publishes via OIDC Trusted Publishing — zero long-lived keys in the repo |
|
|
67
|
+
| Compared properties | Size, padding, spacing, typography, color (CIEDE2000 ΔE), relative position — **absolute coordinates are deliberately excluded** (they are guaranteed false positives in a flexible layout) |
|
|
68
|
+
| Design sources | 4: the Figma API, a rendering snapshot, an image + annotations (pixel sampling — any tool that exports a PNG works), or JSON |
|
|
69
|
+
| Implementation sources | The web (including **shadow DOM, same-origin iframes, and multiple responsive breakpoints**) plus **Electron** (attached to the live window over CDP) |
|
|
70
|
+
| Tests | **160**, covering the CIEDE2000 reference data set (Sharma), match disambiguation, position false-positive guards, and image sampling |
|
|
71
|
+
| Proven in CI | The GitHub Action is validated by **real PRs in an external repo**: blocking the PR, commenting automatically (updating in place), and baseline regression gating |
|
|
72
|
+
| Proven in production | **All 21 pages of cornhsu.com are gated by Parity itself** — dogfooding has already found and fixed three flaky root causes (most recently a scroll-triggered entrance animation; see 0.11.1) |
|
|
64
73
|
|
|
65
|
-
##
|
|
74
|
+
## Install
|
|
66
75
|
|
|
67
|
-
|
|
76
|
+
Two channels — pick whichever runtime you already have. **They are functionally identical.**
|
|
68
77
|
|
|
69
78
|
```sh
|
|
70
|
-
#
|
|
79
|
+
# If you have Node (common in front-end projects): no .NET install needed
|
|
71
80
|
npx cornhsu-parity check
|
|
72
81
|
|
|
73
|
-
#
|
|
82
|
+
# If you have .NET
|
|
74
83
|
dotnet tool install -g Cornhsu.Parity
|
|
75
84
|
```
|
|
76
85
|
|
|
77
|
-
> npm
|
|
78
|
-
> (win32-x64 / win32-arm64 / linux-x64 / linux-arm64 / darwin-x64 / darwin-arm64)
|
|
79
|
-
> Playwright
|
|
80
|
-
>
|
|
86
|
+
> The npm build is the same self-contained native executable; you only download the one for
|
|
87
|
+
> your platform (win32-x64 / win32-arm64 / linux-x64 / linux-arm64 / darwin-x64 / darwin-arm64).
|
|
88
|
+
> Playwright normally bundles its own copy of Node; the npm build strips that out and uses the
|
|
89
|
+
> Node you already have, which saves about 88 MB per platform package.
|
|
81
90
|
|
|
82
|
-
##
|
|
91
|
+
## Quick start
|
|
83
92
|
|
|
84
93
|
```sh
|
|
85
|
-
parity init #
|
|
86
|
-
parity install-browser #
|
|
87
|
-
export FIGMA_TOKEN=... #
|
|
88
|
-
parity check #
|
|
89
|
-
parity report #
|
|
90
|
-
|
|
91
|
-
parity
|
|
92
|
-
|
|
94
|
+
parity init # Generate a parity.config.json template
|
|
95
|
+
parity install-browser # First run only: download Playwright Chromium
|
|
96
|
+
export FIGMA_TOKEN=... # Only the file_content:read scope is needed
|
|
97
|
+
parity check # Compare; writes a report and sets the exit code
|
|
98
|
+
parity report # Re-render the Markdown report from an existing report.json
|
|
99
|
+
# (no re-scan; --md writes a file, otherwise it prints to stdout)
|
|
100
|
+
parity snapshot # Freeze the currently rendered UI as the design baseline —
|
|
101
|
+
# a refactor/redesign guard that needs no Figma at all
|
|
102
|
+
parity lint # Design lint: are the design file's values inside the allowed
|
|
103
|
+
# design-token set? (design only, no implementation)
|
|
104
|
+
parity check --reverse # Reverse view, for a designer redrawing an existing page:
|
|
105
|
+
# how does my draft differ from what ships? (never gates)
|
|
93
106
|
```
|
|
94
107
|
|
|
95
|
-
|
|
108
|
+
When working inside this repo:
|
|
96
109
|
|
|
97
110
|
```sh
|
|
98
111
|
dotnet run --project src/Parity.Cli -- check --config samples/demo/parity.config.json
|
|
99
112
|
```
|
|
100
113
|
|
|
101
|
-
`samples/demo`
|
|
102
|
-
`index.html`
|
|
103
|
-
|
|
114
|
+
`samples/demo` is a fully **offline demo** (the design source is a local JSON file, so no Figma
|
|
115
|
+
token is needed): `index.html` is deliberately broken in a few places, `parity check` reports
|
|
116
|
+
each gap and the unmatched list precisely, and returns exit code 1 (GATE FAIL) because of the
|
|
117
|
+
serious-severity gaps — which is exactly the behaviour you want from a CI gate.
|
|
104
118
|
|
|
105
|
-
##
|
|
119
|
+
## Configuration: `parity.config.json`
|
|
106
120
|
|
|
107
121
|
```jsonc
|
|
108
122
|
{
|
|
109
123
|
"figmaFileKey": "abcd1234",
|
|
110
124
|
"designToken": "env:FIGMA_TOKEN",
|
|
111
|
-
"mapFile": "parity.map.json", //
|
|
112
|
-
"tokensFile": "tokens.json", //
|
|
125
|
+
"mapFile": "parity.map.json", // manual fallback mapping (layer name → selector)
|
|
126
|
+
"tokensFile": "tokens.json", // optional: design tokens (name → value);
|
|
127
|
+
// suggested fixes will name the matching token
|
|
113
128
|
"targets": [
|
|
114
129
|
{ "route": "/", "frame": "10:2", "url": "http://localhost:8080/" }
|
|
115
130
|
],
|
|
116
|
-
"compare": { "position": "relative" }, // relative =
|
|
131
|
+
"compare": { "position": "relative" }, // relative = compare relative position (default); none = skip position
|
|
117
132
|
"tolerances": { "sizePx": 2, "spacingPx": 2, "colorDeltaE": 2.0, "positionPx": 4 },
|
|
118
133
|
"ignore": ["[data-parity-ignore]"],
|
|
119
134
|
"gate": {
|
|
120
135
|
"failOn": ["critical", "serious"],
|
|
121
|
-
"minMatchRate": 0 //
|
|
136
|
+
"minMatchRate": 0 // optional: FAIL outright below this match rate (0–1); 0 = no threshold
|
|
122
137
|
}
|
|
123
138
|
}
|
|
124
139
|
```
|
|
125
140
|
|
|
126
|
-
> gate
|
|
127
|
-
>
|
|
141
|
+
> Besides gaps, the gate also validates **match integrity**: zero matches (or zero design nodes)
|
|
142
|
+
> is always a GATE FAIL — with nothing matched there are no gaps to catch, so a silent PASS
|
|
143
|
+
> would be a false pass, usually caused by a wrong url or frame. `--baseline` mode is not exempt.
|
|
128
144
|
|
|
129
|
-
##
|
|
145
|
+
## Targets: a web page or an Electron desktop app
|
|
130
146
|
|
|
131
|
-
`target.url`
|
|
147
|
+
`target.url` decides what the implementation side is; the commands and the report are identical:
|
|
132
148
|
|
|
133
|
-
| url
|
|
149
|
+
| url form | What it means |
|
|
134
150
|
|---|---|
|
|
135
|
-
| `http(s)://…` |
|
|
136
|
-
| `file://…`(
|
|
137
|
-
| `cdp:http://host:port` |
|
|
151
|
+
| `http(s)://…` | A normal web page, or internal staging |
|
|
152
|
+
| `file://…` (or a relative path) | A local HTML file |
|
|
153
|
+
| `cdp:http://host:port` | **An already-running Electron desktop app** (reads the DOM of the live window) |
|
|
138
154
|
|
|
139
|
-
Electron
|
|
155
|
+
For Electron, start the app with a remote debugging port and point `url` at it. Parity attaches
|
|
156
|
+
and reads the current screen — it does not navigate, and does not disturb the app:
|
|
140
157
|
|
|
141
158
|
```sh
|
|
142
|
-
electron . --remote-debugging-port=9222 #
|
|
159
|
+
electron . --remote-debugging-port=9222 # your app, with this one extra flag
|
|
143
160
|
```
|
|
144
161
|
```jsonc
|
|
145
162
|
{ "route": "/", "frame": "20:5", "url": "cdp:http://localhost:9222" }
|
|
146
163
|
```
|
|
147
164
|
|
|
148
|
-
>
|
|
165
|
+
> Why Electron is nearly free: its UI *is* a Chromium renderer, so it uses the same DOM/CSS
|
|
166
|
+
> measurement path as the web. Mobile native, Flutter and native desktop do not go through a
|
|
167
|
+
> DOM, so they are left for v2.0.
|
|
149
168
|
|
|
150
|
-
##
|
|
169
|
+
## Design sources: Figma, a snapshot, or just an image
|
|
151
170
|
|
|
152
|
-
|
|
|
171
|
+
| Design source | config | Who it is for |
|
|
153
172
|
|---|---|---|
|
|
154
|
-
| **Figma**(
|
|
155
|
-
|
|
|
156
|
-
|
|
|
157
|
-
|
|
|
173
|
+
| **Figma** (primary) | `figmaFileKey` + `FIGMA_TOKEN` | The normal workflow, when you have a Figma file |
|
|
174
|
+
| **Snapshot** (`parity snapshot`) | `designFile` pointing at the generated snapshot JSON | **Refactor/redesign guard**: today's rendering is correct, so freeze it as the baseline and later checks prove nothing drifted (the numeric version of visual regression). Matching goes through selector identity, so it is 100% deterministic |
|
|
175
|
+
| **An image + annotations** | `designImage` (PNG/JPG) + `designFile` (annotations) | When all you have is a picture: an outsourced PNG, or a legacy project down to screenshots. **This is also the path for XD / Sketch / Photoshop and anything else that can export an image** — a universal adapter. The annotations are DesignNode JSON, and `fill` may be omitted: the engine samples the color from the corresponding region of the image. (Text color is deliberately not sampled — anti-aliasing blends it and the reading is unreliable — but you can fill it in by hand.) |
|
|
176
|
+
| Hand-written JSON | `designFile` | Offline demos and tests |
|
|
158
177
|
|
|
159
178
|
```sh
|
|
160
|
-
#
|
|
161
|
-
parity snapshot # 1.
|
|
162
|
-
# config
|
|
163
|
-
parity check # 2.
|
|
179
|
+
# The three-step refactor guard:
|
|
180
|
+
parity snapshot # 1. Freeze the current rendering (writes parity.snapshot.json + a reference screenshot)
|
|
181
|
+
# Point designFile at it in the config, and set each target.frame to its route
|
|
182
|
+
parity check # 2. Refactor fearlessly; 3. check proves it still matches the snapshot
|
|
164
183
|
```
|
|
165
184
|
|
|
166
|
-
##
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
-
|
|
171
|
-
|
|
172
|
-
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
185
|
+
## What gets compared, and what does not
|
|
186
|
+
|
|
187
|
+
Only the things that should hold no matter how the layout flows:
|
|
188
|
+
|
|
189
|
+
- **Intrinsic size** (width/height — except on TEXT nodes, where text-box measurement is
|
|
190
|
+
inherently different between Figma and a browser and comparing it produces a flood of noise)
|
|
191
|
+
- The auto-layout **HUG (fit content) / FILL (fill parent)** axis is skipped too: Figma's
|
|
192
|
+
measured width necessarily differs from the browser's rendered width there. Only **FIXED**
|
|
193
|
+
axes are compared.
|
|
194
|
+
- **Padding / spacing**: all four padding edges, and auto-layout `itemSpacing` against the real
|
|
195
|
+
gap between child elements.
|
|
196
|
+
- **Relative position** (`offsetX`/`offsetY`): for children of freely positioned (non-auto-layout)
|
|
197
|
+
containers, the offset relative to the nearest reliable sibling or parent edge — which is what
|
|
198
|
+
catches "size and color are perfect, but it is in the wrong place." Only reliable edges are used
|
|
199
|
+
as references (TEXT/HUG boxes are never references, TEXT is never a target, and Y is honestly
|
|
200
|
+
skipped when everything above is text), so line-height drift in a flowing layout does not
|
|
201
|
+
produce false positives. Turn it off with `compare.position: "none"`.
|
|
202
|
+
- **Typography**: size, weight, line-height and letter-spacing are compared exactly;
|
|
203
|
+
font-family is a **soft gap** and never gates.
|
|
204
|
+
- **Color**: thresholded on CIEDE2000 (ΔE), not hex equality. Parsing covers modern syntax
|
|
205
|
+
(`rgb(37 99 235 / .5)`, `color(srgb …)`, `oklch()`, `color(display-p3 …)`).
|
|
206
|
+
- **Absolute x/y is deliberately never compared**: it legitimately differs in a flexible layout,
|
|
207
|
+
so comparing it means false positives, which means losing trust.
|
|
208
|
+
|
|
209
|
+
> When the design source is Figma, layer names in the report (both the Markdown and the local UI)
|
|
210
|
+
> **link back to that node in Figma** — a designer clicks once and lands on the layer.
|
|
211
|
+
|
|
212
|
+
## Two workflows for designers
|
|
213
|
+
|
|
214
|
+
**Keeping a new page inside the design system: `parity lint`.** It looks only at the design side
|
|
215
|
+
and checks whether each node's values are in the allowed set from `tokensFile`: color (a hit
|
|
216
|
+
within the ΔE tolerance passes), and fontSize / padding / itemSpacing / cornerRadius (equal to
|
|
217
|
+
any size token passes — spacing, font sizes and corner radii share one scale). Every violation
|
|
218
|
+
carries "the nearest token", so the message is "change it to this", not merely "you are wrong".
|
|
219
|
+
Violations exit 1, so it can run in CI. Dimensions you have not defined tokens for are not linted.
|
|
220
|
+
|
|
221
|
+
**Redrawing against what ships: `parity check --reverse`.** The direction flips: "expected"
|
|
222
|
+
becomes the current implementation and "actual" becomes your draft. That gives a designer a list
|
|
223
|
+
of "how my draft differs from what is live today". It never gates, and always exits 0.
|
|
224
|
+
|
|
225
|
+
## Responsive breakpoints
|
|
226
|
+
|
|
227
|
+
One URL, several breakpoints, each mapped to its own Figma frame — **the render viewport is the
|
|
228
|
+
frame's size**, so a 375-wide phone frame makes your media queries fire naturally:
|
|
189
229
|
|
|
190
230
|
```jsonc
|
|
191
231
|
"targets": [
|
|
192
232
|
{ "route": "/desktop", "frame": "10:2", "url": "http://localhost:8080/" },
|
|
193
|
-
{ "route": "/mobile", "frame": "10:99", "url": "http://localhost:8080/" } //
|
|
233
|
+
{ "route": "/mobile", "frame": "10:99", "url": "http://localhost:8080/" } // a 375-wide phone frame
|
|
194
234
|
]
|
|
195
235
|
```
|
|
196
236
|
|
|
197
|
-
route
|
|
237
|
+
`route` is only a label in the report, so pick something recognizable. You only need `width` /
|
|
238
|
+
`height` on a target when the frame's width is not the viewport width you want to test.
|
|
198
239
|
|
|
199
|
-
## Shadow DOM /
|
|
240
|
+
## Shadow DOM / iframes
|
|
200
241
|
|
|
201
|
-
|
|
242
|
+
Capture walks the **composed tree**: open shadow roots, content slotted through `<slot>`, and
|
|
243
|
+
same-origin iframes (including `srcdoc`) are all visible and all compared — web-component sites
|
|
244
|
+
are no longer wholly invisible. Selectors for elements inside a shadow root or iframe are written
|
|
245
|
+
as `host >>> inner path`.
|
|
202
246
|
|
|
203
|
-
|
|
247
|
+
Limitations, stated honestly: closed shadow roots and cross-origin iframes are unreachable and
|
|
248
|
+
are skipped; map-file selectors cannot reach inside a shadow root (the `data-parity` attribute is
|
|
249
|
+
unaffected and works as usual).
|
|
204
250
|
|
|
205
|
-
##
|
|
251
|
+
## Matching strategy (anchored on the design side)
|
|
206
252
|
|
|
207
|
-
1.
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
253
|
+
1. **Automatic text anchoring**: design TEXT content ↔ page text (matched only when unique;
|
|
254
|
+
when several elements share the text, the layer name disambiguates — and it still refuses to force a match)
|
|
255
|
+
2. **Layer name ↔ id / class / aria-label**: `CTA Button` matches `class="cta-button"` automatically
|
|
256
|
+
3. **Container inference**: an unmatched container is inferred from the lowest common ancestor of
|
|
257
|
+
its already-matched descendants (pure structure — no guessing)
|
|
258
|
+
4. **Manual fallback**: add `data-parity="Layer Name"` in your HTML, or write
|
|
259
|
+
`{ "Layer Name": "CSS selector" }` in `parity.map.json`
|
|
260
|
+
5. Still no match → **honestly listed as unmatched**, so you only fill in what genuinely needs a human
|
|
212
261
|
|
|
213
|
-
##
|
|
262
|
+
## Architecture
|
|
214
263
|
|
|
215
|
-
|
|
264
|
+
One engine (`Parity.Engine`, a pure library) plus several shells. The engine only ever compares
|
|
265
|
+
two normalized trees:
|
|
216
266
|
|
|
217
267
|
```
|
|
218
|
-
IDesignSource ──→ DesignNode
|
|
219
|
-
(Figma / JSON /
|
|
268
|
+
IDesignSource ──→ DesignNode tree ─┐
|
|
269
|
+
(Figma / JSON / later XD, Sketch) ├─→ Normalizer → Matcher → DiffEngine → FidelityReport
|
|
220
270
|
IImplementationSource → RenderedNode ┘
|
|
221
|
-
(Playwright /
|
|
271
|
+
(Playwright / later WPF, desktop)
|
|
222
272
|
```
|
|
223
273
|
|
|
224
274
|
```
|
|
225
|
-
src/Parity.Engine/
|
|
226
|
-
DesignSources/ IDesignSource + Figma(REST +
|
|
227
|
-
ImplementationSources/ IImplementationSource + Web(Playwright)
|
|
228
|
-
Comparison/ Normalizer / Matcher / DiffEngine / ColorDelta(CIEDE2000)
|
|
229
|
-
src/Parity.Cli/ dotnet tool
|
|
230
|
-
tests/Parity.Tests/
|
|
231
|
-
samples/demo/
|
|
275
|
+
src/Parity.Engine/ The engine; FidelityEngine is the only entry point
|
|
276
|
+
DesignSources/ IDesignSource + Figma (REST + local cache) / Json
|
|
277
|
+
ImplementationSources/ IImplementationSource + Web (Playwright)
|
|
278
|
+
Comparison/ Normalizer / Matcher / DiffEngine / ColorDelta (CIEDE2000)
|
|
279
|
+
src/Parity.Cli/ The dotnet tool shell: parity check / init / install-browser
|
|
280
|
+
tests/Parity.Tests/ Unit tests (including the CIEDE2000 reference data)
|
|
281
|
+
samples/demo/ Offline demo: a deliberately broken page + a design JSON
|
|
232
282
|
```
|
|
233
283
|
|
|
234
|
-
##
|
|
284
|
+
## Local report UI (M3)
|
|
235
285
|
|
|
236
286
|
```sh
|
|
237
|
-
parity serve --watch # http://127.0.0.1:4321
|
|
238
|
-
parity map #
|
|
287
|
+
parity serve --watch # http://127.0.0.1:4321, re-scans on file changes (live updates over SSE)
|
|
288
|
+
parity map # Interactive matching: click an unmatched layer → click the element on the
|
|
289
|
+
# screenshot → writes parity.map.json
|
|
239
290
|
```
|
|
240
291
|
|
|
241
|
-
-
|
|
242
|
-
-
|
|
243
|
-
|
|
244
|
-
-
|
|
292
|
+
- A gap list sorted by severity, with exact numbers, color swatches and ΔE
|
|
293
|
+
- A screenshot overlay: solid = implementation box (colored by severity), blue dashed = design
|
|
294
|
+
box, red dashed = unmatched
|
|
295
|
+
- **Binds 127.0.0.1 only**: the report contains your site's structure, so it must not be
|
|
296
|
+
reachable from the local network
|
|
297
|
+
- The UI is a zero-build static SPA, so the dotnet tool needs no Node toolchain
|
|
245
298
|
|
|
246
|
-
##
|
|
299
|
+
## In CI (M4)
|
|
247
300
|
|
|
248
|
-
|
|
301
|
+
Gating CI is the whole differentiator, and this repo is itself a composite action:
|
|
249
302
|
|
|
250
303
|
```yaml
|
|
251
|
-
# .github/workflows/design-check.yml(
|
|
304
|
+
# .github/workflows/design-check.yml (in your project)
|
|
252
305
|
name: Design fidelity
|
|
253
306
|
on: [pull_request]
|
|
254
307
|
jobs:
|
|
@@ -256,69 +309,88 @@ jobs:
|
|
|
256
309
|
runs-on: ubuntu-latest
|
|
257
310
|
permissions:
|
|
258
311
|
contents: read
|
|
259
|
-
pull-requests: write #
|
|
312
|
+
pull-requests: write # lets the action post the fidelity report as a PR comment
|
|
260
313
|
steps:
|
|
261
314
|
- uses: actions/checkout@v4
|
|
262
|
-
#
|
|
315
|
+
# Start your site (or deploy to a preview URL and point the config's url at it)
|
|
263
316
|
- run: |
|
|
264
317
|
npm ci && npm run build
|
|
265
|
-
npm run preview & #
|
|
266
|
-
- uses: HSU-YU-MING/cornhsu-parity@v0.
|
|
318
|
+
npm run preview & # e.g. serving on localhost:8080
|
|
319
|
+
- uses: HSU-YU-MING/cornhsu-parity@v0.12.0 # pin exact versions while 0.x
|
|
267
320
|
with:
|
|
268
321
|
config: parity.config.json
|
|
269
|
-
figma-token: ${{ secrets.FIGMA_TOKEN }} #
|
|
322
|
+
figma-token: ${{ secrets.FIGMA_TOKEN }} # omit when the design source is a local JSON file
|
|
270
323
|
```
|
|
271
324
|
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
-
|
|
275
|
-
|
|
325
|
+
Behaviour:
|
|
326
|
+
|
|
327
|
+
- **PR comment**: posts a fidelity report (score + gap table + **suggested fixes**) and keeps
|
|
328
|
+
updating that same comment instead of adding new ones — so PMs and reviewers see it without
|
|
329
|
+
ever touching the tool.
|
|
330
|
+
- **Blocks the PR**: gaps beyond `gate.failOn` → exit 1 → red PR. (**The comment is posted
|
|
331
|
+
first, then the gate is enforced.**)
|
|
332
|
+
- **Artifacts**: `report.json` plus the Markdown report are uploaded for download.
|
|
276
333
|
|
|
277
|
-
|
|
334
|
+
Action inputs: `config` / `target` / `working-directory` / `version` / `figma-token` /
|
|
335
|
+
`baseline` (regression mode) / `comment` (turn off the PR comment) / `upload-report`.
|
|
278
336
|
|
|
279
|
-
> action
|
|
337
|
+
> The action installs the tool with `dotnet tool install -g Cornhsu.Parity` (published on
|
|
338
|
+
> nuget.org). This repo's own `.github/workflows/ci.yml` instead **builds from source** and runs
|
|
339
|
+
> the offline demo as a self-check, so it does not depend on a published release.
|
|
280
340
|
|
|
281
|
-
##
|
|
341
|
+
## Regression gating: baselines (M5)
|
|
282
342
|
|
|
283
|
-
|
|
343
|
+
A project that already has a pile of gaps cannot start at "zero gaps or no merge". A baseline
|
|
344
|
+
lets you **gate only new and worsened gaps**:
|
|
284
345
|
|
|
285
346
|
```sh
|
|
286
|
-
parity baseline save #
|
|
287
|
-
|
|
288
|
-
parity baseline
|
|
347
|
+
parity baseline save # Store the current gaps + fidelity score as a baseline snapshot
|
|
348
|
+
# (SQLite, in parity.baseline.db, tagged with the git commit)
|
|
349
|
+
parity check --baseline # Compare against the newest baseline: only new or worsened gaps GATE FAIL,
|
|
350
|
+
# and the score trend is shown (baseline 75 → now 83 ↑)
|
|
351
|
+
parity baseline list # Browse snapshot history (the score column is the fidelity trend, for PMs)
|
|
289
352
|
```
|
|
290
353
|
|
|
291
|
-
> **
|
|
354
|
+
> **To use `--baseline` in CI, remember to `git add parity.baseline.db`.** It deliberately lives
|
|
355
|
+
> at the repo root rather than in `.parity/`, which is usually gitignored — otherwise CI cannot
|
|
356
|
+
> find the baseline and silently falls back to the normal gate. The path is configurable via
|
|
357
|
+
> `baselineFile`.
|
|
292
358
|
|
|
293
|
-
-
|
|
294
|
-
-
|
|
295
|
-
-
|
|
359
|
+
- **New** (absent from the baseline, present now) or **worsened** (higher severity) → exit 1, PR blocked
|
|
360
|
+
- **Fixed** (in the baseline, gone now) is listed as encouragement; **unchanged** existing gaps do not gate
|
|
361
|
+
- Ideal for gradual adoption: record reality with `baseline save`, then run `check --baseline` in
|
|
362
|
+
CI, and all the team has to commit to is "do not make fidelity worse"
|
|
296
363
|
|
|
297
|
-
|
|
364
|
+
The storage layer is a separate `Parity.Storage` (EF Core + SQLite, with `Pooling=False` so the
|
|
365
|
+
file is released immediately), and the engine's `BaselineComparer` is a pure, unit-testable function.
|
|
298
366
|
|
|
299
|
-
##
|
|
367
|
+
## Milestones
|
|
300
368
|
|
|
301
|
-
- [x] **M1**
|
|
302
|
-
- [x] **M2**
|
|
303
|
-
- [x] **M3**
|
|
304
|
-
- [x] **M4** GitHub Action
|
|
305
|
-
- [x] **M5** EF Core + SQLite
|
|
369
|
+
- [x] **M1** Engine + CLI prototype: two numeric trees, design side and implementation side
|
|
370
|
+
- [x] **M2** Comparison engine: matching + numeric diffing + tolerances + unmatched list + gate exit codes
|
|
371
|
+
- [x] **M3** Local report UI (`parity serve --watch`, Kestrel bound to 127.0.0.1) + `parity map` interactive matching
|
|
372
|
+
- [x] **M4** GitHub Action: a reusable composite action (`action.yml`) + this repo's own CI (build / test / offline-demo self-check)
|
|
373
|
+
- [x] **M5** EF Core + SQLite baselines and history (regression gating + score trend) + `ImageDesignSource` (image + annotations + pixel sampling) + `parity snapshot` (freeze the current state as the baseline)
|
|
374
|
+
- [ ] **M6** (optional) Cloud shell: public-URL scanning + SSRF protection
|
|
306
375
|
|
|
307
|
-
>
|
|
308
|
-
|
|
376
|
+
> Open work, known blind spots and the next priorities are in [ROADMAP.md](ROADMAP.md);
|
|
377
|
+
> version history is in [CHANGELOG.md](CHANGELOG.md).
|
|
309
378
|
|
|
310
|
-
##
|
|
379
|
+
## Security
|
|
311
380
|
|
|
312
|
-
- Figma token
|
|
313
|
-
|
|
381
|
+
- The Figma token comes from an environment variable (`env:FIGMA_TOKEN`); it never reaches a log
|
|
382
|
+
and never goes in a URL (it is sent as the `X-Figma-Token` header).
|
|
383
|
+
- Fetched frames are cached in `.parity/cache` (gitignored), so re-runs do not hit Figma and can
|
|
384
|
+
compare offline.
|
|
314
385
|
|
|
315
|
-
##
|
|
386
|
+
## See also
|
|
316
387
|
|
|
317
|
-
[**XamlContrast**](https://github.com/HSU-YU-MING/cornhsu-xamlcontrast)
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
388
|
+
[**XamlContrast**](https://github.com/HSU-YU-MING/cornhsu-xamlcontrast) — a sibling project by the
|
|
389
|
+
same author, built on the same philosophy: numeric checks that gate CI. Parity answers "**does the
|
|
390
|
+
implementation match the design?**" (fidelity); XamlContrast answers "**can anyone actually see
|
|
391
|
+
what we built?**" (WCAG contrast, scanned statically from XAML source). One guards fidelity, the
|
|
392
|
+
other readability — and its static color resolution is also the groundwork for the expected values
|
|
393
|
+
of this project's future `WpfImplementationSource` desktop adapter.
|
|
322
394
|
|
|
323
395
|
## License
|
|
324
396
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cornhsu-parity",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.0",
|
|
4
4
|
"description": "Property-Level Design QA that can gate your CI. Compares real numeric values from your Figma file against the rendered UI and fails the PR when the implementation drifts from the design.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"figma",
|
|
@@ -34,11 +34,11 @@
|
|
|
34
34
|
"node": ">=18"
|
|
35
35
|
},
|
|
36
36
|
"optionalDependencies": {
|
|
37
|
-
"@cornhsu/parity-win32-x64": "0.
|
|
38
|
-
"@cornhsu/parity-win32-arm64": "0.
|
|
39
|
-
"@cornhsu/parity-linux-x64": "0.
|
|
40
|
-
"@cornhsu/parity-linux-arm64": "0.
|
|
41
|
-
"@cornhsu/parity-darwin-x64": "0.
|
|
42
|
-
"@cornhsu/parity-darwin-arm64": "0.
|
|
37
|
+
"@cornhsu/parity-win32-x64": "0.12.0",
|
|
38
|
+
"@cornhsu/parity-win32-arm64": "0.12.0",
|
|
39
|
+
"@cornhsu/parity-linux-x64": "0.12.0",
|
|
40
|
+
"@cornhsu/parity-linux-arm64": "0.12.0",
|
|
41
|
+
"@cornhsu/parity-darwin-x64": "0.12.0",
|
|
42
|
+
"@cornhsu/parity-darwin-arm64": "0.12.0"
|
|
43
43
|
}
|
|
44
44
|
}
|