@webority/tokens 0.0.0-stage → 0.89.0

package/renames/renames.d.ts

@@ -0,0 +1,42 @@
+/** Theme reads the phone theme renamed or removed in a release. `from` and `to` are plain dotted paths; the upgrade writes a segment that is not an identifier as ["segment"]. */
+export type RetiredThemeRead =
+    | { kind: "path"; from: string; to: string }
+    | { kind: "prefix"; from: string; to: string }
+    | { kind: "kebab"; under: string; names: Readonly<Record<string, string>> }
+    | { kind: "gone"; from: string; hint: string };
+
+/** A JSX prop that took a boolean and now takes named values: the bare prop or `{true}` becomes `true`, `{false}` becomes `false`. */
+export interface PropValueRule {
+    package: string;
+    components: string[];
+    prop: string;
+    true: string;
+    false: string;
+}
+
+/** A JSX prop that took `true` or a settings object and became an on/off value plus a separate settings prop named `into`. */
+export interface PropSplitRule {
+    package: string;
+    components: string[];
+    prop: string;
+    on: string;
+    off: string;
+    into: string;
+}
+
+/** A Razor tag-helper attribute whose `"true"` and `"false"` values became named values; `values` maps the lower-cased old value to the new one. */
+export interface RazorAttributeRule {
+    tags: string[];
+    attribute: string;
+    values: Readonly<Record<"true" | "false", string>>;
+}
+
+export interface RenameTable {
+    version: string;
+    css: { rename: [string, string][]; reads: [string, string][]; choose: Record<string, string>; checkRole: string[] };
+    themeReads: RetiredThemeRead[];
+    props: { package: string; props: string[]; from: string; to: string }[];
+    propValues: PropValueRule[];
+    propSplits: PropSplitRule[];
+    razorAttributes: RazorAttributeRule[];
+}

package/schema/design-map.schema.json

@@ -0,0 +1,143 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://webority.dev/schema/design-map.schema.json",
+    "title": "Webority design map",
+    "description": "The machine contract of a repo's .webority/design.json. design-map.md stays its prose; webority check validates against this file, then checks that every head names a listed brand, that brand names are unique, and that every brand but the library one has a head.",
+    "type": "object",
+    "required": ["schemaVersion", "tokens", "color"],
+    "properties": {
+        "$schema": { "type": "string" },
+        "$comment": { "type": "string" },
+        "schemaVersion": { "const": 1 },
+        "brandAuthority": { "type": "object" },
+        "type": { "type": "object" },
+        "color": {
+            "type": "object",
+            "properties": {
+                "roles": {
+                    "description": "Role to meaning name (a key of the tokens' color group), never a CSS variable or a hex.",
+                    "type": "object",
+                    "additionalProperties": { "$ref": "#/$defs/meaningName" }
+                }
+            },
+            "required": ["roles"],
+            "additionalProperties": false
+        },
+        "tokens": {
+            "type": "object",
+            "required": ["brands"],
+            "properties": {
+                "brands": {
+                    "description": "Every brand the repo builds. A repo with one brand writes a list of one.",
+                    "type": "array",
+                    "minItems": 1,
+                    "items": { "$ref": "#/$defs/brand" }
+                },
+                "heads": {
+                    "description": "Head project folders that receive copies of their brand's generated files.",
+                    "type": "array",
+                    "minItems": 1,
+                    "items": { "$ref": "#/$defs/head" }
+                }
+            },
+            "additionalProperties": false
+        },
+        "scale": {
+            "type": "object",
+            "propertyNames": { "enum": ["space", "radius", "elevation", "motion"] },
+            "additionalProperties": {
+                "type": "object",
+                "properties": {
+                    "rhythm": { "type": "string" },
+                    "character": { "type": "string" },
+                    "reducedMotion": { "type": "string" },
+                    "durations": {
+                        "description": "Motion role to duration token.",
+                        "type": "object",
+                        "additionalProperties": { "$ref": "#/$defs/groupName" }
+                    },
+                    "roles": {
+                        "type": "object",
+                        "additionalProperties": { "$ref": "#/$defs/groupName" }
+                    }
+                },
+                "additionalProperties": false
+            }
+        },
+        "logo": { "type": "object" },
+        "iconography": {
+            "type": "object",
+            "properties": {
+                "sizes": {
+                    "type": "object",
+                    "additionalProperties": { "$ref": "#/$defs/groupName" }
+                }
+            }
+        },
+        "imagery": { "type": "object" },
+        "moodboards": { "type": "array" },
+        "voice": { "type": "object" },
+        "principles": { "type": "array" },
+        "deliverables": { "type": "object" },
+        "designSources": { "type": "string" },
+        "lastVerified": { "type": "string" }
+    },
+    "additionalProperties": false,
+    "$defs": {
+        "meaningName": {
+            "description": "A meaning name such as primary or text-body.",
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+            "not": { "pattern": "^[0-9]+$" }
+        },
+        "groupName": {
+            "description": "<group>.<name>, resolved against the generated token files.",
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*\\.[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "relativePath": {
+            "description": "A folder relative to the repo root: no leading slash, no drive, no .. segment.",
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?![/\\\\])(?![A-Za-z]:)(?!.*(^|[/\\\\])\\.\\.([/\\\\]|$)).+$"
+        },
+        "brand": {
+            "type": "object",
+            "required": ["name", "source", "export"],
+            "properties": {
+                "name": {
+                    "description": "The brand's name; Canvas shows it as the brand theme of the same name.",
+                    "type": "string",
+                    "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+                },
+                "source": {
+                    "description": "Path of the brand file, or \"library\" in webority-ui only, where the library's own tokens are the source.",
+                    "type": "string",
+                    "minLength": 1
+                },
+                "export": {
+                    "description": "Folder the brand's generated token files are written to.",
+                    "$ref": "#/$defs/relativePath"
+                }
+            },
+            "additionalProperties": false
+        },
+        "head": {
+            "type": "object",
+            "required": ["path", "brand", "kind"],
+            "properties": {
+                "path": { "$ref": "#/$defs/relativePath" },
+                "brand": {
+                    "description": "The name of the brand whose files this head receives.",
+                    "type": "string",
+                    "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+                },
+                "kind": {
+                    "description": "Which generated file the head receives: razor gets brand.css in wwwroot/generated, spa (a Vite web portal) gets brand.css in src/generated for its style entry to import after the theme tokens, phone gets brand.phone.js and email gets email.json in generated.",
+                    "enum": ["razor", "spa", "phone", "email"]
+                }
+            },
+            "additionalProperties": false
+        }
+    }
+}

package/schema/webority-tokens.schema.json

@@ -0,0 +1,211 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://webority.dev/schema/webority-tokens.schema.json",
+    "title": "Webority design tokens",
+    "description": "One source file of the four tiers (palette, scale, meaning, component), a mode, platform or width override file, or a product brand file.",
+    "type": "object",
+    "propertyNames": { "$ref": "#/$defs/groupName" },
+    "properties": {
+        "palette": { "$ref": "#/$defs/paletteGroup" },
+        "color": { "$ref": "#/$defs/meaningGroup" },
+        "effect": { "$ref": "#/$defs/group" },
+        "component": { "$ref": "#/$defs/componentGroup" }
+    },
+    "additionalProperties": { "$ref": "#/$defs/group" },
+    "$defs": {
+        "name": {
+            "description": "Kebab case, not purely numeric (a step name such as 2xl is fine, 200 is not).",
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+            "not": { "pattern": "^[0-9]+$" }
+        },
+        "groupName": {
+            "anyOf": [{ "$ref": "#/$defs/name" }, { "enum": ["$type", "$description", "$extensions"] }]
+        },
+        "componentKey": {
+            "anyOf": [{ "$ref": "#/$defs/name" }, { "const": "$extensions" }]
+        },
+        "reference": { "type": "string", "pattern": "^\\{[a-z0-9-]+(\\.[a-z0-9-]+)+\\}$" },
+        "extensions": {
+            "type": "object",
+            "properties": {
+                "com.webority": {
+                    "type": "object",
+                    "properties": {
+                        "internal": { "const": true },
+                        "elevation": { "description": "Android elevation of a phone shadow.", "type": "integer", "minimum": 0 },
+                        "platforms": {
+                            "type": "array",
+                            "items": { "enum": ["web", "phone"] },
+                            "minItems": 1,
+                            "uniqueItems": true
+                        },
+                        "fluidUntil": {
+                            "description": "Viewport width in px at which a fluid text step stops growing.",
+                            "type": "number",
+                            "exclusiveMinimum": 390,
+                            "maximum": 1440
+                        },
+                        "breakpoints": {
+                            "description": "Per breakpoint, the token a responsive step takes from that width up.",
+                            "type": "object",
+                            "propertyNames": { "enum": ["md", "lg", "xl"] },
+                            "additionalProperties": { "$ref": "#/$defs/reference" }
+                        },
+                        "derive": {
+                            "description": "A colour computed from another instead of written out.",
+                            "enum": ["on-fill", "aa-ink", "dark-aa-ink", "dark-hover"]
+                        },
+                        "faces": {
+                            "description": "Phone font file names, by weight name.",
+                            "type": "object",
+                            "propertyNames": { "$ref": "#/$defs/name" },
+                            "additionalProperties": { "type": "string" }
+                        },
+                        "brand": {
+                            "description": "A product brand file: the product name, kebab case.",
+                            "type": "string",
+                            "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
+                        },
+                        "dark": { "description": "A brand colour override: its dark mode value, a colour or a reference." },
+                        "deviation": {
+                            "description": "A brand file that sets every group: the key of its recorded deviation in deviations.json.",
+                            "type": "string",
+                            "pattern": "^[A-Za-z0-9][A-Za-z0-9-]*/[A-Za-z0-9][A-Za-z0-9-]*(#[a-z0-9-]+)?$"
+                        }
+                    },
+                    "additionalProperties": false
+                }
+            }
+        },
+        "token": {
+            "type": "object",
+            "required": ["$value"],
+            "properties": {
+                "$value": {},
+                "$type": { "type": "string" },
+                "$description": { "type": "string", "minLength": 1 },
+                "$extensions": { "$ref": "#/$defs/extensions" }
+            },
+            "additionalProperties": false
+        },
+        "group": {
+            "type": "object",
+            "propertyNames": { "$ref": "#/$defs/groupName" },
+            "properties": {
+                "$type": { "type": "string" },
+                "$description": { "type": "string" },
+                "$extensions": { "$ref": "#/$defs/extensions" }
+            },
+            "additionalProperties": {
+                "if": { "type": "object", "required": ["$value"] },
+                "then": { "$ref": "#/$defs/token" },
+                "else": { "$ref": "#/$defs/group" }
+            }
+        },
+        "paletteGroup": {
+            "description": "Raw colours, library-internal. Names are today's --wui-* names; product code never reads them.",
+            "$ref": "#/$defs/group"
+        },
+        "meaningGroup": {
+            "description": "Colour meanings. In a source file every meaning carries a description; an override file carries values only.",
+            "type": "object",
+            "propertyNames": { "$ref": "#/$defs/groupName" },
+            "properties": { "$type": { "const": "color" } },
+            "additionalProperties": { "$ref": "#/$defs/token" }
+        },
+        "componentToken": {
+            "description": "A component property with no size level or none of the families below: a dimension may be a literal px value (shape sizes). A typography value is a reference.",
+            "allOf": [
+                { "$ref": "#/$defs/token" },
+                {
+                    "if": { "properties": { "$type": { "const": "typography" } }, "required": ["$type"] },
+                    "then": { "properties": { "$value": { "$ref": "#/$defs/reference" } } }
+                }
+            ]
+        },
+        "componentScaleToken": {
+            "description": "A property of the text, radius or space family: a dimension or typography value is a reference to a scale token, never a literal.",
+            "allOf": [
+                { "$ref": "#/$defs/token" },
+                {
+                    "if": { "properties": { "$type": { "enum": ["dimension", "typography"] } }, "required": ["$type"] },
+                    "then": { "properties": { "$value": { "$ref": "#/$defs/reference" } } }
+                }
+            ]
+        },
+        "componentSize": {
+            "description": "One size of a component: its properties.",
+            "type": "object",
+            "propertyNames": { "$ref": "#/$defs/componentKey" },
+            "properties": { "$extensions": { "$ref": "#/$defs/extensions" } },
+            "patternProperties": {
+                "^(text|.+-text)$": { "$ref": "#/$defs/componentScaleToken" },
+                "^(radius|.+-radius)$": { "$ref": "#/$defs/componentScaleToken" },
+                "^(padding(-.+)?|.+-padding(-.+)?|gap|.+-gap|.+-inset|margin.*)$": { "$ref": "#/$defs/componentScaleToken" }
+            },
+            "additionalProperties": { "$ref": "#/$defs/componentToken" }
+        },
+        "componentEntry": {
+            "description": "One component: properties with no size level directly, and one group per size.",
+            "type": "object",
+            "propertyNames": { "$ref": "#/$defs/componentKey" },
+            "properties": { "$extensions": { "$ref": "#/$defs/extensions" } },
+            "patternProperties": {
+                "^(text|.+-text)$": { "$ref": "#/$defs/componentEntryNode" },
+                "^(radius|.+-radius)$": { "$ref": "#/$defs/componentEntryNode" },
+                "^(padding(-.+)?|.+-padding(-.+)?|gap|.+-gap|.+-inset|margin.*)$": { "$ref": "#/$defs/componentEntryNode" }
+            },
+            "additionalProperties": {
+                "if": { "type": "object", "required": ["$value"] },
+                "then": { "$ref": "#/$defs/componentToken" },
+                "else": { "$ref": "#/$defs/componentSize" }
+            }
+        },
+        "componentEntryNode": {
+            "if": { "type": "object", "required": ["$value"] },
+            "then": { "$ref": "#/$defs/componentScaleToken" },
+            "else": { "$ref": "#/$defs/componentSize" }
+        },
+        "componentGroup": {
+            "description": "Per component, optionally per size, then property. Spacing, text and corner values are references to a scale token; a shape size may be a literal.",
+            "type": "object",
+            "propertyNames": { "$ref": "#/$defs/name" },
+            "additionalProperties": { "$ref": "#/$defs/componentEntry" }
+        },
+        "sourceMeaning": {
+            "description": "Applied to meaning.tokens.json: every meaning needs a description.",
+            "type": "object",
+            "properties": {
+                "color": {
+                    "type": "object",
+                    "additionalProperties": { "required": ["$value", "$description"] }
+                }
+            }
+        },
+        "brand": {
+            "description": "Applied to a product brand file: a product overrides palette steps, colour meanings, fonts and radius and may add colour and effect names of its own, never the space scale. A name the library does not declare needs a $description, which loadBrand checks against the library. A file naming a recorded deviation may set every group.",
+            "type": "object",
+            "required": ["$extensions"],
+            "properties": {
+                "$extensions": {
+                    "type": "object",
+                    "required": ["com.webority"],
+                    "properties": { "com.webority": { "type": "object", "required": ["brand"] } }
+                }
+            },
+            "if": {
+                "required": ["$extensions"],
+                "properties": {
+                    "$extensions": {
+                        "required": ["com.webority"],
+                        "properties": { "com.webority": { "required": ["deviation"] } }
+                    }
+                }
+            },
+            "else": {
+                "propertyNames": { "enum": ["$extensions", "$description", "palette", "color", "effect", "font", "radius"] }
+            }
+        }
+    }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.