@uicopilot/storybook-addon 0.9.0 → 0.9.1
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 +122 -9
- package/dist/manager.mjs +5 -5
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,17 +1,130 @@
|
|
|
1
|
-
|
|
1
|
+
<!--
|
|
2
|
+
IMAGE HOSTING NOTE (read before publishing)
|
|
3
|
+
npm and the Storybook catalog render the README from the *published package*, and
|
|
4
|
+
relative image paths (./hero.png) show as broken there. Every image below is an
|
|
5
|
+
ABSOLUTE public URL under https://app.uiparity.com (the dashboard origin, already
|
|
6
|
+
public — it serves the addon icon). Upload the real assets to those paths, or swap
|
|
7
|
+
in any public CDN URL, before publishing. shields.io badges are already live.
|
|
8
|
+
-->
|
|
2
9
|
|
|
3
|
-
>
|
|
10
|
+
<p align="center">
|
|
11
|
+
<img src="https://app.uiparity.com/logos/logo-v3-a.png" alt="UI Parity" width="96" height="96" />
|
|
12
|
+
</p>
|
|
4
13
|
|
|
5
|
-
|
|
14
|
+
<h1 align="center">UI Parity for Storybook</h1>
|
|
6
15
|
|
|
7
|
-
|
|
16
|
+
<p align="center">
|
|
17
|
+
<strong>Catch design drift between Figma and Storybook before it ships.</strong><br/>
|
|
18
|
+
A compliance score per component — right inside the Storybook you already have.
|
|
19
|
+
</p>
|
|
8
20
|
|
|
9
|
-
|
|
21
|
+
<p align="center">
|
|
22
|
+
<a href="https://www.npmjs.com/package/@uicopilot/storybook-addon"><img src="https://img.shields.io/npm/v/@uicopilot/storybook-addon?color=ea580c&label=npm" alt="npm version" /></a>
|
|
23
|
+
<a href="https://www.npmjs.com/package/@uicopilot/storybook-addon"><img src="https://img.shields.io/npm/dw/@uicopilot/storybook-addon?color=ea580c&label=downloads" alt="weekly downloads" /></a>
|
|
24
|
+
<a href="https://www.npmjs.com/package/@uicopilot/storybook-addon"><img src="https://img.shields.io/npm/l/@uicopilot/storybook-addon?color=ea580c" alt="license" /></a>
|
|
25
|
+
<img src="https://img.shields.io/badge/storybook-%E2%89%A59.0-ff4785" alt="Storybook 9+" />
|
|
26
|
+
</p>
|
|
10
27
|
|
|
11
|
-
|
|
28
|
+
<p align="center">
|
|
29
|
+
<!-- Hero screenshot: the panel catching a drift (wrong color) with the compliance score. -->
|
|
30
|
+
<img src="https://app.uiparity.com/readme/hero.png" alt="UI Parity panel showing a color mismatch and a 69 · D compliance score" width="820" />
|
|
31
|
+
</p>
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Why
|
|
36
|
+
|
|
37
|
+
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.
|
|
38
|
+
|
|
39
|
+
You get a **compliance score and an exact list of what's off** (Expected vs. Actual, per property) — not a fuzzy pixel diff you have to eyeball.
|
|
40
|
+
|
|
41
|
+
## Install
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npm install --save-dev @uicopilot/storybook-addon
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Register it in `.storybook/main.ts`:
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
export default {
|
|
51
|
+
addons: ['@uicopilot/storybook-addon'],
|
|
52
|
+
};
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
That's it — no other config. Restart Storybook and you'll see a **UI Parity** tab in the addon panel and a toolbar button on every story.
|
|
56
|
+
|
|
57
|
+
## Quick start
|
|
58
|
+
|
|
59
|
+
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.
|
|
60
|
+
2. **Map the story to its Figma frame** (one click, "Map to Figma"). This tells UI Parity what the component is _supposed_ to look like.
|
|
61
|
+
3. **Click "Compare to design."** You get a traffic-light verdict, a compliance score (e.g. `69 · D`), and a list of exactly which properties drifted.
|
|
62
|
+
|
|
63
|
+
<!--
|
|
64
|
+
Demo GIF slot — uncomment once demo.gif is uploaded to app.uiparity.com/readme/.
|
|
65
|
+
Should show: map a story → Compare to design → score + issues appear.
|
|
66
|
+
<p align="center">
|
|
67
|
+
<img src="https://app.uiparity.com/readme/demo.gif" alt="Mapping a story to Figma and running Compare to design" width="820" />
|
|
68
|
+
</p>
|
|
69
|
+
-->
|
|
70
|
+
|
|
71
|
+
## What it checks
|
|
72
|
+
|
|
73
|
+
**Compare to design** is the free, deterministic check. It diffs the story's _computed_ styles against the Figma spec — no screenshots, no AI, no credits:
|
|
74
|
+
|
|
75
|
+
| ✅ Catches today | Property |
|
|
76
|
+
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
77
|
+
| Wrong brand / token colors | `color`, fill, background (banded by ΔE, so a barely-visible shift is a minor, a wrong brand color is a critical) |
|
|
78
|
+
| Off typography | `font-family`, size, weight |
|
|
79
|
+
| Spacing drift | padding, gap, margins (sub-5px diffs downgrade to minor) |
|
|
80
|
+
| Corner radius | `border-radius` |
|
|
81
|
+
| Borders | width, color, style |
|
|
82
|
+
|
|
83
|
+
> **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.
|
|
84
|
+
|
|
85
|
+
## The compliance score
|
|
86
|
+
|
|
87
|
+
Every review returns a score `0–100` and a severity band `A–D`, MQM-style:
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
score = 100 − (minor × 1) − (major × 3) − (critical × 10) · capped by band
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
| Band | Meaning | Score cap |
|
|
94
|
+
| ----- | -------------------- | --------- |
|
|
95
|
+
| **A** | Clean — no issues | 100 |
|
|
96
|
+
| **B** | Minor issues only | 99 |
|
|
97
|
+
| **C** | Has a major issue | 89 |
|
|
98
|
+
| **D** | Has a critical issue | 69 |
|
|
99
|
+
|
|
100
|
+
Any open critical (a wrong brand color, say) caps the component at **69 · D** no matter how few issues there are — the score can't hide a real failure. Severities are perceptually adjusted first (color diffs by ΔE2000, dimension diffs by pixel distance), so "barely visible" never scores as "critical."
|
|
12
101
|
|
|
13
102
|
## Requirements
|
|
14
103
|
|
|
15
|
-
- Storybook 9
|
|
16
|
-
- Figma account
|
|
17
|
-
- UI Parity
|
|
104
|
+
- **Storybook** `9.0` or newer
|
|
105
|
+
- A **Figma** account with a **Dev or Full seat** — free/Viewer seats can't grant the design-read access UI Parity needs to index your components
|
|
106
|
+
- A free **[UI Parity](https://uiparity.com)** account — sign in with Google, or start as a guest and sign up to save your results
|
|
107
|
+
|
|
108
|
+
## Self-hosting the dashboard
|
|
109
|
+
|
|
110
|
+
The addon talks to `https://app.uiparity.com` by default. Point it at your own deployment with `STORYBOOK_UICOPILOT_URL` in `.storybook/main.ts`:
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
export default {
|
|
114
|
+
addons: ['@uicopilot/storybook-addon'],
|
|
115
|
+
env: (config) => ({
|
|
116
|
+
...config,
|
|
117
|
+
STORYBOOK_UICOPILOT_URL: 'https://your-dashboard.example.com',
|
|
118
|
+
}),
|
|
119
|
+
};
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## Links
|
|
123
|
+
|
|
124
|
+
- 🌐 **[uiparity.com](https://uiparity.com)** — product & sign-up
|
|
125
|
+
- 📊 **[app.uiparity.com](https://app.uiparity.com)** — the dashboard
|
|
126
|
+
- 💬 **feedback@uiparity.com** — questions, bugs, feature requests
|
|
127
|
+
|
|
128
|
+
## License
|
|
129
|
+
|
|
130
|
+
MIT © UI Parity
|