@iksnerd/blazon 0.3.3 → 0.5.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/CHANGELOG.md +375 -0
- package/dist/chunks/{site-builder-DlaZeZHi.js → site-builder-C8g2sfUv.js} +3471 -3650
- package/dist/cli/commands/approvals.d.ts +1 -1
- package/dist/cli/commands/approvals.d.ts.map +1 -1
- package/dist/cli/commands/mcp-check.d.ts +7 -4
- package/dist/cli/commands/mcp-check.d.ts.map +1 -1
- package/dist/cli/errors.d.ts +3 -1
- package/dist/cli/errors.d.ts.map +1 -1
- package/dist/cli/folder-first.d.ts +7 -0
- package/dist/cli/folder-first.d.ts.map +1 -0
- package/dist/cli/handlers/can.d.ts +1 -1
- package/dist/cli/handlers/can.d.ts.map +1 -1
- package/dist/cli/handlers/list.d.ts.map +1 -1
- package/dist/cli/index.js +1384 -1033
- package/dist/cli/json.d.ts +3 -2
- package/dist/cli/json.d.ts.map +1 -1
- package/dist/cli/operations.d.ts +1 -1
- package/dist/cli/operations.d.ts.map +1 -1
- package/dist/cli/read.d.ts +4 -1
- package/dist/cli/read.d.ts.map +1 -1
- package/dist/cli/where.d.ts +2 -0
- package/dist/cli/where.d.ts.map +1 -1
- package/dist/core/assets/representations.d.ts +44 -0
- package/dist/core/assets/representations.d.ts.map +1 -0
- package/dist/core/assets/scanner.d.ts.map +1 -1
- package/dist/core/assets/sidecar.d.ts.map +1 -1
- package/dist/core/blazon-pin.d.ts +19 -1
- package/dist/core/blazon-pin.d.ts.map +1 -1
- package/dist/core/brand/export.d.ts +13 -5
- package/dist/core/brand/export.d.ts.map +1 -1
- package/dist/core/brand/schema.d.ts +68 -0
- package/dist/core/brand/schema.d.ts.map +1 -1
- package/dist/core/checker/approvals.d.ts +5 -0
- package/dist/core/checker/approvals.d.ts.map +1 -1
- package/dist/core/checker/catalogue.d.ts +37 -7
- package/dist/core/checker/catalogue.d.ts.map +1 -1
- package/dist/core/checker/font-meta.d.ts.map +1 -1
- package/dist/core/checker/index.d.ts +5 -0
- package/dist/core/checker/index.d.ts.map +1 -1
- package/dist/core/checker/review.d.ts +19 -1
- package/dist/core/checker/review.d.ts.map +1 -1
- package/dist/core/docs/directives.d.ts +10 -0
- package/dist/core/docs/directives.d.ts.map +1 -1
- package/dist/core/docs/parser.d.ts.map +1 -1
- package/dist/core/font-roles.d.ts +11 -0
- package/dist/core/font-roles.d.ts.map +1 -0
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/init/from-site/fonts.d.ts.map +1 -1
- package/dist/core/logo/colorways.d.ts +29 -0
- package/dist/core/logo/colorways.d.ts.map +1 -0
- package/dist/core/logo/misuse.d.ts +18 -0
- package/dist/core/logo/misuse.d.ts.map +1 -0
- package/dist/core/mcp-config.d.ts +7 -0
- package/dist/core/mcp-config.d.ts.map +1 -1
- package/dist/core/operations/check.d.ts +1 -1
- package/dist/core/operations/check.d.ts.map +1 -1
- package/dist/core/operations/index.d.ts +1 -1
- package/dist/core/operations/index.d.ts.map +1 -1
- package/dist/core/operations/limits.d.ts +2 -0
- package/dist/core/operations/limits.d.ts.map +1 -1
- package/dist/core/operations/list.d.ts.map +1 -1
- package/dist/core/operations/types.d.ts +13 -0
- package/dist/core/operations/types.d.ts.map +1 -1
- package/dist/core/preflight.d.ts.map +1 -1
- package/dist/core/read/can.d.ts +14 -3
- package/dist/core/read/can.d.ts.map +1 -1
- package/dist/core/read/fonts.d.ts +2 -6
- package/dist/core/read/fonts.d.ts.map +1 -1
- package/dist/core/read/index.d.ts +3 -2
- package/dist/core/read/index.d.ts.map +1 -1
- package/dist/core/read/list.d.ts +15 -1
- package/dist/core/read/list.d.ts.map +1 -1
- package/dist/core/read/logo.d.ts +3 -3
- package/dist/core/read/logo.d.ts.map +1 -1
- package/dist/core/read/lookup.d.ts +2 -2
- package/dist/core/read/lookup.d.ts.map +1 -1
- package/dist/core/read/theme.d.ts +8 -0
- package/dist/core/read/theme.d.ts.map +1 -0
- package/dist/core/read/token.d.ts +6 -2
- package/dist/core/read/token.d.ts.map +1 -1
- package/dist/core/tokens/alias.d.ts +5 -3
- package/dist/core/tokens/alias.d.ts.map +1 -1
- package/dist/core/tokens/contexts.d.ts +11 -3
- package/dist/core/tokens/contexts.d.ts.map +1 -1
- package/dist/core/tokens/formatters/json.d.ts +4 -1
- package/dist/core/tokens/formatters/json.d.ts.map +1 -1
- package/dist/core/tokens/key-lines.d.ts.map +1 -1
- package/dist/core/tokens/merge.d.ts.map +1 -1
- package/dist/core/tokens/resolver/compile.d.ts.map +1 -1
- package/dist/core/tokens/resolver/parse.d.ts.map +1 -1
- package/dist/core/tokens/resolver/sources.d.ts.map +1 -1
- package/dist/core/tokens/walk.d.ts.map +1 -1
- package/dist/index.js +34 -34
- package/dist/plugins/host/call.d.ts.map +1 -1
- package/dist/plugins/roles/roles.d.ts.map +1 -1
- package/dist/server/plugin.d.ts.map +1 -1
- package/dist/types/assets.d.ts +19 -1
- package/dist/types/assets.d.ts.map +1 -1
- package/dist/types/parsed.d.ts +8 -0
- package/dist/types/parsed.d.ts.map +1 -1
- package/dist/types/tokens.d.ts +12 -0
- package/dist/types/tokens.d.ts.map +1 -1
- package/dist/ui/assets/index-b4HhGGrn.js +82 -0
- package/dist/ui/assets/index-pE1ku5gt.css +2 -0
- package/dist/ui/index.html +2 -2
- package/mcp/dist/index.js +358 -45
- package/package.json +3 -2
- package/plugins/blazon.brand-deck/README.md +1 -1
- package/plugins/blazon.brand-deck/bin/blazon-blazon.brand-deck./360/237/224/214 +106 -13
- package/plugins/blazon.favicons/bin/blazon-blazon.favicons./360/237/224/214 +120 -12
- package/plugins/blazon.logo-geometry/bin/blazon-blazon.logo-geometry./360/237/224/214 +45 -1
- package/plugins/blazon.logo-kit/bin/blazon-blazon.logo-kit./360/237/224/214 +45 -1
- package/plugins/blazon.office-template/bin/blazon-blazon.office-template./360/237/224/214 +66 -3
- package/plugins/blazon.platform-tokens/README.md +1 -1
- package/plugins/blazon.press-kit/README.md +17 -9
- package/plugins/blazon.press-kit/bin/blazon-blazon.press-kit./360/237/224/214 +621 -101
- package/plugins/blazon.print-book/README.md +16 -1
- package/plugins/blazon.social-cards/bin/blazon-blazon.social-cards./360/237/224/214 +59 -3
- package/plugins/shipped.lock +9 -9
- package/dist/ui/assets/index-Biy1hkeq.css +0 -2
- package/dist/ui/assets/index-dkJG6W9p.js +0 -82
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,375 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes are listed here. Blazon follows [semantic versioning](https://semver.org/); while it is 0.x, a minor version may break.
|
|
4
|
+
|
|
5
|
+
## Unreleased
|
|
6
|
+
|
|
7
|
+
<!-- Do not write here. A change adds a file under changelog.d/; see changelog.d/README.md. -->
|
|
8
|
+
|
|
9
|
+
## 0.5.1 (2026-11-21)
|
|
10
|
+
|
|
11
|
+
### Fixed
|
|
12
|
+
|
|
13
|
+
- The dev server waits for a folder that a config reload starts to watch before it sends the page its update. Before, an edit made right after a `tokensDir` (or other folder) change could be missed on a busy machine, and the page kept the old value until the next save.
|
|
14
|
+
|
|
15
|
+
## 0.5.0 (2026-11-21)
|
|
16
|
+
|
|
17
|
+
Tagged, not released and not published to npm: its CI run failed on Linux (a hook lock test and a dev server test). Everything in it is part of 0.5.1.
|
|
18
|
+
|
|
19
|
+
### Breaking
|
|
20
|
+
|
|
21
|
+
- `blazon logo` and the MCP `get_logo` list each logo id once, with `files` (a list, in the default order: SVG, then PNG, WebP, JPEG, GIF, then other formats) in place of `file`. A reader that took `file` from a logo entry must take the first of `files`, or choose by format.
|
|
22
|
+
|
|
23
|
+
### Added
|
|
24
|
+
|
|
25
|
+
- `CHANGELOG.md` ships in the npm package, so an agent or a user can read what changed between versions in `node_modules/@iksnerd/blazon/CHANGELOG.md`. `npm run check-pack` requires it.
|
|
26
|
+
- A check now notes, once per resolver context, that the context leaves out tokens the default has while `theme.css` and the other CSS keep the default value for them (`context-css-unchanged`, info). It names the context, how many tokens it removes and the first five paths, and it never fails a check. Give the token a value in the context file, or do not use its variable in that context.
|
|
27
|
+
- A font token can state its `role` (`primary`, `secondary`, `display`,
|
|
28
|
+
`monospace` or `fallback`), a one-line `reason`, and for a fallback what it
|
|
29
|
+
`fallbackFor`. `blazon fonts`, the Typography page, the press kit's
|
|
30
|
+
`fonts.txt` and its `index.html` show them. The new finding
|
|
31
|
+
`font-role-invalid` (a warning) covers a bad `reason` or `fallbackFor`.
|
|
32
|
+
- A logo sidecar can list named `colorways`: each is a logo variant on a color token, with the contrast it must reach (`AA-large`, 3:1, by default, as for a logo). A new `blazon:logo-colorways` directive draws each one as a labelled figure with its measured ratio and a pass or fail in words and a mark. `blazon check` reports a colorway below its level as `contrast-insufficient`, and one it cannot measure as `contrast-unknown`. It draws in the brand book and in the print book.
|
|
33
|
+
- A new `blazon:logo-misuse` directive draws the logo misused in named ways, one captioned figure for each (stretch, rotate, outline, recolor, shadow, low contrast, and squash, crop and busy background on request), each marked as not allowed without relying on color. A sidecar can list its kinds in `misuse`, and an unknown kind is an `asset-misuse-unknown` error. It draws in the brand book and in the print book.
|
|
34
|
+
- `blazon.press-kit` takes a `company.contact` (name, role, email, phone, url) and a `terms` option (the brand's own text and an address), prints them in `about.txt`, the PDF and the new `index.html`, and writes `index.html` at the root of the kit folder and zip: the kit as one static page, with no script and no remote files, for a person who opens it in a browser.
|
|
35
|
+
|
|
36
|
+
### Changed
|
|
37
|
+
|
|
38
|
+
- `blazon list`, `get`, `rules` and `can` now explain a brand folder typed first. When one fails because the current folder has no brand, or a token is not found, and a leading argument is a brand folder, a line says it was read as the group, path, fg or bg, and shows the corrected command, such as `blazon list <group> acme` or `blazon list --cwd acme`. The parse, the exit status and the output of a success are unchanged.
|
|
39
|
+
- `blazon mcp --check` compares the `blazon` entry in the client config with this install: it says when the registered entry runs a different `mcp/dist/index.js` (a source clone, an older install), naming both files, and says it could not tell when the entry does not name a script file. `--json` adds `state` and `sameServer` to the `registered` check. Only the script path is read from an entry; no other argument or environment value is printed.
|
|
40
|
+
|
|
41
|
+
### Fixed
|
|
42
|
+
|
|
43
|
+
- An asset in two formats (`logos/mark.svg` and `logos/mark.png`, one sidecar) is now one asset with one approval.
|
|
44
|
+
`review.value` is a fingerprint of the id, made from all its files; an id with one file keeps its old fingerprint.
|
|
45
|
+
Approving it no longer makes the other file stale, `blazon approvals` prints one row for the id with its files, and
|
|
46
|
+
`approval-stale`, `asset-review-missing` and `review-pending` are reported once for each id. Every reader now takes the
|
|
47
|
+
same file for an id (SVG, then PNG, WebP, JPEG, GIF, then other formats), so the favicons symbol works for `mark.svg`
|
|
48
|
+
beside `mark.png`.
|
|
49
|
+
- The brand deck draws a logo with several files (`logos/mark.svg` and
|
|
50
|
+
`logos/mark.png`) as one slide, from the best format it can embed, instead of
|
|
51
|
+
one slide for each file. Guideline slides and figure grids choose their file the
|
|
52
|
+
same way, whatever order the files are in.
|
|
53
|
+
- A resolver context that leaves out a token the default has no longer publishes it. `tokens.<modifier>.<context>.json`, `brand.json`, `blazon get`, `list` and `can` with `--theme`, and the brand book now leave the token out, and a context's changed group description or contrast pairs reach `brand.json`. `brand.json` stays at version 2: each context gains `removed`, `groupChanges` and `removedGroups`, present only when there is something to say. CSS and `tokens.ts` cannot express a removal, so a removed token keeps the default's value there.
|
|
54
|
+
- A finding about a group's `$type`, `$extensions` or `$deprecated` now names the file that wrote it, not the first file that mentioned the group.
|
|
55
|
+
- `blazon init --from <url>` reads a font name written with a CSS escape (`"Acme \"Sans\""`, `Acme\ Sans`) and keeps a
|
|
56
|
+
`var(--x, "A, B")` fallback in one piece, instead of cutting the font list at the wrong comma.
|
|
57
|
+
- A logo that `logo` in blazon.json names by file is now that file in `blazon.office-template` and `blazon.social-cards`,
|
|
58
|
+
even when its asset has other files. With `logos/mark.svg` and `logos/mark.png`, `"logo": "./assets/logos/mark.png"`
|
|
59
|
+
drew the SVG in the Office template and sized the social cards' logo as the default 4:1 shape. A logo that names an id
|
|
60
|
+
still takes the default order.
|
|
61
|
+
- A build plugin that is refused before it starts (its request is over the cap, or its manifest lists a variable the config does not approve) keeps the files its last run made in `<tokensOutDir>/<id>/`; blazon empties the folder only once the plugin is about to run. A folder that cannot be emptied or made is now a `plugin-failed` finding for that plugin, and the other plugins still run.
|
|
62
|
+
- A resolver document that fails partway no longer drops the `token-file-invalid` findings already collected, and a token file reached by two spellings of one path (`a.json` and `./a.json`) is read and reported once.
|
|
63
|
+
- A resolver pointer such as `#/modifiers/density` finds only a modifier declared under `modifiers`. Before, it also found an inline modifier of that name when the inline item came earlier in `resolutionOrder`, listed it twice, and failed when the inline item came later. It is now a `resolver-invalid` error in both orders.
|
|
64
|
+
- The help of `blazon can`, `list` and `get` showed `--theme <<name>>`, with the angle brackets doubled; it now shows `--theme <name>`.
|
|
65
|
+
- The DTCG export (`tokens.json` and the context files) keeps a group's `$extensions` again. A vendor key such as `com.acme.tool` on `space` was dropped while the same key on `space.small` survived. A group's `dev.blazon` key is still not written.
|
|
66
|
+
- A sidecar beside an image that could not be read is no longer also reported as `asset-sidecar-orphaned`; only `asset-unreadable` is reported.
|
|
67
|
+
- A page that cannot be read now reports only `page-unreadable`. It no longer
|
|
68
|
+
also reports an old `folio:` directive found in it before the failure.
|
|
69
|
+
|
|
70
|
+
## 0.4.0 (2026-11-20)
|
|
71
|
+
|
|
72
|
+
### Added
|
|
73
|
+
|
|
74
|
+
- `can_use` takes `pairs` (up to 50 `{ fg, bg }`) and answers one result for each,
|
|
75
|
+
in order; `blazon can` takes `--pair fg:bg`, repeated. `verbose: false`
|
|
76
|
+
(`--no-verbose`) leaves out the `checks` of an allowed answer and keeps them
|
|
77
|
+
for a denial. A batch answer has `allowed` (true when every pair is) and
|
|
78
|
+
`results`, so `reason` is no longer required in the `can_use` output schema.
|
|
79
|
+
- `list_tokens` and `blazon list` take `tier` (`--tier`: primitive, semantic or
|
|
80
|
+
component) and list the tier of each token. `list_tokens`, `get_token`,
|
|
81
|
+
`blazon list` and `blazon get` take `theme` (`--theme`) and give the values as
|
|
82
|
+
that resolver theme resolves them, with `defaultValue` where the theme changes
|
|
83
|
+
one. The `list_tokens` answer has `themes`, the names of the themes the brand
|
|
84
|
+
has.
|
|
85
|
+
|
|
86
|
+
### Changed
|
|
87
|
+
|
|
88
|
+
- The denial of a pair that no `pairs` rule lists now says that component tokens
|
|
89
|
+
are not read for pairs and where to declare the pair: `pairs` on a token group.
|
|
90
|
+
No verdict changes.
|
|
91
|
+
- `brandHasErrors` now means one thing in all seven MCP tools: the brand's own data has error findings. A `blazon.lock` that names another blazon build no longer sets it, and `check_brand` no longer reports `passed: false` for that alone (the `pin-mismatch` finding is still listed). The mismatch is reported on its own as `pinMismatch` (`pinned`, `running`, `message`) in every tool. `blazon list`, `get`, `can`, `rules`, `fonts` and `logo` print it as one warning line and exit 0, and `check --json`, `build --json` and `tokens --json` carry `brandHasErrors` and `pinMismatch`; `check`, `build` and `tokens` refuse as before.
|
|
92
|
+
- The `blazon.print-book` README gives a Ghostscript command that shrinks the PDF and keeps images at 300 ppi and about JPEG quality 91, with what it did on four books and a deck, and the README no longer claims a size ratio it had not measured.
|
|
93
|
+
|
|
94
|
+
## 0.3.3 (2026-11-20)
|
|
95
|
+
|
|
96
|
+
### Fixed
|
|
97
|
+
|
|
98
|
+
- The print book's page count no longer depends on machine load. The fonts are awaited before the book is paginated, so a slow or busy computer gives the same pages as a quiet one. A book can gain a page or more compared with 0.3.2, because the earlier count was measured with the fallback font: page counts of existing books can change. The starter is 73 pages compact and 83 roomy.
|
|
99
|
+
|
|
100
|
+
## 0.3.2 (2026-11-19)
|
|
101
|
+
|
|
102
|
+
### Added
|
|
103
|
+
|
|
104
|
+
- `blazon.platform-tokens` writes the width of `border` tokens as a dimension named `<token path>.width` (`border.rule` is `border_rule_width` in `dimens.xml`, `BlazonDimensions.borderRuleWidth`, `BlazonDimens.borderRuleWidth`), so every output and option applies. The colour is not written. A style other than `solid` is named in a new `border-style-dropped` info finding; an unreadable width is a `dimension-unreadable` warning. `include` and `exclude` match the border token's path. `border` leaves the `tokens-skipped` list. A brand with no border token gets the same files.
|
|
105
|
+
- `blazon.platform-tokens` takes `include` and `exclude`: lists of token path prefixes in dot form (`["breakpoint", "component.button.website"]`), compared name by name, with no glob or regular expression. `include` keeps only the matching tokens, `exclude` then removes matching ones, in every output and the dark context. A bad list is an `option-invalid` finding; an entry that matches no token is a `filter-unmatched` info finding.
|
|
106
|
+
- `blazon.press-kit` takes a `company` option (`description`, `boilerplate` and up to 20 `facts` as `{ label, value }`) for a brand whose own title and description are a book's: the company description replaces the brand's in `about.txt` and the PDF, and the boilerplate and facts follow. It also takes a `note` (one line) printed in `README.txt`, `about.txt`, `colors/colors.txt` and the PDF, for a kit whose colors are not yet approved. A wrong value is an `option-invalid` finding at `options.company...` or `options.note`, with length limits stated in the plugin README. With neither option the files are unchanged except for the fixes below.
|
|
107
|
+
- `brand.json` carries the license file that sits beside a font file the config embeds (`OFL.txt`, `LICENSE`, `LICENCE`, `COPYING`, in that file's own folder only) as `theme.fontLicenses`: `{ family, licenseFile, licenseText }`, at most 64 KiB, UTF-8, inside the project. A new optional field, so `version` stays 2. A file that is too large, not UTF-8 or reached through a link out of the project is not read, and `font-license-invalid` (a warning) says why.
|
|
108
|
+
|
|
109
|
+
### Changed
|
|
110
|
+
|
|
111
|
+
- The MCP tool `check_brand` says what its counts leave out. A plugin's roles are only in the manifest its program prints, so the server cannot tell a `check` plugin from a build-only one (`blazon.tailwind`, `blazon.shadcn`) without starting it. `pluginsSkipped` still lists every plugin in `blazon.json`; the warning and the tool description now say that only a plugin with a `check` role can add findings, and the warning no longer says the counts "can be higher" without that condition.
|
|
112
|
+
- `blazon.press-kit` `fonts.txt` prints the license from that file (`License file:` and its identifying line) for a font whose token states no license, instead of `License: not stated`.
|
|
113
|
+
- The `blazon.print-book` docs say its PDF is Chrome's output with lossless images, so it is large, and that a post-processing step such as Ghostscript shrinks it.
|
|
114
|
+
- `blazon.platform-tokens`: with a `prefix`, the colorset names in `Colors.xcassets` carry it in lowerCamel (`acmeBlue100`) and the Swift file is `<Prefix>Tokens.swift` (`AcmeTokens.swift`), so generated color symbols do not collide with an app's own assets. With no prefix the output is byte-identical. The Kotlin `package blazon.tokens` stays fixed.
|
|
115
|
+
- The `blazon.platform-tokens` README documents `prefix`, what it reaches, the naming rule per output and which token types are not written.
|
|
116
|
+
- The release audit allowlist is empty. The picomatch advisory it held (GHSA-fc5q-39xc-vjpf) was withdrawn upstream on 2026-11-18, so `npm audit` is clean again; the gate failed on the stale entry, as designed, and the entry and the SECURITY.md section about it are removed.
|
|
117
|
+
|
|
118
|
+
### Fixed
|
|
119
|
+
|
|
120
|
+
- The print book draws a Markdown task item (`- [ ]`, `- [x]`) with no bullet and a visible box: a border in the theme's text color, filled when checked. The browser's own checkbox printed as a nearly invisible pale grey.
|
|
121
|
+
- `blazon.press-kit` `fonts.txt` listed system fonts (`SFMono-Regular`, `Arial`) as brand fonts with `License: not stated`. It now lists a family only when it is the front of a stack and not a system font, or a stylesheet or font file loads it, or its token states a source or license; the rest are one last line, `Fallback fonts, not shipped: ...`. With no option the output changes: that line is new, and a system family is gone from the font list and from the `font-license-unstated` finding. A brand whose stacks name only system fonts now gets `font-none` and no `fonts.txt`. The license is still read only from the font token: the plugin gets no project folder, so it cannot read a license file beside the font files.
|
|
122
|
+
- `blazon.press-kit` `README.txt` ran the PDF's name into its description (`acme-press-kit.pdfOne page`) when the name was long. The descriptions now start two spaces after the longest name, and at column 16 when the names are shorter, so a kit with short names is unchanged.
|
|
123
|
+
- `blazon.press-kit` PDF swatches took the first ten colors in file order, labelled with the last path segment (`500`). They now take whole color groups in the order the brand gives them, labelled with group and step (`blue 500`); a flat color keeps its description. The PDF line of `README.txt` states the rule.
|
|
124
|
+
- A quoted family after a comma in a font stack (`'Inter', 'Arial Narrow'`) was read with its quotes by the shipped plugins' stack reader.
|
|
125
|
+
|
|
126
|
+
## 0.3.1 (2026-11-17)
|
|
127
|
+
|
|
128
|
+
### Added
|
|
129
|
+
|
|
130
|
+
- The release job's dependency audit is `scripts/audit-gate.mjs`, which reads `.github/audit-allowlist.json`: it fails on a new high or critical advisory, on an allowlist entry that has expired or no longer matches, and when `npm audit` did not run. The one entry is the `picomatch` ReDoS (GHSA-fc5q-39xc-vjpf), which has no patched version and is not reachable from blazon (SECURITY.md).
|
|
131
|
+
|
|
132
|
+
## 0.3.0 (2026-11-17)
|
|
133
|
+
|
|
134
|
+
Tagged and pushed, not released: its release job failed at the dependency audit gate on a high advisory in picomatch (via vite) that has no patched version. Everything in it is part of 0.3.1.
|
|
135
|
+
|
|
136
|
+
### Added
|
|
137
|
+
|
|
138
|
+
- The MCP server ships inside `@iksnerd/blazon`. `npm install @iksnerd/blazon` gives you `blazon-mcp` (a second `bin`), and `npx -y -p @iksnerd/blazon blazon-mcp --brand <dir>` starts it with no clone. It is one built file, `mcp/dist/index.js`, with the MCP SDK and zod bundled in at build time, so the package gains no dependency and `npm audit --omit=dev` is unchanged. `blazon-mcp --version` prints the versions it carries.
|
|
139
|
+
- `npm run check-pack` requires `mcp/dist/index.js`, fails when a plain path in `package.json` `files` is not in the package, and the tarball smoke test (`scripts/smoke-tarball.mjs`) runs `blazon mcp --check` and a real `check_brand` and `list_tokens` through the installed server.
|
|
140
|
+
|
|
141
|
+
### Changed
|
|
142
|
+
|
|
143
|
+
- `blazon mcp --print-config` and `--check` from an npm install print `node`, the installed `mcp/dist/index.js`, `--brand` and `BLAZON_BIN`, and `--check` passes with a real handshake on a clean install; `--check` finds the blazon beside the server when `BLAZON_BIN` is not set. The `npx @iksnerd/blazon-mcp` form of a package that is not on npm is gone, from the command line and from the dev server's "Connect your agent" panel. An install that has lost the server file says the install is incomplete and to reinstall, and exits 1.
|
|
144
|
+
- The MCP server reports blazon's version as its own (`serverInfo.version`), where it said `0.0.0`.
|
|
145
|
+
- The manual said the server has eight tools; it has seven.
|
|
146
|
+
- The MCP tool `check_brand` says when plugins did not run. It always ran `blazon check --no-plugins`, so a brand whose `blazon.json` lists plugins such as `blazon.copy` got lower counts than `blazon check`, with no word on why. The answer now carries `pluginsSkipped` (the names from `blazon.json`) and one line in `warnings`; a config with no plugins adds nothing.
|
|
147
|
+
- The docs no longer state blazon's current version by hand (README status, manual, starter, CONTRIBUTING): a placeholder takes its place, and `test/docs/versions.test.ts` fails on a stale one.
|
|
148
|
+
|
|
149
|
+
## 0.2.2 (2026-11-17)
|
|
150
|
+
|
|
151
|
+
### Fixed
|
|
152
|
+
|
|
153
|
+
- A fresh `blazon init` project reported 3 warnings, not the 2 the manual states: `blazon.copy` found a 26-word sentence in the starter's `12-web.md`. The sentence is rewritten, and the first-run test now runs the starter with its own plugins, so a finding from `blazon.copy` on the starter fails the test (it ran the starter with no plugins before).
|
|
154
|
+
|
|
155
|
+
## 0.2.1 (2026-11-17)
|
|
156
|
+
|
|
157
|
+
Tagged and released on GitHub, not published to npm: its starter still reported 3 warnings on a new project. Everything in it is part of 0.2.2.
|
|
158
|
+
|
|
159
|
+
### Changed
|
|
160
|
+
|
|
161
|
+
- A new project lists `blazon.tailwind` and `blazon.shadcn` again, beside `blazon.copy` (both need only Node). `blazon init` then `blazon tokens` writes `dist/tokens/blazon.tailwind/` (`tailwind.css`, `tailwind-reset.css`) and `dist/tokens/blazon.shadcn/` (`shadcn.json`, `shadcn.css`) as well as `theme.css`, `typography.css`, `tokens.ts` and the JSON files, as 0.1.1 did. The starter's `blazon.shadcn` entry keeps the example's `variables` map.
|
|
162
|
+
|
|
163
|
+
## 0.2.0 (2026-11-16)
|
|
164
|
+
|
|
165
|
+
### Breaking
|
|
166
|
+
|
|
167
|
+
- The core no longer writes `tailwind.css` and `tailwind-reset.css`. Add `{ "name": "blazon.tailwind" }` to `plugins` in `blazon.json`, import the files from `dist/tokens/blazon.tailwind/` instead of `dist/tokens/`, and delete the old copies in `dist/tokens/`, which blazon no longer touches. The names `tailwind.css` and `tailwind-reset.css` are no longer reserved in `tokensOutDir`.
|
|
168
|
+
- The `shadcn` key of `blazon.json` is refused with `config-invalid`, and the message names the plugin. Move its map to `{ "name": "blazon.shadcn", "options": { "variables": { ... } } }` in `plugins`; the plugin reports a pick that names no token as `blazon.shadcn/token-missing`, which was `theme-unresolved`.
|
|
169
|
+
- `brand.json` is version 2: `theme.shadcn` is gone. A reader that checks `version` (as RFC 0001 requires) refuses version 1 files and must be updated; `blazon.shadcn` derives the same mapping, in `shadcn.json`. The `get_shadcn` tool and `blazon brand --key theme.shadcn` are removed with it: read `dist/tokens/blazon.shadcn/shadcn.json`.
|
|
170
|
+
- The `build` request of the plugin protocol is version 2 (`check` stays 1). It may carry no `site_dir`, which is how `blazon tokens` calls a plugin. A plugin written for version 1 of the build request is refused with exit 2 and the version named; change its check to 2, and answer a request with no `site_dir` (exit 2 with a reason, or an info finding and nothing written). A plugin that reads `brand.json` must accept version 2 of it. The reference plugins in `examples/plugins/` and `scripts/read-brand.py` do.
|
|
171
|
+
- `blazon get` no longer prints a `tailwind.css` name, and the `names.tailwind` field of its `--json` is gone. The Tailwind variable collision is reported by `blazon.tailwind` (`blazon.tailwind/variable-duplicate`, an error) when the plugin runs, not by `blazon check` as `css-variable-duplicate`, which now covers `theme.css` and a context's block only.
|
|
172
|
+
|
|
173
|
+
### Added
|
|
174
|
+
|
|
175
|
+
- Two shipped build plugins, `blazon.tailwind` and `blazon.shadcn`. `blazon.tailwind` writes `tailwind.css` and `tailwind-reset.css`; `blazon.shadcn` writes `shadcn.json` (which token each shadcn/ui variable takes) and `shadcn.css` (the variables as CSS, with a block for each context that changes one). Both read `brand.json` only, need only Node and write to `<tokensOutDir>/<plugin name>/`.
|
|
176
|
+
- `blazon tokens` runs the `build` plugins after it writes the token files. A plugin that needs the built site answers with the info finding `<name>/needs-site` and writes nothing, so `blazon build` is still the command for those. `blazon tokens` does not empty a plugin's folder: what the plugin writes overwrites the old file, and every other file stays, so the deck or press kit of the last `blazon build` survives. A file an earlier `blazon tokens` wrote and the plugin no longer writes also stays; `blazon build` empties the folder.
|
|
177
|
+
|
|
178
|
+
### Fixed
|
|
179
|
+
|
|
180
|
+
- `npm run release` regenerates `docs/stats.json` and runs the docs tests before it commits, and stops without a commit or tag if they fail. The release commit used to keep the old version in `docs/stats.json`, which failed `test/docs/stats.test.ts` at the pre-push hook and in CI on the tag.
|
|
181
|
+
|
|
182
|
+
## 0.1.1 (2026-11-16)
|
|
183
|
+
|
|
184
|
+
### Added
|
|
185
|
+
|
|
186
|
+
- `blazon.print-book` takes a `layout` option, `"compact"` (the default, the layout as it is) or `"roomy"`, which draws every picture whole and sets the prose and sections as the book was set before pictures were squeezed to share a slide, so it runs on more slides. Any other value is the `blazon.print-book/option-invalid` error.
|
|
187
|
+
- `directive-deprecated` (warning): a page comment `<!-- folio:name -->`, the old spelling, is reported with its page and line. Blazon reads only `blazon:`, so such a comment placed nothing and `blazon check` said nothing. A `blazon:` name that is not a directive was already `directive-unknown`.
|
|
188
|
+
- `token-extension-deprecated` (warning): a `$extensions` key that starts `dev.folio` on a token or a group is reported. It is ignored; rename it to `dev.blazon`.
|
|
189
|
+
- `blazon check` reports a build plugin whose manifest lists a variable that is set and not approved in the plugin's `env`, with the same `plugin-failed` message and fix as `blazon build`. It reads the manifest only and starts no build plugin.
|
|
190
|
+
|
|
191
|
+
## 0.1.0 (2026-11-16)
|
|
192
|
+
|
|
193
|
+
Published to npm as @iksnerd/blazon.
|
|
194
|
+
|
|
195
|
+
First release.
|
|
196
|
+
|
|
197
|
+
### Breaking
|
|
198
|
+
|
|
199
|
+
- A brand's own paths must stay inside its folder. `blazon.json` is data, so a path in it no longer decides what blazon reads or writes outside the project. `tokensDir`, `docsDir`, `assetsDir`, `resolver` and the `logo` files that are outside the project folder, by `../`, an absolute path or a link, now fail with the `config-path-outside` error and are not read. `outDir` and `tokensOutDir` in `blazon.json` that are outside it make blazon refuse to load the config. A token file or a page that is a link to a file outside the project is refused too, as is an icon set's `categories` file. Before, all of these were read or written, and `outDir` was emptied first. Copy the files in, or build to another folder with `blazon build -o <dir>`, which is still any folder you choose. The `dir` of an asset category may still name a shared folder, once the person running blazon approves it (next item).
|
|
200
|
+
- A category's `dir` outside the project folder is refused with `config-path-outside` (on `assets.<key>.dir`) unless the person running blazon approved the folder: `--allow-dir <folder>` on any command (repeatable), or `BLAZON_ALLOW_DIRS` (folders separated as a `PATH` is). `blazon.json` has no key for it, because a hostile brand would write one. Before, any brand could make `blazon dev` show, `blazon build` copy and the MCP tools return the image files of any folder it named. A monorepo script becomes `blazon dev --allow-dir ../shared`; a link or `..` out of an approved folder is still refused. An MCP client that needs a shared folder sets `BLAZON_ALLOW_DIRS` in the server's `env`. Plugins are never given the variable.
|
|
201
|
+
- `blazon mcp --check --json` has `runsPlugins: false` in place of `runsBrandConfig: true`, and its trust notice no longer says that compiling a brand runs plugins: the server runs none. The brand book's "Connect your agent" panel says the same.
|
|
202
|
+
- A plugin starts with an empty environment, `PATH` apart, and is given a variable only when its manifest lists the name in `env` and the project's config approves it in the `env` list of the plugin's entry (`plugins: [{ name: 'blazon.favicons', env: ['BLAZON_CHROME', 'HOME', 'TMPDIR'] }]`). `HOME`, `LANG` and `TMPDIR` are no longer passed on their own. A plugin whose manifest lists a name that is set and not approved is not started: `plugin-failed` names the variable and the key (`plugins[n].env`). `blazon plugin check` adds case 10, which fails when the project's config leaves out a name the manifest lists. The plugins that ship with blazon list what they read in their manifests like any other plugin: the ones that draw in Chrome list `BLAZON_CHROME`, `HOME` and `TMPDIR`, so a config that uses one adds those names to its `env`. RFC 0002 and RFC 0005 say so.
|
|
203
|
+
- `blazon plugin check` runs blazon's own cases for each role a plugin's manifest declares, after the core cases: 6, a valid request is answered with exit `0` or `2` (exit `1` fails it, as blazon treats it as a break); 7, the answer is within the role's stdout limit; 8, on exit `0` the answer is one the role accepts. A plugin that passed before can fail now. 9, for `build` only, warns when the plugin writes in `tokens_dir` outside `out_dir`; a warning does not fail the check, and `--json` gives such a case `"status": "warn"`, a new value beside `ok`, `skip` and `fail`. Fix the plugin, or read the case's detail ([Writing a plugin](docs/manual/13-writing-a-plugin.md#write-and-check-a-plugin)).
|
|
204
|
+
- `blazon check` warns `starter-logo-unchanged` for each configured logo that is still blazon's own mark, so a fresh `blazon init` project now reports 2 warnings (`--strict` fails it) until the logos are replaced.
|
|
205
|
+
- A brand must have a logo. A `blazon.json` with no `logo` now fails `blazon check` with the `logo-missing` error, which used to fire only for a configured file that was not there. Set `logo` to an image in the project.
|
|
206
|
+
- `blazon build -o <dir>` is a path from the folder you run blazon in, as for any command line tool. It was a path from the book, so `blazon build my-brand -o out` wrote `my-brand/out`. A relative `outDir` in `blazon.json` is still a path from the book.
|
|
207
|
+
- The `--json` counts name the notes `info`, as the findings do: `{ "errors": 0, "warnings": 0, "info": 23 }` replaces `notes`.
|
|
208
|
+
- A token's `review` block is now validated. A book that passed `blazon check` before can fail now. Each of these is an `review-invalid` error: a `status` that is not `ok` or `needs-review`, a `by` that is not a string, an `at` that is not a real `YYYY-MM-DD` date, a `value` that is not 12 hex digits, and a `value` on a token group (a group has no value to fingerprint). A malformed `review` in an asset sidecar is an `asset-sidecar-invalid` error. Fix the block, or remove the field.
|
|
209
|
+
- Blazon needs Node 24 or later (`engines` was `>=22`). Node 24 is the current LTS. Blazon does not use type stripping or `require(esm)` yet, and the shipped plugins stay compiled.
|
|
210
|
+
|
|
211
|
+
### Added
|
|
212
|
+
|
|
213
|
+
- The MCP server removes zero-width, bidirectional and Unicode tag characters from the brand text in every answer and says how many in `warnings`; its instructions tell the model to read that text as data. A number or boolean sent as a string (`"5"`, `"true"`) is accepted. A cut `get_fonts`, `get_logo`, `get_shadcn`, `get_token` or `can_use` answer no longer says "narrow with a path".
|
|
214
|
+
- A test shows that no MCP tool starts a plugin the brand config names.
|
|
215
|
+
- `blazon plugin check <program> --core` runs only the core cases of the plugin protocol (1 to 5): no role cases (6 to 9) and no `layout` line. The exit status is unchanged, and `--json` adds `core: true`. Without the flag nothing changes.
|
|
216
|
+
- `blazon explain <code>` says what a finding code means, how to clear it, and where to read more; with no code it lists every code, and an unknown code names the closest ones. `--json` gives the same as data.
|
|
217
|
+
- `blazon doctor` checks the environment (Node against `engines`, the brand folder, the plugin folder's safety, Google Chrome for the plugins that need it, and `blazon.lock`) and prints ok, warn or fail with a fix for each. It runs no plugin and writes nothing; it exits 1 only when a check fails.
|
|
218
|
+
- `--cwd <dir>` sets the folder every command works from. A folder argument is then relative to it.
|
|
219
|
+
- A blazon skill for coding agents, `skills/blazon/SKILL.md`, and a test that fails when it names a command, flag, tool or manual file that does not exist. Chapter 20 says how to install it.
|
|
220
|
+
- A `--json` error carries a stable `code` and, where there is one, a `fix`, beside the `message`, which is unchanged.
|
|
221
|
+
|
|
222
|
+
- A plugin may be listed more than once in `plugins`, each entry with an `as` instance id (dotted lowercase words, at most 64 characters, unique, and not the name of another plugin). Each instance has its own `options`, its own output folder `<tokensOutDir>/<id>/` and its own breaker; the pin stays one for the plugin's name. A finding of a plugin that is listed more than once ends with `(instance <id>)`. An entry with no `as` behaves as before.
|
|
223
|
+
- `blazon can <fg> <bg> --theme <name>` judges the pair in that context of the resolver's `theme` modifier (`--theme dark` on the starter), with the context's colors in place of the default's. An unknown theme exits 2 and lists the valid ones, and `--json` carries `theme`. The MCP tool `can_use` takes `theme` too.
|
|
224
|
+
- The starter has a dark theme. `blazon.resolver.json` loads the five token files and adds a `theme` modifier, light by default, whose `dark` context (`tokens/theme/dark.json`) puts Bone text on a Graphite page with a Carbon canvas and a Bone inverse band, and draws rules in Concrete and Zinc and the three shadows in Zinc. Signal Orange and `text.onSignal` stay as they are. `theme.css` carries it as a `[data-theme="dark"]` block, `blazon check` runs every rule in it, and the book's light and dark switch shows it. Two primitives are new, `color.base.carbon` (#101113) and `color.ink.zinc` (#8C9096), so the starter gains two tokens. Its Color, Form and motion, Logo and Web pages state the dark rules with their measured contrast, and `blazon init` lists `tokens/theme/dark.json` and `blazon.resolver.json`, so a fresh project reports 42 notes (it was 41).
|
|
225
|
+
- The starter has a `type.subhead` step (Big Shoulders Display 32/36px) between `type.h2` and `type.h3`, for a sub-section heading inside a page or chapter. Its Type and Web pages list it, so the starter has 79 tokens in all. The name is additive: `type.h3` keeps its name.
|
|
226
|
+
- The starter gains three tokens (it had 59): `shadow.shim` (2px, a key halfway seated) and `shadow.recess` (2px inset, an input or a tab rail) beside `shadow.plate`, and `type.code` (IBM Plex Mono 14/20px) for commands and code. Its Form and motion page states the key states (rest on the plate, `shadow.shim` under the pointer, no shadow pressed, each move at `motion.duration.snap`), its Color page says why Signal Orange has no hover shade, its Layout page gives ticks the rule colors, and its Web page lets small inverse parts (a tag, a panel's title strip, the active tab) sit beside the one inverse band.
|
|
227
|
+
- `npm run docs:stats` writes `docs/stats.json`, the version, commands, finding-code counts, MCP tools and manual chapters that a project website reads, and a test fails when the committed file is stale.
|
|
228
|
+
- `blazon can <fg> <bg> --role ui` (and an optional `role` on the MCP tool `can_use`) judges a focus ring, border or icon stroke instead of text: the contrast must reach 3:1 (WCAG 1.4.11), the `usage` rules are read for `border`, `icon` and `interactive`, and `pairs` do not apply. The default, `text`, answers as before; `--json` now also carries `role`, and `contrast.threshold` for `ui`. An unknown role exits 2. Manual chapters 8 and 19.
|
|
229
|
+
- `blazon fonts --css` prints the `@font-face` rules for the brand's font files (family, weight, style, `format()` from the extension, `font-display: swap`) and a comment for each stylesheet. `--base <url-prefix>` points `src` at the site's own public folder. With `--json` the text is `fontFace`. Command line only; the `get_fonts` tool is unchanged.
|
|
230
|
+
- `tailwind.css` also maps `shadow` tokens to `--shadow-*`, `cubicBezier` to `--ease-*`, `fontWeight` to `--font-weight-*`, font-size dimensions to `--text-*` and a `duration` named `default` to `--default-transition-duration`. A brand that wrote `plate`, weight or easing utilities by hand from `var(--...)` can use the generated ones. Border, transition and typography composites have no Tailwind namespace and stay `var(--path)`; chapter 8 has the table.
|
|
231
|
+
- `blazon tokens` and `blazon build` write `tailwind-reset.css`, a `@theme` block of `--color-*: initial` and the like for each Tailwind namespace the brand fills, so `rounded-xl` or `bg-blue-500` stop compiling. It is a separate file with no config key: import it after `tailwindcss` and before `tailwind.css`. Note that `--color-*: initial` also removes `white` and `black`. It is removed again when the brand no longer fills a namespace.
|
|
232
|
+
- The starter has six icons in `assets/icons/` (check, warning, arrow-right, download, file, token), each with a sidecar and drawn to the rules on its Icons page, and a local font: `fonts/IBMPlexMono-Regular-latin.woff2` (SIL OFL 1.1, licence in `fonts/OFL.txt`) is listed in `fonts` as a font file, so `blazon fonts` shows the path and the build embeds it. A fresh `blazon init` project now reports 39 starter-file-unchanged notes (was 27), still 0 errors and 2 warnings.
|
|
233
|
+
- The starter has a Web page, `docs/12-web.md` (section `applications`), for a site built in the brand: the type style for each page role, section spacing and widths, which surface goes with which section, buttons, cards, focus, the logo on the web, imagery and copy, and what to do about the shadcn variables the brand does not supply. It uses existing tokens only. `blazon init` now writes 12 pages and a fresh project reports one more `starter-file-unchanged` note; errors and warnings are unchanged. Chapter 19 of the manual points an agent at a brand's Web page.
|
|
234
|
+
- `blazon mcp --print-config [--client claude-code|claude-desktop|cursor|vscode] [--brand <dir>] [--json]` prints the config that registers `blazon-mcp` (stdio) in a client and writes no file. It uses the built `mcp/dist/index.js` when there is one; otherwise it prints the proposed `npx -y @iksnerd/blazon-mcp` form and says the package is not published. An unknown client exits 2.
|
|
235
|
+
- `blazon dev` has a "Connect your agent" button in the brand book's top bar: a panel with the same snippets for each client and a copy button, for the project's folder. The dev server serves them at `/__blazon/mcp-config`.
|
|
236
|
+
- `blazon list [group] [dir]` lists the tokens: path, type, CSS-ready value, and the token each aliases, so a coding agent can find a path without opening the token files. A group path keeps one group, `--type <type>` keeps one `$type`. `--json` prints `tokens` (and `group`, `type` when given); the text groups the lines under a header for each top-level group. An unknown group or type exits 2. `blazon get` takes a token path only and exits 2 for a group path. The function is `listTokens` in `src/core/read`.
|
|
237
|
+
- `blazon brand [dir]` prints the brand as `brand.json` holds it, compiled now and written nowhere, and `--key theme.shadcn` prints one part. `blazon tokens` does not write `dist/site/brand.json`, so a copy from an earlier build can be out of date; this command never is.
|
|
238
|
+
- A separate MCP server, `mcp/`, so a coding agent can ask blazon about a brand as tool calls: `get_token`, `get_rules`, `can_use`, `get_fonts`, `get_logo`, `get_shadcn` and `check_brand` (`list_tokens` came later, making eight). It runs the blazon CLI with `--json` and returns the parsed answer; it does not import blazon and blazon gains no dependency. It is private and not published. `get_shadcn` reads a built `dist/site/brand.json`, since no command prints `theme.shadcn`. Manual chapter 20, "Blazon for agents (MCP)".
|
|
239
|
+
- The CLI can read a brand, not only make or check one: `blazon get <path>` (a token's value, type, its variable in `theme.css` and in `tailwind.css`, its `usage`, `pairs`, `logo` and `review` rules with where each is written, and its file), `blazon rules [path]` (the rules of a token, a group or the whole brand), `blazon can <fg> <bg>` (whether a token may be text on another, from the usage rules and the pairs; exits 0 allowed, 1 denied, 2 unknown token), `blazon fonts` and `blazon logo` (the fonts the brand loads and the logo variants with their sidecar rules). Each takes `--json` and writes nothing. The logic is in `src/core/read/`. Manual chapter 8 and chapter 19 describe them.
|
|
240
|
+
- `shadcn` in `blazon.json` and `theme.shadcn` in `brand.json`: a coding agent building with shadcn/ui gets the brand's colors as shadcn's variables (`--primary`, `--ring`, `--chart-1`, ...) as data. For each variable blazon can supply, `brand.json` gives the token and its value in the default context, from the theme roles or from the `shadcn` map; `unsupplied` lists the rest, and `pairs` (when the brand declares contrast `pairs`) says whether a rule covers each shadcn text-on-surface pair. Blazon writes no shadcn file. A `shadcn` entry whose token does not exist is `theme-unresolved`. `brand.json` stays at version 1. Manual: [Using shadcn/ui](docs/manual/19-building-a-website.md#using-shadcnui).
|
|
241
|
+
- Manual chapter 19, "Building a website from a brand": how a developer or a coding agent reads a brand's rules and values so a site follows them, and which decisions are the brand owner's to state. The starter's `AGENTS.md` points to it.
|
|
242
|
+
- `blazon check` validates `print.cmyk` and `print.pms` as it does `print.ral`. A `cmyk` that is not an array of exactly four numbers from 0 to 100 is a `print-cmyk-invalid` error, and a `pms` that is not a non-empty single-line string is a `print-pms-invalid` error. `print-ral-invalid` now also refuses `RAL5012` (no space), which the book would have shown as `RAL RAL5012`. The values in the repository's examples pass all three checks.
|
|
243
|
+
- `print.ral` in `dev.blazon`: a RAL number such as `"5012"`, next to `cmyk` and `pms`. It is written as `RAL 5012` on the brand book's color card, the brand deck's palette slide and the press kit's `colors.txt`, and kept as written in `colors.json` and `brand.json`. A value that is not a non-empty single-line string, or that starts with `RAL`, is a `print-ral-invalid` error. `blazon check` does not ask for it.
|
|
244
|
+
- A stability chapter in the manual (18): the stable and unstable surfaces, the rule for a breaking change, and how to move a brand's pin. `test/surface/public-surface.json` records the stable surfaces and a test fails when they change without the record. `scripts/pin-compare.ts` builds a brand with two blazon builds and reports what differs: the findings, every file under `dist/`, and the keys of `brand.json`.
|
|
245
|
+
- A test that every finding code a shipped plugin raises is in its section of chapter 14. It found two that were missing, `blazon.favicons/symbol-not-drawn` and `blazon.print-book/favicons-not-in-site`.
|
|
246
|
+
- RFC 0001 open questions 1, 5 and 7 are decided in writing: keep `dev.blazon`, no inferred contrast pairs, plain-data config deferred.
|
|
247
|
+
- Two reference chapters in the manual: a glossary of every word blazon uses (chapter 16) and the data model, field by field, with the lists a value is checked against (chapter 17). A test fails when a field of the model, a member of one of those lists or a key of `brand.json` is missing from the chapter.
|
|
248
|
+
- An `assets` category can be `reference: true`, for material that follows the guidelines but is kept for comparison, or was supplied by someone else, such as card faces extracted from the guidelines or a favicon set a third party sent. Like an experimental category it does not gate the book (no `review-pending`, `asset-review-missing` or `page-review-pending`), but the brand book labels it "Reference" and lists it on the Review page, and the brand deck leaves it out. A category cannot be both `experimental` and `reference`. It is in `brand.json` as `categories[].reference`. RFC 0001 section 11.
|
|
249
|
+
- The shipped plugin `blazon.copy` holds a brand book's text to the brand's copy rules, as a `check` plugin: terms the brand avoids, title-case headings and sentences over a length it sets. It reads `brand.json` and needs only Node. A group of terms can be scoped to pages and assets (`only`, `skip`, with a trailing `*` as a prefix), headings can have a word limit and their own scope (`headings: { maxWords, only, skip }`), a term ending in `*` is a stem that finds every form of a word, `ignoreQuoted` leaves quoted text out of the search, and Cyrillic text is split into sentences. Ten plugins now ship. The starter enables it with blazon's own rules (`blazon.json`, with the deck and the social cards still commented out), and two long sentences on the starter's logo page were split to meet its 25-word limit. Design: RFC 0006.
|
|
250
|
+
- The starter has a voice and tone page, `docs/11-voice.md`, declared as the custom section `voice` in its `blazon.json`: the voice as four traits, the tone for each place blazon writes, word choices, formatting and a checklist before publishing. It is blazon's own voice, to be replaced with the brand's. `voice` is not a standard section: neither the Auth0 deck nor the Slack guidelines has one.
|
|
251
|
+
- The README is a landing page: a screenshot, a rule that fails the build, a diagram of how blazon works and links to the manual for the reference.
|
|
252
|
+
- The shipped plugin `blazon.logo-geometry` replaces `scripts/logo-geometry.py`, which is removed. It measures each logo's symmetry, balance and grid, fails the build for an axis the options `require` and a logo lacks, and draws the construction figure, with the same numbers and the same figure bytes as the script on the example logos. It needs no `uv` and no Pillow: Node reads an SVG, and a Chrome reads a PNG or WebP. It also reads what the script refused, `transform` and arcs and rounded rectangles, and it names what it still does not read (live text, `<use>`, strokes, a `<style>` element). `--crop`, `--grid`, `--require` and `--tolerance` are the options `crop` (per logo), `grid`, `require` and `tolerance`.
|
|
253
|
+
|
|
254
|
+
- A plugin pin mismatch names the files that changed: `pin mismatch: …; modified lib/data, added lib/new; review the change and pin it again`. The lock now keeps a `files` list for a directory pin, the lines the `t1:` digest is the hash of, and refuses a list that does not hash to the digest. A lock without the list still works, and `t1:` is unchanged. Run `blazon plugin pin <path> --name <name>` again to add the list to an existing pin.
|
|
255
|
+
- `--json` on `blazon approvals` (the list with each fingerprint and state), `blazon pin` (the commit and the file) and `blazon plugin check` (each case with `ok`, `skip` or `fail`). `blazon plugin pin` and `blazon plugin profile` refuse `--json`: they print a digest and JSON already.
|
|
256
|
+
|
|
257
|
+
- `blazon help` and `blazon help <command>` print the same help as `--help` and `<command> --help`.
|
|
258
|
+
|
|
259
|
+
- Every color written as text is a badge in that color, in the book's pages and in the text blazon prints itself. A hex or `rgb()` code inside an inline code span is now a badge too: a span that is only a color becomes the badge, and in a span with more in it each color becomes one and the rest stays code. An asset's description, traits and do and don't lines, and a token's value, are badged the same way. Code blocks and links still show a color as written.
|
|
260
|
+
- A `build` plugin's request has `tokens_dir`: the folder with the token files that `blazon build` has written before the plugin runs. A plugin that works from the exported tokens reads them there, instead of from a sibling folder nothing promised. A plugin ignores a request field it does not know, so no plugin breaks.
|
|
261
|
+
|
|
262
|
+
- `blazon tokens --json` prints the findings as JSON, as `check` and `build` do, and `blazon init --json` prints what it made (`dir`, `created`, `kept`) and never asks.
|
|
263
|
+
|
|
264
|
+
- `blazon dev` says in its terminal each error the brand has as files change: the file and line, the code, the message and what to do, once for each error, and a line when they are fixed. It said nothing while the book was broken, and the errors showed only in the browser. Warnings and notes stay in the viewer.
|
|
265
|
+
|
|
266
|
+
- A book with no tokens in it is the warning `tokens-missing` ("the tokens folder holds no tokens"), where `blazon check` used to pass it with a note. It fails with `--strict`.
|
|
267
|
+
- `blazon pin` on a folder that is not there says so in one line and exits 2, and so does `blazon plugin pin` on a path with nothing at it; both used to print a raw system error and exit 1. An empty folder name (`blazon check ''`) and an empty value for `-p` are refused with exit 2, where the first used the current folder and the second said the port was 0. The help no longer shows `--no-plugins` as on by default, `--color` says it takes hex with or without the `#`, and a wrong `platforms` option of `blazon.platform-tokens` names the value that is wrong.
|
|
268
|
+
|
|
269
|
+
- The brand book's viewer has a documentation-site layout: a top bar across the window (logo, breadcrumb, search, contexts, light and dark switch), a sidebar that is open from 1024 px and a drawer below it, groups that open and close and are remembered per reader with **Expand all** and **Collapse all**, a short page header unless the page says `opener: full`, and an "On this page" list on a page with four or more sections. The icon-only sidebar and Cmd+B are gone. A resolver `theme` modifier with `light` and `dark` contexts is now driven by the light and dark switch, and dark mode is painted from that context's `background` and `text` roles, not from `inverse`. The print book is unchanged: no index, and the full cover on every chapter.
|
|
270
|
+
|
|
271
|
+
- `blazon:email-signature` places a form that makes a person's email signature: name, position, phone and email, then the logo and the fixed lines from the new `emailSignature` config block. The HTML is a table with inline styles that mail apps keep, every field is escaped, and an address outside `domains`, or with anything but letters, digits and `. _ + ' -` before the `@`, is refused. It copies as formatted text or downloads as an HTML file. The form's preview shows the book's own `logo` while the signature it copies still loads `logoUrl` (a mail app draws the logo from an address when the email is opened); the page says so, explains why in a short note, and warns when `logoUrl` does not load.
|
|
272
|
+
- `review` takes `by`, `at` and `value`: who confirmed the item, when, and a fingerprint of its resolved value (of the file bytes, for an asset). Tokens, token groups and assets can carry it.
|
|
273
|
+
- `approval-stale` warns when an approved item's value no longer matches its recorded `value`, and names who approved it and when. An approval with no `value` never warns.
|
|
274
|
+
- The `review.value` fingerprint is specified in RFC 0001: the canonical form, the hash and seven test vectors that a test holds the code to.
|
|
275
|
+
- `brand.json` has a top-level `generator` (`name`, and the blazon `commit` and `dirty` flag when blazon can say them). It has no date or host, so the file stays the same for the same inputs.
|
|
276
|
+
- `blazon approvals` lists the approved tokens and assets with the fingerprint of their value today, to record in `review.value`.
|
|
277
|
+
- The Review page has an Approved section: every item marked `review: ok`, with who approved it, when, and the note. An approval whose value changed is marked and listed first.
|
|
278
|
+
- An `assets` category can be `experimental: true`, for explorations that are part of the book but not the identity. Its assets are labelled "Experiment" wherever a page draws them, listed in an Experiments section of the Review page and carried in `brand.json`, and they do not raise `review-pending`, `page-review-pending` or `asset-review-missing`, so they no longer stop `--strict` from passing. The brand deck leaves them out.
|
|
279
|
+
- `blazon init` writes blazon's own brand book (`examples/blazon/`) as the starter, and its colour, font, `--from` and logo answers write blazon's token names (`color.signal.primary`, `interactive.primary`, `text.*`, `surface.*`, `font.family.*`). The starter is no longer a second copy: `npm run build-starter`, run by `prepack`, builds the package's `template/` from the example. The `--ramp` option and the 50 to 950 ramp generator are gone, with the `brand.*` tokens and `gradient.brand`. A new book starts with blazon's identity and a `starter-file-unchanged` note on each file still unedited.
|
|
280
|
+
- `dev.blazon.font` holds a font token's `source`, `license` and `licenseUrl`. It is checked (`font-meta-invalid`), shown on the Typography page and printed by `blazon.press-kit`. A `license` that looks like an SPDX identifier but is not on the SPDX list gets a `font-license-unknown` note (info, so `--strict` still passes); a license written as a name is left alone.
|
|
281
|
+
- A logo sidecar takes `initiative`, a program the brand runs. `blazon:logo-initiative` draws the program lockup, and `blazon.logo-kit` exports it.
|
|
282
|
+
- `blazon pin` writes `blazon.lock`, naming the commit of the blazon that runs it. `check`, `tokens` and `build` refuse another blazon (`pin-mismatch`, or `pin-invalid` for a broken file). A book with no `blazon.lock` is not checked.
|
|
283
|
+
- `blazon.social-cards` bounds its findings to 60,000 bytes, so a brand with many invalid cards no longer turns its result into `plugin-failed` by overflowing the 64 KB a build call may print: the first findings that fit, errors first, then one `findings-left-out` warning that says how many are not shown. `blazon.social-cards` and `blazon.brand-deck` launch Chrome through the shared launcher; nothing changes for the user.
|
|
284
|
+
- The manual says what to do when a pinned plugin's `#!/usr/bin/env node` is refused: `node` from Homebrew or a version manager is a link, `BLAZON_PLUGIN_PATH` must name the folder of the real file, and the shipped plugins are not affected because they run on blazon's own `node`.
|
|
285
|
+
- `blazon.office-template` takes an alias as an accent: `accents: ["chart.mix.2"]` resolves to the color its token resolves to, as `blazon.favicons` already did. It was `option-invalid` because the lookup held only tokens that are not aliases; the plugin's own pick of other colors still leaves aliases out.
|
|
286
|
+
- Every shipped plugin that answers through the shared entry (`blazon.favicons`, `blazon.press-kit`, `blazon.logo-kit`, `blazon.office-template`, `blazon.platform-tokens`, `blazon.print-book`) bounds its findings to 60,000 bytes, as `blazon.social-cards` does: errors first, then warnings, then notes, and one `<plugin>/findings-left-out` warning with the count. Before, a result with many findings could pass the 64 KB a build call may print and become `plugin-failed`. The host cannot do this for a plugin, because it only sees the answer once it is printed; a plugin of your own has to bound its findings itself.
|
|
287
|
+
- `blazon check`, `blazon tokens` and `blazon build` take `--no-plugins`: no plugin runs, whatever the config lists, so the tokens can be built where there is no browser. It cannot be combined with `--plugin`. A book that kept a second, plugin-free config for this can drop it.
|
|
288
|
+
- `blazon dev` and `blazon preview` use the `port` in `blazon.json` again. The `-p, --port` option carried a default of 3000, so a port passed on the command line always won, and the config's port was never read. Without `-p` the port is now the config's, else 3000; `-p` still wins.
|
|
289
|
+
- An unknown config key with no close match now says that it may belong to a newer blazon and that the book's blazon pin should move first; a key close to a real one still gets "did you mean". Chapter 15 gains the rule that a new blazon option needs the pin moved before the book uses it.
|
|
290
|
+
- `blazon dev` watches `blazon.lock` and shows the pin findings on the Review page, with no restart.
|
|
291
|
+
|
|
292
|
+
### Fixed
|
|
293
|
+
|
|
294
|
+
- `blazon dev` and `blazon preview` answer 404 on Vite's `/__open-in-editor?file=...` route. Vite registers it on every dev server with no switch to turn it off, and any web page that can reach localhost could make a running editor open a local path. The dev server also sets `server.fs.allow` to the viewer's own folder (`dist/ui` when installed, the checkout from source) with `strict` on, instead of Vite's workspace-root search: an installed blazon served its own package files (`package.json`, `bin/`, plugin programs) over `/@fs/`, and the search would reach a folder above it if blazon's `package.json` lost its `workspaces` field.
|
|
295
|
+
- `blazon dev` and `blazon build` read and served the SVGs of any folder through an icon set whose `package` was a path (`../../Downloads`). `package` must now be a package name (`name` or `@scope/name`); a path fails with `icon-set-invalid`. `blazon preview` followed a link in the built site (`dist/site/leak.txt -> ~/secret`) and served what it pointed at; it now answers 403 for a link that leaves the site.
|
|
296
|
+
|
|
297
|
+
- A resolver with an inline modifier or set that reuses the name of a declared set or modifier is a `resolver-invalid` error, not an uncaught TypeError.
|
|
298
|
+
- Modifier, context and inline item names in a resolver must be letters, digits, `_` and `-`, so a name can no longer become a path outside `tokensOutDir`, break a selector or close a CSS comment. `blazon tokens` also refuses to write a file outside `tokensOutDir`.
|
|
299
|
+
- Token and resolver JSON files that start with a UTF-8 byte order mark parse instead of reporting `token-file-invalid`.
|
|
300
|
+
- `theme.css` no longer lets `*/` in a deprecation message, group name or context name end a generated comment.
|
|
301
|
+
- A string `fontWeight` outside 1 to 1000 (`"0"`, `"1200"`) is an `token-value-invalid` finding, as a number already was.
|
|
302
|
+
- The MCP server passes each option as one argument (`--theme=dark`), so a value that starts with a dash, such as `--cwd=/other/dir`, can no longer be read as an option and change the brand folder; `can_use` `theme` and `list_tokens` `type` refuse such a value.
|
|
303
|
+
- The MCP server no longer passes `NODE_*` environment variables (such as `NODE_AUTH_TOKEN`) to blazon.
|
|
304
|
+
- The MCP server keeps at most 64 cached answers.
|
|
305
|
+
- `blazon plugin check` and `blazon plugin pin` with no program or path exit 2 with a `missing-argument` error, as JSON under `--json`; `blazon init --json` errors carry a `code`, and a site that cannot be read is `site-unreadable`.
|
|
306
|
+
- `blazon plugin` refuses `--name`, `--digest` and `--entry` unless the action is `pin`, and a target for `profile`, instead of ignoring them.
|
|
307
|
+
- `blazon build --out-dir 2024` (the kebab spelling) takes the number as a folder name instead of failing with a TypeError.
|
|
308
|
+
- `blazon dev` and `blazon preview` listen on this machine only; `--host [address]` opens them to the network. They listened on every interface before.
|
|
309
|
+
- The exit status help no longer says every exit 2 did nothing: `blazon init --from` copies the starter first.
|
|
310
|
+
- Two pages with one slug (`01-colors.md` and `colors.md`) are a `page-slug-duplicate` error naming both files; the book opened only the first, silently.
|
|
311
|
+
- A page or an asset that cannot be read is a `page-unreadable` or `asset-unreadable` error; it used to be written to the console, dropped, and `blazon check` passed (and `--json` output was polluted).
|
|
312
|
+
- A page's title is no longer taken from a `# comment` inside a code fence, and a bare `#` no longer reaches across a line break to the next line.
|
|
313
|
+
- `approval-stale` no longer fires for a token whose alias does not resolve or loops, and so no longer tells you to record the fingerprint of the broken `{...}` text; one unreadable token file used to bring one for every approved alias into it.
|
|
314
|
+
- `token-value-duplicate` compares tokens that sit at the root of a file as siblings; it cut the last letter off their names, so `ab` and `ac` were compared and `ab` and `cd` were not.
|
|
315
|
+
- `page-tokens-unplaced` no longer notes a page that places tokens with `cards`, `strokes`, `spots`, `logo-on`, `formats` or `patterns`; the exempt directives now come from the directive table.
|
|
316
|
+
- With a token file unreadable, the findings that a directive names a missing color, border, format or pattern are left out as well, not only "no token at".
|
|
317
|
+
- `blazon explain` lists what `contrast-pair-invalid`, `token-type-unknown`, `section-missing` and `token-file-invalid` point at as the code does: a group, a token or group, the project.
|
|
318
|
+
- A contrast pair measures a translucent foreground blended over its background, as WCAG does; `transparent` or `rgba(0,0,0,.05)` on white used to pass AAA. A translucent background gives `contrast-unknown`, as what is behind it is not known. A failing ratio is floored to two decimals, so 4.496 no longer prints as "4.50:1; AA needs 4.5:1".
|
|
319
|
+
- A plugin whose manifest call exits 1 or 2, or prints a manifest blazon cannot load, now counts toward the breaker (three in a row stop it for the run) and, for exit 1 and a bad manifest, starts the dev server's cooldown; before, it was reported every time and never stopped.
|
|
320
|
+
- `--plugin ./bin/blazon-acme.x.🔌` is accepted: the plugin's name is what lies between `blazon-` and the final `.🔌`.
|
|
321
|
+
- A plugin instance id that is a file blazon writes in `tokensOutDir` (`tokens.json`, `theme.css`, `tokens.<modifier>.<context>.json` and the rest) is refused as `config-invalid`; it would have replaced the file with a folder.
|
|
322
|
+
- A plugin's standard error is kept from its end (the last 8 KB), not its start, so the "last lines of standard error" a failed plugin shows are the last lines it wrote, and a secret that crossed byte 8192 is no longer cut before it is scrubbed.
|
|
323
|
+
- Scrubbing also removes a secret in lowercase percent-encoding, inside the base64 of a longer string (such as Basic auth, at any of the three alignments) and as a JSON string escape (`\uXXXX`, `\"`, Go's `<`).
|
|
324
|
+
- A plugin that runs out of time, or prints too much, is sent SIGTERM and killed 2 seconds later instead of at once, so one that started Chrome can close it.
|
|
325
|
+
- The manual no longer says `blazon plugin check --core` checks a plugin written for another host: the manifest is still read against blazon's roles, so a plugin that declares neither `check` nor `build` fails case 1.
|
|
326
|
+
- Plugin output is scrubbed of secrets after its control and format characters are removed, not before, so a secret split by a zero-width character or an escape byte no longer reaches a finding, an exit 2 message or the stderr tail; a finding whose code the scrubber would change is refused as a malformed answer.
|
|
327
|
+
- MCP truncation keeps the most findings that fit, not a power-of-two fraction of them (120 that fit used to come back as 62), counts the `warnings` it adds in that fit, and keeps `counts` and `passed` when it falls back to cutting the text. The fallback cuts on code points, not inside a surrogate pair.
|
|
328
|
+
- A plugin's finding message stays within 1000 characters with its ` (instance X)` suffix counted.
|
|
329
|
+
- Every error and warning finding code, and every note but `asset-local-missing`, has a fix line, and a test fails when an error or warning code has none.
|
|
330
|
+
- A plugin call that exits 2 counts as a break for the run breaker, as RFC 0002 section 7 now says, so a plugin that always exits 2 is stopped after three calls. The dev server's cooldown still takes exit 2 as a change to wait for, not a break.
|
|
331
|
+
|
|
332
|
+
- A `plugin-failed` finding gave one fix for every cause, "pin the plugin", which was wrong for a plugin that crashed or for blazon installed under a shared folder such as `/tmp`, where the manual said to run `chmod go-w` on the folder. Each cause now carries its own fix, in `--json`, `brand.json` (a new optional `fix` on a finding) and the "Next" list; for a shared folder it is to install blazon under your own home folder. A plugin that breaks now shows the last lines of its standard error in the message (`exited with 3; stderr: boom: cannot find thing`), at most 5 lines and 500 characters, with secrets taken out; a plugin that answered shows none.
|
|
333
|
+
- A program named with `--plugin` could take the id of an instance's `as`, and the two shared an output folder and a breaker, so one emptied the other's files. Ids are now checked across the config and `--plugin` together: the later one is refused with `plugin-failed`, which names both. An id taken from a plugin's name, with no `as`, is now held to the 64 characters an `as` is, and two different `--plugin` programs for one plugin are refused.
|
|
334
|
+
- The starter's key shadows read as a glow in the dark theme. `shadow.plate` and `shadow.shim` are now Carbon in `tokens/theme/dark.json` (they were Zinc), the one ink darker than the Graphite page, so a key stands on a shadow and not on a second edge. `shadow.recess` stays Zinc. Its Form and motion and Web pages say so.
|
|
335
|
+
- The starter's rules were near-white lines on the dark page. In `tokens/theme/dark.json` `rule.default` is now Zinc (it was Concrete): 5.14:1 on the Graphite page and 5.89:1 on the Carbon canvas, above the 3:1 a part's edge needs. `rule.quiet` is now Steel (it was Zinc), 2.30:1, for hairlines that carry no meaning alone. The focus outline no longer follows the rule: the starter's `shadcn.ring` is `text.primary`, 14.48:1 in dark and Graphite in light as before. Its Color, Layout and Web pages say so.
|
|
336
|
+
- The starter's primary key has an edge that shows on its fill in both themes. Its edge was `border.rule`, which the dark theme makes Concrete: 2.15:1 on Signal Orange, below the 3:1 a part's edge needs. Two tokens are new, `rule.onSignal` (Graphite in both themes) and `border.onSignal` (a 2px rule in it), so the starter gains two tokens. `blazon can rule.onSignal interactive.primary --role ui` reports 5.29:1, and the value is the same in dark. The key keeps the Zinc shadow of dark. Its Color, Form and motion and Web pages say so.
|
|
337
|
+
- A token file named in a resolver document that is not valid JSON is an `token-file-invalid` finding with its line, as without a resolver, and the other files still load. It was one `resolver-invalid` error that left the brand with no tokens, followed by an error for every directive and theme role. While a token file cannot be read, a page directive's `no token at` and a `token-type-missing` are left out with the other findings that only say a token is missing.
|
|
338
|
+
- `logo-contrast-insufficient` runs in every context and judges each surface by the text color the theme pairs with it, so a dark theme's dark page is checked with the dark-surface logo and its light inverse with the light-surface one, and a finding only that context has is tagged with it. The `blazon:logo-usage` figure follows the same rule: with the book's dark mode on a theme whose inverse is light, the light-surface logo stands on the inverse and the dark-surface logo on the page. Both used to put the light-surface logo on the background whatever its color, so a dark theme hid the logo.
|
|
339
|
+
- The brand book in the dark mode of a brand's own dark theme: the clear-space and minimum-size figures draw each logo on the surface of its darkness (the light inverse for a logo made for light backgrounds), and links are judged against the page the theme paints, not the inverse. The Graphite logo vanished on the Graphite page, and links were Graphite on Graphite.
|
|
340
|
+
- The starter maps the shadcn variables it left out: `destructive` is `text.primary` (the brand has no red) and `chart-1` to `chart-5` are `text.primary`, `text.muted`, `surface.canvas`, `rule.default` and `rule.quiet`, so `theme.shadcn.unsupplied` is empty for it. Its Web page and chapter 19 say so.
|
|
341
|
+
- Docs: chapter 19 covers widths written once, hex values outside CSS and the text styles for measure and labels, the checks sample counts match a real starter, and the manual lists the links that leave it.
|
|
342
|
+
- `starter-file-unchanged` also covers `fonts/`: a project that keeps the starter's IBM Plex Mono file and its `OFL.txt` gets a note for each, so a fresh `blazon init` project reports 41 notes (it was 39). A project with no `fonts/` folder gets none.
|
|
343
|
+
- The starter's wordmark logos (`blazon-graphite`, `blazon-bone`) state their minimum size in the sidecar (`minSize`, height 32px), where the Web page said it was not there. `minSize` was already a sidecar field; `blazon logo` and `brand.json` carry it. The mark alone has none in its sidecar, because the favicon check would warn on a 16px tab icon.
|
|
344
|
+
- The `blazon.logo-geometry` construction figure marks the box center with a hollow ring and the center of mass with the filled dot, and its caption names both (`center of mass (dot) -1.1% x, +1.1% y from the box center (ring)`), so a dot that sits off the crossing of the axes no longer reads as a misplaced mark.
|
|
345
|
+
- `theme.shadcn.pairs[].declared` and `blazon can` now agree: a pair written on a token that a shadcn token aliases counts for both (the starter's `primary` on `primary-foreground` said `declared: false` while `blazon can` allowed it).
|
|
346
|
+
- `blazon init` with `--from` or `--logo` also removes blazon's own mark (`assets/logos/blazon-mark`) when it replaces the starter's logo; it used to stay behind under the brand's name.
|
|
347
|
+
- `blazon init --from` no longer claims the colors, fonts and logo were read from the site when some were not: the intro page names what was read and what is still blazon's own starter, and the next steps say to add a logo when none was found. After a site that could not be read it prints no next steps, and says to start again in a new folder, since a folder that already has the starter is kept as it is.
|
|
348
|
+
- `blazon build` no longer deletes the brand's own files. An `outDir` that is or holds `tokensDir`, `docsDir`, `assetsDir`, a category's own folder, the resolver, a logo or a font file used to pass `blazon check` and then be emptied by the build. It is now an `output-dirs-overlap` error, and `buildSite` and `emitTokenOutputs` refuse it too, so calling them from code is as safe as the command. The token files a resolver names count as inputs wherever they are, and a path is compared by where it really is, so a symbolic link to an input, or a folder reached through one, is caught. An `outDir` or `tokensOutDir` inside an input folder is refused as well, because the next build would read the output as tokens, pages or assets.
|
|
349
|
+
- `blazon tokens` and `blazon build` no longer delete or overwrite a file the brand reads. A token file a resolver names that sat in `tokensOutDir` under a name like `tokens.mode.dark.json` was removed as a stale output of blazon's own; it is now left alone, and a source that has the name of a real output is an error before anything is written. An icon set's `categories` file and a build plugin's folder under `tokensOutDir` count as inputs for the `outDir` check too. What the dev server watches, what the output check protects and what the writers refuse to touch are now one list, `projectInputs` in `src/core/inputs.ts`.
|
|
350
|
+
- An icon set's package in `node_modules` is an input for the `outDir` check, and a build whose icon package is gone by the time its icons are copied stops with an error naming the set, where it used to report success and leave the icons out. A resolver source that is a symbolic link is held by the link as well as by its target, so an `outDir` that holds only the link is refused.
|
|
351
|
+
- A build plugin named only with `--plugin` can no longer have a file the brand reads deleted with its output folder. The plugin writer checks the folder before it empties it, as the output check does for the plugins in the config, and stops the plugin with a `plugin-failed` finding.
|
|
352
|
+
- A resolver context that points a token at another token holding the same value keeps the change: the context's `metadataChanges` carries it with the new `aliasOf`, and the brand book shows it. It was dropped because the CSS value did not change.
|
|
353
|
+
- In `blazon dev`, the result of a check that was running when a change replaced it can no longer arrive after the new page data and put the old findings and tokens back. This happened when the change switched the plugins off.
|
|
354
|
+
- A finding about a token from a resolver source named a file that does not exist (`tokens/tokens/base.json`) and gave no line. It now names the file as the project has it, with the line, or the resolver document for a source written inside it.
|
|
355
|
+
- Every token says which file it is in the same way, from the project root, whichever loader read it. A project with no resolver gave `colors.json` as a token's `sourceFile` in `brand.json` (the docs said `tokens/colors.json`), and a tokens folder that was not directly in the project, such as `brand/tokens`, showed `tokens/` in the path of an `token-file-invalid` finding. A source written inside a resolver document in a subfolder named only the document's file name.
|
|
356
|
+
- A context is put back together from the default and its changes in one place, `contextItems` in `src/core/tokens/contexts.ts`, which the token export and the brand book both use. Contexts are combined field by field, so choosing two modifiers that change one token in different ways (a value and a description) shows both, and the theme follows the tokens as shown. The brand book with a context chosen now shows that context's descriptions and deprecations too, and `brand.json` carries them as `metadataChanges` on the context (absent when there are none).
|
|
357
|
+
- A resolver context that changes only a token's description, deprecation, type or extension, and not its value, is kept in that context's `tokens.<modifier>.<context>.json`. It used to be dropped, so the file kept the default's text.
|
|
358
|
+
|
|
359
|
+
### Changed
|
|
360
|
+
|
|
361
|
+
- The config is plain JSON in `blazon.json`, and nothing else. It was code (`blazon.config.ts`, `.js`, `.mjs`, `brandbook.config.ts`, `brandbook.config.js`), run through Vite; it is now data a person can read and a tool can write, with no comments and no code. A folder that still has one of the old files stops with a `config-invalid` error that names the file and says to move its values into `blazon.json`. `defineConfig` and the `@iksnerd/blazon/config` entry are gone, the starter's config no longer holds commented-out plugins (`blazon init` leaves them out, and the manual says how to add one), and the `blazon.cue-rules` plugin takes its rules text in `options.rules`. RFC 0001 open question 7 is decided.
|
|
362
|
+
- Every finding code follows one rule, `<area>-<problem>` in kebab-case with the problem word from a fixed list, and 42 codes are renamed, such as `unresolved-alias` to `alias-unresolved` and `needs-review` to `review-pending`. Codes freeze at 1.0, and there is no alias: a script, approval or filter that names an old code now gets the unknown-code error. The old-to-new table is in the manual's [Checks](docs/manual/03-checks.md#how-codes-are-named) chapter.
|
|
363
|
+
- Releases are one command, `npm run release -- <version>`, and CI on the tag builds the package fresh, installs the tarball and runs blazon from it, then attaches it with `SHA256SUMS` and a build provenance attestation; a `publish` job is in `ci.yml` but stays off until `NPM_PUBLISH` is set. `npm pack` now builds first, the package no longer carries a `prepare` script (npm 12 warned every installer about it; contributors run `npm run hooks`), and `scripts/check-pack.mjs` fails a tarball that lacks `dist/`, the starter, a plugin program or the lock.
|
|
364
|
+
- The starter's `AGENTS.md`, its web page and `blazon init` no longer link a manual on a website, which does not exist yet. `AGENTS.md` names the `docs/manual/` folder of the blazon source repository and each chapter by title, and `init` no longer prints a `The manual:` line.
|
|
365
|
+
- The viewer build writes Geist's OFL license as `assets/geist-OFL.txt` beside the font files, so it is in `dist/ui` and in every built site. `THIRD-PARTY-NOTICES.md` names both starter IBM Plex Mono files, `jszip`, `lightningcss` and `pako`.
|
|
366
|
+
- A plugin that exits `2` ("cannot answer") three times in a row in one run is now stopped for the rest of that run, as a break is. In `blazon dev` exit `2` does not start the 30-second cooldown, since its message asks for a change the next save may make.
|
|
367
|
+
- The text output names places you can open and commands you can run from where you are. A finding with a file starts with `file:line` (`acme/tokens/colors.json:17 color.base.bone: ...`), as compilers print it, in `check`, `tokens` and `build`. `blazon init acme` and `blazon check acme` give their next steps as `blazon dev acme` and `acme/tokens/colors.json`, and `init --color` says the primary is set instead of asking for it. Every error is `blazon <command>: <what happened>` with the fix on its own line, replacing `[blazon <command> error]`, and `blazon drift` names a CSS file that is not there instead of printing `ENOENT`. `--json` is unchanged, except that `error.message` follows the new wording.
|
|
368
|
+
- `blazon dev` treats a burst of file events as one change: it waits 75 ms after the last event, then compiles once and sends one update. A `git checkout` of 24 files sent 24 updates, each from its own compile. A single save is sent 75 ms later than before.
|
|
369
|
+
- `blazon check` and `blazon tokens` on a folder that is not there say so without first printing their "Checking…" or "Compiling…" banner.
|
|
370
|
+
- An `token-file-invalid` finding has `file`, as the other findings with a position do, and a token file whose top level is not an object is reported under `tokens/<file>`, not the bare file name.
|
|
371
|
+
- `blazon drift` and `blazon init --from` say why a fetch failed (the refused connection, the name that does not resolve) after `fetch failed`.
|
|
372
|
+
- `--severity` without `--json` is refused (exit 2) instead of ignored: it cuts the list that `--json` prints.
|
|
373
|
+
- `blazon init --color <hex>` no longer makes every command print color codes into a pipe. The color library read any `--color` argument as a request for color; blazon now decides from the terminal, `NO_COLOR`, `TERM=dumb`, `--no-color` and `FORCE_COLOR`.
|
|
374
|
+
- `blazon check` refuses a dimension or duration that is not one (`"abc"`, `"12"`, `"4pixels"`; a bare `0`, a function such as `calc()` or `var()`, and a keyword such as `auto` still pass), and an `oklch()` or `oklab()` whose lightness is outside 0 to 1 or 0% to 100% (`oklch(60 0.2 250)` is white in CSS; 60% was meant). They passed without a word, so a brand with a wrong value reported as sound.
|
|
375
|
+
- A token file that does not parse no longer brings a screenful of errors with it. While any token file is unreadable, the findings that only say a token is missing (`alias-unresolved`, `theme-unresolved`, and the `token-value-invalid` for an alias that could not be followed) are left out; fixing the file brings back whichever are real.
|