@iksnerd/blazon 0.1.0 → 0.2.0

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 (73) hide show
  1. package/README.md +14 -19
  2. package/dist/chunks/{site-builder-vpzUWoiA.js → site-builder-BtGOvjBC.js} +1836 -2111
  3. package/dist/cli/commands/tokens.d.ts +4 -0
  4. package/dist/cli/commands/tokens.d.ts.map +1 -1
  5. package/dist/cli/handlers/brand.d.ts +1 -1
  6. package/dist/cli/handlers/index.d.ts +2 -2
  7. package/dist/cli/index.js +915 -941
  8. package/dist/core/brand/export.d.ts +2 -9
  9. package/dist/core/brand/export.d.ts.map +1 -1
  10. package/dist/core/brand/schema.d.ts +0 -58
  11. package/dist/core/brand/schema.d.ts.map +1 -1
  12. package/dist/core/brand-theme.d.ts +0 -2
  13. package/dist/core/brand-theme.d.ts.map +1 -1
  14. package/dist/core/checker/catalogue.d.ts +18 -2
  15. package/dist/core/checker/catalogue.d.ts.map +1 -1
  16. package/dist/core/checker/contrast.d.ts +1 -1
  17. package/dist/core/checker/variables.d.ts +2 -2
  18. package/dist/core/checker/variables.d.ts.map +1 -1
  19. package/dist/core/config/removed-keys.d.ts +6 -0
  20. package/dist/core/config/removed-keys.d.ts.map +1 -0
  21. package/dist/core/config/validate.d.ts +1 -1
  22. package/dist/core/config/validate.d.ts.map +1 -1
  23. package/dist/core/docs/directives.d.ts +9 -0
  24. package/dist/core/docs/directives.d.ts.map +1 -1
  25. package/dist/core/docs/parser.d.ts.map +1 -1
  26. package/dist/core/emit.d.ts +1 -3
  27. package/dist/core/emit.d.ts.map +1 -1
  28. package/dist/core/index.d.ts.map +1 -1
  29. package/dist/core/operations/list.d.ts.map +1 -1
  30. package/dist/core/plugin-name.d.ts +1 -1
  31. package/dist/core/read/token.d.ts +1 -6
  32. package/dist/core/read/token.d.ts.map +1 -1
  33. package/dist/core/tokens/walk.d.ts.map +1 -1
  34. package/dist/index.js +33 -33
  35. package/dist/plugins/roles/integrate.d.ts +5 -2
  36. package/dist/plugins/roles/integrate.d.ts.map +1 -1
  37. package/dist/plugins/roles/roles.d.ts +9 -2
  38. package/dist/plugins/roles/roles.d.ts.map +1 -1
  39. package/dist/plugins/wire/profile.d.ts +5 -0
  40. package/dist/plugins/wire/profile.d.ts.map +1 -1
  41. package/dist/types/config.d.ts +1 -3
  42. package/dist/types/config.d.ts.map +1 -1
  43. package/dist/types/theme.d.ts +0 -3
  44. package/dist/types/theme.d.ts.map +1 -1
  45. package/dist/ui/assets/{index-BdbihVvH.js → index-CLKH0m9J.js} +45 -47
  46. package/dist/ui/index.html +1 -1
  47. package/package.json +1 -1
  48. package/plugins/blazon.brand-deck/bin/blazon-blazon.brand-deck./360/237/224/214 +24 -2
  49. package/plugins/blazon.copy/bin/blazon-blazon.copy./360/237/224/214 +25 -3
  50. package/plugins/blazon.favicons/bin/blazon-blazon.favicons./360/237/224/214 +26 -3
  51. package/plugins/blazon.logo-geometry/bin/blazon-blazon.logo-geometry./360/237/224/214 +37 -8
  52. package/plugins/blazon.logo-kit/bin/blazon-blazon.logo-kit./360/237/224/214 +37 -8
  53. package/plugins/blazon.office-template/bin/blazon-blazon.office-template./360/237/224/214 +37 -8
  54. package/plugins/blazon.platform-tokens/bin/blazon-blazon.platform-tokens./360/237/224/214 +37 -9
  55. package/plugins/blazon.press-kit/bin/blazon-blazon.press-kit./360/237/224/214 +37 -8
  56. package/plugins/blazon.print-book/README.md +3 -1
  57. package/plugins/blazon.print-book/bin/blazon-blazon.print-book./360/237/224/214 +43 -8
  58. package/plugins/blazon.shadcn/README.md +27 -0
  59. package/plugins/blazon.shadcn/bin/blazon-blazon.shadcn./360/237/224/214 +8273 -0
  60. package/plugins/blazon.shadcn/package.json +3 -0
  61. package/plugins/blazon.social-cards/bin/blazon-blazon.social-cards./360/237/224/214 +37 -8
  62. package/plugins/blazon.tailwind/README.md +23 -0
  63. package/plugins/blazon.tailwind/bin/blazon-blazon.tailwind./360/237/224/214 +420 -0
  64. package/plugins/blazon.tailwind/package.json +3 -0
  65. package/plugins/shipped.lock +24 -10
  66. package/template/AGENTS.md +1 -1
  67. package/template/blazon.json +0 -10
  68. package/template/docs/01-principles.md +1 -1
  69. package/template/docs/12-web.md +2 -2
  70. package/dist/core/tokens/formatters/tailwind.d.ts +0 -37
  71. package/dist/core/tokens/formatters/tailwind.d.ts.map +0 -1
  72. package/dist/core/tokens/shadcn.d.ts +0 -43
  73. package/dist/core/tokens/shadcn.d.ts.map +0 -1
package/README.md CHANGED
@@ -10,26 +10,21 @@ Design tokens, guidelines and brand assets in one repo, compiled into CSS, TypeS
10
10
 
11
11
  Brand guidelines usually live in a PDF or a slide deck, and the values developers need are copied out of it by hand. Blazon keeps them in the repo as [DTCG](https://www.designtokens.org/TR/2025.10/format/) (Design Tokens Community Group) token files and Markdown. One build writes the CSS variables, a typed TypeScript module and a static brand book, and `blazon check` fails the build when a token breaks the brand's own rules. It reads the same DTCG files as Style Dictionary and Tokens Studio, and adds the rules, the checks and the book.
12
12
 
13
- > **Status: pre-release (0.1.0).** Not published to npm yet. The package is named `@iksnerd/blazon`. The npm package named `blazon` is an unrelated project (a type checker), so `npx blazon` does not run this tool and must not be used to try it.
14
- >
15
- > Once published, run it with `npx @iksnerd/blazon`, or install it in a project and run `npx --no-install blazon` or `./node_modules/.bin/blazon`. The name can still change before the first publish.
13
+ > **Status: pre-release (0.1.0), on npm as `@iksnerd/blazon`.** It is 0.x, so a minor version may break ([versioning](#versioning-and-stability)). The npm package named `blazon` is an unrelated project (a type checker): `npx blazon` in a folder where `@iksnerd/blazon` is not installed runs that one, not this tool. Run it with `npx @iksnerd/blazon <command>`, or install it and run `npx blazon` (the installed program wins) or `./node_modules/.bin/blazon`.
16
14
 
17
15
  Jump to: [Quick start](#quick-start), [Set up with your agent](#set-up-with-your-agent), [Use blazon from your agent (MCP)](#use-blazon-from-your-agent-mcp), [When not to use blazon](#when-not-to-use-blazon), [How it works](#how-it-works), [Plugins](#plugins), [Commands](#commands), [Configuration](#configuration), [Versioning and stability](#versioning-and-stability), [Security](#security), [Documentation](#documentation), [Contributing](#contributing).
18
16
 
19
17
  ## Quick start
20
18
 
21
- Node 24 or later; macOS and Linux, and WSL on Windows is untried. Blazon is not published, so clone it, build it once and run it from the clone:
19
+ Node 24 or later; macOS and Linux, and WSL on Windows is untried. Install blazon in the folder that holds your brand, then run it:
22
20
 
23
21
  ```bash
24
- git clone https://github.com/iksnerd/blazon.git
25
- cd blazon
26
- npm ci
27
- npm run build # builds dist/, which bin/blazon.js runs
28
- node bin/blazon.js init my-brand
29
- node bin/blazon.js dev my-brand # the book, with live reload, at http://localhost:3000
22
+ npm install @iksnerd/blazon
23
+ npx blazon init my-brand
24
+ npx blazon dev my-brand # the book, with live reload, at http://localhost:3000
30
25
  ```
31
26
 
32
- There is no `blazon` on your PATH until you run `npm link` in the clone. The rest of this README writes `blazon`; without the link, write `node bin/blazon.js` in its place.
27
+ After the install, `npx blazon` runs the installed program. Without an install, write `npx @iksnerd/blazon` in its place, because `npx blazon` alone runs an unrelated package. The rest of this README writes `blazon` for either. To work on blazon itself from a clone, see [CONTRIBUTING](CONTRIBUTING.md#local-setup).
33
28
 
34
29
  `blazon init` copies blazon's own brand book, [`examples/blazon/`](examples/blazon/), into the folder:
35
30
 
@@ -46,15 +41,15 @@ my-brand/
46
41
 
47
42
  The book starts as blazon's brand and becomes yours as you replace it. `blazon check` notes every file that is still the starter's text, which is the list of what is left to do, and warns about each logo that is still blazon's own. To start from a company's site instead, run `blazon init acme-brand --from https://acme.com`: blazon reads the page and its stylesheets for colors, fonts and the logo, and flags each value `needs-review` until the brand owner confirms it ([how](docs/manual/01-getting-started.md#starting-from-a-live-site)).
48
43
 
49
- To look at a finished book first, run blazon's own brand book from the clone with no build: `npm run dev:blazon`.
44
+ To look at a finished book first, clone the repository and run blazon's own brand book with no build: `npm run dev:blazon` ([CONTRIBUTING](CONTRIBUTING.md#local-setup)).
50
45
 
51
46
  ## Set up with your agent
52
47
 
53
- Paste this into a coding agent (Claude Code, Codex, Cursor) in the folder where the brand should live. Replace `<path to your blazon clone>`, and give the agent your colors, fonts and logo, or a site address. Blazon is not published; once it is, the first line becomes the package install.
48
+ Paste this into a coding agent (Claude Code, Codex, Cursor) in the folder where the brand should live. Give the agent your colors, fonts and logo, or a site address.
54
49
 
55
50
  ```text
56
- Set up a blazon brand book here. Blazon is not on npm: build it from my clone at <path to your blazon clone>
57
- with `npm install && npm run build` there, then run it as `node <that path>/bin/blazon.js`.
51
+ Set up a blazon brand book here. Install it with `npm install @iksnerd/blazon` (never run `npx blazon`
52
+ before that: the npm package named `blazon` is an unrelated project), then run it as `npx blazon`.
58
53
  Run `blazon init brand` (add `--from <site url>` to read a site's colors, fonts and logo).
59
54
  Read brand/AGENTS.md and follow it. Replace the starter's tokens, docs and assets with my brand:
60
55
  <my colors, fonts and logo, or the site address>. Ask me for any color, font or license you
@@ -99,8 +94,8 @@ The same token is written as `--color-signal-orange: #FF5A1F;` in `theme.css` an
99
94
 
100
95
  ## When not to use blazon
101
96
 
102
- - **You need a release you can install.** Blazon is pre-release and not on npm; you build it from a clone.
103
- - **You need many output formats.** Blazon writes CSS, Tailwind v4, TypeScript and JSON, and the platform plugin writes Android, Swift and Kotlin for colors and dimensions only. [Style Dictionary](https://styledictionary.com) has a general system of custom transforms and formats.
97
+ - **You need a stable interface.** Blazon is 0.x: a minor version may break a stable surface, and the CHANGELOG lists it under "Breaking". Pin the version you build with ([chapter 15](docs/manual/15-maintaining-a-brand-book.md#pin-the-blazon-you-build-with)).
98
+ - **You need many output formats.** Blazon writes CSS, TypeScript and JSON, the Tailwind and shadcn/ui plugins write a Tailwind v4 theme and the shadcn/ui variables, and the platform plugin writes Android, Swift and Kotlin for colors and dimensions only. [Style Dictionary](https://styledictionary.com) has a general system of custom transforms and formats.
104
99
  - **You want rules enforced in a design tool.** Blazon reads token files in the repo and does not sync with Figma or Tokens Studio. A file exported from them works if it is DTCG 2025.10, but the `usage` roles and `tier` names are blazon's, so the editor will not enforce them.
105
100
  - **You are on Windows.** It is tested on macOS and Linux with Node 24; WSL is untried.
106
101
 
@@ -127,7 +122,7 @@ The same compile feeds the dev server, so a change to a token, a page or the con
127
122
  - **Holds the brand's rules, not only its values.** `$extensions["dev.blazon"]` carries where a token may be used, its role and tier, print specs (CMYK, PMS, RAL), contrast pairs, forbidden logo backgrounds and proportions.
128
123
  - **Varies them by context.** A [DTCG resolver document](https://www.designtokens.org/TR/2025.10/resolver/) declares modifiers such as `locale` or `theme`. Each context compiles to its own CSS block holding only what it changes, and the book gets a switcher. [Contexts](docs/manual/04-contexts.md)
129
124
  - **Checks them.** Bad aliases and types, a token used where its source denies it, contrast below its level, duplicate values, values still marked for review, malformed asset sidecars, page directives that name nothing, and more. [Every finding](docs/manual/03-checks.md)
130
- - **Writes code.** `theme.css`, `typography.css`, a Tailwind v4 `tailwind.css` with an optional `tailwind-reset.css` that closes Tailwind's defaults, a typed `tokens.ts` and a `tokens.json` with aliases resolved. [Using the outputs](docs/manual/08-using-the-outputs.md)
125
+ - **Writes code.** `theme.css`, `typography.css`, a typed `tokens.ts` and a `tokens.json` with aliases resolved. [Using the outputs](docs/manual/08-using-the-outputs.md)
131
126
  - **Exports the whole brand.** `blazon build` also writes `brand.json`: the tokens with their rules, the pages, the assets and the findings, in one versioned file with a JSON Schema, readable from any language. [`brand.json`](docs/manual/11-brand-json.md)
132
127
  - **Builds a brand book that wears the brand.** The viewer takes its colors, typefaces and logo from your tokens. Pages place live content from them: swatches, the type scale, the logo on each background with its clear space, icons, patterns and social formats. It has search, a dark mode, and a Review page listing what `blazon check` found. [Pages](docs/manual/05-pages.md), [assets and icons](docs/manual/06-assets-and-icons.md)
133
128
  - **Compares them with a live site.** `blazon drift <url-or-css-file>` reports which tokens that name a `source.cssVar` have changed since.
@@ -136,7 +131,7 @@ The same compile feeds the dev server, so a change to a token, a page or the con
136
131
 
137
132
  ## Plugins
138
133
 
139
- A plugin is a program, in any language, that blazon runs for a check or a build step. Blazon ships ten, so there is nothing to install: name one in `blazon.json` and run `blazon build`. A plugin starts with an empty environment and gets only the variables its manifest lists and you approve in its entry's `env`. The ones that draw in Chrome list `BLAZON_CHROME`, `HOME` and `TMPDIR`:
134
+ A plugin is a program, in any language, that blazon runs for a check or a build step. Blazon ships twelve, so there is nothing to install: name one in `blazon.json` and run `blazon build`. A plugin starts with an empty environment and gets only the variables its manifest lists and you approve in its entry's `env`. The ones that draw in Chrome list `BLAZON_CHROME`, `HOME` and `TMPDIR`:
140
135
 
141
136
  ```json
142
137
  {