@0001-labs/design-system-1 0.3.0 → 0.3.1

package/DS1/0-face/constraint-panel.ts

@@ -1,5 +1,6 @@
+import { paintFaultLines } from './fault-lines';
 import { measureConstraints, type Constraint, type Finding } from './constraints';
-import { PHONE_WIDTHS, checkSite, findSitePages, inspectInFrame, ruleLine, summarizePages, summarizeRules, type PageResult } from './constraint-site';
+import { VIEWPORT_WIDTHS, checkSite, findSitePages, inspectInFrame, ruleLine, summarizePages, summarizeRules, type PageResult } from './constraint-site';
 
 // appendChild, not append: a Worker project's types redefine append for its HTML rewriter.
 
@@ -38,7 +39,8 @@ export function createConstraintPanel() {
       --danger: var(--ds-danger-color, light-dark(#de0331, #ff5f5f));
     }
     :host([hidden]) { display: none !important; }
-    .rings { position: absolute; inset: 0; overflow: hidden; }
+    .fault-lines { z-index: 0 !important; }
+    .rings { z-index: 1; position: absolute; inset: 0; overflow: hidden; }
     .frames { position: absolute; width: 0; height: 0; overflow: hidden; }
     .ring {
       position: absolute;
@@ -60,6 +62,7 @@ export function createConstraintPanel() {
       text-align: center;
     }
     aside {
+      z-index: 2;
       position: absolute;
       inset-block: 0;
       inset-inline-end: 0;
@@ -106,14 +109,18 @@ export function createConstraintPanel() {
     .code b { color: var(--danger); font-weight: 400; }
     .rule { color: var(--muted); }
     p { margin: 0; }
+    :host([data-lines-only]) aside { inset-block: 0 auto; width: auto; padding: calc(var(--u) / 2); }
+    :host([data-lines-only]) aside > :not(header), :host([data-lines-only]) header > :not([data-lines], [data-close]) { display: none; }
+    :host([data-lines-only]) header { margin: 0; }
     @media print { :host { display: none !important; } }
-  </style><div class="rings"></div><div class="frames"></div><aside aria-label="Constraints">
-    <header><strong>Constraints</strong><button type="button" data-run>Page</button><button type="button" data-site>Site</button><button type="button" data-close aria-label="Close">Close</button></header>
-    <p data-status aria-live="polite"></p>
+  </style><svg class="fault-lines" aria-hidden="true"></svg><div class="rings"></div><div class="frames"></div><aside aria-label="Constraints">
+    <header><strong>Constraints</strong><button type="button" data-run>Page</button><button type="button" data-site>Site</button><button type="button" data-lines>Lines</button><button type="button" data-close aria-label="Close">Close</button></header>
+    <p data-status aria-live="polite"></p><p class="rule">Fault lines: dashed reference · red drift</p>
     <ol data-findings></ol>
     <section data-rules hidden><h3>Rules</h3><ol></ol></section>
     <section data-pages hidden><h3>Pages</h3><ol></ol></section>
   </aside>`;
+  const faultLines = shadow.querySelector<SVGSVGElement>('.fault-lines')!;
   const rings = shadow.querySelector<HTMLDivElement>('.rings')!;
   const list = shadow.querySelector<HTMLOListElement>('[data-findings]')!;
   const rulesSection = shadow.querySelector<HTMLElement>('[data-rules]')!;
@@ -123,6 +130,9 @@ export function createConstraintPanel() {
   const status = shadow.querySelector<HTMLElement>('[data-status]')!;
   const title = shadow.querySelector('strong')!;
   const frames = shadow.querySelector<HTMLDivElement>('.frames')!;
+  const linesButton = shadow.querySelector<HTMLButtonElement>('[data-lines]')!;
+  const setLinesOnly = (enabled: boolean) => { panel.toggleAttribute('data-lines-only', enabled); linesButton.textContent = enabled ? 'Results' : 'Lines'; };
+  linesButton.addEventListener('click', () => setLinesOnly(!panel.hasAttribute('data-lines-only')));
   const siteButton = shadow.querySelector<HTMLButtonElement>('[data-site]')!;
   let site: AbortController | null = null;
   let findings: (Finding & { constraint: Constraint })[] = [];
@@ -131,6 +141,7 @@ export function createConstraintPanel() {
 
   const place = () => {
     frame = 0;
+    paintFaultLines(document, faultLines);
     rings.replaceChildren(...findings.map(({ element }, index) => {
       const rect = element.getBoundingClientRect();
       const ring = document.createElement('div');
@@ -144,6 +155,8 @@ export function createConstraintPanel() {
     }));
   };
   const schedule = () => { if (!frame) frame = requestAnimationFrame(place); };
+  const layoutChanges = new MutationObserver(schedule);
+  const sizeChanges = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(schedule);
 
   const stopSite = () => {
     site?.abort();
@@ -276,7 +289,7 @@ export function createConstraintPanel() {
     title.textContent = 'Constraints';
     status.textContent = 'Finding the pages…';
     const pages = await findSitePages();
-    const widths = `${PHONE_WIDTHS.slice(0, -1).join(', ')} and ${PHONE_WIDTHS[PHONE_WIDTHS.length - 1]}px`;
+    const widths = `${VIEWPORT_WIDTHS.slice(0, -1).join(', ')} and ${VIEWPORT_WIDTHS[VIEWPORT_WIDTHS.length - 1]}px`;
     let broken = 0;
     const results = await checkSite({
       pages,
@@ -302,13 +315,21 @@ export function createConstraintPanel() {
   const show = (mode: 'page' | 'site' = 'page') => {
     if (!panel.isConnected) document.body.appendChild(panel);
     panel.hidden = false;
+    setLinesOnly(window.innerWidth < 640);
     if (mode === 'site') void runSite(); else run();
+    layoutChanges.observe(document.body, {subtree:true, childList:true, attributes:true, attributeFilter:['style','class','hidden','data-ds-fault-lines','data-ds-fault-axis']});
+    sizeChanges?.observe(document.body);
     window.addEventListener('scroll', schedule, { passive: true, capture: true });
     window.addEventListener('resize', schedule);
   };
   const hide = () => {
     stopSite();
     panel.hidden = true;
+    if (frame) cancelAnimationFrame(frame);
+    frame = 0;
+    faultLines.replaceChildren();
+    layoutChanges.disconnect();
+    sizeChanges?.disconnect();
     window.removeEventListener('scroll', schedule, { capture: true });
     window.removeEventListener('resize', schedule);
   };

package/DS1/0-face/constraint-site.ts

@@ -8,6 +8,7 @@ import { calculateScalingFactor, defaultScalingConfig } from './scaling';
 
 /** The narrowest phone still sold, the common ones and the widest. */
 export const PHONE_WIDTHS = [320, 375, 393, 430];
+export const VIEWPORT_WIDTHS = [...PHONE_WIDTHS, 768, 1024, 1440];
 /** Pages checked side by side, each in its own frame. */
 export const PAGES_AT_ONCE = 3;
 
@@ -61,7 +62,7 @@ const wait = (ms: number) => new Promise(done => setTimeout(done, ms));
  * order of `widths`. The page reflows at each width without loading again. The address carries `ph=out`,
  * the analytics opt-out most trackers honour, so the check counts no visits.
  */
-export async function inspectInFrame(host: Element | ShadowRoot, url: string, widths: number[] = PHONE_WIDTHS, height = 844): Promise<PageCheck[]> {
+export async function inspectInFrame(host: Element | ShadowRoot, url: string, widths: number[] = VIEWPORT_WIDTHS, height = 844): Promise<PageCheck[]> {
   const frame = document.createElement('iframe');
   frame.setAttribute('aria-hidden', 'true');
   frame.tabIndex = -1;
@@ -114,7 +115,7 @@ export function checkPage(page: ParentNode): PageCheck {
  * each width as it comes. Stops starting pages when `signal` aborts. Whatever the pages store in this
  * browser while they are checked is put back afterwards.
  */
-export async function checkSite({ pages, widths = PHONE_WIDTHS, inspect, onResult, signal, atOnce = PAGES_AT_ONCE }: {
+export async function checkSite({ pages, widths = VIEWPORT_WIDTHS, inspect, onResult, signal, atOnce = PAGES_AT_ONCE }: {
   pages: string[];
   widths?: number[];
   /** One page at every width, in the order of `widths`. */

package/DS1/0-face/constraints.ts

@@ -1,3 +1,4 @@
+import { faultLineGrids, inspectFaultLines } from './fault-lines';
 import { labelledButtons, inspectButtonLabels } from './button-label';
 import { inspectTextContrast, measureTextContrast } from "./text-contrast";
 import { inspectWordWrap, wordHeaders } from './word-wrap';
@@ -35,6 +36,14 @@ export type Constraint = {
   count: (root: ParentNode) => number;
 };
 
+/** The actual initial, including a component nested in another open shadow root. */
+function isAvatarInitial(element: Element): boolean {
+  for (let parent: Element | null = element; parent; parent = parent.assignedSlot ?? parent.parentElement ?? (parent.getRootNode() as ShadowRoot).host ?? null) {
+    if (parent.matches('ds-avatar, .ds-avatar')) return true;
+  }
+  return false;
+}
+
 /** A pixel either way is the same place. */
 const near = (a: number, b: number) => Math.abs(a - b) <= 1;
 const px = (n: number) => `${Math.round(n)}px`;
@@ -103,6 +112,14 @@ function rows(found: ReturnType<typeof cards>) {
 }
 
 export const constraints: Constraint[] = [
+  {
+    code: 'page.fault-lines',
+    rule: 'Fault lines keep related card and control grids aligned across the whole page, with matching track edges and gaps at every checked viewport width.',
+    why: 'Compare separate sections in the same alignment family; responsive layouts may change together, while unrelated groups and intentional exceptions remain independent.',
+    components: ['ds-page'],
+    check: { file: 'tests/fault-lines.test.ts', test: 'fault lines catch shifted tracks and unequal gaps across sections at each viewport' },
+    measures: ['alignment group', 'alignment groups'], count: root => faultLineGrids(root).length, inspect: inspectFaultLines,
+  },
   {
     code: 'select.hug',
     rule: 'Select and date-picker triggers use hug sizing, never fill sizing or growing to occupy the available row.',
@@ -146,6 +163,16 @@ export const constraints: Constraint[] = [
     count: root => measureTextContrast(root).length,
     inspect: inspectTextContrast,
   },
+  {
+    code: 'avatar.initial-contrast',
+    rule: 'Avatar initials have at least 4.5:1 contrast against their rendered fill, including after a theme or identity colour changes.',
+    why: 'Check each initial inside the avatar’s shadow root and in overlapping groups; decorative initials still need to be readable. Explicit ink overrides must pass too.',
+    components: ['ds-avatar'],
+    check: { file: 'tests/avatar-contrast.test.ts', test: 'avatar initials stay readable after theme and CSS-variable changes, and the avatar constraint catches overrides' },
+    measures: ['avatar initial', 'avatar initials'],
+    count: root => measureTextContrast(root).filter(result => isAvatarInitial(result.element)).length,
+    inspect: root => inspectTextContrast(root).filter(finding => isAvatarInitial(finding.element)),
+  },
   {
     code: 'card.media-level',
     rule: "A card's picture stands on the card's foot, a square below the words at least, so the pictures of cards side by side stand on one level whatever the words above them.",

package/DS1/0-face/define.ts

@@ -13,7 +13,7 @@ export function define(name: string, element: CustomElementConstructor): void {
   const type = element as StyledConstructor;
   const prototype = element.prototype as StyledElement;
   const original = prototype.createRenderRoot;
-  if (original) {
+  if (original && typeof document !== 'undefined') {
     const definingDocument = document;
     prototype.createRenderRoot = function (this: StyledElement) {
       if (this.ownerDocument === definingDocument || !type.elementStyles?.length) return original.call(this);

package/DS1/0-face/fault-lines.ts

@@ -0,0 +1,159 @@
+import type { Finding } from './constraints';
+
+const tolerance = 1;
+const near = (a: number, b: number) => Math.abs(a - b) <= tolerance;
+const style = (el: Element) => el.ownerDocument.defaultView!.getComputedStyle(el);
+const visible = (el: Element) => {
+  const box = el.getBoundingClientRect();
+  return box.width > 0 && box.height > 0 && style(el).visibility !== 'hidden' && style(el).display !== 'none';
+};
+
+/** Walk each open shadow tree once; slotted children already occur in the light tree. */
+function elements(root: ParentNode): Element[] {
+  return Array.from(root.querySelectorAll('*')).flatMap(el => [el, ...(el.shadowRoot ? elements(el.shadowRoot) : [])]);
+}
+
+type Grid = { element: Element; family: string | null; axis: 'x' | 'y'; lines: number[]; gaps: number[]; crossGap?: number; internalDrift: boolean; start: number; end: number };
+
+/** Related grids opt in by name; unlabelled card grids are candidates for human review. */
+export function faultLineGrids(root: ParentNode): Grid[] {
+  return elements(root).flatMap(element => {
+    const family = element.getAttribute('data-ds-fault-lines');
+    if (family === 'off' || !visible(element)) return [];
+    const children = Array.from(element.children).filter(visible);
+    if (!children.length) return [];
+    if (family === null && (!/grid/.test(style(element).display) || children.length < 2 ||
+      !children.every(child => child.matches('ds-card, .ds-card, ds-button, button')))) return [];
+    const axis = element.getAttribute('data-ds-fault-axis') === 'y' ? 'y' : 'x';
+    const boxes = children.map(child => child.getBoundingClientRect());
+    const crossStart = (box: DOMRect) => axis === 'x' ? box.top : box.left;
+    const crossEnd = (box: DOMRect) => axis === 'x' ? box.bottom : box.right;
+    const start = (box: DOMRect) => axis === 'x' ? box.left : box.top;
+    const end = (box: DOMRect) => axis === 'x' ? box.right : box.bottom;
+    const bands: DOMRect[][] = [];
+    for (const box of boxes.sort((a,b) => crossStart(a)-crossStart(b))) {
+      const band = bands.find(row => near(crossStart(row[0]!), crossStart(box)));
+      if (band) band.push(box); else bands.push([box]);
+    }
+    // The fullest band defines the tracks; an incomplete final row is valid.
+    const band = [...bands].sort((a,b) => b.length-a.length)[0]!.sort((a,b) => start(a)-start(b));
+    const lines = band.flatMap(box => [start(box), end(box)]);
+    const gaps = band.slice(1).map((box,index) => start(box)-end(band[index]!));
+    const crossGaps = bands.slice(1).map((row,index) => Math.min(...row.map(crossStart))-Math.max(...bands[index]!.map(crossEnd)));
+    const internalDrift = bands.some(row => row.length === band.length && row.slice().sort((a,b)=>start(a)-start(b)).some((box,index)=>!near(start(box),lines[index*2]!) || !near(end(box),lines[index*2+1]!))) || crossGaps.some(gap=>!near(gap,crossGaps[0]!));
+    return [{element, family, axis, lines, gaps, crossGap: crossGaps[0], internalDrift, start: lines[0]!, end: lines[lines.length - 1]!}];
+  });
+}
+
+function referenceFor(grids: Grid[], i: number) {
+  const current = grids[i]!;
+  return grids.slice(0,i).find(other => {
+      if (other.axis !== current.axis || other.lines.length !== current.lines.length) return false;
+      if (current.family !== null || other.family !== null) return current.family !== null && current.family === other.family;
+      return near(current.start,other.start) && near(current.end,other.end);
+    });
+}
+
+/** Fault lines compare rendered tracks across separate sections, in the current viewport. */
+export function inspectFaultLines(root: ParentNode): Finding[] {
+  const grids = faultLineGrids(root);
+  const findings: Finding[] = [];
+  for (let i = 0; i < grids.length; i++) {
+    const current = grids[i]!;
+    if (current.internalDrift) findings.push({element:current.element, ...(current.family === null ? {review:true} : {}), message:`Fault lines at ${current.element.ownerDocument.documentElement.clientWidth}px: tracks or repeated gaps drift inside ${current.family || 'this card grid'}. Align its complete rows and repeated spacing.`});
+    const reference = referenceFor(grids, i);
+    if (!reference) continue;
+    const drift = current.lines.map((line,index) => Math.abs(line-reference.lines[index]!));
+    const gapDrift = current.gaps.some((gap,index) => !near(gap,reference.gaps[index]!));
+    const rowDrift = current.crossGap !== undefined && reference.crossGap !== undefined && !near(current.crossGap,reference.crossGap);
+    if (!drift.some(value => value > tolerance) && !gapDrift && !rowDrift) continue;
+    const width = current.element.ownerDocument.documentElement.clientWidth;
+    const review = current.family === null;
+    findings.push({element: current.element, ...(review ? {review:true} : {}), message:
+      `Fault lines at ${width}px: ${current.family || 'these card grids'} ${review ? 'may be related but have' : 'have'} misaligned ${current.axis === 'x' ? 'column' : 'row'} edges or unequal gaps (edge drift ${Math.round(Math.max(...drift))}px; gaps ${current.gaps.map(Math.round).join('/')}px versus ${reference.gaps.map(Math.round).join('/')}px${rowDrift ? `; cross-axis gap ${Math.round(current.crossGap!)}px versus ${Math.round(reference.crossGap!)}px` : ''}). ${review ? 'Name the related groups with data-ds-fault-lines to enforce alignment, or mark an intentional exception off.' : 'Use the same tracks and gap for this family at this viewport.'}`});
+  }
+  return findings;
+}
+
+
+/** The same rendered geometry as the checker, painted without affecting layout or hit testing. */
+export function paintFaultLines(root: ParentNode, layer: SVGSVGElement): void {
+  const doc = layer.ownerDocument;
+  const width = doc.documentElement.clientWidth;
+  const height = doc.defaultView!.innerHeight;
+  layer.setAttribute('viewBox', `0 0 ${width} ${height}`);
+  layer.setAttribute('width', String(width));
+  layer.setAttribute('height', String(height));
+  layer.setAttribute('aria-hidden', 'true');
+  layer.style.cssText = 'position:fixed;inset:0;pointer-events:none;overflow:hidden;z-index:2147483644';
+  layer.replaceChildren();
+  const grids = faultLineGrids(root);
+  const failed = new Set(inspectFaultLines(root).map(finding => finding.element));
+  const drawn = new Set<string>();
+  const referenceInk = '#087ba8';
+  const faultInk = '#de0331';
+  function mark(tag: string, attributes: Record<string, string | number>, title?: string) {
+    const node = doc.createElementNS('http://www.w3.org/2000/svg', tag);
+    for (const [key, value] of Object.entries(attributes)) node.setAttribute(key, String(value));
+    if (title) {const tip = doc.createElementNS(node.namespaceURI, 'title');tip.textContent = title;node.appendChild(tip);}
+    layer.appendChild(node);
+    return node;
+  }
+  for (let index = 0; index < grids.length; index++) {
+    const grid = grids[index]!;
+    const reference = referenceFor(grids, index) ?? grid;
+    for (const edge of reference.lines) {
+      const key = `${grid.axis}:${edge}`;
+      if (drawn.has(key)) continue;
+      drawn.add(key);
+      mark('line', { 'data-fault-reference': '', x1: grid.axis === 'x' ? edge : 0, y1: grid.axis === 'y' ? edge : 0,
+        x2: grid.axis === 'x' ? edge : width, y2: grid.axis === 'y' ? edge : height,
+        stroke: referenceInk, 'stroke-width': 1, 'stroke-dasharray': '4 4' }, 'Reference edge');
+    }
+    const broken = failed.has(grid.element);
+    if (!broken) continue;
+    // Draw each actual child so drift inside a later row is visible too.
+    for (const child of Array.from(grid.element.children).filter(visible)) {
+      const box = child.getBoundingClientRect();
+      const edges = grid.axis === 'x' ? [box.left, box.right] : [box.top, box.bottom];
+      for (const edge of edges) {
+        if (reference.lines.some(expected => near(edge, expected))) continue;
+        mark('line', { 'data-fault-actual': '', x1: grid.axis === 'x' ? edge : box.left, y1: grid.axis === 'y' ? edge : box.top,
+          x2: grid.axis === 'x' ? edge : box.right, y2: grid.axis === 'y' ? edge : box.bottom,
+          stroke: faultInk, 'stroke-width': 2 }, 'Actual edge differs from the dashed reference');
+      }
+    }
+    // Row spacing can drift even when every column edge still aligns.
+    const rows: DOMRect[][] = [];
+    for (const child of Array.from(grid.element.children).filter(visible)) {
+      const box = child.getBoundingClientRect();
+      const start = grid.axis === 'x' ? box.top : box.left;
+      const row = rows.find(row => near(grid.axis === 'x' ? row[0]!.top : row[0]!.left, start));
+      if (row) row.push(box); else rows.push([box]);
+    }
+    rows.sort((a,b) => grid.axis === 'x' ? a[0]!.top-b[0]!.top : a[0]!.left-b[0]!.left);
+    const bounds = grid.element.getBoundingClientRect();
+    const crossGap = reference.crossGap ?? grid.crossGap;
+    if (crossGap !== undefined) for (let row = 1; row < rows.length; row++) {
+      const previousEnd = Math.max(...rows[row-1]!.map(box => grid.axis === 'x' ? box.bottom : box.right));
+      const actual = Math.min(...rows[row]!.map(box => grid.axis === 'x' ? box.top : box.left));
+      const expected = previousEnd+crossGap;
+      if (near(actual,expected)) continue;
+      for (const [edge,kind] of [[expected,'reference'],[actual,'actual']] as const) {
+        mark('line', {[`data-fault-${kind}`]: '', x1:grid.axis === 'x' ? bounds.left : edge, y1:grid.axis === 'x' ? edge : bounds.top,
+          x2:grid.axis === 'x' ? bounds.right : edge, y2:grid.axis === 'x' ? edge : bounds.bottom,
+          stroke:kind === 'reference' ? referenceInk : faultInk, 'stroke-width':kind === 'reference' ? 1 : 2,
+          'stroke-dasharray':kind === 'reference' ? '4 4' : ''}, `Row gap ${Math.round(actual-previousEnd)}px; reference ${Math.round(crossGap)}px`);
+      }
+    }
+    const box = grid.element.getBoundingClientRect();
+    const label = mark('text', { 'data-fault-gap': '', x: Math.max(4,box.left), y: Math.max(16,Math.min(height-4,box.top+16)),
+      fill: faultInk, stroke: 'var(--ds-background-color, white)', 'stroke-width': 3, 'paint-order': 'stroke',
+      'font-family': 'var(--ds-typeface-regular, sans-serif)', 'font-size': 12 });
+    const gaps = grid.gaps.map(gap => Math.round(gap)).join('/');
+    const expected = reference.gaps.map(gap => Math.round(gap)).join('/');
+    label.textContent = `Gap ${gaps || '—'}px · reference ${expected || '—'}px` +
+      (grid.crossGap !== undefined && reference.crossGap !== undefined && !near(grid.crossGap,reference.crossGap)
+        ? ` · row gap ${Math.round(grid.crossGap)}px / ${Math.round(reference.crossGap)}px` : '');
+  }
+}

package/DS1/1-root/cjk.css

@@ -1,4 +1,4 @@
-/* version 0.3.0 */
+/* version 0.3.1 */
 
 /* Noto Sans for Japanese and Chinese, for a product that shows them. Opt in:
    link it beside one.css or fonts.css, or ask Sync 1 for "cjk": true. Without

package/DS1/1-root/fonts.css

@@ -1,4 +1,4 @@
-/* version 0.3.0 */
+/* version 0.3.1 */
 
 /* Design system 1's faces and the typeface tokens that name them, on their
    own: a page that does not load one.css links this sheet (one.css imports

package/DS1/1-root/one.css

@@ -1,4 +1,4 @@
-/* version 0.3.0 */
+/* version 0.3.1 */
 
 @import "./grid.css";
 @import "./component-tokens.css";
@@ -246,7 +246,8 @@ body {
 }
 
 .ds-input::placeholder {
-  color: var(--ds-input-placeholder-color, var(--ds-text-color-muted));
+  /* one.css is copied on its own, without component-tokens.css: the fallback is that file's muted ink. */
+  color: var(--ds-input-placeholder-color, var(--ds-text-color-muted, light-dark(#5f5f5f, #cacaca)));
 }
 
 .ds-card {

package/DS1/2-core/ds-avatar.ts

@@ -1,6 +1,7 @@
 import { LitElement, html, nothing, unsafeCSS, type PropertyValues } from "lit";
 import { styleMap } from "lit/directives/style-map.js";
 import { keyed } from "lit/directives/keyed.js";
+import { contrastRatio, colorReader, composite, type RGBA } from "../0-face/text-contrast";
 import { define } from "../0-face/define";
 import { provideIcons } from "./ds-icon";
 import { avatarIcon } from "./generated/icon-avatar";
@@ -12,9 +13,11 @@ provideIcons({ avatar: avatarIcon });
 
 /** The ink that reads on a fill: black on a light one, white on a dark one. */
 const inkOn = (rgb: number[]) => {
-  const linear = rgb.map((n) => (n <= 0.04045 ? n / 12.92 : ((n + 0.055) / 1.055) ** 2.4));
-  const luminance = linear[0] * 0.2126 + linear[1] * 0.7152 + linear[2] * 0.0722;
-  return luminance > 0.22 ? "var(--ds-black)" : "var(--ds-white)";
+  const fill = [...rgb, 1] as RGBA;
+  const white: RGBA = [1, 1, 1, 1], black: RGBA = [42 / 255, 42 / 255, 42 / 255, 1];
+  if (contrastRatio(black, fill) >= 4.5) return "var(--ds-black)";
+  if (contrastRatio(white, fill) >= 4.5) return "var(--ds-white)";
+  return "black";
 };
 
 /** Saved identity colours are hex; their ink must stay legible in either theme. */
@@ -93,6 +96,28 @@ export class Avatar extends LitElement {
     this.fit = "cover";
     this.logo = this.mask = this.outlined = this.pending = this.plain = this.loaded = this.failed = false;
   }
+  private inkObserver?: MutationObserver;
+  private inkFrame = 0;
+  private readonly queueInk = () => {
+    const view = this.ownerDocument.defaultView!;
+    if (!this.inkFrame) this.inkFrame = view.requestAnimationFrame(() => { this.inkFrame = 0; this.resolveInk(); });
+  };
+  connectedCallback() {
+    super.connectedCallback();
+    const view = this.ownerDocument.defaultView!;
+    this.inkObserver = new view.MutationObserver(this.queueInk);
+    // Observe only the painted ancestors, never our own shadow's ink writes.
+    for (let parent: Element | null = this; parent; parent = parent.parentElement ?? (parent.getRootNode() as ShadowRoot).host ?? null) {
+      this.inkObserver.observe(parent, { attributes: true, attributeFilter: ['class', 'style', 'data-theme'] });
+    }
+    view.addEventListener('load', this.queueInk, true);
+  }
+  disconnectedCallback() {
+    super.disconnectedCallback(); this.inkObserver?.disconnect();
+    const view = this.ownerDocument.defaultView!;
+    view.cancelAnimationFrame(this.inkFrame); this.inkFrame = 0;
+    view.removeEventListener('load', this.queueInk, true);
+  }
   protected willUpdate(changed: PropertyValues<this>) {
     if (changed.has("src")) {
       this.loaded = false;
@@ -102,7 +127,7 @@ export class Avatar extends LitElement {
   }
   /** A fill named by a variable (`var(--brand-highlight)`) gets its ink once the browser has resolved it. */
   protected updated() {
-    if (this.ink || this.pending || this.plain || !this.color || avatarInk(this.color)) return;
+    if (this.ink || this.pending || this.plain) return;
     this.resolveInk();
   }
   /** Reads the fill as drawn; while the variable is still undefined (its stylesheet on its way), looks again next
@@ -110,9 +135,23 @@ export class Avatar extends LitElement {
   private resolveInk(tries = 0) {
     const frame = this.renderRoot.querySelector<HTMLElement>(".frame");
     if (!frame || !this.isConnected) return;
-    const ink = inkOnResolved(getComputedStyle(frame).backgroundColor);
-    if (ink) { frame.style.color = ink; return; }
-    if (tries < 60) requestAnimationFrame(() => this.resolveInk(tries + 1));
+    if (this.ink || this.pending || this.plain) return;
+    const view = this.ownerDocument.defaultView!;
+    const read = colorReader(this.ownerDocument);
+    let fill = read(view.getComputedStyle(frame).backgroundColor);
+    if (fill && fill[3] > 0) {
+      for (let parent: Element | null = this; parent && fill[3] < 1; parent = parent.parentElement ?? (parent.getRootNode() as ShadowRoot).host ?? null) {
+        const background = read(view.getComputedStyle(parent).backgroundColor);
+        if (background) fill = composite(fill, background);
+      }
+      if (fill[3] < 1) return;
+      const tokens = view.getComputedStyle(this);
+      const black = read(tokens.getPropertyValue('--ds-black').trim()), white = read(tokens.getPropertyValue('--ds-white').trim());
+      const ink = black && contrastRatio(black, fill) >= 4.5 ? 'var(--ds-black)' : white && contrastRatio(white, fill) >= 4.5 ? 'var(--ds-white)' : contrastRatio([0,0,0,1], fill) >= 4.5 ? 'black' : 'white';
+      if (frame.style.color !== ink) frame.style.color = ink;
+      return;
+    }
+    if (tries < 60) this.ownerDocument.defaultView!.requestAnimationFrame(() => this.resolveInk(tries + 1));
     if (tries === 0 && this.ownerDocument.readyState !== "complete") {
       this.ownerDocument.defaultView?.addEventListener("load", () => this.resolveInk(60), { once: true });
     }
@@ -129,7 +168,7 @@ export class Avatar extends LitElement {
         >`;
     return html`<span
       class="frame"
-      style=${styleMap({ backgroundColor: !this.pending && !this.plain ? this.color || undefined : undefined, color: !this.pending ? this.ink || avatarInk(this.color) : undefined })}
+      style=${styleMap({ backgroundColor: !this.pending && !this.plain ? this.color || undefined : undefined, color: !this.pending ? this.ink || (!this.plain ? avatarInk(this.color) : undefined) : undefined })}
       role=${this.label ? "img" : nothing}
       aria-label=${this.label || nothing}
       aria-hidden=${this.label ? nothing : "true"}

package/DS1/2-core/styles/ds-button-host.css

@@ -39,7 +39,8 @@
 }
 
 :host([fit][control="slotted"]) ::slotted(:is(button, a)) {
-  width: max-content !important;
+  /* The host hugs on the grid; its visible face must occupy that same box. */
+  width: 100% !important;
   min-width: var(--ds-button-min-width, 0px) !important;
   justify-content: var(--ds-button-align, flex-start) !important;
 }

package/DS1/2-core/styles/ds-button.css

@@ -46,7 +46,8 @@
 }
 :host([fit]) :is(button, a) {
   flex: 0 0 auto;
-  width: max-content;
+  /* Hug sizing belongs to the host, including its grid rounding. */
+  width: 100%;
   min-width: var(--ds-button-min-width, 0px);
   justify-content: var(--ds-button-align, flex-start);
 }

package/DS1/2-core/styles/ds-tag.css

@@ -29,7 +29,8 @@
   padding-inline: var(--_tag-padding, calc(4px * var(--ds-sf, 1)));
   border-radius: var(--_tag-radius, var(--ds-radius));
   background: var(--ds-tag-background, light-dark(color-mix(in srgb, var(--ds-tag-accent, var(--ds-grey, #7a7a7a)) 28%, white), color-mix(in srgb, var(--ds-tag-accent, var(--ds-grey, #7a7a7a)) 20%, var(--ds-black, #2a2a2a))));
-  color: var(--ds-tag-color, light-dark(color-mix(in srgb, var(--ds-tag-accent, var(--ds-grey, #7a7a7a)) 45%, black), var(--ds-tag-accent, var(--ds-grey, #7a7a7a))));
+  /* Tint the dark-mode ink: raw grey/accent colours cannot meet 4.5:1 on this fill. */
+  color: var(--ds-tag-color, light-dark(color-mix(in srgb, var(--ds-tag-accent, var(--ds-grey, #7a7a7a)) 45%, black), color-mix(in srgb, var(--ds-tag-accent, var(--ds-grey, #7a7a7a)) 30%, white)));
   font-family: var(--ds-typeface-regular);
   font-feature-settings: var(--ds-font-features);
   font-size: var(--_tag-font-size, var(--ds-type-size-default));

package/DS1/3-unit/context-trigger.ts

@@ -29,6 +29,7 @@ export function bindContextMenuTrigger(
   let suppressed: HTMLElement | null = null;
   let release: ReturnType<typeof setTimeout> | undefined;
   let disposed = false;
+  let mousePress: { event: PointerEvent; path: EventTarget[]; target: EventTarget | null } | undefined;
   if (aria) trigger.setAttribute("aria-haspopup", "menu");
   if (selection) trigger.classList.add("ds-context-trigger");
   const enabled = (control: HTMLElement) => control.isConnected &&
@@ -48,6 +49,7 @@ export function bindContextMenuTrigger(
     release = setTimeout(clearSuppression, 1000);
   };
   const cancel = () => {
+    mousePress = undefined;
     clearTimeout(timer); timer = undefined; point = undefined;
     doc.removeEventListener("pointermove", move);
     doc.removeEventListener("pointerup", cancel);
@@ -56,10 +58,28 @@ export function bindContextMenuTrigger(
   };
   const context = (event: MouseEvent) => {
     if (event.defaultPrevented) return;
-    const control = resolve(event); if (!control || !enabled(control)) return;
+    // Settling a transform on pointerdown can move another row beneath the
+    // pointer before Chromium hit-tests contextmenu. Keep the initiating row.
+    const pressed = mousePress;
+    mousePress = undefined;
+    const followsPress = pressed && event.button === 2 && Math.hypot(event.clientX - pressed.event.clientX, event.clientY - pressed.event.clientY) <= 10;
+    // Native events lose their composed path after dispatch. Delegated and
+    // shadow-root controls still need the original path and unretargeted target.
+    const gesture = followsPress ? new Proxy(pressed.event, {
+      get(target, key) {
+        if (key === "composedPath") return () => pressed.path;
+        if (key === "target") return pressed.target;
+        const value = Reflect.get(target, key, target);
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+    }) : event;
+    // Adopted controls retain their creating realm’s prototype; ownerDocument
+    // alone cannot choose an instanceof constructor. Containment stays authoritative.
+    if (gesture !== event && (typeof (gesture.target as Node | null)?.nodeType !== "number" || !trigger.contains(gesture.target as Node))) return;
+    const control = resolve(gesture); if (!control || !enabled(control)) return;
     cancel();
     if (suppressed === control) { event.preventDefault(); return; }
-    if (open({ x: event.clientX, y: event.clientY }, control, event) === false) return;
+    if (open({ x: event.clientX, y: event.clientY }, control, gesture) === false) return;
     event.preventDefault();
     if (selection && event.button === 0) arm(control);
   };
@@ -88,6 +108,11 @@ export function bindContextMenuTrigger(
       if (open(at, control, event) !== false) arm(control);
     }, LONG_PRESS);
   };
+  const rememberMouse = (event: PointerEvent) => {
+    mousePress = !event.defaultPrevented && event.pointerType === "mouse" && event.button === 2 ? { event, path: event.composedPath(), target: event.target } : undefined;
+  };
+  trigger.addEventListener("pointerdown", rememberMouse, true);
+  trigger.addEventListener("pointercancel", cancel, true);
   trigger.addEventListener("contextmenu", context);
   trigger.addEventListener("keydown", key);
   trigger.addEventListener("pointerdown", press);
@@ -98,6 +123,8 @@ export function bindContextMenuTrigger(
       trigger.removeEventListener("contextmenu", context);
       trigger.removeEventListener("keydown", key);
       trigger.removeEventListener("pointerdown", press);
+      trigger.removeEventListener("pointerdown", rememberMouse, true);
+      trigger.removeEventListener("pointercancel", cancel, true);
       if (aria) {
         if (previousAria === null) trigger.removeAttribute("aria-haspopup"); else trigger.setAttribute("aria-haspopup", previousAria);
       }

package/DS1/3-unit/ds-form.ts

@@ -1,3 +1,4 @@
+import { define } from "../0-face/define";
 // ds-form.ts
 // Form component for handling form submissions and validation
 
@@ -338,7 +339,7 @@ export class Form extends LitElement {
   }
 }
 
-customElements.define("ds-form", Form);
+define("ds-form", Form);
 
 declare global {
   interface HTMLElementTagNameMap {

package/DS1/3-unit/ds-table.ts

@@ -1,3 +1,4 @@
+import { define } from "../0-face/define";
 // ds-table.ts
 // A data table: rows one square high on hairlines, drawn from data with the
 // same rules as a native `<table class="ds-table">` (1-root/table.css). With
@@ -498,7 +499,7 @@ function text(value: unknown): string {
   return typeof value === "number" ? value.toLocaleString() : String(value);
 }
 
-customElements.define("ds-table", DsTable);
+define("ds-table", DsTable);
 
 declare global {
   interface HTMLElementTagNameMap {

package/DS1/4-page/ds-container.ts

@@ -1,3 +1,4 @@
+import { define } from "../0-face/define";
 // ds-container.ts
 // Container component with responsive width constraints
 
@@ -19,7 +20,7 @@ export class Container extends LitElement {
   }
 }
 
-customElements.define("ds-container", Container);
+define("ds-container", Container);
 
 declare global {
   interface HTMLElementTagNameMap {

package/dist/0-face/constraint-panel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constraint-panel.d.ts","sourceRoot":"","sources":["../../DS1/0-face/constraint-panel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAKlF,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB;kBA2Rf,MAAM,GAAG,MAAM;;;;;;oBA9KI,UAAU;;EAuMlD;AAED,4HAA4H;AAC5H,eAAO,MAAM,gBAAgB,aAAa,CAAC;AAiB3C;;;;GAIG;AACH,eAAO,MAAM,WAAW,eACiD,CAAC;AAE1E,mHAAmH;AACnH,wBAAgB,gBAAgB,CAAC,MAAM,SAAyB,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAIxF;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CA4C7C"}
+{"version":3,"file":"constraint-panel.d.ts","sourceRoot":"","sources":["../../DS1/0-face/constraint-panel.ts"],"names":[],"mappings":"AACA,OAAO,EAAsB,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAKlF,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB;kBAuSf,MAAM,GAAG,MAAM;;;;;;oBAjLI,UAAU;;EAkNlD;AAED,4HAA4H;AAC5H,eAAO,MAAM,gBAAgB,aAAa,CAAC;AAiB3C;;;;GAIG;AACH,eAAO,MAAM,WAAW,eACiD,CAAC;AAE1E,mHAAmH;AACnH,wBAAgB,gBAAgB,CAAC,MAAM,SAAyB,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAIxF;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CA4C7C"}