@kenlo/sds-design-system 0.9.9 → 1.0.2

package/foundations/custom-scheme.js

@@ -24,6 +24,21 @@
 import { pickLabelColour, FALLBACK_TOKENS } from './contrast.js';
 
 const STYLE_ID = 'sds-custom-scheme';
+/**
+ * What the document wears while the primary slot holds a gradient.
+ *
+ * `border-color` and `color` reject a gradient, so a stroke reads the `-solid` companion —
+ * the first stop, flat. Painting a gradient ON a stroke needs a different shape of rule
+ * altogether: a two-layer background over a transparent border. A stylesheet cannot ask
+ * what a custom property contains, so the JavaScript that fills the slot says it here.
+ *
+ * KDLS wrote those rules under `[data-color-scheme="lya"]`, its own brand gradient. This
+ * says the thing that is actually true — the slot holds a gradient — rather than which
+ * brand is in use, so it works for any site's gradient.
+ */
+const GRADIENT_MARK = 'data-primary-gradient';
+/** The complement's own element — see applyComplementColor for why it is not the same one. */
+const COMPLEMENT_STYLE_ID = 'sds-custom-complement';
 const TONES = [10, 20, 30, 40, 50, 60, 70, 80, 90];
 /** The tones a component uses as a surface, and therefore needs a label colour for. */
 const SURFACE_TONES = [10, 20, 30, 40, 50];
@@ -125,23 +140,67 @@ export function generateGradientPalette(hexes) {
   }, {});
 }
 
-/** WCAG relative luminance, deciding whether text on the colour is white or black. */
-/** The token for the contrast pick, so a literal never reaches the stylesheet. */
-export function onPrimaryToken(hex) {
-  return FALLBACK_TOKENS[onPrimaryColor(hex)];
-}
-
-export function onPrimaryColor(hex) {
+/** WCAG relative luminance. */
+function luminance(hex) {
   const clean = assertHex(hex).replace(/^#/, '').slice(0, 6);
   const n = parseInt(clean, 16);
   const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
   const r = toLinear(((n >> 16) & 255) / 255);
   const g = toLinear(((n >> 8) & 255) / 255);
   const b = toLinear((n & 255) / 255);
-  const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
-  return 1.05 / (lum + 0.05) >= (lum + 0.05) / 0.05 ? '#FFFFFF' : '#000000';
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG contrast between a surface and white or black. */
+const contrastWithWhite = (hex) => 1.05 / (luminance(hex) + 0.05);
+const contrastWithBlack = (hex) => (luminance(hex) + 0.05) / 0.05;
+
+/** The ratio below which WCAG stops calling normal text readable. */
+const AA = 4.5;
+
+/** The token for the contrast pick, so a literal never reaches the stylesheet. */
+export function onPrimaryToken(hex) {
+  return FALLBACK_TOKENS[onPrimaryColor(hex)];
+}
+
+export function onPrimaryColor(hex) {
+  return contrastWithWhite(hex) >= contrastWithBlack(hex) ? '#FFFFFF' : '#000000';
 }
 
+/**
+ * The label for a surface made of several stops, judged by the WORST of them.
+ *
+ * A label is as readable as its least readable part, and a gradient draws the text across
+ * every stop. Choosing against the first one — which is what this did — picked white for
+ * `#2E7D32 → #BF71E5`, the portal's own default pair: 5.13:1 on the green end and 3.13:1
+ * on the purple, under AA, on the half of the control nobody looks at.
+ *
+ * It warns rather than throws when neither choice clears AA, because that is a fact about
+ * the two colours somebody chose, not a bug: no label clears 4.5:1 over that pair. The
+ * system picks the better of the two and says so, so a CMS can tell the estate agency
+ * before the site is published. Silently shipping 3.13:1 is how a design system becomes
+ * the reason a site cannot be read.
+ */
+export function onGradientColor(hexes) {
+  const worst = (against) => Math.min(...hexes.map(against));
+  const best = worst(contrastWithWhite) >= worst(contrastWithBlack) ? '#FFFFFF' : '#000000';
+  const ratio = best === '#FFFFFF' ? worst(contrastWithWhite) : worst(contrastWithBlack);
+
+  if (ratio < AA) {
+    const weakest = hexes
+      .map((hex) => [hex, best === '#FFFFFF' ? contrastWithWhite(hex) : contrastWithBlack(hex)])
+      .sort((a, b) => a[1] - b[1])[0];
+    console.warn(
+      `[sds] no label colour reaches ${AA}:1 across this gradient — `
+      + `the best available is ${best} at ${ratio.toFixed(2)}:1, weakest on ${weakest[0]}. `
+      + 'Choose a pair with less distance in lightness.',
+    );
+  }
+  return best;
+}
+
+export const onGradientToken = (hexes) => FALLBACK_TOKENS[onGradientColor(hexes)];
+
 function invertPalette(light) {
   return {
     10: light[90], 20: light[80], 30: light[70], 40: light[60], 50: light[50],
@@ -206,6 +265,7 @@ function inject(light, onColor, solidOf) {
 /** Fills the primary slot with a solid ramp generated from one hex. */
 export function applyCustomColor(hex) {
   inject(generatePalette(hex), onPrimaryToken(hex), (value) => value);
+  document.documentElement.removeAttribute(GRADIENT_MARK);
 }
 
 /**
@@ -214,9 +274,67 @@ export function applyCustomColor(hex) {
  * where a label starts.
  */
 export function applyCustomGradient(hexes) {
-  inject(generateGradientPalette(hexes), onPrimaryToken(hexes[0]), firstStopOf);
+  inject(generateGradientPalette(hexes), onGradientToken(hexes), firstStopOf);
+  document.documentElement.setAttribute(GRADIENT_MARK, '');
 }
 
+/**
+ * The complementary colour — the second of the two a site's brand actually has.
+ *
+ * A brand has a highlight and a complement. The highlight fills the primary slot and
+ * paints everything; the complement paints one thing, the ghost button, which is the
+ * outlined control. SDS could only receive the first of the two, so a product that
+ * modelled both had to drop one at the border.
+ *
+ * It is a LAYER rather than a third mode, and that is the whole design:
+ *
+ *     applyCustomColor(highlight)                    one solid
+ *     applyCustomColor(highlight) + this             two solids
+ *     applyCustomGradient([start, end])              gradient — this is not used
+ *
+ * So "two solids" is "one solid" with one more call, and no component needs to be told
+ * which of the three is in effect. `Button.css` reads `var(--color-complement-50,
+ * var(--color-primary-50-solid))`: with no complement set the fallback fires and the ghost
+ * button is byte for byte what it has always been, in every consumer that never uses this.
+ *
+ * Its own <style> element, not the primary's. One replacing the other would mean that
+ * re-picking the highlight silently dropped the complement — two answers, not one.
+ *
+ * No `-solid` twins. That suffix exists because the primary slot may hold a gradient and
+ * `color` / `box-shadow` reject one; this slot is solid by definition, so the twin would
+ * be the same value under a longer name. No `-on` labels either: the ghost button paints
+ * the complement ON the complement's own pale tones, which is the contrast the primary
+ * ramp already answers for.
+ */
+export function applyComplementColor(hex) {
+  const light = generatePalette(hex);
+  const dark = invertPalette(light);
+  const vars = (palette) => TONES
+    .map((tone) => `--color-complement-${tone}:${palette[tone]};`)
+    .join('');
+
+  let el = document.getElementById(COMPLEMENT_STYLE_ID);
+  if (!el) {
+    el = document.createElement('style');
+    el.id = COMPLEMENT_STYLE_ID;
+    document.head.appendChild(el);
+  }
+  el.textContent = `:root{${vars(light)}}[data-theme="dark"]{${vars(dark)}}`;
+}
+
+export function clearComplementColor() {
+  document.getElementById(COMPLEMENT_STYLE_ID)?.remove();
+}
+
+/**
+ * Drops both layers.
+ *
+ * Both, because this is what runs when the reader picks an installed scheme — `leaf`,
+ * `sea` — and at that moment the site is not on custom colours at all. Leaving the
+ * complement behind would paint the ghost button a colour nothing else on screen explains.
+ */
 export function clearCustomScheme() {
   document.getElementById(STYLE_ID)?.remove();
+  document.documentElement.removeAttribute(GRADIENT_MARK);
+  clearComplementColor();
 }

package/foundations/fonts/OFL.txt

@@ -0,0 +1,114 @@
+Manrope
+Designed by Mikhail Sharanda.
+Licensed under the SIL Open Font License, Version 1.1.
+
+Obtained from Google Fonts (https://fonts.google.com/specimen/Manrope), which reports the
+licence as "ofl". The .woff2 files in this directory are Google's own subsets, downloaded
+unmodified by scripts/gen-font.mjs — run `npm run gen:font` to refresh them.
+
+Manrope is the only typeface this package REDISTRIBUTES, which is why it is the only one
+this file has to cover. The four opt-in families the picker offers — Inter, Montserrat,
+Nunito and Source Sans 3 — are also SIL OFL 1.1, and are equally covered where they are
+actually served from: Kenlo's bucket, published by the kdls-design-system pipeline.
+Referencing a file by URL is not redistribution; carrying it in a package is.
+
+The full licence text follows, as published by SIL at https://openfontlicense.org.
+
+-------------------------------------------------------------------------------
+Copyright (c) <dates>, <Copyright Holder> (<URL|email>),
+with Reserved Font Name <Reserved Font Name>.
+Copyright (c) <dates>, <additional Copyright Holder> (<URL|email>),
+with Reserved Font Name <additional Reserved Font Name>.
+Copyright (c) <dates>, <additional Copyright Holder> (<URL|email>).
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/foundations/fonts/fonts.json

@@ -0,0 +1,152 @@
+{
+  "bucket": "https://storage.googleapis.com/kenlo-open-docs/kdls-design-system/assets/fonts",
+  "families": [
+    {
+      "id": "manrope",
+      "scheme": "manrope",
+      "label": "Manrope",
+      "mode": "local",
+      "subsets": [
+        "cyrillic-ext",
+        "cyrillic",
+        "greek",
+        "vietnamese",
+        "latin-ext",
+        "latin"
+      ],
+      "bytes": 74804
+    },
+    {
+      "id": "inter",
+      "scheme": "inter",
+      "label": "Inter",
+      "mode": "bucket",
+      "subsets": [
+        "cyrillic-ext",
+        "cyrillic",
+        "greek-ext",
+        "greek",
+        "vietnamese",
+        "latin-ext",
+        "latin",
+        "cyrillic-ext",
+        "cyrillic",
+        "greek-ext",
+        "greek",
+        "vietnamese",
+        "latin-ext",
+        "latin",
+        "cyrillic-ext",
+        "cyrillic",
+        "greek-ext",
+        "greek",
+        "vietnamese",
+        "latin-ext",
+        "latin",
+        "cyrillic-ext",
+        "cyrillic",
+        "greek-ext",
+        "greek",
+        "vietnamese",
+        "latin-ext",
+        "latin"
+      ],
+      "bytes": 875552
+    },
+    {
+      "id": "montserrat",
+      "scheme": "montserrat",
+      "label": "Montserrat",
+      "mode": "bucket",
+      "subsets": [
+        "cyrillic-ext",
+        "cyrillic",
+        "vietnamese",
+        "latin-ext",
+        "latin",
+        "cyrillic-ext",
+        "cyrillic",
+        "vietnamese",
+        "latin-ext",
+        "latin",
+        "cyrillic-ext",
+        "cyrillic",
+        "vietnamese",
+        "latin-ext",
+        "latin",
+        "cyrillic-ext",
+        "cyrillic",
+        "vietnamese",
+        "latin-ext",
+        "latin"
+      ],
+      "bytes": 639664
+    },
+    {
+      "id": "nunito",
+      "scheme": "nunito",
+      "label": "Nunito",
+      "mode": "bucket",
+      "subsets": [
+        "cyrillic-ext",
+        "cyrillic",
+        "vietnamese",
+        "latin-ext",
+        "latin",
+        "cyrillic-ext",
+        "cyrillic",
+        "vietnamese",
+        "latin-ext",
+        "latin",
+        "cyrillic-ext",
+        "cyrillic",
+        "vietnamese",
+        "latin-ext",
+        "latin",
+        "cyrillic-ext",
+        "cyrillic",
+        "vietnamese",
+        "latin-ext",
+        "latin"
+      ],
+      "bytes": 549376
+    },
+    {
+      "id": "source-sans-3",
+      "scheme": "source-sans",
+      "label": "Source Sans 3",
+      "mode": "bucket",
+      "subsets": [
+        "cyrillic-ext",
+        "cyrillic",
+        "greek-ext",
+        "greek",
+        "vietnamese",
+        "latin-ext",
+        "latin",
+        "cyrillic-ext",
+        "cyrillic",
+        "greek-ext",
+        "greek",
+        "vietnamese",
+        "latin-ext",
+        "latin",
+        "cyrillic-ext",
+        "cyrillic",
+        "greek-ext",
+        "greek",
+        "vietnamese",
+        "latin-ext",
+        "latin",
+        "cyrillic-ext",
+        "cyrillic",
+        "greek-ext",
+        "greek",
+        "vietnamese",
+        "latin-ext",
+        "latin"
+      ],
+      "bytes": 610544
+    }
+  ]
+}