@getvitops/generator 8.2.0-alpha.0 → 8.3.0-alpha.0

package/config.schema.json

@@ -68,6 +68,10 @@
                                 "type": "string"
                               },
                               "description": "Step → colour overrides (hex or oklch()) pinned VERBATIM at those steps. Every other step takes its lightness from the shared ladder, with chroma and hue interpolated between the anchors — so an anchor is reproduced exactly and is the only step allowed off the ladder. An explicit anchor overrides the seed at that step; two anchors that resolve to the same step are an error."
+                            },
+                            "acknowledgeOffLadder": {
+                              "type": "boolean",
+                              "description": "Acknowledge that this hue deliberately pins colours off the shared lightness ladder (typically to match an existing brand palette exactly). Silences the per-step \"off the ladder\" build warnings for THIS hue only; the monotonicity and contrast checks still run."
                             }
                           },
                           "required": [
@@ -98,6 +102,10 @@
                                 }
                               ],
                               "description": "Fixed brand kit: authored tones placed verbatim at their nearest steps plus tinted off-white/off-black endpoints; no interpolation. Either an ordered light → dark array or a step → colour map."
+                            },
+                            "acknowledgeOffLadder": {
+                              "type": "boolean",
+                              "description": "Acknowledge that this hue deliberately pins colours off the shared lightness ladder (typically to match an existing brand palette exactly). Silences the per-step \"off the ladder\" build warnings for THIS hue only; the monotonicity and contrast checks still run."
                             }
                           },
                           "required": [
@@ -135,6 +143,21 @@
                                 "chromatic"
                               ],
                               "description": "`surface` — a page/panel colour: gets a bare `bg-<role>` plus the full emphasis range and text scale. `chromatic` (default) — a signal colour: tints and solids only, no bare `bg-<role>`."
+                            },
+                            "solid": {
+                              "description": "Ramp step (100…900) the role's solid family starts from; default 600. `bg-<role>-solid` is this step and `-solid-bold` / `-solid-x-bold` walk one and two rungs DARKER, so `solid: 400` gives 400 → 500 → 600. Use it when the brand colour is bright and lives lower on the ramp (a yellow at 400) instead of reaching for raw `bg-<hue>-<step>` classes. Like the default family it is the same in light and dark. The contrast check still runs on the pair this produces.",
+                              "type": [
+                                "number",
+                                "string"
+                              ]
+                            },
+                            "foreground": {
+                              "type": "string",
+                              "enum": [
+                                "light",
+                                "dark"
+                              ],
+                              "description": "Polarity of `text-on-<role>`, the foreground for a filled surface. Default is whichever of near-white / near-black has more contrast on the solid. Set `\"dark\"` so a bright fill carries dark text (or `\"light\"` for the reverse). The build still fails if the forced pair is below APCA Lc 60."
                             }
                           },
                           "required": [
@@ -164,13 +187,31 @@
                 "additionalProperties": false
               },
               "shadows": {
-                "description": "Named shadows → `--shadow-<name>` tokens and `.drop-shadow-<name>` utilities. Values are shadow parameter lists (offset/blur/colour). Each token feeds two consumers with different grammars — `box-shadow` (pattern geometry, via the `--ds-*` group aliases) and `filter: drop-shadow(…)` (the utilities and the `shadow:` state shortcut) — so values must stay in the intersection: **one layer, no spread radius, no `inset`**. `drop-shadow()` rejects all three, and rejecting them invalidates the whole filter, so the shadow vanishes rather than degrading.",
+                "description": "Named shadows → `--shadow-<name>` tokens and `.drop-shadow-<name>` utilities. A value is either a string (below) or `{ \"box\"?: string, \"drop\"?: string }` for a shadow that needs the two grammars to differ: `box` is what `--shadow-<name>` holds and what `box-shadow` consumers (pattern geometry, `--ds-*`) read, so it MAY use spread, `inset` and several layers; `drop` is emitted as `--shadow-<name>-drop` and is what `.drop-shadow-<name>` and the `shadow:` state shortcut read, so it must obey the drop-shadow() limits. Omit `drop` and no drop-shadow utility is emitted for that name; omit `box` and `--shadow-<name>` takes the `drop` value. The plain string form keeps working and feeds both consumers from one value. For that string form: each token feeds two consumers with different grammars — `box-shadow` (pattern geometry, via the `--ds-*` group aliases) and `filter: drop-shadow(…)` (the utilities and the `shadow:` state shortcut) — so values must stay in the intersection: **one layer, no spread radius, no `inset`**. `drop-shadow()` rejects all three, and rejecting them invalidates the whole filter, so the shadow vanishes rather than degrading.",
                 "type": "object",
                 "propertyNames": {
                   "type": "string"
                 },
                 "additionalProperties": {
-                  "type": "string"
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "box": {
+                          "type": "string",
+                          "description": "`box-shadow` value: spread, `inset` and multiple layers allowed."
+                        },
+                        "drop": {
+                          "type": "string",
+                          "description": "`drop-shadow()` value: one layer, at most three lengths, no `inset`."
+                        }
+                      },
+                      "additionalProperties": false
+                    }
+                  ]
                 }
               },
               "fonts": {
@@ -184,7 +225,7 @@
                 }
               },
               "typeScale": {
-                "description": "Fluid modular TYPE scale → `--text-<name>` tokens, consumed by typography roles and text-size utilities.",
+                "description": "Fluid modular TYPE scale → `--text-<name>` tokens, consumed by typography roles and text-size utilities.\n\n**Recipe for marketing headings:** one ratio cannot serve both a ~16px body and a ~76px hero — a ratio big enough for the hero collapses the small end to unreadable. Extend `names` upward instead of raising the ratio: keep `base` ≈ \"1rem\" at the body step, `ratio` ≈ 1.2 at `maxVw` (≈ 1.125–1.15 `minRatio` at `minVw` so headings tame on phones), and add names (`4xl`, `5xl`) for the display sizes — the steps above `baseStep` are what headings read, the steps below it only need `xs`/`sm`. Aim the largest named step at your hero (≈ 4.5–5rem at `maxVw`), then point the `display`/`title` roles at those steps rather than hand-writing `clamp()` in a role. If a step still needs its own value, set that role's `size` literally — roles may bypass the scale.",
                 "type": "object",
                 "properties": {
                   "base": {
@@ -245,6 +286,55 @@
                 ],
                 "additionalProperties": false
               },
+              "layout": {
+                "type": "object",
+                "properties": {
+                  "widths": {
+                    "type": "object",
+                    "properties": {
+                      "measure": {
+                        "type": "string",
+                        "description": "Reading column → `--width-measure` (framework default 65ch)."
+                      },
+                      "breakout": {
+                        "type": "string",
+                        "description": "`.breakout` track → `--width-breakout` (default 90ch)."
+                      },
+                      "spotlight": {
+                        "type": "string",
+                        "description": "`.spotlight` track → `--width-spotlight` (default 120ch)."
+                      },
+                      "nav": {
+                        "type": "string",
+                        "description": "Navigation column beside content → `--width-nav` (default 16rem)."
+                      }
+                    },
+                    "additionalProperties": false,
+                    "description": "Content track widths for `.centered`. In `ch` so the reading measure stays character-based; keep measure ≤ breakout ≤ spotlight."
+                  },
+                  "regionSpace": {
+                    "type": "object",
+                    "properties": {
+                      "min": {
+                        "type": "string",
+                        "description": "Floor → `--region-space-min` (default 3rem)."
+                      },
+                      "preferred": {
+                        "type": "string",
+                        "description": "Preferred value → `--region-space` (default 8vh)."
+                      },
+                      "max": {
+                        "type": "string",
+                        "description": "Ceiling → `--region-space-max` (default 8rem)."
+                      }
+                    },
+                    "additionalProperties": false,
+                    "description": "Vertical padding of `.region`: `padding-block: clamp(min, preferred, max)`."
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Optional layout tokens. Each key you set is emitted as a `:root` custom property (css, bricks and tailwind formats); each you omit keeps the framework default. Lets the live editor tune widths and region spacing instead of a hand-written override stylesheet."
+              },
               "spaceScale": {
                 "description": "Fluid modular SPACE scale → `--space-<name>` tokens, consumed by spacing/gap utilities and vertical rhythm.",
                 "type": "object",
@@ -466,7 +556,7 @@
                           "number"
                         ]
                       },
-                      "description": "A bag of CSS-ish keys, each mapped to a declaration plus a `--<role>-<sfx>` override hook. The recognised set is **closed**: `family`, `size`, `weight`, `style`, `line-height`, `tracking` (→ `letter-spacing`), `text-transform`, `text-decoration`, `text-wrap`, `color`. Note the last four are spelled with their full CSS property names — `transform` and `decoration` are NOT accepted. Anything unrecognised is **ignored**, not passed through, so the generator warns rather than emitting it: a silently-dropped `transform: uppercase` is how title-case navigation reaches production. Note also that `style`, `text-transform`, `text-decoration` and `text-wrap` are emitted on **every** role at their identity value (`normal`/`none`/`none`/`wrap`) whether declared or not, so applying one role class over another fully resets it — which means **omitting `text-wrap` is not \"inherit\"**: it emits `text-wrap: wrap` and cancels the `pretty` the role would otherwise inherit from a `pretty` ancestor such as a `body`-mapped role. Declare it on every role — `balance` for heading-like roles, `pretty` for copy, `wrap` for short single-line labels."
+                      "description": "A bag of CSS-ish keys, each mapped to a declaration plus a `--<role>-<sfx>` override hook. The recognised set is **closed**: `family`, `size`, `weight`, `style`, `line-height`, `tracking` (→ `letter-spacing`), `text-transform`, `text-decoration`, `text-wrap`, `color`. The canonical spellings of the last four are their full CSS property names (`text-transform`, `text-decoration`, …); `transform` and `decoration` are accepted as aliases of the first two and normalised to them. Anything unrecognised is **ignored**, not passed through, so the generator warns rather than emitting it: a silently-dropped key (a typo for `text-transform`, say) is how title-case navigation reaches production. Note also that `style`, `text-transform`, `text-decoration` and `text-wrap` are emitted on **every** role at their identity value (`normal`/`none`/`none`/`wrap`) whether declared or not, so applying one role class over another fully resets it — which means **omitting `text-wrap` is not \"inherit\"**: it emits `text-wrap: wrap` and cancels the `pretty` the role would otherwise inherit from a `pretty` ancestor such as a `body`-mapped role. Declare it on every role — `balance` for heading-like roles, `pretty` for copy, `wrap` for short single-line labels."
                     }
                   },
                   "headings": {
@@ -604,7 +694,7 @@
           "type": "string"
         },
         "defaultColorScheme": {
-          "description": "Initial appearance. `\"system\"` follows the OS via `prefers-color-scheme` and is what makes `<wc-color-scheme-toggle>`'s \"System\" position resolve to anything — it removes the theme attribute, so without this the page falls through to light. It also gives a no-JS page the OS appearance. Defaults to `\"light\"`, because switching an existing site to `\"system\"` visibly flips it dark for dark-OS visitors.",
+          "description": "Initial appearance. `\"dark\"` makes the site DARK-ONLY: the dark tokens become the `:root` appearance (with `color-scheme: dark`), no light block or `data-theme` flip is emitted, and the light-mode contrast checks are skipped — so a palette that only works dark (bright fills with dark text, for example) builds. Do not ship `<wc-color-scheme-toggle>` on such a site. `\"system\"` follows the OS via `prefers-color-scheme` and is what makes `<wc-color-scheme-toggle>`'s \"System\" position resolve to anything — it removes the theme attribute, so without this the page falls through to light. It also gives a no-JS page the OS appearance. Defaults to `\"light\"`, because switching an existing site to `\"system\"` visibly flips it dark for dark-OS visitors.",
           "type": "string",
           "enum": [
             "light",
@@ -694,6 +784,7 @@
           "type": "object",
           "properties": {
             "streetAddress": {
+              "description": "Street line. Optional: a business with no public street address (home-based, service-area) omits it, and the generated legal documents and JSON-LD simply leave the line out.",
               "type": "string"
             },
             "addressLocality": {
@@ -713,12 +804,28 @@
             }
           },
           "required": [
-            "streetAddress",
             "addressLocality",
             "addressCountry"
           ],
           "additionalProperties": false
         },
+        "description": {
+          "description": "One or two sentences on what the organization does → JSON-LD `description` and a fallback for SEO. Localisable.",
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          ]
+        },
         "taxID": {
           "description": "Tax identification number.",
           "type": "string"
@@ -759,6 +866,7 @@
                   "type": "object",
                   "properties": {
                     "streetAddress": {
+                      "description": "Street line. Optional: a business with no public street address (home-based, service-area) omits it, and the generated legal documents and JSON-LD simply leave the line out.",
                       "type": "string"
                     },
                     "addressLocality": {
@@ -778,7 +886,6 @@
                     }
                   },
                   "required": [
-                    "streetAddress",
                     "addressLocality",
                     "addressCountry"
                   ],
@@ -849,6 +956,7 @@
                 "type": "object",
                 "properties": {
                   "streetAddress": {
+                    "description": "Street line. Optional: a business with no public street address (home-based, service-area) omits it, and the generated legal documents and JSON-LD simply leave the line out.",
                     "type": "string"
                   },
                   "addressLocality": {
@@ -868,7 +976,6 @@
                   }
                 },
                 "required": [
-                  "streetAddress",
                   "addressLocality",
                   "addressCountry"
                 ],
@@ -2226,70 +2333,115 @@
           "additionalProperties": false
         },
         "seo": {
-          "description": "SEO defaults: title/description templates, robots policy, verification tokens, Open Graph + Twitter cards, and post-deploy indexing notification.",
+          "description": "SEO defaults: site name, title/description defaults, robots policy, verification tokens, Open Graph + Twitter cards, and post-deploy indexing notification. Read by `<Seo />`, `vitops robots` and `vitops search notify`.",
           "type": "object",
           "properties": {
+            "siteName": {
+              "description": "`og:site_name`, and the `<title>` when a page passes none. Defaults to `organization.name`, so most sites never state it.",
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string"
+                  },
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
             "titleTemplate": {
-              "description": "Page-title pattern (e.g. \"%s · Acme\").",
-              "type": "string"
+              "description": "Page-title pattern; `%s` is the page title (e.g. \"%s · Acme\"). Applies to `<title>` only, never to `og:title`, and is skipped when the page title already equals the site name.",
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string"
+                  },
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                }
+              ]
             },
-            "descriptionTemplate": {
-              "type": "string"
+            "defaultTitle": {
+              "description": "`<title>` for pages that pass none. Used verbatim — the template is not applied. Defaults to the site name.",
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string"
+                  },
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                }
+              ]
+            },
+            "defaultDescription": {
+              "description": "`<meta name=\"description\">` for pages that pass none.",
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string"
+                  },
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                }
+              ]
             },
             "robots": {
-              "description": "e.g. \"index,follow\" / \"noindex,nofollow\".",
+              "description": "Site-wide robots directive (e.g. \"index,follow\" / \"noindex,nofollow\"). `site.environments.<env>.robots` wins over it.",
               "type": "string"
             },
             "googleSiteVerification": {
+              "description": "Google Search Console verification token (`<meta name=\"google-site-verification\">`).",
               "type": "string"
             },
             "bingSiteVerification": {
+              "description": "Bing Webmaster Tools verification token (`<meta name=\"msvalidate.01\">`).",
               "type": "string"
             },
             "openGraph": {
+              "description": "Open Graph defaults. Per-page `<Seo />` props override them.",
               "type": "object",
               "properties": {
                 "type": {
-                  "type": "string"
+                  "description": "Default `og:type`. Default `website`.",
+                  "type": "string",
+                  "enum": [
+                    "website",
+                    "article",
+                    "profile"
+                  ]
                 },
-                "siteName": {
+                "locale": {
+                  "description": "`og:locale`. `en-CA` and `en_CA` both emit `en_CA`.",
                   "type": "string"
                 },
-                "title": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "propertyNames": {
-                        "type": "string"
-                      },
-                      "additionalProperties": {
-                        "type": "string"
-                      }
-                    }
-                  ],
-                  "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
-                },
-                "description": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "propertyNames": {
-                        "type": "string"
-                      },
-                      "additionalProperties": {
-                        "type": "string"
-                      }
-                    }
-                  ],
-                  "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
+                "localeAlternates": {
+                  "description": "Other locales the same content exists in → `og:locale:alternate`.",
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
                 },
                 "image": {
+                  "description": "Fallback share image for pages that bring none.",
                   "anyOf": [
                     {
                       "type": "string"
@@ -2298,7 +2450,8 @@
                       "type": "object",
                       "properties": {
                         "src": {
-                          "type": "string"
+                          "type": "string",
+                          "description": "Absolute, or relative to `site` (resolved at render time)."
                         },
                         "alt": {
                           "type": "string"
@@ -2308,26 +2461,28 @@
                         },
                         "height": {
                           "type": "number"
+                        },
+                        "type": {
+                          "description": "MIME type, e.g. `image/png`.",
+                          "type": "string"
                         }
                       },
                       "required": [
-                        "src",
-                        "alt"
+                        "src"
                       ],
                       "additionalProperties": false
                     }
                   ]
-                },
-                "locale": {
-                  "type": "string"
                 }
               },
               "additionalProperties": false
             },
             "twitter": {
+              "description": "Twitter/X card defaults.",
               "type": "object",
               "properties": {
                 "card": {
+                  "description": "Card type when no image resolves (default `summary`).",
                   "type": "string",
                   "enum": [
                     "summary",
@@ -2337,73 +2492,12 @@
                   ]
                 },
                 "site": {
+                  "description": "The site's own handle, e.g. \"@acme\".",
                   "type": "string"
                 },
                 "creator": {
+                  "description": "Default author handle, e.g. \"@ada\".",
                   "type": "string"
-                },
-                "title": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "propertyNames": {
-                        "type": "string"
-                      },
-                      "additionalProperties": {
-                        "type": "string"
-                      }
-                    }
-                  ],
-                  "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
-                },
-                "description": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "propertyNames": {
-                        "type": "string"
-                      },
-                      "additionalProperties": {
-                        "type": "string"
-                      }
-                    }
-                  ],
-                  "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
-                },
-                "image": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "properties": {
-                        "src": {
-                          "type": "string"
-                        },
-                        "alt": {
-                          "type": "string"
-                        },
-                        "width": {
-                          "type": "number"
-                        },
-                        "height": {
-                          "type": "number"
-                        }
-                      },
-                      "required": [
-                        "src",
-                        "alt"
-                      ],
-                      "additionalProperties": false
-                    }
-                  ]
                 }
               },
               "additionalProperties": false
@@ -2671,6 +2765,40 @@
                   }
                 ]
               },
+              "conversionActionId": {
+                "description": "Google Ads only: the conversion action **resource id(s)** (a numeric id, or a full `customers/…/conversionActions/…` resource name) used for server-side offline conversion upload — NOT the same value as `conversionLabel`, which is the opaque label the web tag uses and which the Ads API's upload endpoint does not accept. Only meaningful when `reporting: \"server\"`.",
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "call": {
+                        "description": "Fired on a tel: link click.",
+                        "type": "string"
+                      },
+                      "email": {
+                        "description": "Fired on a mailto: link click.",
+                        "type": "string"
+                      },
+                      "form": {
+                        "description": "Fired on a form submission.",
+                        "type": "string"
+                      }
+                    },
+                    "additionalProperties": false
+                  }
+                ]
+              },
+              "reporting": {
+                "description": "Google Ads only: `\"client\"` (default) fires the conversion via `gtag.js` in the browser at click/submit time; `\"server\"` uploads it via the Ads API from the conversion endpoint instead (see `conversionActionId`). An action with no matching `conversionActionId` keeps firing client-side regardless of this setting, so setting it before `conversionActionId` is filled in never silently drops a conversion.",
+                "type": "string",
+                "enum": [
+                  "client",
+                  "server"
+                ]
+              },
               "domain": {
                 "description": "Bare hostname to verify with this platform. Defaults to the host of `domains.canonical` — set it only when the ad account is verified against a different domain.",
                 "type": "string"
@@ -2933,7 +3061,8 @@
               "description": "Which legal template set the generated documents use. Default `ca`.",
               "type": "string",
               "enum": [
-                "ca"
+                "ca",
+                "qc"
               ]
             },
             "privacyPolicy": {
@@ -2974,6 +3103,7 @@
                           "type": "object",
                           "properties": {
                             "streetAddress": {
+                              "description": "Street line. Optional: a business with no public street address (home-based, service-area) omits it, and the generated legal documents and JSON-LD simply leave the line out.",
                               "type": "string"
                             },
                             "addressLocality": {
@@ -2993,7 +3123,6 @@
                             }
                           },
                           "required": [
-                            "streetAddress",
                             "addressLocality",
                             "addressCountry"
                           ],
@@ -3005,6 +3134,14 @@
                     }
                   ]
                 },
+                "privacyOfficerTitle": {
+                  "description": "Title of the person in charge of the protection of personal information (e.g. \"President\"). Quebec Law 25 requires the title and contact details to be published; the `qc` templates print it beside the `privacyOfficer` contact. Not asserted when absent.",
+                  "type": "string"
+                },
+                "impactAssessments": {
+                  "description": "Attests that a privacy impact assessment is carried out before personal information is communicated outside Quebec (Law 25, s. 17). The `qc` privacy policy states that assurance only when this is `true` — a fact the config cannot otherwise know, so it is never assumed.",
+                  "type": "boolean"
+                },
                 "retention": {
                   "description": "How long personal information is kept, in prose (e.g. \"24 months after last contact\").",
                   "type": "string"