@getvitops/generator 0.4.0 → 0.6.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 (7) hide show
  1. package/dist/index.d.mts +20 -1
  2. package/dist/index.d.mts.map +1 -1
  3. package/dist/index.mjs +628 -219
  4. package/dist/index.mjs.map +1 -1
  5. package/package.json +3 -3
  6. package/schema.json +99 -34
  7. package/site.schema.json +223 -66
package/site.schema.json CHANGED
@@ -4,7 +4,8 @@
4
4
  "type": "object",
5
5
  "properties": {
6
6
  "defaultLocale": {
7
- "type": "string"
7
+ "type": "string",
8
+ "description": "The locale used when none is specified; must be a `locales` key."
8
9
  },
9
10
  "locales": {
10
11
  "type": "object",
@@ -15,12 +16,15 @@
15
16
  "type": "object",
16
17
  "properties": {
17
18
  "name": {
18
- "type": "string"
19
+ "type": "string",
20
+ "description": "Display name of the locale (e.g. \"English\")."
19
21
  },
20
22
  "tagline": {
23
+ "description": "Site tagline in this locale.",
21
24
  "type": "string"
22
25
  },
23
26
  "basePath": {
27
+ "description": "URL prefix for this locale (e.g. \"/fr\").",
24
28
  "type": "string"
25
29
  }
26
30
  },
@@ -28,9 +32,11 @@
28
32
  "name"
29
33
  ],
30
34
  "additionalProperties": false
31
- }
35
+ },
36
+ "description": "Locales the site is published in, keyed by BCP 47 tag (e.g. \"en\", \"fr\")."
32
37
  },
33
38
  "organization": {
39
+ "description": "schema.org Organization details for JSON-LD (name, legalName, logo, tax IDs, sameAs profiles).",
34
40
  "type": "object",
35
41
  "properties": {
36
42
  "name": {
@@ -47,7 +53,8 @@
47
53
  "type": "string"
48
54
  }
49
55
  }
50
- ]
56
+ ],
57
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
51
58
  },
52
59
  "legalName": {
53
60
  "type": "string"
@@ -100,16 +107,19 @@
100
107
  "type": "string"
101
108
  },
102
109
  "addressLocality": {
103
- "type": "string"
110
+ "type": "string",
111
+ "description": "City."
104
112
  },
105
113
  "addressRegion": {
114
+ "description": "State / province.",
106
115
  "type": "string"
107
116
  },
108
117
  "postalCode": {
109
118
  "type": "string"
110
119
  },
111
120
  "addressCountry": {
112
- "type": "string"
121
+ "type": "string",
122
+ "description": "Country (ISO 3166-1 alpha-2 preferred)."
113
123
  }
114
124
  },
115
125
  "required": [
@@ -117,7 +127,8 @@
117
127
  "addressLocality",
118
128
  "addressCountry"
119
129
  ],
120
- "additionalProperties": false
130
+ "additionalProperties": false,
131
+ "description": "schema.org `PostalAddress` field names, so JSON-LD generation is lossless."
121
132
  },
122
133
  "taxID": {
123
134
  "type": "string"
@@ -126,6 +137,7 @@
126
137
  "type": "string"
127
138
  },
128
139
  "sameAs": {
140
+ "description": "Profile URLs → JSON-LD `sameAs` (mirrors `links`).",
129
141
  "type": "array",
130
142
  "items": {
131
143
  "type": "string",
@@ -136,6 +148,7 @@
136
148
  "additionalProperties": false
137
149
  },
138
150
  "contact": {
151
+ "description": "Primary contact: either a `locations` key (string reference) or an inline name/email/phone/address object.",
139
152
  "anyOf": [
140
153
  {
141
154
  "type": "string"
@@ -161,16 +174,19 @@
161
174
  "type": "string"
162
175
  },
163
176
  "addressLocality": {
164
- "type": "string"
177
+ "type": "string",
178
+ "description": "City."
165
179
  },
166
180
  "addressRegion": {
181
+ "description": "State / province.",
167
182
  "type": "string"
168
183
  },
169
184
  "postalCode": {
170
185
  "type": "string"
171
186
  },
172
187
  "addressCountry": {
173
- "type": "string"
188
+ "type": "string",
189
+ "description": "Country (ISO 3166-1 alpha-2 preferred)."
174
190
  }
175
191
  },
176
192
  "required": [
@@ -178,7 +194,8 @@
178
194
  "addressLocality",
179
195
  "addressCountry"
180
196
  ],
181
- "additionalProperties": false
197
+ "additionalProperties": false,
198
+ "description": "schema.org `PostalAddress` field names, so JSON-LD generation is lossless."
182
199
  }
183
200
  },
184
201
  "additionalProperties": false
@@ -186,13 +203,16 @@
186
203
  ]
187
204
  },
188
205
  "domains": {
206
+ "description": "Canonical domain + redirecting aliases.",
189
207
  "type": "object",
190
208
  "properties": {
191
209
  "canonical": {
192
210
  "type": "string",
193
- "format": "uri"
211
+ "format": "uri",
212
+ "description": "The canonical origin used for absolute URLs and SEO."
194
213
  },
195
214
  "aliases": {
215
+ "description": "Alias domains and how they redirect to the canonical one.",
196
216
  "type": "array",
197
217
  "items": {
198
218
  "type": "object",
@@ -242,9 +262,11 @@
242
262
  "additionalProperties": false
243
263
  },
244
264
  "primaryLocation": {
265
+ "description": "The main `locations` key (for JSON-LD and defaults).",
245
266
  "type": "string"
246
267
  },
247
268
  "locations": {
269
+ "description": "Physical locations (schema.org LocalBusiness): address, geo, opening hours, service area.",
248
270
  "type": "object",
249
271
  "propertyNames": {
250
272
  "type": "string"
@@ -266,7 +288,8 @@
266
288
  "type": "string"
267
289
  }
268
290
  }
269
- ]
291
+ ],
292
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
270
293
  },
271
294
  "name": {
272
295
  "anyOf": [
@@ -282,7 +305,8 @@
282
305
  "type": "string"
283
306
  }
284
307
  }
285
- ]
308
+ ],
309
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
286
310
  },
287
311
  "email": {
288
312
  "type": "string",
@@ -299,16 +323,19 @@
299
323
  "type": "string"
300
324
  },
301
325
  "addressLocality": {
302
- "type": "string"
326
+ "type": "string",
327
+ "description": "City."
303
328
  },
304
329
  "addressRegion": {
330
+ "description": "State / province.",
305
331
  "type": "string"
306
332
  },
307
333
  "postalCode": {
308
334
  "type": "string"
309
335
  },
310
336
  "addressCountry": {
311
- "type": "string"
337
+ "type": "string",
338
+ "description": "Country (ISO 3166-1 alpha-2 preferred)."
312
339
  }
313
340
  },
314
341
  "required": [
@@ -316,7 +343,8 @@
316
343
  "addressLocality",
317
344
  "addressCountry"
318
345
  ],
319
- "additionalProperties": false
346
+ "additionalProperties": false,
347
+ "description": "schema.org `PostalAddress` field names, so JSON-LD generation is lossless."
320
348
  },
321
349
  "geo": {
322
350
  "type": "object",
@@ -407,7 +435,8 @@
407
435
  "type": "string"
408
436
  }
409
437
  }
410
- ]
438
+ ],
439
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
411
440
  },
412
441
  "areaServed": {
413
442
  "type": "array",
@@ -442,6 +471,7 @@
442
471
  }
443
472
  },
444
473
  "services": {
474
+ "description": "Services offered (schema.org Service/Offer): name, description, slug, price offers.",
445
475
  "type": "object",
446
476
  "propertyNames": {
447
477
  "type": "string"
@@ -463,7 +493,8 @@
463
493
  "type": "string"
464
494
  }
465
495
  }
466
- ]
496
+ ],
497
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
467
498
  },
468
499
  "description": {
469
500
  "anyOf": [
@@ -479,7 +510,8 @@
479
510
  "type": "string"
480
511
  }
481
512
  }
482
- ]
513
+ ],
514
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
483
515
  },
484
516
  "slug": {
485
517
  "anyOf": [
@@ -495,7 +527,8 @@
495
527
  "type": "string"
496
528
  }
497
529
  }
498
- ]
530
+ ],
531
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
499
532
  },
500
533
  "offers": {
501
534
  "type": "array",
@@ -516,7 +549,8 @@
516
549
  "type": "string"
517
550
  }
518
551
  }
519
- ]
552
+ ],
553
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
520
554
  },
521
555
  "price": {
522
556
  "anyOf": [
@@ -559,6 +593,7 @@
559
593
  }
560
594
  },
561
595
  "links": {
596
+ "description": "Public profile URLs (also feed JSON-LD `sameAs` via `organization.sameAs`).",
562
597
  "type": "object",
563
598
  "properties": {
564
599
  "googleMaps": {
@@ -593,6 +628,7 @@
593
628
  "additionalProperties": false
594
629
  },
595
630
  "dns": {
631
+ "description": "Desired DNS state per domain (provider, nameservers, records) — declarative reference, not applied automatically.",
596
632
  "type": "object",
597
633
  "propertyNames": {
598
634
  "type": "string"
@@ -656,6 +692,7 @@
656
692
  }
657
693
  },
658
694
  "cloudflare": {
695
+ "description": "Deliberate escape hatch for provider-specific Cloudflare settings — out of scope to model here.",
659
696
  "type": "object",
660
697
  "propertyNames": {
661
698
  "type": "string"
@@ -672,19 +709,24 @@
672
709
  "properties": {
673
710
  "url": {
674
711
  "type": "string",
675
- "format": "uri"
712
+ "format": "uri",
713
+ "description": "Public origin of this environment."
676
714
  },
677
715
  "api": {
716
+ "description": "API origin, when different from `url`.",
678
717
  "type": "string",
679
718
  "format": "uri"
680
719
  },
681
720
  "analytics": {
721
+ "description": "Whether analytics fire in this environment.",
682
722
  "type": "boolean"
683
723
  },
684
724
  "robots": {
725
+ "description": "Robots policy (e.g. \"noindex,nofollow\" for dev).",
685
726
  "type": "string"
686
727
  },
687
728
  "variant": {
729
+ "description": "Active `abTesting.variants` key for this environment.",
688
730
  "type": "string"
689
731
  }
690
732
  },
@@ -692,9 +734,11 @@
692
734
  "url"
693
735
  ],
694
736
  "additionalProperties": false
695
- }
737
+ },
738
+ "description": "Deploy environments (production, dev, …): URL, API origin, analytics toggle, robots policy, active A/B variant."
696
739
  },
697
740
  "abTesting": {
741
+ "description": "A/B testing: cookie-based split plus named variants whose `overrides` patch the config per environment.",
698
742
  "type": "object",
699
743
  "properties": {
700
744
  "enabled": {
@@ -704,16 +748,19 @@
704
748
  "type": "string"
705
749
  },
706
750
  "cookieMaxAge": {
751
+ "description": "Seconds.",
707
752
  "type": "integer",
708
753
  "exclusiveMinimum": 0,
709
754
  "maximum": 9007199254740991
710
755
  },
711
756
  "splitRatio": {
757
+ "description": "Fraction of traffic sent to the variant (0–1).",
712
758
  "type": "number",
713
759
  "minimum": 0,
714
760
  "maximum": 1
715
761
  },
716
762
  "variants": {
763
+ "description": "Named variants; each targets an environment and may deep-merge config `overrides`.",
717
764
  "type": "object",
718
765
  "propertyNames": {
719
766
  "type": "string"
@@ -756,6 +803,7 @@
756
803
  "type": "object",
757
804
  "properties": {
758
805
  "$schema": {
806
+ "description": "URL of the published JSON Schema (stamped by `vitops init`) so editors provide autocomplete + validation.",
759
807
  "type": "string"
760
808
  },
761
809
  "colors": {
@@ -772,7 +820,8 @@
772
820
  "type": "object",
773
821
  "properties": {
774
822
  "seed": {
775
- "type": "string"
823
+ "type": "string",
824
+ "description": "Seed colour (hex or oklch()). An 11-step numeric scale (50…950, tinted near-white → tinted near-black) is generated in OKLCH from it; the seed is preserved at its natural step."
776
825
  },
777
826
  "anchors": {
778
827
  "type": "object",
@@ -781,13 +830,15 @@
781
830
  },
782
831
  "additionalProperties": {
783
832
  "type": "string"
784
- }
833
+ },
834
+ "description": "Step → colour overrides (hex or oklch()) that pin specific steps of the generated scale; the remaining steps interpolate around them."
785
835
  }
786
836
  },
787
837
  "required": [
788
838
  "seed"
789
839
  ],
790
- "additionalProperties": false
840
+ "additionalProperties": false,
841
+ "description": "Seeded hue: the 11-step scale is GENERATED in OKLCH from `seed` (anchors pin specific steps)."
791
842
  },
792
843
  {
793
844
  "type": "object",
@@ -809,15 +860,18 @@
809
860
  "type": "string"
810
861
  }
811
862
  }
812
- ]
863
+ ],
864
+ "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."
813
865
  }
814
866
  },
815
867
  "required": [
816
868
  "tones"
817
869
  ],
818
- "additionalProperties": false
870
+ "additionalProperties": false,
871
+ "description": "Fixed hue: authored brand tones used verbatim; no generation."
819
872
  }
820
- ]
873
+ ],
874
+ "description": "A palette hue, authored one of two ways: `{ seed, anchors? }` generates an 11-step numeric OKLCH scale (50…950) from the seed, or `{ tones }` supplies a fixed brand kit used verbatim."
821
875
  }
822
876
  },
823
877
  "roles": {
@@ -847,6 +901,7 @@
847
901
  "additionalProperties": false
848
902
  },
849
903
  "shadows": {
904
+ "description": "Named shadows → `--shadow-<name>` tokens and `.drop-shadow-<name>` utilities. Values are shadow parameter lists (offset/blur/colour), applied via `filter: drop-shadow(…)`.",
850
905
  "type": "object",
851
906
  "propertyNames": {
852
907
  "type": "string"
@@ -856,6 +911,7 @@
856
911
  }
857
912
  },
858
913
  "fonts": {
914
+ "description": "Raw font stacks by name, emitted as `--font-<name>` tokens (referenced by `typography.families`).",
859
915
  "type": "object",
860
916
  "propertyNames": {
861
917
  "type": "string"
@@ -865,40 +921,51 @@
865
921
  }
866
922
  },
867
923
  "typeScale": {
924
+ "description": "Fluid modular TYPE scale → `--text-<name>` tokens, consumed by typography roles and text-size utilities.",
868
925
  "type": "object",
869
926
  "properties": {
870
927
  "base": {
871
- "type": "string"
928
+ "type": "string",
929
+ "description": "Anchor size (a CSS length, e.g. \"1rem\") — the value at `baseStep`."
872
930
  },
873
931
  "ratio": {
874
- "type": "number"
932
+ "type": "number",
933
+ "description": "Modular ratio between adjacent steps at large viewports."
875
934
  },
876
935
  "steps": {
936
+ "description": "Token count when `names` is absent (steps are then named 1..steps).",
877
937
  "type": "number"
878
938
  },
879
939
  "names": {
940
+ "description": "Step names, smallest → largest (e.g. [\"xs\",\"sm\",\"md\",…]); each becomes a token suffix.",
880
941
  "type": "array",
881
942
  "items": {
882
943
  "type": "string"
883
944
  }
884
945
  },
885
946
  "baseStep": {
947
+ "description": "1-based index of the step whose value is `base`.",
886
948
  "type": "number"
887
949
  },
888
950
  "baseline": {
951
+ "description": "Named step used as the fluid pivot / GUI scale centre (defaults to `baseStep`).",
889
952
  "type": "string"
890
953
  },
891
954
  "fluid": {
955
+ "description": "Makes the scale fluid: each step compiles to a clamp() that interpolates from `minRatio` at `minVw` to `ratio` at `maxVw`.",
892
956
  "type": "object",
893
957
  "properties": {
894
958
  "minVw": {
895
- "type": "string"
959
+ "type": "string",
960
+ "description": "Viewport width (CSS length) where fluid scaling bottoms out."
896
961
  },
897
962
  "maxVw": {
898
- "type": "string"
963
+ "type": "string",
964
+ "description": "Viewport width (CSS length) where fluid scaling tops out."
899
965
  },
900
966
  "minRatio": {
901
- "type": "number"
967
+ "type": "number",
968
+ "description": "Modular ratio at/below `minVw` (usually < `ratio`)."
902
969
  }
903
970
  },
904
971
  "required": [
@@ -916,40 +983,51 @@
916
983
  "additionalProperties": false
917
984
  },
918
985
  "spaceScale": {
986
+ "description": "Fluid modular SPACE scale → `--space-<name>` tokens, consumed by spacing/gap utilities and vertical rhythm.",
919
987
  "type": "object",
920
988
  "properties": {
921
989
  "base": {
922
- "type": "string"
990
+ "type": "string",
991
+ "description": "Anchor size (a CSS length, e.g. \"1rem\") — the value at `baseStep`."
923
992
  },
924
993
  "ratio": {
925
- "type": "number"
994
+ "type": "number",
995
+ "description": "Modular ratio between adjacent steps at large viewports."
926
996
  },
927
997
  "steps": {
998
+ "description": "Token count when `names` is absent (steps are then named 1..steps).",
928
999
  "type": "number"
929
1000
  },
930
1001
  "names": {
1002
+ "description": "Step names, smallest → largest (e.g. [\"xs\",\"sm\",\"md\",…]); each becomes a token suffix.",
931
1003
  "type": "array",
932
1004
  "items": {
933
1005
  "type": "string"
934
1006
  }
935
1007
  },
936
1008
  "baseStep": {
1009
+ "description": "1-based index of the step whose value is `base`.",
937
1010
  "type": "number"
938
1011
  },
939
1012
  "baseline": {
1013
+ "description": "Named step used as the fluid pivot / GUI scale centre (defaults to `baseStep`).",
940
1014
  "type": "string"
941
1015
  },
942
1016
  "fluid": {
1017
+ "description": "Makes the scale fluid: each step compiles to a clamp() that interpolates from `minRatio` at `minVw` to `ratio` at `maxVw`.",
943
1018
  "type": "object",
944
1019
  "properties": {
945
1020
  "minVw": {
946
- "type": "string"
1021
+ "type": "string",
1022
+ "description": "Viewport width (CSS length) where fluid scaling bottoms out."
947
1023
  },
948
1024
  "maxVw": {
949
- "type": "string"
1025
+ "type": "string",
1026
+ "description": "Viewport width (CSS length) where fluid scaling tops out."
950
1027
  },
951
1028
  "minRatio": {
952
- "type": "number"
1029
+ "type": "number",
1030
+ "description": "Modular ratio at/below `minVw` (usually < `ratio`)."
953
1031
  }
954
1032
  },
955
1033
  "required": [
@@ -976,7 +1054,8 @@
976
1054
  },
977
1055
  "additionalProperties": {
978
1056
  "type": "string"
979
- }
1057
+ },
1058
+ "description": "Cascade-wide fallback tokens, emitted as `--<prop>-default`."
980
1059
  },
981
1060
  "radii": {
982
1061
  "type": "object",
@@ -985,9 +1064,11 @@
985
1064
  },
986
1065
  "additionalProperties": {
987
1066
  "type": "string"
988
- }
1067
+ },
1068
+ "description": "Shape primitives, emitted as `--br-<name>` (referenced by pattern bases)."
989
1069
  },
990
1070
  "groups": {
1071
+ "description": "Group-level tokens, emitted as `--<prop>-<group>`; patterns opt in via their `group` key.",
991
1072
  "type": "object",
992
1073
  "propertyNames": {
993
1074
  "type": "string"
@@ -999,10 +1080,12 @@
999
1080
  },
1000
1081
  "additionalProperties": {
1001
1082
  "type": "string"
1002
- }
1083
+ },
1084
+ "description": "A CSS declaration block: property → value. Values stay strings (they can be hex, var(), clamp(), keywords, …); the generator, not the schema, interprets them."
1003
1085
  }
1004
1086
  },
1005
1087
  "z": {
1088
+ "description": "Z-index tiers → `--z-tier-<name>`.",
1006
1089
  "type": "object",
1007
1090
  "propertyNames": {
1008
1091
  "type": "string"
@@ -1012,6 +1095,7 @@
1012
1095
  }
1013
1096
  },
1014
1097
  "items": {
1098
+ "description": "The component patterns to emit, keyed by name.",
1015
1099
  "type": "object",
1016
1100
  "propertyNames": {
1017
1101
  "type": "string"
@@ -1020,6 +1104,7 @@
1020
1104
  "type": "object",
1021
1105
  "properties": {
1022
1106
  "group": {
1107
+ "description": "Token-cascade group this pattern belongs to (e.g. tag / control / panel); base declarations resolve through `--<prop>-<group>` before `--<prop>-default`.",
1023
1108
  "type": "string"
1024
1109
  },
1025
1110
  "overrides": {
@@ -1029,15 +1114,19 @@
1029
1114
  },
1030
1115
  "additionalProperties": {
1031
1116
  "type": "string"
1032
- }
1117
+ },
1118
+ "description": "Per-pattern token overrides, emitted as `--<prop>-<name>-group` values."
1033
1119
  },
1034
1120
  "element": {
1121
+ "description": "Style at element level via zero-specificity `:where(<element>)` (instead of, or alongside, a class).",
1035
1122
  "type": "string"
1036
1123
  },
1037
1124
  "class": {
1125
+ "description": "Class name to emit (defaults to the pattern's key).",
1038
1126
  "type": "string"
1039
1127
  },
1040
1128
  "default_role": {
1129
+ "description": "Semantic colour role applied to the bare/default variant.",
1041
1130
  "type": "string"
1042
1131
  },
1043
1132
  "base": {
@@ -1047,9 +1136,11 @@
1047
1136
  },
1048
1137
  "additionalProperties": {
1049
1138
  "type": "string"
1050
- }
1139
+ },
1140
+ "description": "Base CSS declarations. Geometry properties (padding, border-radius, border, box-shadow, font-size) are wrapped in per-pattern override hooks (`--p-<name>`, `--br-<name>`, `--b-<name>`, `--ds-<name>`, `--fs-<name>`) so consumers can restyle one pattern by setting one variable."
1051
1141
  },
1052
1142
  "states": {
1143
+ "description": "Interaction states (hover / active / focus-visible), each a map of shortcuts: `step` (intensify fills/text by n emphasis stops), `scale` (transform scale), `lift` (translateY + shadow), `shadow` (a shadow name → drop-shadow(var(--shadow-<name>)), or true → lift shadow), `ring` (focus ring), or raw `css` declarations. Hover rules are wrapped in `@media (hover: hover)`.",
1053
1144
  "type": "object",
1054
1145
  "propertyNames": {
1055
1146
  "type": "string"
@@ -1063,22 +1154,26 @@
1063
1154
  }
1064
1155
  },
1065
1156
  "roles": {
1157
+ "description": "Semantic colour role variants to emit as `<pattern>-<role>` classes (fills use the role solid / on-solid tokens).",
1066
1158
  "type": "array",
1067
1159
  "items": {
1068
1160
  "type": "string"
1069
1161
  }
1070
1162
  }
1071
1163
  },
1072
- "additionalProperties": false
1164
+ "additionalProperties": false,
1165
+ "description": "One component pattern (button, link, badge, card, …): base declarations + interaction states + semantic role variants, resolved through the pattern token cascade."
1073
1166
  }
1074
1167
  }
1075
1168
  },
1076
- "additionalProperties": false
1169
+ "additionalProperties": false,
1170
+ "description": "Component patterns and their token cascade: `defaults` → `groups` → per-pattern `overrides`, plus shape (`radii`) and z-index primitives."
1077
1171
  },
1078
1172
  "typography": {
1079
1173
  "type": "object",
1080
1174
  "properties": {
1081
1175
  "families": {
1176
+ "description": "Role-facing family aliases → CSS font values, usually referencing the top-level `fonts` tokens (e.g. \"var(--font-display)\").",
1082
1177
  "type": "object",
1083
1178
  "propertyNames": {
1084
1179
  "type": "string"
@@ -1088,6 +1183,7 @@
1088
1183
  }
1089
1184
  },
1090
1185
  "roles": {
1186
+ "description": "Semantic type roles (display, title, heading, body, quote, caption, eyebrow, code, lead, footnote, tag, …), each emitted as a `font-<role>` class.",
1091
1187
  "type": "object",
1092
1188
  "propertyNames": {
1093
1189
  "type": "string"
@@ -1106,10 +1202,12 @@
1106
1202
  "type": "number"
1107
1203
  }
1108
1204
  ]
1109
- }
1205
+ },
1206
+ "description": "An open bag of CSS-ish keys (family / size / weight / line-height / tracking / transform / decoration / text-wrap / …); the generator maps known keys and passes the rest through."
1110
1207
  }
1111
1208
  },
1112
1209
  "headings": {
1210
+ "description": "Maps heading elements (h1…h6) to type roles so bare headings pick up role styling.",
1113
1211
  "type": "object",
1114
1212
  "propertyNames": {
1115
1213
  "type": "string"
@@ -1119,12 +1217,14 @@
1119
1217
  }
1120
1218
  }
1121
1219
  },
1122
- "additionalProperties": false
1220
+ "additionalProperties": false,
1221
+ "description": "Typography: family aliases, semantic type roles (→ `font-<role>` classes), and the heading-element → role mapping."
1123
1222
  },
1124
1223
  "animations": {
1125
1224
  "type": "object",
1126
1225
  "properties": {
1127
1226
  "effects": {
1227
+ "description": "Effect classes to emit (`.fade-in`, `.reveal-left`, …), keyed by class name.",
1128
1228
  "type": "object",
1129
1229
  "propertyNames": {
1130
1230
  "type": "string"
@@ -1133,7 +1233,8 @@
1133
1233
  "type": "object",
1134
1234
  "properties": {
1135
1235
  "kf": {
1136
- "type": "string"
1236
+ "type": "string",
1237
+ "description": "Keyframe family driving the effect: composite (transform/opacity), paint, or layout."
1137
1238
  },
1138
1239
  "css": {
1139
1240
  "type": "object",
@@ -1149,7 +1250,8 @@
1149
1250
  "type": "number"
1150
1251
  }
1151
1252
  ]
1152
- }
1253
+ },
1254
+ "description": "Extra literal declarations merged into the effect class as-is."
1153
1255
  },
1154
1256
  "vars": {
1155
1257
  "type": "object",
@@ -1165,19 +1267,23 @@
1165
1267
  "type": "number"
1166
1268
  }
1167
1269
  ]
1168
- }
1270
+ },
1271
+ "description": "Effect endpoint variables (`--<key>: <value>`, e.g. opacity-from, translate-y-to) that override the keyframe defaults."
1169
1272
  }
1170
1273
  },
1171
1274
  "required": [
1172
1275
  "kf"
1173
1276
  ],
1174
- "additionalProperties": false
1277
+ "additionalProperties": false,
1278
+ "description": "A named animation effect class — a pure value layer (`--_anim` + `--<prop>-from/-to`) over the static keyframe engine."
1175
1279
  }
1176
1280
  },
1177
1281
  "journeys": {
1282
+ "description": "Multi-part journey classes composed from `base` building blocks.",
1178
1283
  "type": "object",
1179
1284
  "properties": {
1180
1285
  "base": {
1286
+ "description": "Named journey building blocks: part name → var map.",
1181
1287
  "type": "object",
1182
1288
  "propertyNames": {
1183
1289
  "type": "string"
@@ -1200,6 +1306,7 @@
1200
1306
  }
1201
1307
  },
1202
1308
  "compose": {
1309
+ "description": "Combinations of base parts, each emitted as a `.<parts>-journey` class.",
1203
1310
  "type": "array",
1204
1311
  "items": {
1205
1312
  "type": "array",
@@ -1212,9 +1319,11 @@
1212
1319
  "additionalProperties": false
1213
1320
  }
1214
1321
  },
1215
- "additionalProperties": false
1322
+ "additionalProperties": false,
1323
+ "description": "Animation effect + journey classes (pure value layers). The animation engine itself — keyframes, drivers, floats, utilities — is static framework CSS, not configured here."
1216
1324
  },
1217
1325
  "displayName": {
1326
+ "description": "Human-readable theme name (localisable).",
1218
1327
  "anyOf": [
1219
1328
  {
1220
1329
  "type": "string"
@@ -1231,16 +1340,20 @@
1231
1340
  ]
1232
1341
  },
1233
1342
  "extends": {
1343
+ "description": "Another `designSystem` key to inherit from; this entry then only supplies what it overrides.",
1234
1344
  "type": "string"
1235
1345
  }
1236
1346
  },
1237
1347
  "additionalProperties": false
1238
- }
1348
+ },
1349
+ "description": "Named-theme map of design systems. `default` is the base; other entries may `extends` another and supply a partial patch. Light/dark is automatic (functional tokens flip per appearance), not a separate theme entry. A bare design system (with `colors`) is shorthand for `{ default: … }`."
1239
1350
  },
1240
1351
  "defaultTheme": {
1352
+ "description": "Which `designSystem` entry to use by default (convention: \"default\").",
1241
1353
  "type": "string"
1242
1354
  },
1243
1355
  "defaultColorScheme": {
1356
+ "description": "Initial appearance to render before any user/system preference applies.",
1244
1357
  "type": "string",
1245
1358
  "enum": [
1246
1359
  "light",
@@ -1248,9 +1361,11 @@
1248
1361
  ]
1249
1362
  },
1250
1363
  "respectSystemPreference": {
1364
+ "description": "Follow the user's OS light/dark preference.",
1251
1365
  "type": "boolean"
1252
1366
  },
1253
1367
  "fonts": {
1368
+ "description": "Font LOADING (a serialisable projection of the Astro Fonts API: provider, weights, subsets, preload). Font TOKENS live in `designSystem.<theme>.fonts` and reference the same `cssVariable`.",
1254
1369
  "type": "array",
1255
1370
  "items": {
1256
1371
  "type": "object",
@@ -1387,6 +1502,7 @@
1387
1502
  }
1388
1503
  },
1389
1504
  "preload": {
1505
+ "description": "Emit `<Font preload />` for this family (true, or a list of weight/style faces).",
1390
1506
  "anyOf": [
1391
1507
  {
1392
1508
  "type": "boolean"
@@ -1432,6 +1548,7 @@
1432
1548
  }
1433
1549
  },
1434
1550
  "tags": {
1551
+ "description": "Free-form content-tag taxonomy (site-specific; not interpreted by the generator).",
1435
1552
  "type": "object",
1436
1553
  "propertyNames": {
1437
1554
  "type": "string"
@@ -1439,6 +1556,7 @@
1439
1556
  "additionalProperties": {}
1440
1557
  },
1441
1558
  "postTypes": {
1559
+ "description": "Free-form content-type definitions (site-specific; not interpreted by the generator).",
1442
1560
  "type": "object",
1443
1561
  "propertyNames": {
1444
1562
  "type": "string"
@@ -1446,6 +1564,7 @@
1446
1564
  "additionalProperties": {}
1447
1565
  },
1448
1566
  "galleries": {
1567
+ "description": "Named image galleries (title, tags, images with localisable alt/caption).",
1449
1568
  "type": "object",
1450
1569
  "propertyNames": {
1451
1570
  "type": "string"
@@ -1467,7 +1586,8 @@
1467
1586
  "type": "string"
1468
1587
  }
1469
1588
  }
1470
- ]
1589
+ ],
1590
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
1471
1591
  },
1472
1592
  "tags": {
1473
1593
  "type": "array",
@@ -1497,7 +1617,8 @@
1497
1617
  "type": "string"
1498
1618
  }
1499
1619
  }
1500
- ]
1620
+ ],
1621
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
1501
1622
  },
1502
1623
  "caption": {
1503
1624
  "anyOf": [
@@ -1513,7 +1634,8 @@
1513
1634
  "type": "string"
1514
1635
  }
1515
1636
  }
1516
- ]
1637
+ ],
1638
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
1517
1639
  }
1518
1640
  },
1519
1641
  "required": [
@@ -1531,6 +1653,7 @@
1531
1653
  }
1532
1654
  },
1533
1655
  "testimonials": {
1656
+ "description": "Named testimonial groups (quote, name, role, rating, date).",
1534
1657
  "type": "object",
1535
1658
  "propertyNames": {
1536
1659
  "type": "string"
@@ -1552,7 +1675,8 @@
1552
1675
  "type": "string"
1553
1676
  }
1554
1677
  }
1555
- ]
1678
+ ],
1679
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
1556
1680
  },
1557
1681
  "items": {
1558
1682
  "type": "array",
@@ -1573,7 +1697,8 @@
1573
1697
  "type": "string"
1574
1698
  }
1575
1699
  }
1576
- ]
1700
+ ],
1701
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
1577
1702
  },
1578
1703
  "name": {
1579
1704
  "type": "string"
@@ -1606,6 +1731,7 @@
1606
1731
  }
1607
1732
  },
1608
1733
  "templates": {
1734
+ "description": "Named content templates rendered at SSR time: `nav` (menu trees), `form` (field lists + submit), or `nodes` (raw element trees).",
1609
1735
  "type": "object",
1610
1736
  "propertyNames": {
1611
1737
  "type": "string"
@@ -1714,7 +1840,8 @@
1714
1840
  "type": "string"
1715
1841
  }
1716
1842
  }
1717
- ]
1843
+ ],
1844
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
1718
1845
  },
1719
1846
  "required": {
1720
1847
  "type": "boolean"
@@ -1832,15 +1959,19 @@
1832
1959
  }
1833
1960
  },
1834
1961
  "navigation": {
1962
+ "description": "Site navigation settings (which nav template renders where).",
1835
1963
  "type": "object",
1836
1964
  "properties": {
1837
1965
  "activeTemplate": {
1966
+ "description": "Which nav template is active, optionally per breakpoint.",
1838
1967
  "type": "object",
1839
1968
  "properties": {
1840
1969
  "default": {
1970
+ "description": "A `templates` key.",
1841
1971
  "type": "string"
1842
1972
  },
1843
1973
  "breakpoints": {
1974
+ "description": "Breakpoint name → `templates` key overrides.",
1844
1975
  "type": "object",
1845
1976
  "propertyNames": {
1846
1977
  "type": "string"
@@ -1856,15 +1987,18 @@
1856
1987
  "additionalProperties": false
1857
1988
  },
1858
1989
  "seo": {
1990
+ "description": "SEO defaults: title/description templates, robots policy, verification tokens, Open Graph + Twitter cards.",
1859
1991
  "type": "object",
1860
1992
  "properties": {
1861
1993
  "titleTemplate": {
1994
+ "description": "Page-title pattern (e.g. \"%s · Acme\").",
1862
1995
  "type": "string"
1863
1996
  },
1864
1997
  "descriptionTemplate": {
1865
1998
  "type": "string"
1866
1999
  },
1867
2000
  "robots": {
2001
+ "description": "e.g. \"index,follow\" / \"noindex,nofollow\".",
1868
2002
  "type": "string"
1869
2003
  },
1870
2004
  "googleSiteVerification": {
@@ -1896,7 +2030,8 @@
1896
2030
  "type": "string"
1897
2031
  }
1898
2032
  }
1899
- ]
2033
+ ],
2034
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
1900
2035
  },
1901
2036
  "description": {
1902
2037
  "anyOf": [
@@ -1912,7 +2047,8 @@
1912
2047
  "type": "string"
1913
2048
  }
1914
2049
  }
1915
- ]
2050
+ ],
2051
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
1916
2052
  },
1917
2053
  "image": {
1918
2054
  "anyOf": [
@@ -1981,7 +2117,8 @@
1981
2117
  "type": "string"
1982
2118
  }
1983
2119
  }
1984
- ]
2120
+ ],
2121
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
1985
2122
  },
1986
2123
  "description": {
1987
2124
  "anyOf": [
@@ -1997,7 +2134,8 @@
1997
2134
  "type": "string"
1998
2135
  }
1999
2136
  }
2000
- ]
2137
+ ],
2138
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
2001
2139
  },
2002
2140
  "image": {
2003
2141
  "anyOf": [
@@ -2035,6 +2173,7 @@
2035
2173
  "additionalProperties": false
2036
2174
  },
2037
2175
  "analytics": {
2176
+ "description": "Analytics provider IDs (gated per environment via `environments.<env>.analytics`).",
2038
2177
  "type": "object",
2039
2178
  "properties": {
2040
2179
  "googleAnalyticsId": {
@@ -2050,6 +2189,7 @@
2050
2189
  "additionalProperties": false
2051
2190
  },
2052
2191
  "notifications": {
2192
+ "description": "Where site notifications (e.g. form submissions) are sent.",
2053
2193
  "type": "object",
2054
2194
  "properties": {
2055
2195
  "email": {
@@ -2061,6 +2201,7 @@
2061
2201
  "additionalProperties": false
2062
2202
  },
2063
2203
  "tracking": {
2204
+ "description": "Marketing/conversion tracking toggles per platform.",
2064
2205
  "type": "object",
2065
2206
  "properties": {
2066
2207
  "enabled": {
@@ -2076,12 +2217,14 @@
2076
2217
  "additionalProperties": false
2077
2218
  },
2078
2219
  "security": {
2220
+ "description": "Security integrations (bot protection).",
2079
2221
  "type": "object",
2080
2222
  "properties": {
2081
2223
  "turnstile": {
2082
2224
  "type": "object",
2083
2225
  "properties": {
2084
2226
  "siteKey": {
2227
+ "description": "Cloudflare Turnstile site key (public).",
2085
2228
  "type": "string"
2086
2229
  }
2087
2230
  },
@@ -2091,6 +2234,7 @@
2091
2234
  "additionalProperties": false
2092
2235
  },
2093
2236
  "legal": {
2237
+ "description": "Legal pages + cookie-consent configuration.",
2094
2238
  "type": "object",
2095
2239
  "properties": {
2096
2240
  "privacyPolicy": {
@@ -2147,6 +2291,7 @@
2147
2291
  "type": "boolean"
2148
2292
  },
2149
2293
  "type": {
2294
+ "description": "Consent model.",
2150
2295
  "type": "string",
2151
2296
  "enum": [
2152
2297
  "opt-in",
@@ -2177,15 +2322,19 @@
2177
2322
  "additionalProperties": false
2178
2323
  },
2179
2324
  "icons": {
2325
+ "description": "Icon sets and the specific icons to bundle from each (keys are iconify collection names).",
2180
2326
  "type": "object",
2181
2327
  "properties": {
2182
2328
  "ui": {
2329
+ "description": "Icon set used for UI chrome (e.g. \"lucide\").",
2183
2330
  "type": "string"
2184
2331
  },
2185
2332
  "brand": {
2333
+ "description": "Icon set used for brand marks.",
2186
2334
  "type": "string"
2187
2335
  },
2188
2336
  "semantic": {
2337
+ "description": "Named semantic icons to include.",
2189
2338
  "type": "array",
2190
2339
  "items": {
2191
2340
  "type": "string"
@@ -2243,21 +2392,27 @@
2243
2392
  "additionalProperties": false
2244
2393
  },
2245
2394
  "favicon": {
2395
+ "description": "Favicon/PWA asset generation (consumed by `@getvitops/utils` favicon tooling).",
2246
2396
  "type": "object",
2247
2397
  "properties": {
2248
2398
  "source": {
2249
- "type": "string"
2399
+ "type": "string",
2400
+ "description": "Source image (SVG/PNG) the favicon set is generated from."
2250
2401
  },
2251
2402
  "lowResSource": {
2403
+ "description": "Alternate source for small raster sizes (16/32px) when the main source scales down poorly.",
2252
2404
  "type": "string"
2253
2405
  },
2254
2406
  "name": {
2407
+ "description": "App name for the generated web manifest / PWA.",
2255
2408
  "type": "string"
2256
2409
  },
2257
2410
  "themeColor": {
2411
+ "description": "PWA theme color (also `<meta name=\"theme-color\">`).",
2258
2412
  "type": "string"
2259
2413
  },
2260
2414
  "backgroundColor": {
2415
+ "description": "PWA background color.",
2261
2416
  "type": "string"
2262
2417
  }
2263
2418
  },
@@ -2267,6 +2422,7 @@
2267
2422
  "additionalProperties": false
2268
2423
  },
2269
2424
  "deployment": {
2425
+ "description": "How the site is built and deployed (platform, commands, output directory) — informational for tooling.",
2270
2426
  "type": "object",
2271
2427
  "properties": {
2272
2428
  "platform": {
@@ -2313,7 +2469,8 @@
2313
2469
  "type": "string"
2314
2470
  }
2315
2471
  }
2316
- ]
2472
+ ],
2473
+ "description": "A string, or a per-locale map of strings (`{ en: \"…\", fr: \"…\" }`)."
2317
2474
  },
2318
2475
  "image": {
2319
2476
  "anyOf": [