guard-my-design-system 1.0.0 → 1.0.2

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.
Files changed (2) hide show
  1. package/README.md +89 -32
  2. package/package.json +11 -3
package/README.md CHANGED
@@ -1,35 +1,51 @@
1
1
  # guard-my-design-system
2
2
 
3
- **No new mess.**
3
+ [![npm](https://img.shields.io/npm/v/guard-my-design-system?color=2dd4bf&label=npm)](https://www.npmjs.com/package/guard-my-design-system) [![downloads](https://img.shields.io/npm/dm/guard-my-design-system?color=2dd4bf&label=downloads)](https://www.npmjs.com/package/guard-my-design-system) [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![no telemetry](https://img.shields.io/badge/no-telemetry-2dd4bf)](https://github.com/gregkozakiewicz/guard-my-design-system#what-makes-the-verdict-trustworthy) [![GitHub Action](https://img.shields.io/badge/GitHub_Action-v1-2dd4bf)](#on-a-pull-request)
4
4
 
5
- Design systems don't die in a redesign. They die one pull request at a time:
6
- a colour that's nearly the token, a spacing value that's off the scale, an
7
- `!important` that seemed harmless on a Friday.
5
+ ## Your design system dies one pull request at a time. This makes sure it doesn't.
8
6
 
9
- This is the smoke alarm at the door. It checks **only the lines a pull request
10
- adds**, says nothing about the past, and points each new sin at the on-system
11
- value the author probably meant. Old wiring is not its business; new sparks
12
- are.
7
+ A pull request guard that checks **only the lines a change adds**, says nothing
8
+ about the past, and points each new sin at the on-system value the author
9
+ probably meant. Old wiring is not its business; new sparks are.
13
10
 
14
11
  It learns your system by scanning your repo with the
15
12
  [roast-my-design-system](https://github.com/gregkozakiewicz/roast-my-design-system)
16
- engine, then judges the diff against what it learned. No config files, no
17
- rules to write, no tokens to register. Your codebase is the rulebook.
13
+ engine, then judges the diff against what it learned. No config files, no rules
14
+ to write, no tokens to register. Your codebase is the rulebook.
15
+
16
+ This is what a pull request sees, on real code, with the guard's own comment:
17
+
18
+ ![The guard's comment on a pull request: six new issues, each with a file path and line, the stray colours shown with swatches next to their nearest token, an off-scale spacing value next to its nearest step, a new typeface, an !important, and an arbitrary Tailwind value, ending with the note that only added lines are checked](https://raw.githubusercontent.com/gregkozakiewicz/guard-my-design-system/main/docs/pr-comment.png?v=1.0.2)
19
+
20
+ One comment per pull request, updated in place as the author fixes things. Push
21
+ a fix and the same comment counts down instead of piling up:
22
+
23
+ ![The same pull request after fixes were pushed: the guard's single comment has updated in place, now showing three remaining issues, with the fix commits visible in the timeline above it and all checks passing below](https://raw.githubusercontent.com/gregkozakiewicz/guard-my-design-system/main/docs/pr-comment-updated.png?v=1.0.2)
18
24
 
19
25
  ## What it catches
20
26
 
21
- - a hard-coded colour where a token exists, with the nearest token named
22
- - a spacing value the codebase has never used, with the nearest step named
23
- - a typeface the system doesn't declare
24
- - `!important`
25
- - arbitrary Tailwind values (`w-[137px]`, `mt-[37px]`)
27
+ - **A hard-coded colour where a token exists**, with the nearest token named.
28
+ - **A spacing value the codebase has never used**, with the nearest step named.
29
+ - **A typeface the system does not declare.**
30
+ - **`!important`**, the cascade admitting defeat.
31
+ - **Arbitrary Tailwind values** (`w-[137px]`, `mt-[37px]`) that sidestep the scale.
26
32
 
27
33
  And what it deliberately ignores: everything that was already there. Even if
28
- the codebase carries years of mess, the guard only asks one question of a
29
- change: does it make things worse?
34
+ the codebase carries years of mess, the guard asks one question of a change:
35
+ does it make things worse?
36
+
37
+ ## Why this exists
38
+
39
+ Nobody can win the argument "please go and clean up the codebase". Everyone can
40
+ win "let us at least stop digging". The guard makes not-digging automatic, and
41
+ it matters more now than ever: AI agents write a growing share of UI code, and
42
+ they drift off-system faster than review can catch. Rules files ask nicely; the
43
+ guard checks.
30
44
 
31
45
  ## On a pull request
32
46
 
47
+ Five minutes, once:
48
+
33
49
  ```yaml
34
50
  # .github/workflows/guard.yml
35
51
  name: guard
@@ -47,12 +63,7 @@ jobs:
47
63
  - uses: gregkozakiewicz/guard-my-design-system@v1
48
64
  ```
49
65
 
50
- Every pull request gets one comment, updated in place, like:
51
-
52
- > **🛡 guard-my-design-system: 2 new issues in this pull request**
53
- >
54
- > - `Card.tsx:24` — new colour `#4a7be8`. Nearest token: `#3b6fe0`.
55
- > - `Card.tsx:31` — new spacing value `13px`. Nearest existing value: `12px`.
66
+ After that you forget it exists, which is the whole point of a smoke alarm.
56
67
 
57
68
  Prefer a failed check over a comment? Strict mode is the one setting:
58
69
 
@@ -62,25 +73,71 @@ Prefer a failed check over a comment? Strict mode is the one setting:
62
73
  strict: true
63
74
  ```
64
75
 
76
+ `exclude` keeps folders out of the system scan, same syntax as the CLI below.
77
+
65
78
  ## On your machine
66
79
 
67
80
  Judge your uncommitted work before anyone else sees it:
68
81
 
69
82
  ```bash
70
- npx guard-my-design-system
83
+ npx guard-my-design-system@latest
71
84
  ```
72
85
 
73
- Flags: `--base <ref>` to diff against something other than main,
74
- `--strict` to exit 1 on findings, `--json` for machines,
75
- `--exclude <paths>` to leave folders out of the system scan.
86
+ | Command | What you get |
87
+ |---|---|
88
+ | <code>npx&nbsp;guard-my-design-system@latest</code> | Your working tree's added lines judged against main, in the terminal |
89
+ | <code>npx&nbsp;guard-my-design-system@latest&nbsp;&lt;path&gt;</code> | Judge a different repo than the current directory |
90
+ | <code>...&nbsp;--base&nbsp;&lt;ref&gt;</code> | Diff against something other than main |
91
+ | `... --strict` | Exit 1 on findings, so it slots into scripts and hooks |
92
+ | `... --markdown` | The verdict as markdown, the same text the PR comment carries |
93
+ | `... --json` | Findings as JSON on stdout, for scripts and pipelines |
94
+ | <code>...&nbsp;--exclude&nbsp;lab/</code> | Leave folders out of the system scan (comma-separate for more). A `.roastignore` file at the repo root works too |
95
+
96
+ Requires Node 18+ and git.
97
+
98
+ ## What makes the verdict trustworthy
99
+
100
+ - **Only added lines are checked.** The existing codebase is never judged,
101
+ never counted, never mentioned. Nobody rips out a smoke alarm because it
102
+ criticised their old wiring.
103
+ - **Deterministic, not AI sampling.** The same engine that powers
104
+ roast-my-design-system reads the diff and returns the same verdict every
105
+ run. No model, no sampling, no drift.
106
+ - **Read-only, no network, no telemetry.** The scan and the diff both happen
107
+ locally in your CI runner or terminal. Nothing about your code leaves the
108
+ machine it runs on.
109
+ - **Honest exemptions, inherited from roast.** Email and print styling must be
110
+ inline, so it is never flagged. Artwork files carry hex that is drawing, not
111
+ styling. Defining a new token is extending the system, not a sin.
112
+ - **Findings are blunt, advice starts from intent.** Every flag names the
113
+ on-system value the author probably meant, so the fix takes thirty seconds
114
+ and no meeting.
76
115
 
77
116
  ## The family
78
117
 
79
118
  [roast-my-design-system](https://github.com/gregkozakiewicz/roast-my-design-system)
80
- diagnoses the whole codebase and scores it against a 34-repo benchmark.
81
- guard keeps new work from adding to the pile. Roast diagnoses it, guard
82
- protects it.
119
+ diagnoses the whole codebase: a health score against a 34-repo benchmark, the
120
+ receipts behind it, and the agent rules that keep AI-written UI on-system.
121
+ guard keeps new work from adding to the pile.
122
+
123
+ Roast diagnoses it. Guard protects it.
124
+
125
+ **Your design system dies one pull request at a time. This makes sure it doesn't.**
126
+
127
+ <a href="https://github.com/gregkozakiewicz/guard-my-design-system"><img src="https://img.shields.io/badge/If%20it%20caught%20something%20before%20review%20did%2C%20a%20star%20helps%20other%20people%20find%20it-a855f7?style=for-the-badge&logo=github&logoColor=white" alt="If it caught something before review did, a star helps other people find it"></a>
128
+
129
+ ## License
130
+
131
+ MIT. The code is yours to fork, modify and redistribute; the copyright notice
132
+ travels with it.
133
+
134
+ If you build a report, summary or audit of your own from this tool's findings,
135
+ keep one line in it: *Built with
136
+ [guard-my-design-system](https://github.com/gregkozakiewicz/guard-my-design-system)
137
+ by Greg Kozakiewicz*.
83
138
 
84
- ## Licence
139
+ **guard-my-design-system**™ and the GK mark are trademarks of Greg Kozakiewicz.
140
+ Forking is welcome, republishing under this name is not: see
141
+ [brand and attribution](https://gregkozakiewicz.github.io/roast-my-design-system/brand.html).
85
142
 
86
- MIT © [Greg Kozakiewicz](https://gregkozakiewicz.com)
143
+ 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,7 +1,7 @@
1
1
  {
2
2
  "name": "guard-my-design-system",
3
- "version": "1.0.0",
4
- "description": "No new mess. A pull request guard that judges only the lines a change adds against the design system the repo already has, and names the on-system value the author probably meant.",
3
+ "version": "1.0.2",
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": {
7
7
  "guard-my-design-system": "index.mjs"
@@ -17,11 +17,19 @@
17
17
  "design-system",
18
18
  "design-tokens",
19
19
  "lint",
20
+ "linter",
20
21
  "ci",
21
22
  "pull-request",
22
23
  "code-review",
24
+ "github-action",
25
+ "design-drift",
26
+ "design-ops",
27
+ "code-quality",
28
+ "ai-agents",
23
29
  "tailwind",
24
- "css"
30
+ "css",
31
+ "style-guide",
32
+ "developer-tools"
25
33
  ],
26
34
  "author": "Greg Kozakiewicz (https://gregkozakiewicz.com)",
27
35
  "license": "MIT",