@uicopilot/storybook-addon 0.19.0 → 0.20.1

package/README.md

@@ -1,23 +1,29 @@
 # UI Parity for Storybook
 
-**Catch design drift between Figma and Storybook before it ships.** A clear traffic-light verdict per component — right inside the Storybook you already have.
+**How much of your design system is actually in code, and does it match Figma?** UI Parity measures it from what renders, story by story, inside the Storybook you already have: **coverage, parity and drift** for the whole library, with what it didn't check stated.
 
 [![npm version](https://img.shields.io/npm/v/@uicopilot/storybook-addon?color=ea580c&label=npm)](https://www.npmjs.com/package/@uicopilot/storybook-addon)
 [![weekly downloads](https://img.shields.io/npm/dw/@uicopilot/storybook-addon?color=ea580c&label=downloads)](https://www.npmjs.com/package/@uicopilot/storybook-addon)
 [![license](https://img.shields.io/npm/l/@uicopilot/storybook-addon?color=ea580c)](https://www.npmjs.com/package/@uicopilot/storybook-addon)
 ![Storybook 9+](https://img.shields.io/badge/storybook-%E2%89%A59.0-ff4785)
 
-![UI Parity panel showing a color mismatch and its traffic-light verdict](https://app.uiparity.com/readme/hero.png)
+![The UI Parity Coverage overview: 161 of 462 stories checked, 60% match Figma, drift listed by component](https://app.uiparity.com/landing/step-4-see-the-drift.jpg)
 
 ---
 
 ## Why
 
-Your design system is the contract. When a button ships with the wrong brand color or 4px too much padding, nobody notices until it's in production — or a designer files a ticket weeks later. UI Parity checks each component against its Figma frame **inside Storybook**, so drift shows up while you're still in the story.
+Your design system is the contract. When a button ships with the wrong brand color or 4px too much padding, nobody notices until it's in production, or a designer files a ticket weeks later. UI Parity checks every story against its Figma variant **inside Storybook** and answers three questions:
 
-You get a **traffic-light verdict and an exact list of what's off** (Expected vs. Actual, per property) — not a fuzzy pixel diff you have to eyeball.
+| Number       | Question                                          | Example from a real run                        |
+| ------------ | ------------------------------------------------- | ---------------------------------------------- |
+| **Coverage** | How much of the library was checked?              | 161 of 462 stories                             |
+| **Parity**   | Of what was checked, how much matches the design? | 96 of 161 (60%)                                |
+| **Drift**    | Where, and by how much?                           | 65 stories in 16 of 58 components, worst first |
 
-**The short version:** point a story at its Figma frame once, then press a button to find out whether the code still matches the design. No baselines to approve, no snapshots to maintain.
+Every difference is a named property with **Expected vs. Actual**, not a pixel diff to eyeball. No baselines to approve, no snapshots to maintain.
+
+**It won't guess.** When a story could be several Figma variants, or none, it says **"not compared"** and why, instead of producing findings against the wrong design.
 
 ## Install
 
@@ -61,12 +67,13 @@ Templates also exist for Ant Design, Mantine, Carbon (IBM), Chakra UI, and Paste
 
 ## Quick start
 
-1. **Open the UI Parity panel** on any story and sign in with Google — or hit **"Try without signing in"** to start a guest session.
-2. **Connect Figma and pick the pages to index.** The setup wizard walks you through it: connect Figma, paste your file URL, choose which pages to sync, and it indexes the frames in those pages.
-3. **Map the story to its Figma frame** (one click, "Map to Figma"). This tells UI Parity what the component is _supposed_ to look like.
-4. **Click "Compare to design."** You get a **traffic-light verdict** — `Matches design` · `Minor differences` · `Major differences` — and a list of exactly which properties drifted (Expected vs. Actual).
+1. **Open the UI Parity panel** on any story and sign in with Google, or hit **"Try without signing in"** to start a guest session.
+2. **Connect Figma and pick the pages to index.** The setup wizard walks you through it: connect Figma, paste your file URL, choose which pages to sync, and it indexes the components on those pages.
+3. **Auto-map.** UI Parity links every story to its Figma variant. Stories it isn't sure about are flagged, never guessed.
+4. **Confirm the unsure ones.** The **Confirm variants** tab shows the story beside the Figma variant it might be, with the variant's properties as controls. One look, one click, and it sticks.
+5. **Review all.** One run checks every mapped story. The **Coverage** tab shows coverage, parity and the drifting components; each row opens its stories.
 
-Mapping is a one-time cost per component. After that, every re-check is one click.
+You can still map and check a single story from the panel (**Map to Figma**, then **Compare to design**).
 
 ## What it checks
 
@@ -79,10 +86,16 @@ Mapping is a one-time cost per component. After that, every re-check is one clic
 | Spacing drift              | padding, gap, margins (sub-10px diffs are downgraded a severity level)                                            |
 | Corner radius              | `border-radius`                                                                                                   |
 | Borders                    | width, color, style                                                                                               |
+| Part sizes                 | icons, avatars, segments and fixed widths                                                                         |
+| Part gaps                  | the distance between the parts of a component                                                                     |
 
 Because it reads the **computed** styles off the rendered DOM, it doesn't care how you wrote them. Tailwind classes, CSS Modules, styled-components, vanilla-extract, plain CSS, inline styles — all produce the same computed values, and that's what gets compared.
 
-> **AI visual review** — catching layout, shadows, missing elements, and icon drift from a screenshot comparison — is rolling out next. Today the deterministic spec-diff is what everyone gets, free.
+**Not drift:** the same box built differently (padding on a child instead of the parent), 1–2 px rounding, and hover or focus states.
+
+**Not checked yet:** which parts are present (icons, buttons, avatars) and content insets. A passing story says so instead of a bare green "matches".
+
+> **On the roadmap, not shipped:** coverage per Figma variant axis, every instance in a multi-instance story checked against its own variant, a drift check in CI, and an AI review as a second opinion on top of the deterministic check.
 
 ## The verdict
 
@@ -108,9 +121,16 @@ The result isn't buried in one panel. Once a story has been checked, you see it
 
 ## Review every story at once
 
-UI Parity registers a **test provider** in Storybook's Testing module (the same sidebar area Storybook's own test widgets use). Hit **Run** and it checks every mapped story in one pass, streaming results into the sidebar as each one lands.
+Hit **Review all** in the Coverage tab, or **Run** in Storybook's Testing module (UI Parity registers a test provider there). It checks every mapped story in one pass and streams results into the sidebar as each one lands.
 
-This is the "did anything drift?" sweep — run it after a design-system bump, a token change, or a dependency upgrade, and read the answer off the sidebar. The Run button stays disabled until you're connected and have at least one mapped story.
+The **Coverage** tab then shows the library-wide answer:
+
+- **Coverage:** stories checked, out of all your stories.
+- **Parity:** of the stories checked, how many match.
+- **Why only N checked?** Every story that wasn't checked is listed with its reason: not mapped, several variants fit, no Figma variant, or not run yet.
+- **Drift by component:** worst first. Each row expands to its stories; click one to open it.
+
+Run it after a design-system bump, a token change or a dependency upgrade. Results persist across reloads; results from an older run are labelled as such.
 
 ## Works with any Storybook framework
 
@@ -129,7 +149,7 @@ Both are useful, and they answer different questions.
 | Compares against | **The last approved screenshot** of your own component         | **The Figma frame** — the design source of truth                         |
 | Catches          | Any change from the previous build                             | Divergence from what the design says, even if it's been wrong for months |
 | Output           | A pixel diff image to eyeball                                  | Named properties with Expected vs. Actual values                         |
-| Needs            | Baselines to approve and re-approve                            | A one-time story → frame mapping                                         |
+| Needs            | Baselines to approve and re-approve                            | Auto-mapping, plus one click for each story it is unsure about           |
 | Blind spot       | A component that never matched the design still passes forever | Anything not expressed as a comparable style property                    |
 
 Snapshot tools tell you **something changed**. UI Parity tells you **it doesn't match the design** — which is the question that comes up in design review, not code review. Teams run both.
@@ -185,7 +205,10 @@ Worth knowing before you point it at a private design system:
 Confirm the addon is in the `addons` array of `.storybook/main.ts` and restart Storybook. If you've changed the addon version, clear the cache: `rm -rf node_modules/.cache .cache storybook-static`.
 
 **"Compare to design" is disabled.**
-The story isn't mapped to a Figma frame yet. Map it from the panel first.
+The story isn't mapped to a Figma variant yet. Run auto-map from the Coverage tab, or map it from the panel.
+
+**A story says "not compared".**
+Several Figma variants fit it, or none does. Open **Confirm variants**, pick the right one, and it is checked from the next run on.
 
 **Figma won't connect / no frames show up after sync.**
 Two usual causes: a Figma **Viewer or free seat** (a Dev or Full seat is required for design-read access), or the frames live on a page you didn't select during setup. Re-run the Figma step and include the page.