guard-my-design-system 1.3.2 → 1.3.4
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 +94 -90
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,11 +4,9 @@
|
|
|
4
4
|
|
|
5
5
|
## Your design system dies one pull request at a time. This makes sure it doesn't.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
It speaks in nearests, not scoldings:
|
|
7
|
+
The guard checks pull requests for design-system drift. It looks only at the
|
|
8
|
+
lines a change adds. It never judges the code that was already there. For each
|
|
9
|
+
problem it finds, it names the closest value your system already has:
|
|
12
10
|
|
|
13
11
|
> `Card.tsx:24` — new colour `#4a7be8`. Nearest token: `var(--blue-500)`, `#3b6fe0`.
|
|
14
12
|
>
|
|
@@ -20,62 +18,64 @@ It speaks in nearests, not scoldings:
|
|
|
20
18
|
>
|
|
21
19
|
> `site.css:35` — `!important`. The cascade admitting defeat; raise specificity or fix the source order.
|
|
22
20
|
|
|
23
|
-
It learns your system by scanning your
|
|
21
|
+
It learns your design system by scanning your repository with the
|
|
24
22
|
[roast-my-design-system](https://github.com/gregkozakiewicz/roast-my-design-system)
|
|
25
|
-
engine
|
|
26
|
-
|
|
23
|
+
engine. It reads CSS, SCSS, styled components, Lit `` css`…` `` templates and
|
|
24
|
+
Stencil styling. You do not write any config, rules or token lists. Your
|
|
25
|
+
codebase is the rulebook.
|
|
27
26
|
|
|
28
|
-
This is
|
|
27
|
+
This is the guard's comment on a real pull request:
|
|
29
28
|
|
|
30
29
|
|
|
31
30
|
|
|
32
|
-
|
|
33
|
-
|
|
31
|
+
The guard posts one comment per pull request. When the author pushes fixes,
|
|
32
|
+
it updates that same comment. It never adds more comments:
|
|
34
33
|
|
|
35
34
|
|
|
36
35
|
|
|
37
36
|
## What it catches
|
|
38
37
|
|
|
39
|
-
- **A hard-coded colour where a token exists
|
|
40
|
-
|
|
41
|
-
- **A spacing value
|
|
42
|
-
|
|
38
|
+
- **A hard-coded colour where a token exists.** The finding names the token:
|
|
39
|
+
`var(--blue-500)`, not just a hex code.
|
|
40
|
+
- **A spacing value your codebase has never used**, with the nearest existing
|
|
41
|
+
step named.
|
|
42
|
+
- **A border radius, font size or shadow your system does not declare**, with
|
|
43
43
|
the nearest existing value named.
|
|
44
|
-
- **A typeface
|
|
45
|
-
- **`!important
|
|
46
|
-
- **Arbitrary Tailwind values**
|
|
44
|
+
- **A typeface your system does not declare.**
|
|
45
|
+
- **`!important`.**
|
|
46
|
+
- **Arbitrary Tailwind values** such as `w-[137px]` and `mt-[37px]`.
|
|
47
47
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
does it make things worse?
|
|
48
|
+
It ignores everything that was already in the codebase. It asks one question
|
|
49
|
+
of a change: does it make things worse?
|
|
51
50
|
|
|
52
51
|
## When the guard is wrong
|
|
53
52
|
|
|
54
|
-
Sometimes an off-system value is
|
|
55
|
-
|
|
56
|
-
|
|
53
|
+
Sometimes an off-system value is correct. A partner's brand colour, for
|
|
54
|
+
example. Write a comment on the line above, and the guard lets that one line
|
|
55
|
+
pass:
|
|
57
56
|
|
|
58
57
|
```css
|
|
59
58
|
/* guard-ignore-next-line — partner brand colour, agreed with design */
|
|
60
59
|
background: #e4002b;
|
|
61
60
|
```
|
|
62
61
|
|
|
63
|
-
|
|
64
|
-
The
|
|
65
|
-
|
|
66
|
-
file
|
|
62
|
+
This works in any file the guard reads: `//` in components, `/* */` in styles.
|
|
63
|
+
The comment is visible in code review. It silences exactly one line. It keeps
|
|
64
|
+
working on later pull requests that touch the same line. There is no config
|
|
65
|
+
file and there are no rule IDs.
|
|
67
66
|
|
|
68
67
|
## Why this exists
|
|
69
68
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
69
|
+
You cannot ask a team to clean up years of styling. You can stop new problems
|
|
70
|
+
getting in. The guard does that automatically, on every pull request.
|
|
71
|
+
|
|
72
|
+
It matters more now than ever. AI tools write a growing share of UI code, and
|
|
73
|
+
they drift off-system faster than review can catch. Rules files ask nicely;
|
|
74
|
+
the guard checks.
|
|
75
75
|
|
|
76
76
|
## On a pull request
|
|
77
77
|
|
|
78
|
-
|
|
78
|
+
Set it up once. It takes about five minutes:
|
|
79
79
|
|
|
80
80
|
```yaml
|
|
81
81
|
# .github/workflows/guard.yml
|
|
@@ -94,9 +94,10 @@ jobs:
|
|
|
94
94
|
- uses: gregkozakiewicz/guard-my-design-system@v1
|
|
95
95
|
```
|
|
96
96
|
|
|
97
|
-
After that
|
|
97
|
+
After that it runs on every pull request and needs no attention from you.
|
|
98
98
|
|
|
99
|
-
|
|
99
|
+
If you want the check to fail instead of commenting, turn on strict mode.
|
|
100
|
+
It is the only setting:
|
|
100
101
|
|
|
101
102
|
```yaml
|
|
102
103
|
- uses: gregkozakiewicz/guard-my-design-system@v1
|
|
@@ -104,14 +105,15 @@ Prefer a failed check over a comment? Strict mode is the one setting:
|
|
|
104
105
|
strict: true
|
|
105
106
|
```
|
|
106
107
|
|
|
107
|
-
`exclude` keeps folders out of the system scan
|
|
108
|
+
`exclude` keeps folders out of the system scan. It uses the same syntax as
|
|
109
|
+
the CLI below.
|
|
108
110
|
|
|
109
|
-
|
|
110
|
-
`uses: gregkozakiewicz/guard-my-design-system@<commit-sha>`.
|
|
111
|
+
If your team pins actions for security, use an exact commit instead of a
|
|
112
|
+
version tag: `uses: gregkozakiewicz/guard-my-design-system@<commit-sha>`.
|
|
111
113
|
|
|
112
114
|
## On your machine
|
|
113
115
|
|
|
114
|
-
|
|
116
|
+
Check your own work before you open a pull request:
|
|
115
117
|
|
|
116
118
|
```bash
|
|
117
119
|
npx guard-my-design-system@latest
|
|
@@ -119,21 +121,21 @@ npx guard-my-design-system@latest
|
|
|
119
121
|
|
|
120
122
|
| Command | What you get |
|
|
121
123
|
|---|---|
|
|
122
|
-
| <code>npx guard-my-design-system@latest</code> |
|
|
123
|
-
| <code>npx guard-my-design-system@latest <path></code> | Judge a different
|
|
124
|
-
| <code>... --base <ref></code> |
|
|
125
|
-
| `... --strict` | Exit 1
|
|
124
|
+
| <code>npx guard-my-design-system@latest</code> | The lines you have added, judged against main, in the terminal |
|
|
125
|
+
| <code>npx guard-my-design-system@latest <path></code> | Judge a different repository |
|
|
126
|
+
| <code>... --base <ref></code> | Compare against a branch other than main |
|
|
127
|
+
| `... --strict` | Exit with code 1 when there are findings, for scripts and hooks |
|
|
126
128
|
| `... --markdown` | The verdict as markdown, the same text the PR comment carries |
|
|
127
|
-
| `... --json` | Findings as JSON
|
|
128
|
-
| <code>... --exclude lab/</code> |
|
|
129
|
+
| `... --json` | Findings as JSON, for scripts and pipelines |
|
|
130
|
+
| <code>... --exclude lab/</code> | Keep folders out of the system scan (separate more with commas). A `.roastignore` file at the repository root works too |
|
|
131
|
+
| `... --version` | The version number |
|
|
129
132
|
|
|
130
|
-
|
|
133
|
+
You need Node 18 or later, and git.
|
|
131
134
|
|
|
132
135
|
## Not on GitHub?
|
|
133
136
|
|
|
134
|
-
The CLI works anywhere git works
|
|
135
|
-
GitHub
|
|
136
|
-
with two lines in `.gitlab-ci.yml`:
|
|
137
|
+
The CLI works anywhere git works. Only the comment-posting Action needs
|
|
138
|
+
GitHub. On GitLab, add this to `.gitlab-ci.yml`:
|
|
137
139
|
|
|
138
140
|
```yaml
|
|
139
141
|
guard:
|
|
@@ -145,7 +147,7 @@ guard:
|
|
|
145
147
|
- npx guard-my-design-system@latest --strict --base origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME
|
|
146
148
|
```
|
|
147
149
|
|
|
148
|
-
Bitbucket
|
|
150
|
+
On Bitbucket, add this to `bitbucket-pipelines.yml`:
|
|
149
151
|
|
|
150
152
|
```yaml
|
|
151
153
|
pipelines:
|
|
@@ -158,55 +160,57 @@ pipelines:
|
|
|
158
160
|
- npx guard-my-design-system@latest --strict --base origin/$BITBUCKET_PR_DESTINATION_BRANCH
|
|
159
161
|
```
|
|
160
162
|
|
|
161
|
-
The verdict prints in the pipeline log and `--strict` fails the step
|
|
162
|
-
|
|
163
|
+
The verdict prints in the pipeline log, and `--strict` fails the step. The
|
|
164
|
+
updating PR comment works on GitHub only, for now.
|
|
163
165
|
|
|
164
166
|
## What makes the verdict trustworthy
|
|
165
167
|
|
|
166
168
|
- **Only added lines are checked.** The existing codebase is never judged,
|
|
167
|
-
never counted, never mentioned.
|
|
168
|
-
|
|
169
|
-
- **Deterministic, not AI sampling.** The same engine that powers
|
|
169
|
+
never counted, never mentioned.
|
|
170
|
+
- **The results are deterministic.** The same engine that powers
|
|
170
171
|
roast-my-design-system reads the diff and returns the same verdict every
|
|
171
|
-
|
|
172
|
-
- **Read-only
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
- **
|
|
179
|
-
|
|
180
|
-
and no meeting.
|
|
172
|
+
time. No AI model is involved.
|
|
173
|
+
- **Read-only. No network. No telemetry.** Everything runs on your machine or
|
|
174
|
+
your CI runner. Nothing about your code leaves it.
|
|
175
|
+
- **Fair exemptions, inherited from roast.** Email and print styling must be
|
|
176
|
+
inline, so the guard never flags it. Files that draw SVG artwork are not
|
|
177
|
+
judged on their colours. Defining a new token is extending the system, not
|
|
178
|
+
a problem.
|
|
179
|
+
- **Every finding comes with a fix.** The guard names the on-system value the
|
|
180
|
+
author probably meant, so most fixes take under a minute and no meeting.
|
|
181
181
|
|
|
182
182
|
## Honest limits
|
|
183
183
|
|
|
184
|
-
Things the guard deliberately does not do,
|
|
185
|
-
in a pull request:
|
|
186
|
-
|
|
187
|
-
- **Monorepos are judged as one
|
|
188
|
-
|
|
189
|
-
appears in `apps/web`.
|
|
190
|
-
- **Spacing is compared within one unit.**
|
|
191
|
-
`13px
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
workflow
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
GitHub-
|
|
184
|
+
Things the guard deliberately does not do, listed here so they never surprise
|
|
185
|
+
you in a pull request:
|
|
186
|
+
|
|
187
|
+
- **Monorepos are judged as one codebase.** The guard learns the system from
|
|
188
|
+
the whole repository. A colour that is legitimate in `packages/ui` counts
|
|
189
|
+
as known when it appears in `apps/web`. For per-package scores, use roast.
|
|
190
|
+
- **Spacing is compared within one unit.** If your scale uses rem and someone
|
|
191
|
+
adds `13px`, the guard flags it. But it will not claim `0.75rem` is the
|
|
192
|
+
nearest value to `13px`. Converting units would be a guess, and the guard
|
|
193
|
+
does not guess.
|
|
194
|
+
- **Taste is not judged.** The right token in the wrong place passes.
|
|
195
|
+
Defining a new token is never flagged. The guard checks drift, not
|
|
196
|
+
decisions.
|
|
197
|
+
- **On a pull request from a fork, the comment cannot be posted.** GitHub
|
|
198
|
+
gives the workflow a read-only token. The guard still runs, and the verdict
|
|
199
|
+
appears in the workflow log with a line explaining why. The same happens if
|
|
200
|
+
the workflow is missing `pull-requests: write`.
|
|
201
|
+
- **Not on GitHub?** Covered: GitLab and Bitbucket recipes are in
|
|
202
|
+
[Not on GitHub?](#not-on-github) above.
|
|
203
|
+
- **Inside `` css`…` `` templates, the line-by-line check catches colours but
|
|
204
|
+
not yet spacing, radii or shadows.** The whole-repository scan reads those
|
|
205
|
+
templates in full, so the system is still learned correctly. The
|
|
206
|
+
line-level gap will close with a future engine release.
|
|
203
207
|
|
|
204
208
|
## The family
|
|
205
209
|
|
|
206
210
|
[roast-my-design-system](https://github.com/gregkozakiewicz/roast-my-design-system)
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
guard
|
|
211
|
+
examines your whole codebase: a health score against a 34-repo benchmark, the
|
|
212
|
+
evidence behind it, and the agent rules that keep AI-written UI on-system.
|
|
213
|
+
The guard stops new work adding to the pile.
|
|
210
214
|
|
|
211
215
|
Roast diagnoses it. Guard protects it.
|
|
212
216
|
|
|
@@ -216,7 +220,7 @@ Roast diagnoses it. Guard protects it.
|
|
|
216
220
|
|
|
217
221
|
## License
|
|
218
222
|
|
|
219
|
-
MIT.
|
|
223
|
+
MIT. You may fork, modify and redistribute the code. The copyright notice
|
|
220
224
|
travels with it.
|
|
221
225
|
|
|
222
226
|
If you build a report, summary or audit of your own from this tool's findings,
|
|
@@ -225,7 +229,7 @@ keep one line in it: *Built with
|
|
|
225
229
|
by Greg Kozakiewicz*.
|
|
226
230
|
|
|
227
231
|
**guard-my-design-system**™ and the GK mark are trademarks of Greg Kozakiewicz.
|
|
228
|
-
Forking is welcome
|
|
232
|
+
Forking is welcome. Republishing under this name is not. See
|
|
229
233
|
[brand and attribution](https://gregkozakiewicz.github.io/guard-my-design-system/brand.html).
|
|
230
234
|
|
|
231
235
|
Built and designed by <a href="https://gregkozakiewicz.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/gk-mark-dark.png?v=3.10.1"><img src="https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/gk-mark.png?v=3.10.1" height="15" alt="GK mark"></picture> Greg Kozakiewicz</a>.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "guard-my-design-system",
|
|
3
|
-
"version": "1.3.
|
|
3
|
+
"version": "1.3.4",
|
|
4
4
|
"description": "Your design system dies one pull request at a time. This makes sure it doesn't. A guard that judges only the lines a change adds, against the system the repo already has, and names the on-system value the author probably meant.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|