jouw-stem__design-system 0.1.0

package/src/scss/mixins/typography.scss

@@ -0,0 +1,172 @@
+@use "../../dist/scss/tokens" as *;
+@use "./breakpoint.scss" as *;
+
+// 17-variant typography system (TD-080).
+//   - Display L/M/S    — marketing hero, splash, billboard.
+//   - Headline L/M/S   — page-titles, primary section-openers.
+//   - Title L/M/S      — card, dialog, modal titles.
+//   - Body L/M/S       — paragraph + supporting text (default reading size at M).
+//   - Label L/M/S      — buttons, chips, form-labels, captions.
+//   - Code             — inline + block code (monospace family).
+//   - Overline         — uppercase tracking-label.
+//
+// Scale-basis: major-third (~1.25) between role-sizes. Stack:
+// font-family / font-size / line-height / letter-spacing / font-weight.
+// Citations: Material Design 3 "Type system", Apple HIG "Typography >
+// Specifications", IBM Carbon "Productive vs Expressive typography",
+// Refactoring UI "Establishing a type system".
+
+@mixin _display($size) {
+  font-family: var(--font-display);
+  font-weight: 600;
+  color: $text-heading;
+
+  @if ($size == "l") {
+    font-size: 60px; line-height: 1.1; letter-spacing: -0.02em;
+  } @else if ($size == "m") {
+    font-size: 48px; line-height: 1.1; letter-spacing: -0.02em;
+  } @else if ($size == "s") {
+    font-size: 38px; line-height: 1.1; letter-spacing: -0.01em;
+  }
+}
+
+@mixin _headline($size) {
+  font-family: var(--font-display);
+  font-weight: 600;
+  color: $text-heading;
+
+  @if ($size == "l") {
+    font-size: 32px; line-height: 1.2; letter-spacing: -0.01em;
+  } @else if ($size == "m") {
+    font-size: 26px; line-height: 1.25; letter-spacing: -0.005em;
+  } @else if ($size == "s") {
+    font-size: 22px; line-height: 1.3; letter-spacing: 0;
+  }
+}
+
+@mixin _title($size) {
+  font-family: var(--font-sans);
+  font-weight: 600;
+  color: $text-heading;
+
+  @if ($size == "l") {
+    font-size: 20px; line-height: 1.3; letter-spacing: 0;
+  } @else if ($size == "m") {
+    font-size: 17px; line-height: 1.35; letter-spacing: 0;
+  } @else if ($size == "s") {
+    font-size: 15px; line-height: 1.4; letter-spacing: 0;
+  }
+}
+
+@mixin _body($size) {
+  font-family: var(--font-sans);
+  font-weight: 400;
+  letter-spacing: 0;
+
+  @if ($size == "l") {
+    font-size: 18px; line-height: 1.5;
+  } @else if ($size == "m") {
+    font-size: 16px; line-height: 1.5;
+  } @else if ($size == "s") {
+    font-size: 14px; line-height: 1.5;
+  }
+}
+
+@mixin _label($size) {
+  font-family: var(--font-sans);
+  font-weight: 500;
+
+  @if ($size == "l") {
+    font-size: 15px; line-height: 1.4; letter-spacing: 0;
+  } @else if ($size == "m") {
+    font-size: 13px; line-height: 1.4; letter-spacing: 0.01em;
+  } @else if ($size == "s") {
+    font-size: 11px; line-height: 1.4; letter-spacing: 0.02em;
+  }
+}
+
+@mixin _code() {
+  font-family: "Fira Code", Menlo, Monaco, Consolas, "Courier New", monospace;
+  font-size: 14px;
+  line-height: 1.5;
+  letter-spacing: 0;
+  font-weight: 400;
+}
+
+@mixin _overline() {
+  font-family: var(--font-sans);
+  font-size: 11px;
+  line-height: 1.4;
+  letter-spacing: 0.08em;
+  font-weight: 600;
+  text-transform: uppercase;
+}
+
+// Static (non-responsive) typography. Pick role + size; the mixin
+// emits one block. Use this when the variant should not scale across
+// breakpoints (e.g. a chip label always reads at Label-S).
+@mixin static-typography($role: "body", $size: "m", $isStrong: false) {
+  // ─── 17-variant API ───
+  @if ($role == "display")  { @include _display($size); }
+  @else if ($role == "headline") { @include _headline($size); }
+  @else if ($role == "title")    { @include _title($size); }
+  @else if ($role == "body")     { @include _body($size); }
+  @else if ($role == "label")    { @include _label($size); }
+  @else if ($role == "code")     { @include _code(); }
+  @else if ($role == "overline") { @include _overline(); }
+
+  // ─── Back-compat aliases (pre-TD-080) ───
+  // `text`     → body. Old size-keys (2xs/xs/s/m/l/xl/2xl/3xs) collapse
+  //              onto the closest body variant.
+  // `heading`  → display (xl/2xl), headline (l/m), or title (s/xs).
+  @else if ($role == "text") {
+    @if ($size == "3xs" or $size == "2xs" or $size == "xs" or $size == "s") {
+      @include _body("s");
+    } @else if ($size == "m") {
+      @include _body("m");
+    } @else {
+      @include _body("l");
+    }
+  } @else if ($role == "heading") {
+    @if ($size == "2xl" or $size == "xl") {
+      @include _display(if($size == "2xl", "l", "m"));
+    } @else if ($size == "l" or $size == "m") {
+      @include _headline(if($size == "l", "l", "m"));
+    } @else {
+      @include _title("l");
+    }
+  }
+
+  // `isStrong` adds weight on body — preserved for back-compat with
+  // existing component callsites.
+  @if ($isStrong and ($role == "text" or $role == "body")) {
+    font-weight: 600;
+  }
+}
+
+// Responsive typography — same role but the largest sizes step down on
+// narrow viewports so they don't blow out the layout on phone/tablet.
+// On desktop+ they render at the full size.
+@mixin typography($role: "body", $size: "m", $isStrong: false) {
+  // Display + Headline + Title L scale down one step on phone/tablet.
+  // Others render static — Body/Label/Code/Overline are already
+  // calibrated for the smallest viewport.
+  @if ($role == "display" and ($size == "l" or $size == "m")) {
+    @include _display(if($size == "l", "m", "s"));
+    @include breakpoint-from(laptop) {
+      @include _display($size);
+    }
+  } @else if ($role == "headline" and $size == "l") {
+    @include _headline("m");
+    @include breakpoint-from(laptop) {
+      @include _headline("l");
+    }
+  } @else if ($role == "title" and $size == "l") {
+    @include _title("m");
+    @include breakpoint-from(laptop) {
+      @include _title("l");
+    }
+  } @else {
+    @include static-typography($role, $size, $isStrong);
+  }
+}

package/src/scss/utility-classes/utility-classes-spacing.scss

@@ -0,0 +1,281 @@
+@use "../variables/spacers.scss" as *;
+
+.ds-m-1{ margin: $space-1; }
+
+.ds-mt-1{ margin-top: $space-1; }
+
+.ds-mr-1{ margin-right: $space-1; }
+
+.ds-mb-1{ margin-bottom: $space-1; }
+
+.ds-ml-1{ margin-left: $space-1; }
+
+.ds-p-1{ padding: $space-1; }
+
+.ds-pt-1{ padding-top: $space-1; }
+
+.ds-pr-1{ padding-right: $space-1; }
+
+.ds-pb-1{ padding-bottom: $space-1; }
+
+.ds-pl-1{ padding-left: $space-1; }
+
+.ds-m-2{ margin: $space-2; }
+
+.ds-mt-2{ margin-top: $space-2; }
+
+.ds-mr-2{ margin-right: $space-2; }
+
+.ds-mb-2{ margin-bottom: $space-2; }
+
+.ds-ml-2{ margin-left: $space-2; }
+
+.ds-p-2{ padding: $space-2; }
+
+.ds-pt-2{ padding-top: $space-2; }
+
+.ds-pr-2{ padding-right: $space-2; }
+
+.ds-pb-2{ padding-bottom: $space-2; }
+
+.ds-pl-2{ padding-left: $space-2; }
+
+.ds-m-3{ margin: $space-3; }
+
+.ds-mt-3{ margin-top: $space-3; }
+
+.ds-mr-3{ margin-right: $space-3; }
+
+.ds-mb-3{ margin-bottom: $space-3; }
+
+.ds-ml-3{ margin-left: $space-3; }
+
+.ds-p-3{ padding: $space-3; }
+
+.ds-pt-3{ padding-top: $space-3; }
+
+.ds-pr-3{ padding-right: $space-3; }
+
+.ds-pb-3{ padding-bottom: $space-3; }
+
+.ds-pl-3{ padding-left: $space-3; }
+
+.ds-m-4{ margin: $space-4; }
+
+.ds-mt-4{ margin-top: $space-4; }
+
+.ds-mr-4{ margin-right: $space-4; }
+
+.ds-mb-4{ margin-bottom: $space-4; }
+
+.ds-ml-4{ margin-left: $space-4; }
+
+.ds-p-4{ padding: $space-4; }
+
+.ds-pt-4{ padding-top: $space-4; }
+
+.ds-pr-4{ padding-right: $space-4; }
+
+.ds-pb-4{ padding-bottom: $space-4; }
+
+.ds-pl-4{ padding-left: $space-4; }
+
+.ds-m-5{ margin: $space-5; }
+
+.ds-mt-5{ margin-top: $space-5; }
+
+.ds-mr-5{ margin-right: $space-5; }
+
+.ds-mb-5{ margin-bottom: $space-5; }
+
+.ds-ml-5{ margin-left: $space-5; }
+
+.ds-p-5{ padding: $space-5; }
+
+.ds-pt-5{ padding-top: $space-5; }
+
+.ds-pr-5{ padding-right: $space-5; }
+
+.ds-pb-5{ padding-bottom: $space-5; }
+
+.ds-pl-5{ padding-left: $space-5; }
+
+.ds-m-6{ margin: $space-6; }
+
+.ds-mt-6{ margin-top: $space-6; }
+
+.ds-mr-6{ margin-right: $space-6; }
+
+.ds-mb-6{ margin-bottom: $space-6; }
+
+.ds-ml-6{ margin-left: $space-6; }
+
+.ds-p-6{ padding: $space-6; }
+
+.ds-pt-6{ padding-top: $space-6; }
+
+.ds-pr-6{ padding-right: $space-6; }
+
+.ds-pb-6{ padding-bottom: $space-6; }
+
+.ds-pl-6{ padding-left: $space-6; }
+
+.ds-m-8{ margin: $space-8; }
+
+.ds-mt-8{ margin-top: $space-8; }
+
+.ds-mr-8{ margin-right: $space-8; }
+
+.ds-mb-8{ margin-bottom: $space-8; }
+
+.ds-ml-8{ margin-left: $space-8; }
+
+.ds-p-8{ padding: $space-8; }
+
+.ds-pt-8{ padding-top: $space-8; }
+
+.ds-pr-8{ padding-right: $space-8; }
+
+.ds-pb-8{ padding-bottom: $space-8; }
+
+.ds-pl-8{ padding-left: $space-8; }
+
+.ds-m-10{ margin: $space-10; }
+
+.ds-mt-10{ margin-top: $space-10; }
+
+.ds-mr-10{ margin-right: $space-10; }
+
+.ds-mb-10{ margin-bottom: $space-10; }
+
+.ds-ml-10{ margin-left: $space-10; }
+
+.ds-p-10{ padding: $space-10; }
+
+.ds-pt-10{ padding-top: $space-10; }
+
+.ds-pr-10{ padding-right: $space-10; }
+
+.ds-pb-10{ padding-bottom: $space-10; }
+
+.ds-pl-10{ padding-left: $space-10; }
+
+.ds-m-12{ margin: $space-12; }
+
+.ds-mt-12{ margin-top: $space-12; }
+
+.ds-mr-12{ margin-right: $space-12; }
+
+.ds-mb-12{ margin-bottom: $space-12; }
+
+.ds-ml-12{ margin-left: $space-12; }
+
+.ds-p-12{ padding: $space-12; }
+
+.ds-pt-12{ padding-top: $space-12; }
+
+.ds-pr-12{ padding-right: $space-12; }
+
+.ds-pb-12{ padding-bottom: $space-12; }
+
+.ds-pl-12{ padding-left: $space-12; }
+
+.ds-m-14{ margin: $space-14; }
+
+.ds-mt-14{ margin-top: $space-14; }
+
+.ds-mr-14{ margin-right: $space-14; }
+
+.ds-mb-14{ margin-bottom: $space-14; }
+
+.ds-ml-14{ margin-left: $space-14; }
+
+.ds-p-14{ padding: $space-14; }
+
+.ds-pt-14{ padding-top: $space-14; }
+
+.ds-pr-14{ padding-right: $space-14; }
+
+.ds-pb-14{ padding-bottom: $space-14; }
+
+.ds-pl-14{ padding-left: $space-14; }
+
+.ds-m-16{ margin: $space-16; }
+
+.ds-mt-16{ margin-top: $space-16; }
+
+.ds-mr-16{ margin-right: $space-16; }
+
+.ds-mb-16{ margin-bottom: $space-16; }
+
+.ds-ml-16{ margin-left: $space-16; }
+
+.ds-p-16{ padding: $space-16; }
+
+.ds-pt-16{ padding-top: $space-16; }
+
+.ds-pr-16{ padding-right: $space-16; }
+
+.ds-pb-16{ padding-bottom: $space-16; }
+
+.ds-pl-16{ padding-left: $space-16; }
+
+.ds-m-20{ margin: $space-20; }
+
+.ds-mt-20{ margin-top: $space-20; }
+
+.ds-mr-20{ margin-right: $space-20; }
+
+.ds-mb-20{ margin-bottom: $space-20; }
+
+.ds-ml-20{ margin-left: $space-20; }
+
+.ds-p-20{ padding: $space-20; }
+
+.ds-pt-20{ padding-top: $space-20; }
+
+.ds-pr-20{ padding-right: $space-20; }
+
+.ds-pb-20{ padding-bottom: $space-20; }
+
+.ds-pl-20{ padding-left: $space-20; }
+
+.ds-m-24{ margin: $space-24; }
+
+.ds-mt-24{ margin-top: $space-24; }
+
+.ds-mr-24{ margin-right: $space-24; }
+
+.ds-mb-24{ margin-bottom: $space-24; }
+
+.ds-ml-24{ margin-left: $space-24; }
+
+.ds-p-24{ padding: $space-24; }
+
+.ds-pt-24{ padding-top: $space-24; }
+
+.ds-pr-24{ padding-right: $space-24; }
+
+.ds-pb-24{ padding-bottom: $space-24; }
+
+.ds-pl-24{ padding-left: $space-24; }
+
+.ds-m-32{ margin: $space-32; }
+
+.ds-mt-32{ margin-top: $space-32; }
+
+.ds-mr-32{ margin-right: $space-32; }
+
+.ds-mb-32{ margin-bottom: $space-32; }
+
+.ds-ml-32{ margin-left: $space-32; }
+
+.ds-p-32{ padding: $space-32; }
+
+.ds-pt-32{ padding-top: $space-32; }
+
+.ds-pr-32{ padding-right: $space-32; }
+
+.ds-pb-32{ padding-bottom: $space-32; }
+
+.ds-pl-32{ padding-left: $space-32; }

package/src/scss/utility-classes/utility-classes-typography.scss

@@ -0,0 +1,114 @@
+@use "../fonts.scss" as *;
+@use "../mixins/typography.scss" as *;
+
+.ds-heading-xs {
+  @include typography("heading", "xs");
+}
+
+.ds-heading-s {
+  @include typography("heading", "s");
+}
+
+.ds-heading-m {
+  @include typography("heading", "m");
+}
+
+.ds-heading-l {
+  @include typography("heading", "l");
+}
+
+.ds-heading-xl {
+  @include typography("heading", "xl");
+}
+
+.ds-heading-2xl {
+  @include typography("heading", "2xl");
+}
+
+.ds-text-3xs {
+  @include typography("text", "3xs");
+}
+
+.ds-text-2xs {
+  @include typography("text", "2xs");
+}
+
+.ds-text-xs {
+  @include typography("text", "xs");
+}
+
+.ds-text-s {
+  @include typography("text", "s");
+}
+
+.ds-text-m {
+  @include typography("text", "m");
+}
+
+.ds-text-l {
+  @include typography("text", "l");
+}
+
+.ds-text-xl {
+  @include typography("text", "xl");
+}
+
+.ds-text-2xl {
+  @include typography("text", "2xl");
+}
+
+.ds-heading-static-xs {
+  @include static-typography("heading", "xs");
+}
+
+.ds-heading-static-s {
+  @include static-typography("heading", "s");
+}
+
+.ds-heading-static-m {
+  @include static-typography("heading", "m");
+}
+
+.ds-heading-static-l {
+  @include static-typography("heading", "l");
+}
+
+.ds-heading-static-xl {
+  @include static-typography("heading", "xl");
+}
+
+.ds-heading-static-2xl {
+  @include static-typography("heading", "2xl");
+}
+
+.ds-text-static-3xs {
+  @include static-typography("text", "3xs");
+}
+
+.ds-text-static-2xs {
+  @include static-typography("text", "2xs");
+}
+
+.ds-text-static-xs {
+  @include static-typography("text", "xs");
+}
+
+.ds-text-static-s {
+  @include static-typography("text", "s");
+}
+
+.ds-text-static-m {
+  @include static-typography("text", "m");
+}
+
+.ds-text-static-l {
+  @include static-typography("text", "l");
+}
+
+.ds-text-static-xl {
+  @include static-typography("text", "xl");
+}
+
+.ds-text-static-2xl {
+  @include static-typography("text", "2xl");
+}

package/tokens/brand.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "./brand.schema.json",
+  "$comment": "THIS IS THE ONE FILE YOU EDIT TO REBRAND. See BRAND.md for the field guide. After editing, run `npm run build:tokens`.",
+
+  "name": "White-Label Template",
+
+  "palette": {
+    "$comment": "Each role aliases a named ramp from tokens/primitives/color.json. Available ramps: neutral, navy, blue, purple, orange, amber, yellow, green, red, pink, teal. The build pipeline copies the chosen ramp under primary/secondary/accent/etc. so semantics can stay brand-agnostic.",
+    "primary":   { "ramp": "navy" },
+    "secondary": { "ramp": "blue" },
+    "accent":    { "ramp": "amber" },
+    "neutral":   { "ramp": "neutral" },
+    "success":   { "ramp": "green" },
+    "warning":   { "ramp": "amber" },
+    "danger":    { "ramp": "red" },
+    "info":      { "ramp": "blue" }
+  },
+
+  "fonts": {
+    "$comment": "Default to a system font stack — zero-cost, no network round-trip, looks native everywhere. To use custom fonts: drop .woff2 files in src/assets/fonts/ and add entries to `faces` below. See BRAND_FONTS.md.",
+    "sans":    "system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif",
+    "display": "system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif",
+    "mono":    "ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace",
+    "faces":   []
+  },
+
+  "feel": {
+    "$comment": "Coarse-grained visual knobs. The build pipeline reads these and selects matching primitive scales.",
+    "radiusScale":  "fibonacci",
+    "shadowDepth":  "default",
+    "useGradients": true
+  }
+}

package/tokens/brand.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://white-label-style-library/tokens/brand.schema.json",
+  "title": "Brand configuration",
+  "description": "The single visual-identity entry point for the design system. Edit tokens/brand.json and run `npm run build:tokens` to rebrand.",
+  "type": "object",
+  "required": ["name", "palette", "fonts"],
+  "additionalProperties": true,
+  "properties": {
+    "$schema":  { "type": "string" },
+    "$comment": { "type": "string" },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Product/brand name displayed in the docs site and used in package.json after `npm run init`."
+    },
+    "palette": {
+      "type": "object",
+      "description": "Maps each brand role to a primitive ramp from tokens/primitives/color.json. All roles required so semantics can reference {primary.X}, {accent.Y}, etc.",
+      "required": ["primary", "secondary", "accent", "neutral", "success", "warning", "danger", "info"],
+      "additionalProperties": false,
+      "properties": {
+        "primary":   { "$ref": "#/$defs/paletteRole" },
+        "secondary": { "$ref": "#/$defs/paletteRole" },
+        "accent":    { "$ref": "#/$defs/paletteRole" },
+        "neutral":   { "$ref": "#/$defs/paletteRole" },
+        "success":   { "$ref": "#/$defs/paletteRole" },
+        "warning":   { "$ref": "#/$defs/paletteRole" },
+        "danger":    { "$ref": "#/$defs/paletteRole" },
+        "info":      { "$ref": "#/$defs/paletteRole" }
+      }
+    },
+    "fonts": {
+      "type": "object",
+      "required": ["sans", "display", "mono", "faces"],
+      "additionalProperties": false,
+      "properties": {
+        "$comment": { "type": "string" },
+        "sans":    { "type": "string", "description": "Body CSS font stack" },
+        "display": { "type": "string", "description": "Heading/display CSS font stack" },
+        "mono":    { "type": "string", "description": "Monospace CSS font stack" },
+        "faces": {
+          "type": "array",
+          "description": "@font-face entries for custom .woff2 files in src/assets/fonts/. Empty array uses the system stack.",
+          "items": { "$ref": "#/$defs/fontFace" }
+        }
+      }
+    },
+    "feel": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "$comment":     { "type": "string" },
+        "radiusScale":  { "enum": ["fibonacci", "linear"], "description": "Radius progression style" },
+        "shadowDepth":  { "enum": ["subtle", "default", "dramatic"], "description": "Shadow intensity preset" },
+        "useGradients": { "type": "boolean", "description": "Whether the brand permits decorative gradients" }
+      }
+    }
+  },
+  "$defs": {
+    "paletteRole": {
+      "type": "object",
+      "required": ["ramp"],
+      "additionalProperties": false,
+      "properties": {
+        "ramp": {
+          "type": "string",
+          "enum": ["neutral", "navy", "blue", "purple", "orange", "amber", "yellow", "green", "red", "pink", "teal"],
+          "description": "Name of a primitive ramp in tokens/primitives/color.json. Add new ramps there before referencing them here."
+        }
+      }
+    },
+    "fontFace": {
+      "type": "object",
+      "required": ["family", "src"],
+      "additionalProperties": false,
+      "properties": {
+        "family":  { "type": "string", "description": "@font-face font-family value" },
+        "src":     { "type": "string", "description": "Filename in src/assets/fonts/ or absolute URL" },
+        "weight":  { "oneOf": [{ "type": "number" }, { "type": "string" }], "description": "@font-face font-weight (numeric or 'normal'/'bold')" },
+        "style":   { "enum": ["normal", "italic"] },
+        "display": { "enum": ["auto", "block", "swap", "fallback", "optional"] }
+      }
+    }
+  }
+}