@iksnerd/blazon 0.2.2 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/README.md +7 -6
  2. package/dist/chunks/{site-builder-CsBH_ocA.js → site-builder-NRN9UNyn.js} +2490 -2406
  3. package/dist/cli/commands/mcp-check.d.ts +3 -1
  4. package/dist/cli/commands/mcp-check.d.ts.map +1 -1
  5. package/dist/cli/commands/mcp.d.ts +2 -1
  6. package/dist/cli/commands/mcp.d.ts.map +1 -1
  7. package/dist/cli/index.js +1153 -1126
  8. package/dist/core/brand/export.d.ts +3 -1
  9. package/dist/core/brand/export.d.ts.map +1 -1
  10. package/dist/core/brand/schema.d.ts +21 -0
  11. package/dist/core/brand/schema.d.ts.map +1 -1
  12. package/dist/core/checker/catalogue.d.ts +8 -0
  13. package/dist/core/checker/catalogue.d.ts.map +1 -1
  14. package/dist/core/fonts.d.ts +10 -1
  15. package/dist/core/fonts.d.ts.map +1 -1
  16. package/dist/core/index.d.ts.map +1 -1
  17. package/dist/core/inputs.d.ts.map +1 -1
  18. package/dist/core/mcp-config.d.ts +12 -6
  19. package/dist/core/mcp-config.d.ts.map +1 -1
  20. package/dist/core/operations/list.d.ts.map +1 -1
  21. package/dist/index.js +32 -32
  22. package/dist/types/data.d.ts +10 -0
  23. package/dist/types/data.d.ts.map +1 -1
  24. package/dist/ui/assets/index-Biy1hkeq.css +2 -0
  25. package/dist/ui/assets/{index-CLKH0m9J.js → index-BpdgjM9E.js} +7 -0
  26. package/dist/ui/index.html +2 -2
  27. package/mcp/dist/index.js +22748 -0
  28. package/package.json +7 -4
  29. package/plugins/blazon.office-template/bin/blazon-blazon.office-template./360/237/224/214 +1 -1
  30. package/plugins/blazon.platform-tokens/README.md +58 -2
  31. package/plugins/blazon.platform-tokens/bin/blazon-blazon.platform-tokens./360/237/224/214 +57 -12
  32. package/plugins/blazon.press-kit/README.md +54 -3
  33. package/plugins/blazon.press-kit/bin/blazon-blazon.press-kit./360/237/224/214 +247 -49
  34. package/plugins/blazon.print-book/README.md +6 -0
  35. package/plugins/shipped.lock +4 -4
  36. package/template/AGENTS.md +1 -1
  37. package/template/docs/01-principles.md +1 -1
  38. package/dist/ui/assets/index-DluSqfla.css +0 -2
package/package.json CHANGED
@@ -1,10 +1,11 @@
1
1
  {
2
2
  "name": "@iksnerd/blazon",
3
- "version": "0.2.2",
3
+ "version": "0.3.2",
4
4
  "description": "Brand book and design token compiler: DTCG tokens, brand rules checked by blazon check, a static brand book that wears the brand",
5
5
  "type": "module",
6
6
  "bin": {
7
- "blazon": "./bin/blazon.js"
7
+ "blazon": "./bin/blazon.js",
8
+ "blazon-mcp": "./mcp/dist/index.js"
8
9
  },
9
10
  "main": "./dist/index.js",
10
11
  "module": "./dist/index.js",
@@ -23,6 +24,7 @@
23
24
  "files": [
24
25
  "dist",
25
26
  "bin",
27
+ "mcp/dist/index.js",
26
28
  "plugins",
27
29
  "template",
28
30
  "THIRD-PARTY-NOTICES.md"
@@ -32,13 +34,14 @@
32
34
  ],
33
35
  "scripts": {
34
36
  "dev": "vite build --watch",
35
- "build": "vite build && vite build -c vite.viewer.config.ts && npm run build:plugins",
37
+ "build": "vite build && vite build -c vite.viewer.config.ts && npm run build:plugins && npm run build:mcp",
38
+ "build:mcp": "node scripts/build-mcp.mjs",
36
39
  "build:plugins": "tsx scripts/build-plugins.mjs && tsx scripts/shipped-lock.mjs",
37
40
  "test": "vitest run",
38
41
  "test:related": "vitest related --run",
39
42
  "test:files": "vitest run",
40
43
  "test:deck": "vitest run test/deck/brand-deck-plan test/deck/brand-deck-fonts.test.ts test/deck/brand-deck-examples.test.ts test/deck/examples-deck.test.ts test/plugins/shipped/brand-deck test/brand/brand-python.test.ts",
41
- "test:docs": "vitest run test/docs/manual.test.ts test/docs/rfc.test.ts test/docs/checks-generated.test.ts",
44
+ "test:docs": "vitest run test/docs/manual.test.ts test/docs/rfc.test.ts test/docs/checks-generated.test.ts test/docs/versions.test.ts",
42
45
  "conformance:reads": "rm -f reads.json reads.json.lines && CONFORMANCE_READS=reads.json vitest run test/plugins/host && tsx scripts/conformance-reads.ts reads.json",
43
46
  "test:watch": "vitest",
44
47
  "typecheck": "node node_modules/typescript7/bin/tsc --noEmit && node scripts/typecheck-mcp.mjs",
@@ -311,7 +311,7 @@ var GENERIC = /* @__PURE__ */ new Set([
311
311
  ]);
312
312
  /** The families of a CSS font stack, unquoted, in order */
313
313
  function families(stack) {
314
- return [...stack.matchAll(/"([^"]+)"|'([^']+)'|([^,]+)/g)].map((match) => (match[1] ?? match[2] ?? match[3]).trim()).filter((name) => name !== "");
314
+ return [...stack.matchAll(/\s*"([^"]+)"|\s*'([^']+)'|([^,]+)/g)].map((match) => (match[1] ?? match[2] ?? match[3]).trim()).filter((name) => name !== "");
315
315
  }
316
316
  /** The first family of the stack that names a font: not a generic, not a var(). */
317
317
  var fontOf = (stack) => stack ? families(stack).find((name) => !GENERIC.has(name.toLowerCase()) && !/[()]/.test(name)) : void 0;
@@ -11,12 +11,68 @@ The source is `src/shipped/platform-tokens/`, and `npm run build` (`npm run buil
11
11
  | `android/values/colors.xml` | `<color name="color_brand_primary">`, `#RRGGBB` or `#AARRGGBB` |
12
12
  | `android/values-night/colors.xml` | The colors the dark context changes |
13
13
  | `android/values/dimens.xml` | `<dimen>` in dp: a px is 1 dp, a rem is 16 |
14
- | `ios/BlazonTokens.swift` | `public enum BlazonColors` (SwiftUI `Color`) and `BlazonDimensions` (`CGFloat`); a color the dark context changes follows the system appearance |
14
+ | `ios/BlazonTokens.swift` (`ios/<Prefix>Tokens.swift` with a `prefix`) | `public enum BlazonColors` (SwiftUI `Color`) and `BlazonDimensions` (`CGFloat`); a color the dark context changes follows the system appearance |
15
15
  | `ios/Colors.xcassets` | A colorset for each color, with a dark appearance where the dark context changes it |
16
16
  | `compose/Colors.kt`, `compose/Dimens.kt` | `BlazonColors`, `BlazonDarkColors` (every color, dark where the dark context sets one, so the whole object can be swapped) and `BlazonDimens` (`Dp`) |
17
17
 
18
- Only `color` and `dimension` tokens are written; any other type is named once in a `tokens-skipped` finding. A token's value is its resolved value, so an alias is written with the value it points at and keeps its own name. Colors are converted to sRGB with colorjs.io, with alpha kept.
18
+ `color` and `dimension` tokens are written, and from a `border` token its width, as a dimension named `<token path>.width` (`border.rule` is `border.rule.width`: `border_rule_width` on Android, `borderRuleWidth` in Swift and Kotlin). The border's colour is not written (it is a colour token or a hex in the composite) and its style is not carried: a style other than `solid` gets one `border-style-dropped` info finding for the token. A width that is not in px or rem is a `dimension-unreadable` warning and the token is left out. `include` and `exclude` match the border token's own path (`border.rule`), not `.width`. Any other type is named once in a `tokens-skipped` finding. That leaves out typography, fontFamily, fontWeight, shadow, gradient, duration, cubicBezier, transition and number tokens. A token's value is its resolved value, so an alias is written with the value it points at and keeps its own name. Colors are converted to sRGB with colorjs.io, with alpha kept.
19
19
 
20
20
  ## Checked with the platform tools
21
21
 
22
22
  The Swift file type-checks with `swiftc -typecheck` for macOS 10.15 and iOS 13, and the asset catalog compiles with `actool`. Kotlin is not compiled; it is written against the Compose `Color(Long)` and `Dp` API.
23
+
24
+ ## Options
25
+
26
+ | Option | Default | Does |
27
+ |---|---|---|
28
+ | `platforms` | `["android", "ios", "compose"]` | Any of those three |
29
+ | `dark` | the context named `dark` | The name of the context that is the dark appearance |
30
+ | `prefix` | none | Letters and digits, starting with a letter. See "What the prefix reaches" |
31
+ | `include` | none (every token) | A list of token path prefixes in dot form; only the tokens under one of them are written |
32
+ | `exclude` | none | A list of token path prefixes in dot form; the tokens under one of them are not written. Applied after `include` |
33
+
34
+ `include` and `exclude` take path prefixes, not patterns: no glob, no regular expression. An entry matches a token when its names, split at the dots, are the first names of the token's path, compared as plain text one by one. `["breakpoint", "component.button.website"]` matches `breakpoint.md` and every token under `component.button.website`, and does not match `breakpoints.x`. Each name is letters, digits, `_` and `-`, and a list holds 1 to 100 entries (an empty list is refused, it would write nothing); anything else is an `option-invalid` finding and the option is ignored. They apply to colors, dimensions and the dark context, in every output. An entry that matches no token of the brand is not an error: a `filter-unmatched` info finding names it, so a typo shows. A token left out by `include` or `exclude` is not counted in `tokens-skipped`.
35
+
36
+ ```json
37
+ {
38
+ "plugins": [
39
+ { "name": "blazon.platform-tokens", "options": { "prefix": "Acme", "exclude": ["radius"] } }
40
+ ]
41
+ }
42
+ ```
43
+
44
+ Run on blazon's own example brand with this entry, `blazon tokens` writes the same 39 files as with no options except for the iOS names below, and no `radius.*` dimension in any output.
45
+
46
+ ## What the prefix reaches
47
+
48
+ Checked by running the plugin on the example brand with and without `"prefix": "Acme"` and comparing the two file trees and the names in them.
49
+
50
+ | Output | Reached | With `Acme` |
51
+ |---|---|---|
52
+ | `android/values/colors.xml`, `values-night/colors.xml`, `dimens.xml` | Yes, first in each resource name | `acme_social_format_square_height` |
53
+ | `ios/` Swift file name | Yes | `AcmeTokens.swift` (`BlazonTokens.swift` with no prefix) |
54
+ | `ios/Colors.xcassets` colorset names | Yes, the prefix in lowerCamel in front of the Swift name | `acmeSignalOrange.colorset` |
55
+ | Swift types | Yes | `AcmeColors`, `AcmeDimensions` |
56
+ | Kotlin objects | Yes | `AcmeColors`, `AcmeDarkColors`, `AcmeDimens` |
57
+ | Names of the members of the Swift and Kotlin types | No, the type already says it | `AcmeColors.signalOrange` |
58
+ | Kotlin `package` line | No | `package blazon.tokens` |
59
+ | `README.txt` | Only the Swift file name it mentions | `add AcmeTokens.swift and Colors.xcassets ...` |
60
+
61
+ The Kotlin package stays `blazon.tokens` with any prefix. The Kotlin files are meant to be copied into your module and the package line set to yours (the file says so in `README.txt`), so the plugin does not guess a package name, and a second option for it is not worth the surface. With no prefix every file is byte-identical to what earlier versions wrote.
62
+
63
+ ## Names
64
+
65
+ One token has a name for each output, from its dotted path. Android keeps every segment; the others drop a leading `color` segment of a color token, because the type or the catalog says it is a color. Take the color `color.brand.primary` and the dimension `space.4` with the prefix `Acme`:
66
+
67
+ | Output | Color | Dimension | Rule |
68
+ |---|---|---|---|
69
+ | Android resource | `acme_color_brand_primary` | `acme_space_4` | prefix, then every segment, lower snake case |
70
+ | Swift member | `brandPrimary` | `space4` | lowerCamel, leading `color` dropped |
71
+ | Kotlin member | `brandPrimary` | `space4` | as Swift |
72
+ | Asset catalog colorset | `acmeBrandPrimary` | none | prefix in lowerCamel, then the Swift name |
73
+
74
+ So one color is `acme_color_brand_primary` on Android and `brandPrimary` elsewhere; that is deliberate and the names are not changed. Without the prefix the Android name has no `acme_`, and the colorset is `brandPrimary`. The longer rules (digits, keywords, collisions) are in the manual.
75
+
76
+ ## Not written
77
+
78
+ Typography, fontFamily, fontWeight, shadow, gradient, duration, cubicBezier, transition and number tokens are not written, and nor is the colour or style of a `border` token (its width is); the build names the skipped types in one `tokens-skipped` finding.
@@ -8120,6 +8120,10 @@ function nameTokens(paths, style, kind, prefix) {
8120
8120
  };
8121
8121
  });
8122
8122
  }
8123
+ /** The name of a colorset in the asset catalog: the Swift name, with the prefix in front as lowerCamel (`acmeBlue100`), or the Swift name alone with no prefix */
8124
+ var assetName = (prefix, swift) => prefix ? `${lowerFirst(prefix)}${upperFirst(swift)}` : swift;
8125
+ /** The Swift file name: `BlazonTokens.swift`, or `AcmeTokens.swift` with the prefix `acme` */
8126
+ var swiftFile = (prefix) => `${typeName(prefix, "Tokens")}.swift`;
8123
8127
  /** The Swift and Kotlin type name for a group of tokens: `BlazonColors`, or `AcmeColors` with the prefix `acme` */
8124
8128
  var typeName = (prefix, suffix) => `${prefix ? upperFirst(prefix) : "Blazon"}${suffix}`;
8125
8129
  var HEADER$1 = "// Written by blazon.platform-tokens from brand.json. Do not edit: build again instead.";
@@ -8212,12 +8216,12 @@ extension Color {
8212
8216
  #endif
8213
8217
  }
8214
8218
  }`;
8215
- /** iOS: BlazonTokens.swift with enums of SwiftUI Colors and CGFloat dimensions, and an asset catalog with a colorset for each color, with dark appearances */
8219
+ /** iOS: BlazonTokens.swift (or <Prefix>Tokens.swift) with enums of SwiftUI Colors and CGFloat dimensions, and an asset catalog with a colorset for each color, with dark appearances */
8216
8220
  function iosFiles(plan) {
8217
8221
  const files = /* @__PURE__ */ new Map();
8218
8222
  if (plan.colors.length) {
8219
8223
  files.set("ios/Colors.xcassets/Contents.json", json({ info: INFO }));
8220
- for (const c of plan.colors) files.set(`ios/Colors.xcassets/${c.swift}.colorset/Contents.json`, json({
8224
+ for (const c of plan.colors) files.set(`ios/Colors.xcassets/${assetName(plan.prefix, c.swift)}.colorset/Contents.json`, json({
8221
8225
  colors: [entry(c.light), ...c.dark ? [entry(c.dark, true)] : []],
8222
8226
  info: INFO
8223
8227
  }));
@@ -8229,7 +8233,7 @@ function iosFiles(plan) {
8229
8233
  if (plan.colors.length) out.push("", `public enum ${typeName(plan.prefix, "Colors")} {`, ...plan.colors.map((c) => ` public static let ${c.swift} = ${c.dark ? `Color(blazonLight: ${rgba(c.light)}, dark: ${rgba(c.dark)})` : srgb(c.light)}`), "}");
8230
8234
  if (plan.dimensions.length) out.push("", "// px tokens are points 1:1; rem tokens are 16 points to the rem.", `public enum ${typeName(plan.prefix, "Dimensions")} {`, ...plan.dimensions.map((d) => ` public static let ${d.swift}: CGFloat = ${dp(d.dp)}`), "}");
8231
8235
  if (dynamic) out.push("", DYNAMIC);
8232
- files.set("ios/BlazonTokens.swift", `${out.join("\n")}\n`);
8236
+ files.set(`ios/${swiftFile(plan.prefix)}`, `${out.join("\n")}\n`);
8233
8237
  return files;
8234
8238
  }
8235
8239
  /** The plugin's name, which blazon's config names it by, and the prefix of its finding codes */
@@ -8260,8 +8264,17 @@ var PLATFORMS = [
8260
8264
  var KEYS = [
8261
8265
  "platforms",
8262
8266
  "dark",
8263
- "prefix"
8267
+ "prefix",
8268
+ "include",
8269
+ "exclude"
8264
8270
  ];
8271
+ var PATH = /^[\p{L}\p{N}_-]+(\.[\p{L}\p{N}_-]+)*$/u;
8272
+ /** True when `path` is `prefix` or lies under it: the names are compared one by one, so `breakpoint` does not reach `breakpoints.x`. Plain comparison, no pattern. */
8273
+ function underPrefix(path, prefix) {
8274
+ const names = path.split(".");
8275
+ const head = prefix.split(".");
8276
+ return head.length <= names.length && head.every((name, at) => name === names[at]);
8277
+ }
8265
8278
  var finding = findingFor(NAME);
8266
8279
  var invalid = (message) => finding("option-invalid", "error", "options", message);
8267
8280
  /**
@@ -8295,6 +8308,12 @@ function parseOptions(raw, contexts) {
8295
8308
  if (typeof raw.prefix !== "string" || !/^([A-Za-z][A-Za-z0-9]*)?$/.test(raw.prefix)) findings.push(invalid("prefix must be letters and digits, starting with a letter"));
8296
8309
  else options.prefix = raw.prefix;
8297
8310
  }
8311
+ for (const key of ["include", "exclude"]) {
8312
+ const list = raw[key];
8313
+ if (list === void 0) continue;
8314
+ if (!Array.isArray(list) || list.length === 0 || list.length > 100 || list.some((item) => typeof item !== "string" || !PATH.test(item))) findings.push(invalid(`${key} must be a list of 1 to 100 token paths in dot form, such as "breakpoint" or "component.button.website", each name letters, digits, "_" and "-" (no pattern characters)`));
8315
+ else options[key] = [...new Set(list)];
8316
+ }
8298
8317
  return {
8299
8318
  options,
8300
8319
  findings
@@ -8310,6 +8329,9 @@ var PLATFORM_OF = {
8310
8329
  swift: "ios",
8311
8330
  kotlin: "compose"
8312
8331
  };
8332
+ var isComposite = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && "width" in value;
8333
+ /** The width of a border token in dp: the `width` of its composite value, or the value itself when it is a plain dimension */
8334
+ var borderWidth = (token) => isComposite(token.resolved) ? readDimension(token.resolved.width, void 0) : readDimension(token.resolved, token.value);
8313
8335
  var byPath = (a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
8314
8336
  var count = (n, what) => `${n} ${what}${n === 1 ? "" : "s"}`;
8315
8337
  /** The context that is the dark appearance: the one the option names, else the one named `dark`; none, or a finding when two modifiers have one */
@@ -8323,16 +8345,27 @@ function darkContext(contexts, options, findings) {
8323
8345
  }
8324
8346
  return matches[0];
8325
8347
  }
8348
+ /** The tokens `include` and `exclude` leave, and an info finding for each entry that matched no token of the brand (a typo shows) */
8349
+ function filterTokens(tokens, options, findings) {
8350
+ const { include, exclude } = options;
8351
+ const keep = (path) => (!include || include.some((prefix) => underPrefix(path, prefix))) && !(exclude ?? []).some((prefix) => underPrefix(path, prefix));
8352
+ for (const [key, list] of [["include", include], ["exclude", exclude]]) for (const prefix of list ?? []) if (!tokens.some((token) => underPrefix(token.path, prefix))) findings.push(finding("filter-unmatched", "info", `options.${key}`, `${key} ${JSON.stringify(prefix)} matches no token of the brand: check the spelling (it matches a whole name or a group of names, not part of a name)`));
8353
+ return {
8354
+ kept: tokens.filter((token) => keep(token.path)),
8355
+ keep
8356
+ };
8357
+ }
8326
8358
  /** The tokens to write, their names, and what was said about each. */
8327
8359
  function planTokens(brand, options) {
8328
8360
  const findings = [];
8329
- const tokens = [...brand.tokens].sort(byPath);
8361
+ const { kept, keep } = filterTokens([...brand.tokens].sort(byPath), options, findings);
8362
+ const tokens = kept;
8330
8363
  const skipped = /* @__PURE__ */ new Map();
8331
- for (const token of tokens) if (token.type !== "color" && token.type !== "dimension") skipped.set(token.type || "untyped", (skipped.get(token.type || "untyped") ?? 0) + 1);
8364
+ for (const token of tokens) if (token.type !== "color" && token.type !== "dimension" && token.type !== "border") skipped.set(token.type || "untyped", (skipped.get(token.type || "untyped") ?? 0) + 1);
8332
8365
  if (skipped.size) {
8333
8366
  const total = [...skipped.values()].reduce((sum, n) => sum + n, 0);
8334
8367
  const list = [...skipped].sort(([a], [b]) => a < b ? -1 : 1).map(([type, n]) => `${type} (${n})`);
8335
- findings.push(finding("tokens-skipped", "info", "tokens", `${count(total, "token")} not written: this plugin writes color and dimension tokens only. Skipped types: ${list.join(", ")}`));
8368
+ findings.push(finding("tokens-skipped", "info", "tokens", `${count(total, "token")} not written: this plugin writes color and dimension tokens, and the width of border tokens, only. Skipped types: ${list.join(", ")}`));
8336
8369
  }
8337
8370
  const colors = /* @__PURE__ */ new Map();
8338
8371
  const dimensions = /* @__PURE__ */ new Map();
@@ -8352,13 +8385,22 @@ function planTokens(brand, options) {
8352
8385
  const amount = readDimension(token.resolved, token.value);
8353
8386
  if (amount === void 0) findings.push(finding("dimension-unreadable", "warning", token.path, `${token.path} is not a px or rem dimension (${JSON.stringify(token.value)}), so it was left out`));
8354
8387
  else dimensions.set(token.path, amount);
8388
+ } else if (token.type === "border") {
8389
+ const amount = borderWidth(token);
8390
+ if (amount === void 0) {
8391
+ findings.push(finding("dimension-unreadable", "warning", token.path, `${token.path} has no border width in px or rem (${JSON.stringify(token.value)}), so it was left out`));
8392
+ continue;
8393
+ }
8394
+ dimensions.set(`${token.path}.width`, amount);
8395
+ const style = isComposite(token.resolved) ? token.resolved.style : void 0;
8396
+ if (style !== void 0 && style !== "solid") findings.push(finding("border-style-dropped", "info", token.path, `${token.path} has the style ${typeof style === "string" ? JSON.stringify(style) : "a custom stroke style"}, which has no equivalent in these files: only its width was written, as ${token.path}.width`));
8355
8397
  }
8356
8398
  const context = darkContext(brand.contexts, options, findings);
8357
8399
  const darks = /* @__PURE__ */ new Map();
8358
8400
  if (context) {
8359
8401
  const unmatched = [];
8360
8402
  let dimensionsChanged = 0;
8361
- for (const token of [...context.tokens].sort(byPath)) if (token.type === "color") {
8403
+ for (const token of [...context.tokens].filter((item) => keep(item.path)).sort(byPath)) if (token.type === "color") {
8362
8404
  const light = colors.get(token.path);
8363
8405
  if (!light) {
8364
8406
  unmatched.push(token.path);
@@ -8369,6 +8411,9 @@ function planTokens(brand, options) {
8369
8411
  } else if (token.type === "dimension") {
8370
8412
  const light = dimensions.get(token.path);
8371
8413
  if (light !== void 0 && readDimension(token.resolved, token.value) !== light) dimensionsChanged++;
8414
+ } else if (token.type === "border") {
8415
+ const light = dimensions.get(`${token.path}.width`);
8416
+ if (light !== void 0 && borderWidth(token) !== light) dimensionsChanged++;
8372
8417
  }
8373
8418
  if (unmatched.length) findings.push(finding("dark-unmatched", "warning", "contexts", `${context.context} sets ${count(unmatched.length, "color")} that the main tokens do not have, so ${unmatched.length === 1 ? "it was" : "they were"} left out: ${unmatched.join(", ")}`));
8374
8419
  if (dimensionsChanged) findings.push(finding("dark-dimensions-ignored", "info", "contexts", `${context.context} changes ${count(dimensionsChanged, "dimension token")}; dimensions are written once, with the main values`));
@@ -8407,20 +8452,20 @@ function planTokens(brand, options) {
8407
8452
  findings
8408
8453
  };
8409
8454
  }
8410
- var WHERE = {
8455
+ var WHERE = (prefix) => ({
8411
8456
  android: {
8412
8457
  folder: "android/",
8413
8458
  line: "copy values/ (and values-night/, if there is one) into your module's src/main/res/, beside any file of the same name"
8414
8459
  },
8415
8460
  ios: {
8416
8461
  folder: "ios/",
8417
- line: "add BlazonTokens.swift and Colors.xcassets to your Xcode target"
8462
+ line: `add ${swiftFile(prefix)} and Colors.xcassets to your Xcode target`
8418
8463
  },
8419
8464
  compose: {
8420
8465
  folder: "compose/",
8421
8466
  line: "copy Colors.kt and Dimens.kt into your module's source folder and set the package line to yours"
8422
8467
  }
8423
- };
8468
+ });
8424
8469
  async function build(text) {
8425
8470
  const job = jobFor(text);
8426
8471
  const brand = readBrand(job.brand);
@@ -8434,7 +8479,7 @@ async function build(text) {
8434
8479
  if (made.size) written.push(platform);
8435
8480
  for (const [file, data] of made) files.set(file, data);
8436
8481
  }
8437
- if (written.length) files.set("README.txt", `Design tokens for apps, written by blazon.platform-tokens from brand.json.\n\n${written.map((platform) => `${WHERE[platform].folder} ${WHERE[platform].line}`).join("\n")}\n`);
8482
+ if (written.length) files.set("README.txt", `Design tokens for apps, written by blazon.platform-tokens from brand.json.\n\n${written.map((platform) => `${WHERE(options.prefix)[platform].folder} ${WHERE(options.prefix)[platform].line}`).join("\n")}\n`);
8438
8483
  for (const [file, data] of [...files].sort(([a], [b]) => a < b ? -1 : 1)) {
8439
8484
  node_fs.default.mkdirSync(node_path.default.dirname(node_path.default.join(job.outDir, file)), { recursive: true });
8440
8485
  node_fs.default.writeFileSync(node_path.default.join(job.outDir, file), data);
@@ -10,8 +10,59 @@ The source is `src/shipped/press-kit/`, and `npm run build` (`npm run build:plug
10
10
  |---|---|
11
11
  | `logos/` | Assets that are logos (the `logos` category, or the files `logo.onLight` and `logo.onDark` name), as they are, in a folder for each background their sidecars name |
12
12
  | `colors/` | The color tokens that are not aliases, as JSON, CSS and text; CMYK, Pantone and RAL only where a token states them |
13
- | `fonts.txt` | The families of `fontDisplay`, `fontBody`, the font tokens and the font stylesheets; the source and license only where a font token states them (its `font` extension) or the data has them, else `not stated` |
14
- | `about.txt` | `brand.title` and `brand.description`; without one, a line saying none is set |
15
- | `press-kit.pdf` | The title, the description, up to ten colors and one logo, drawn in Chrome |
13
+ | `fonts.txt` | The brand's fonts: the front family of `fontDisplay`, `fontBody` and each font token, and the families the font stylesheets load, unless it is a system font nothing loads (then it is a fallback); the source and license only where a font token states them (its `font` extension) or the data has them, else the license file blazon found beside the family's font files (`License file:` with its path), else `not stated`. The fallbacks are one last line, `Fallback fonts, not shipped` |
14
+ | `about.txt` | `brand.title`, then the `company` option's description, else `brand.description` (without either, a line saying none is set), then the company's boilerplate and facts and the `note` |
15
+ | `press-kit.pdf` | The title, the description (the company's when the option gives one), the boilerplate, the facts, the note, up to ten colors and one logo, drawn in Chrome |
16
16
 
17
17
  A logo marked `needs-review`, and a generated logo with no `review`, are left out, with a finding for each. A color token marked `needs-review` is left out too, unless the `unreviewed` option is `true`, which includes it labelled as unreviewed.
18
+
19
+ ## Options
20
+
21
+ Every option is plain data in the plugin's `options` in `blazon.json`. A wrong one is an `option-invalid` finding at `options.<key>` that names the key; it is left at its default and the rest of the kit is written. An unknown key, a wrong type, an empty or blank text, a text over its limit and a list over its limit are all wrong.
22
+
23
+ | Option | Type | Default | Does |
24
+ |---|---|---|---|
25
+ | `name` | string | `press-kit` | Folder, zip and PDF name, without an extension: letters, digits, dots, hyphens and underscores, up to 64 characters |
26
+ | `pdf` | boolean | `true` | `false` writes no PDF and needs no browser |
27
+ | `unreviewed` | boolean | `false` | `true` includes the colors marked `needs-review`, labelled as unreviewed |
28
+ | `logos` | list of asset ids | every logo | The logos to include; one that is not ready stays out |
29
+ | `company` | object | none | The company behind the brand, for a brand whose own title and description are a book's. Keys: `description`, `boilerplate`, `facts` |
30
+ | `company.description` | string, up to 1000 characters | none | Replaces `brand.description` in `about.txt` and the PDF when given |
31
+ | `company.boilerplate` | string, up to 2000 characters | none | One text printed after the description in `about.txt` and the PDF; blank lines make paragraphs |
32
+ | `company.facts` | list of up to 20 `{ "label", "value" }` | none | Labelled lines in the order given, such as the legal name and the registration number. A label is up to 60 characters and a value up to 300, each on one line |
33
+ | `note` | string, up to 280 characters, one line | none | Printed as `Note: ...` in `README.txt`, `about.txt`, `colors/colors.txt` and the PDF, such as that the colors are not yet approved |
34
+
35
+ With none of `company` and `note` the files are the bytes they were before, apart from the fixes in the next section.
36
+
37
+ ```json
38
+ {
39
+ "plugins": [
40
+ {
41
+ "name": "blazon.press-kit",
42
+ "env": ["BLAZON_CHROME", "HOME", "TMPDIR"],
43
+ "options": {
44
+ "name": "acme-press-kit",
45
+ "company": {
46
+ "description": "Acme builds payment tools for teams that move money across borders.",
47
+ "boilerplate": "Acme Ltd is a licensed payment institution. Press enquiries: press@acme.example.",
48
+ "facts": [
49
+ { "label": "Legal name", "value": "Acme Ltd" },
50
+ { "label": "Registered address", "value": "1 Example Street, London" },
51
+ { "label": "Registration number", "value": "01234567" }
52
+ ]
53
+ },
54
+ "note": "The colours are proposed and not yet approved."
55
+ }
56
+ }
57
+ ]
58
+ }
59
+ ```
60
+
61
+ That entry was run on `examples/blazon`; `about.txt` then reads the company description, the boilerplate, the three facts and `Note: The colours are proposed and not yet approved.`, each in its own paragraph.
62
+
63
+ ## Fonts and swatches
64
+
65
+ - A family is a brand font when it is at the front of a font stack and is not a system font, or when a stylesheet or font file of the brand loads it, or when its font token states a source or license. The same families blazon treats as system fonts everywhere (`blazon fonts`) are fallbacks, and so is every family after the first in a stack. They are not listed as fonts with `License: not stated`; `fonts.txt` ends with one line, `Fallback fonts, not shipped: ...`. A stack with no brand font writes no `fonts.txt`.
66
+ - The license comes from the font token (`license`, `licenseUrl`, `source` of its `dev.blazon` `font`), then from the license file beside the family's font files (`OFL.txt`, `LICENSE`, `LICENCE`, `COPYING`), which blazon reads into `brand.json` as `theme.fontLicenses`: the plugin is given the brand and the built site, not the project folder, so it never opens the file itself. It prints `License file:` with the project path and, as `License:`, an `SPDX-License-Identifier:` line or the first short line that is not a copyright notice (`see <path>` when none). The kit copies no font and no license text.
67
+ - The PDF draws up to ten colors. A color belongs to the group named by the path before its last segment (`color.blue.500` is step `500` of `color.blue`). Groups run in the order their first color appears in the brand, each group's steps together, a group goes in whole, and the walk stops at the first group that does not fit in the places left (the first group alone is cut at ten). A swatch reads `blue 500`; a color straight under `color` keeps its short description, else its last segment.
68
+ - `README.txt` aligns its descriptions two spaces after the longest file name, or at column 16 when the names are shorter.