guard-my-design-system 1.3.3 → 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 -96
- 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,64 +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
|
-
|
|
27
|
-
|
|
28
|
-
write, no tokens to register. Your codebase is the rulebook.
|
|
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.
|
|
29
26
|
|
|
30
|
-
This is
|
|
27
|
+
This is the guard's comment on a real pull request:
|
|
31
28
|
|
|
32
29
|
|
|
33
30
|
|
|
34
|
-
|
|
35
|
-
|
|
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:
|
|
36
33
|
|
|
37
34
|
|
|
38
35
|
|
|
39
36
|
## What it catches
|
|
40
37
|
|
|
41
|
-
- **A hard-coded colour where a token exists
|
|
42
|
-
|
|
43
|
-
- **A spacing value
|
|
44
|
-
|
|
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
|
|
45
43
|
the nearest existing value named.
|
|
46
|
-
- **A typeface
|
|
47
|
-
- **`!important
|
|
48
|
-
- **Arbitrary Tailwind values**
|
|
44
|
+
- **A typeface your system does not declare.**
|
|
45
|
+
- **`!important`.**
|
|
46
|
+
- **Arbitrary Tailwind values** such as `w-[137px]` and `mt-[37px]`.
|
|
49
47
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
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?
|
|
53
50
|
|
|
54
51
|
## When the guard is wrong
|
|
55
52
|
|
|
56
|
-
Sometimes an off-system value is
|
|
57
|
-
|
|
58
|
-
|
|
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:
|
|
59
56
|
|
|
60
57
|
```css
|
|
61
58
|
/* guard-ignore-next-line — partner brand colour, agreed with design */
|
|
62
59
|
background: #e4002b;
|
|
63
60
|
```
|
|
64
61
|
|
|
65
|
-
|
|
66
|
-
The
|
|
67
|
-
|
|
68
|
-
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.
|
|
69
66
|
|
|
70
67
|
## Why this exists
|
|
71
68
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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.
|
|
77
75
|
|
|
78
76
|
## On a pull request
|
|
79
77
|
|
|
80
|
-
|
|
78
|
+
Set it up once. It takes about five minutes:
|
|
81
79
|
|
|
82
80
|
```yaml
|
|
83
81
|
# .github/workflows/guard.yml
|
|
@@ -96,9 +94,10 @@ jobs:
|
|
|
96
94
|
- uses: gregkozakiewicz/guard-my-design-system@v1
|
|
97
95
|
```
|
|
98
96
|
|
|
99
|
-
After that
|
|
97
|
+
After that it runs on every pull request and needs no attention from you.
|
|
100
98
|
|
|
101
|
-
|
|
99
|
+
If you want the check to fail instead of commenting, turn on strict mode.
|
|
100
|
+
It is the only setting:
|
|
102
101
|
|
|
103
102
|
```yaml
|
|
104
103
|
- uses: gregkozakiewicz/guard-my-design-system@v1
|
|
@@ -106,14 +105,15 @@ Prefer a failed check over a comment? Strict mode is the one setting:
|
|
|
106
105
|
strict: true
|
|
107
106
|
```
|
|
108
107
|
|
|
109
|
-
`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.
|
|
110
110
|
|
|
111
|
-
|
|
112
|
-
`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>`.
|
|
113
113
|
|
|
114
114
|
## On your machine
|
|
115
115
|
|
|
116
|
-
|
|
116
|
+
Check your own work before you open a pull request:
|
|
117
117
|
|
|
118
118
|
```bash
|
|
119
119
|
npx guard-my-design-system@latest
|
|
@@ -121,21 +121,21 @@ npx guard-my-design-system@latest
|
|
|
121
121
|
|
|
122
122
|
| Command | What you get |
|
|
123
123
|
|---|---|
|
|
124
|
-
| <code>npx guard-my-design-system@latest</code> |
|
|
125
|
-
| <code>npx guard-my-design-system@latest <path></code> | Judge a different
|
|
126
|
-
| <code>... --base <ref></code> |
|
|
127
|
-
| `... --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 |
|
|
128
128
|
| `... --markdown` | The verdict as markdown, the same text the PR comment carries |
|
|
129
|
-
| `... --json` | Findings as JSON
|
|
130
|
-
| <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 |
|
|
131
132
|
|
|
132
|
-
|
|
133
|
+
You need Node 18 or later, and git.
|
|
133
134
|
|
|
134
135
|
## Not on GitHub?
|
|
135
136
|
|
|
136
|
-
The CLI works anywhere git works
|
|
137
|
-
GitHub
|
|
138
|
-
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`:
|
|
139
139
|
|
|
140
140
|
```yaml
|
|
141
141
|
guard:
|
|
@@ -147,7 +147,7 @@ guard:
|
|
|
147
147
|
- npx guard-my-design-system@latest --strict --base origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME
|
|
148
148
|
```
|
|
149
149
|
|
|
150
|
-
Bitbucket
|
|
150
|
+
On Bitbucket, add this to `bitbucket-pipelines.yml`:
|
|
151
151
|
|
|
152
152
|
```yaml
|
|
153
153
|
pipelines:
|
|
@@ -160,59 +160,57 @@ pipelines:
|
|
|
160
160
|
- npx guard-my-design-system@latest --strict --base origin/$BITBUCKET_PR_DESTINATION_BRANCH
|
|
161
161
|
```
|
|
162
162
|
|
|
163
|
-
The verdict prints in the pipeline log and `--strict` fails the step
|
|
164
|
-
|
|
163
|
+
The verdict prints in the pipeline log, and `--strict` fails the step. The
|
|
164
|
+
updating PR comment works on GitHub only, for now.
|
|
165
165
|
|
|
166
166
|
## What makes the verdict trustworthy
|
|
167
167
|
|
|
168
168
|
- **Only added lines are checked.** The existing codebase is never judged,
|
|
169
|
-
never counted, never mentioned.
|
|
170
|
-
|
|
171
|
-
- **Deterministic, not AI sampling.** The same engine that powers
|
|
169
|
+
never counted, never mentioned.
|
|
170
|
+
- **The results are deterministic.** The same engine that powers
|
|
172
171
|
roast-my-design-system reads the diff and returns the same verdict every
|
|
173
|
-
|
|
174
|
-
- **Read-only
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
- **
|
|
181
|
-
|
|
182
|
-
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.
|
|
183
181
|
|
|
184
182
|
## Honest limits
|
|
185
183
|
|
|
186
|
-
Things the guard deliberately does not do,
|
|
187
|
-
in a pull request:
|
|
188
|
-
|
|
189
|
-
- **Monorepos are judged as one
|
|
190
|
-
|
|
191
|
-
appears in `apps/web`.
|
|
192
|
-
- **Spacing is compared within one unit.**
|
|
193
|
-
`13px
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
workflow
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
GitHub-
|
|
205
|
-
- **Inside `` css`…` `` templates,
|
|
206
|
-
|
|
207
|
-
templates in full, so the system is learned correctly
|
|
208
|
-
line-level gap
|
|
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.
|
|
209
207
|
|
|
210
208
|
## The family
|
|
211
209
|
|
|
212
210
|
[roast-my-design-system](https://github.com/gregkozakiewicz/roast-my-design-system)
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
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.
|
|
216
214
|
|
|
217
215
|
Roast diagnoses it. Guard protects it.
|
|
218
216
|
|
|
@@ -222,7 +220,7 @@ Roast diagnoses it. Guard protects it.
|
|
|
222
220
|
|
|
223
221
|
## License
|
|
224
222
|
|
|
225
|
-
MIT.
|
|
223
|
+
MIT. You may fork, modify and redistribute the code. The copyright notice
|
|
226
224
|
travels with it.
|
|
227
225
|
|
|
228
226
|
If you build a report, summary or audit of your own from this tool's findings,
|
|
@@ -231,7 +229,7 @@ keep one line in it: *Built with
|
|
|
231
229
|
by Greg Kozakiewicz*.
|
|
232
230
|
|
|
233
231
|
**guard-my-design-system**™ and the GK mark are trademarks of Greg Kozakiewicz.
|
|
234
|
-
Forking is welcome
|
|
232
|
+
Forking is welcome. Republishing under this name is not. See
|
|
235
233
|
[brand and attribution](https://gregkozakiewicz.github.io/guard-my-design-system/brand.html).
|
|
236
234
|
|
|
237
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": {
|