@scattered-light/loomiere 0.0.0-stage → 0.1.1

package/generator/brand.schema.json

@@ -0,0 +1,657 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Brand inputs",
+  "description": "The small set of answers that defines a theme. generator/generate.mjs turns these into primitive tokens.",
+  "type": "object",
+  "required": [
+    "name",
+    "space",
+    "color",
+    "type",
+    "radius",
+    "stroke",
+    "elevation",
+    "motion"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string",
+      "description": "Brand id, used in file names and build output."
+    },
+    "description": {
+      "type": "string"
+    },
+    "space": {
+      "type": "object",
+      "description": "Spacing is the unit times each step. Token names are unit counts, so space-4 is 4 units whatever the unit is.",
+      "required": [
+        "unit",
+        "steps"
+      ],
+      "properties": {
+        "unit": {
+          "type": "number",
+          "description": "Smallest spacing unit in px (e.g. 3 or 4)."
+        },
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "number"
+          },
+          "description": "Multipliers of the unit to emit. Halves become names like space-0-5."
+        }
+      }
+    },
+    "color": {
+      "type": "object",
+      "required": [
+        "paper",
+        "ink",
+        "contrast",
+        "palettes"
+      ],
+      "properties": {
+        "paper": {
+          "type": "string",
+          "description": "The lightest color (usually white). Becomes color.white; every step is measured against it."
+        },
+        "ink": {
+          "type": "string",
+          "description": "The darkest color (usually black). Becomes color.black and the dark end of every ramp."
+        },
+        "contrast": {
+          "type": "object",
+          "description": "Named contrast tables. Each step sits where its contrast against paper equals its target, so the same step means the same contrast in every palette.",
+          "additionalProperties": {
+            "type": "object",
+            "required": [
+              "targets"
+            ],
+            "properties": {
+              "targets": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "number"
+                },
+                "description": "Step \u2192 WCAG contrast ratio against paper, lightest first. Keep the lightest above 1 so it is never white."
+              },
+              "locked": {
+                "type": "array",
+                "items": {
+                  "type": "integer"
+                },
+                "description": "Steps that keys may never take, e.g. 500 stays at 4.5:1 so it always passes AA."
+              }
+            }
+          }
+        },
+        "palettes": {
+          "type": "object",
+          "description": "Role name \u2192 palette. Roles (neutral, primary, \u2026) are what tokens are named after, so brands are interchangeable.",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "label": {
+                "type": "string",
+                "description": "The brand's own name for the palette (e.g. stone). Shown in descriptions only."
+              },
+              "keys": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Brand colors the ramp passes through, in any order. One is enough; add a light and a dark key to bend the ramp the way the brand does."
+              },
+              "exact": {
+                "type": "boolean",
+                "description": "Put each key in the palette as-is, on the step nearest its contrast (never on a locked step). Off by default, as in Leonardo, where keys only shape the ramp."
+              },
+              "contrast": {
+                "type": "string",
+                "description": "Which contrast table to use. Defaults to \"spot\"."
+              },
+              "darkest": {
+                "type": "string",
+                "description": "Where this palette ends, if not at ink. Use it when the brand has its own tinted black for this color, e.g. a deep plum for a purple. Steps darker than it can reach land on it."
+              },
+              "tone": {
+                "type": "object",
+                "required": [
+                  "color",
+                  "intensity"
+                ],
+                "description": "Tints the ramp like a transparent color layered over a grayscale. Used for neutrals.",
+                "properties": {
+                  "color": {
+                    "type": "string",
+                    "description": "The tone color, usually a brand color or its complement."
+                  },
+                  "intensity": {
+                    "oneOf": [
+                      {
+                        "type": "number"
+                      },
+                      {
+                        "type": "array",
+                        "prefixItems": [
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "number"
+                          }
+                        ]
+                      }
+                    ],
+                    "description": "Opacity of the tone, 0\u20131. A [light, dark] pair changes along the ramp on a log curve, e.g. [0.1, 0.6] keeps the lights clean and the darks rich."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "pairs": {
+          "type": "object",
+          "description": "Brand pairs: named background/text combinations that pass AA. Each becomes pair.<name>.* tokens and a .sl-pair-<name> class. Pick them with npm run lab.",
+          "propertyNames": {
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "required": [
+              "bg",
+              "fg"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "bg": {
+                "type": "string",
+                "pattern": "^(white|black|paper|ink|[a-z]+\\.[0-9]+)$",
+                "description": "Background. A palette color as role.step (\"secondary.600\"), or white/black for paper and ink."
+              },
+              "fg": {
+                "type": "string",
+                "pattern": "^(white|black|paper|ink|[a-z]+\\.[0-9]+)$",
+                "description": "Text, icons and strong borders. Must reach 4.5:1 on bg."
+              },
+              "accent": {
+                "type": "string",
+                "pattern": "^(white|black|paper|ink|[a-z]+\\.[0-9]+)$",
+                "description": "Links, buttons and focus rings. Must reach 4.5:1 on bg. Defaults to fg."
+              },
+              "dark": {
+                "type": "object",
+                "additionalProperties": false,
+                "description": "What changes in dark mode. Parts left out carry over.",
+                "properties": {
+                  "bg": {
+                    "type": "string",
+                    "pattern": "^(white|black|paper|ink|[a-z]+\\.[0-9]+)$",
+                    "description": "Background. A palette color as role.step (\"secondary.600\"), or white/black for paper and ink."
+                  },
+                  "fg": {
+                    "type": "string",
+                    "pattern": "^(white|black|paper|ink|[a-z]+\\.[0-9]+)$",
+                    "description": "Text, icons and strong borders. Must reach 4.5:1 on bg."
+                  },
+                  "accent": {
+                    "type": "string",
+                    "pattern": "^(white|black|paper|ink|[a-z]+\\.[0-9]+)$",
+                    "description": "Links, buttons and focus rings. Must reach 4.5:1 on bg. Defaults to fg."
+                  }
+                }
+              },
+              "description": {
+                "type": "string",
+                "description": "Why the pair exists or where it's used."
+              }
+            }
+          }
+        },
+        "data": {
+          "type": "array",
+          "description": "Categorical colors for charts, in the order they should be used: [name, hex] pairs.",
+          "items": {
+            "type": "array",
+            "prefixItems": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "string"
+              }
+            ]
+          }
+        },
+        "vision": {
+          "type": "object",
+          "description": "Color vision themes are generated from the brand's spot palettes and data colors. Pin any of their colors per theme here; the others move to make room.",
+          "properties": {
+            "deuteranopia": {
+              "type": "object",
+              "properties": {
+                "keys": {
+                  "type": "object",
+                  "description": "Per palette role, the color that stands for it (its most colorful key) in this theme. The whole palette moves with it.",
+                  "additionalProperties": {
+                    "type": "string",
+                    "pattern": "^#[0-9a-fA-F]{6}$"
+                  }
+                },
+                "data": {
+                  "type": "object",
+                  "description": "Per data color name, the color to use in this theme.",
+                  "additionalProperties": {
+                    "type": "string",
+                    "pattern": "^#[0-9a-fA-F]{6}$"
+                  }
+                }
+              }
+            },
+            "protanopia": {
+              "type": "object",
+              "properties": {
+                "keys": {
+                  "type": "object",
+                  "description": "Per palette role, the color that stands for it (its most colorful key) in this theme. The whole palette moves with it.",
+                  "additionalProperties": {
+                    "type": "string",
+                    "pattern": "^#[0-9a-fA-F]{6}$"
+                  }
+                },
+                "data": {
+                  "type": "object",
+                  "description": "Per data color name, the color to use in this theme.",
+                  "additionalProperties": {
+                    "type": "string",
+                    "pattern": "^#[0-9a-fA-F]{6}$"
+                  }
+                }
+              }
+            },
+            "tritanopia": {
+              "type": "object",
+              "properties": {
+                "keys": {
+                  "type": "object",
+                  "description": "Per palette role, the color that stands for it (its most colorful key) in this theme. The whole palette moves with it.",
+                  "additionalProperties": {
+                    "type": "string",
+                    "pattern": "^#[0-9a-fA-F]{6}$"
+                  }
+                },
+                "data": {
+                  "type": "object",
+                  "description": "Per data color name, the color to use in this theme.",
+                  "additionalProperties": {
+                    "type": "string",
+                    "pattern": "^#[0-9a-fA-F]{6}$"
+                  }
+                }
+              }
+            },
+            "achromatopsia": {
+              "type": "object",
+              "properties": {
+                "keys": {
+                  "type": "object",
+                  "description": "Per palette role, the color that stands for it (its most colorful key) in this theme. The whole palette moves with it.",
+                  "additionalProperties": {
+                    "type": "string",
+                    "pattern": "^#[0-9a-fA-F]{6}$"
+                  }
+                },
+                "data": {
+                  "type": "object",
+                  "description": "Per data color name, the color to use in this theme.",
+                  "additionalProperties": {
+                    "type": "string",
+                    "pattern": "^#[0-9a-fA-F]{6}$"
+                  }
+                }
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "type": {
+      "type": "object",
+      "description": "A modular scale: each step is the base times ratio^n. Base and up are fluid between two viewport widths; steps below the base are fixed.",
+      "required": [
+        "families",
+        "base",
+        "ratio",
+        "viewport",
+        "steps",
+        "baseStep",
+        "lineHeight"
+      ],
+      "properties": {
+        "families": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "description": "Role \u2192 font stack."
+        },
+        "base": {
+          "$ref": "#/$defs/minMax",
+          "description": "Size of the base step in px at the small and large viewport."
+        },
+        "ratio": {
+          "$ref": "#/$defs/minMax",
+          "description": "Scale ratio at each viewport (1.2 = minor third, 1.25 = major third, 1.333 = perfect fourth)."
+        },
+        "viewport": {
+          "$ref": "#/$defs/minMax",
+          "description": "Viewport widths in px where sizes stop growing or shrinking."
+        },
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Step names, smallest first."
+        },
+        "baseStep": {
+          "type": "string",
+          "description": "Which step is the base size."
+        },
+        "lineHeight": {
+          "type": "object",
+          "description": "Line height = the font's own height + leading in em. Leading eases from `text` at textStep to `heading` at headingStep; small text needs more air than headings.",
+          "required": [
+            "text",
+            "heading",
+            "textStep",
+            "headingStep"
+          ],
+          "properties": {
+            "text": {
+              "type": "number",
+              "description": "Leading in em for small text (at textStep and below)."
+            },
+            "heading": {
+              "type": "number",
+              "description": "Leading in em for headings (at headingStep and above); can be negative to tighten past the font's own height."
+            },
+            "textStep": {
+              "type": "string"
+            },
+            "headingStep": {
+              "type": "string"
+            },
+            "solidFrom": {
+              "type": "string",
+              "description": "From this step up, line height is 1 (set solid) for big display text."
+            }
+          }
+        },
+        "small": {
+          "type": "object",
+          "description": "Sizes below the base step. Fixed by default: small text has little room to shrink before it stops being readable.",
+          "properties": {
+            "fixed": {
+              "type": "boolean",
+              "description": "true (default): whole px from the ratio at the small viewport. false: fluid like the rest."
+            },
+            "floor": {
+              "type": "number",
+              "description": "Smallest size in px any step may have."
+            }
+          }
+        },
+        "metrics": {
+          "type": "object",
+          "description": "Measurements of each family role (display, body, mono). Line heights start from the font's own height (ascent + descent) so a taller font gets more room without pins. The brand builder measures them for you.",
+          "additionalProperties": {
+            "type": "object",
+            "description": "Font measurements in em, as the font file reports them.",
+            "properties": {
+              "ascent": {
+                "type": "number"
+              },
+              "descent": {
+                "type": "number"
+              },
+              "capHeight": {
+                "type": "number"
+              },
+              "xHeight": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "ascent",
+              "descent"
+            ]
+          }
+        },
+        "stepDown": {
+          "type": "boolean",
+          "description": "true: on small screens each size above the base starts at the size the step below reaches on large screens, so headings drop one step instead of shrinking by the base's ratio."
+        },
+        "displayFrom": {
+          "type": "string",
+          "description": "First step set in the display family; its line heights use the display font's measurements, smaller steps use the body font's."
+        }
+      }
+    },
+    "radius": {
+      "$ref": "#/$defs/scale",
+      "description": "Corner rounding: base radius in px times each step."
+    },
+    "stroke": {
+      "$ref": "#/$defs/scale",
+      "description": "Border widths: base width in px times each step."
+    },
+    "elevation": {
+      "type": "object",
+      "description": "Shadow color and strength. The shadow shapes are shared across brands.",
+      "properties": {
+        "shadowColor": {
+          "type": "string"
+        },
+        "strength": {
+          "type": "number",
+          "description": "Multiplies shadow opacity. 1 is the default."
+        }
+      }
+    },
+    "motion": {
+      "type": "object",
+      "description": "Durations in ms, scaled by speed. Easing curves are foundation tokens.",
+      "properties": {
+        "speed": {
+          "type": "number",
+          "description": "1 is the default. Below 1 is snappier, above 1 is calmer."
+        },
+        "durations": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "number"
+          }
+        }
+      }
+    },
+    "roles": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Which palette plays which part. Leave out for neutral chrome, primary accent and the default ladder.",
+      "properties": {
+        "chrome": {
+          "type": "string",
+          "description": "Palette for surfaces, text and borders. Usually the neutral."
+        },
+        "accent": {
+          "type": "string",
+          "description": "Palette for links, focus and the loudest actions. Any brand color; not always primary (a red brand may want a calmer accent)."
+        },
+        "emphasis": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The ladder components draw from, loudest first.",
+          "properties": {
+            "bold": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "style",
+                "color"
+              ],
+              "properties": {
+                "style": {
+                  "enum": [
+                    "solid",
+                    "soft",
+                    "outline",
+                    "ghost"
+                  ],
+                  "description": "solid: filled; soft: tinted fill; outline: border only; ghost: no fill or border until hover."
+                },
+                "color": {
+                  "type": "string",
+                  "description": "accent, chrome or a palette name."
+                }
+              },
+              "description": "The main call to action."
+            },
+            "standard": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "style",
+                "color"
+              ],
+              "properties": {
+                "style": {
+                  "enum": [
+                    "solid",
+                    "soft",
+                    "outline",
+                    "ghost"
+                  ],
+                  "description": "solid: filled; soft: tinted fill; outline: border only; ghost: no fill or border until hover."
+                },
+                "color": {
+                  "type": "string",
+                  "description": "accent, chrome or a palette name."
+                }
+              },
+              "description": "Ordinary actions."
+            },
+            "subtle": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "style",
+                "color"
+              ],
+              "properties": {
+                "style": {
+                  "enum": [
+                    "solid",
+                    "soft",
+                    "outline",
+                    "ghost"
+                  ],
+                  "description": "solid: filled; soft: tinted fill; outline: border only; ghost: no fill or border until hover."
+                },
+                "color": {
+                  "type": "string",
+                  "description": "accent, chrome or a palette name."
+                }
+              },
+              "description": "Less important actions."
+            },
+            "quiet": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "style",
+                "color"
+              ],
+              "properties": {
+                "style": {
+                  "enum": [
+                    "solid",
+                    "soft",
+                    "outline",
+                    "ghost"
+                  ],
+                  "description": "solid: filled; soft: tinted fill; outline: border only; ghost: no fill or border until hover."
+                },
+                "color": {
+                  "type": "string",
+                  "description": "accent, chrome or a palette name."
+                }
+              },
+              "description": "The least."
+            }
+          }
+        },
+        "concepts": {
+          "type": "object",
+          "description": "Picks that replace a role's default step for one concept, keyed \"chrome.<slot>\" or \"accent.<slot>\". Modes left out keep the default. The Roles step of loomiere studio lists the concepts.",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "light": {
+                "type": "string",
+                "description": "palette.step (\"primary.1000\", \"neutral.on.100\"), \"white\" (paper), \"black\" (ink) or a hex."
+              },
+              "dark": {
+                "type": "string",
+                "description": "palette.step (\"primary.1000\", \"neutral.on.100\"), \"white\" (paper), \"black\" (ink) or a hex."
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "minMax": {
+      "type": "object",
+      "required": [
+        "min",
+        "max"
+      ],
+      "properties": {
+        "min": {
+          "type": "number"
+        },
+        "max": {
+          "type": "number"
+        }
+      }
+    },
+    "scale": {
+      "type": "object",
+      "required": [
+        "base",
+        "steps"
+      ],
+      "properties": {
+        "base": {
+          "type": "number"
+        },
+        "steps": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "number"
+          }
+        }
+      }
+    }
+  }
+}