@repobit/dex-system-design 0.25.11 → 0.26.0

package/src/components/carousel/carousel.js

@@ -1,6 +1,8 @@
 import { LitElement, html } from "lit";
-import { tokens } from "../../tokens/tokens.js";
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import "../../tokens/tokens.js";
 import carouselCSS from "../carousel/carousel.css.js";
+import "../heading/heading.js";
 import "../modal/modal.js";
 export class CarouselItem extends LitElement {
   static properties = {
@@ -52,12 +54,13 @@ export class CarouselItem extends LitElement {
     `;
   }
 
-  static styles = [tokens, carouselCSS];
+  static styles = [carouselCSS];
 }
 
 class CustomCarousel extends LitElement {
   static properties = {
     title       : { type: String },
+    headingLevel: { type: Number, attribute: "heading-level" },
     selectedItem: { type: Object }
   };
 
@@ -65,6 +68,31 @@ class CustomCarousel extends LitElement {
     super();
     this.selectedItem = null;
     this.title = "";
+    this.headingLevel = 2;
+  }
+
+  /**
+   * The heading element this section renders. Level is the document-outline
+   * question and belongs to whoever composes the page; the type scale is this
+   * component's own and does not move with it. Defaults to h2, because a
+   * reusable section cannot know it is the only thing on the page, and two of
+   * these used to put two h1s on one.
+   */
+  get _headingTag() {
+    const n = Number(this.headingLevel);
+    return Number.isInteger(n) && n >= 1 && n <= 6 ? `h${n}` : "h2";
+  }
+
+  /* bd-h already builds the dynamic tag, and it keeps the two questions apart
+     the way this component needs: as= is the outline level the page composes,
+     visual-level= is the type role, which is ours. Building the element here
+     meant re-implementing bd-h and then hand-writing the type on top of it --
+     and the hand-written type carried no line-height and no margin, so the
+     title rendered with the browser's own h2 margins. */
+  _renderTitle(className) {
+    return html`<bd-h as=${this._headingTag} visual-level="h3" class=${className}
+      >${this.title}</bd-h
+    >`;
   }
 
   firstUpdated() {
@@ -224,7 +252,7 @@ class CustomCarousel extends LitElement {
       <div class="bd-carousel">
         ${this.title
           ? html`<div class="bd-header-carousel">
-              <h1 class="bd-section-title">${this.title}</h1>
+              ${this._renderTitle("bd-section-title")}
             </div>`
           : ""}
 
@@ -265,7 +293,7 @@ class CustomCarousel extends LitElement {
     `;
   }
 
-  static styles = [tokens, carouselCSS];
+  static styles = [carouselCSS];
 }
 
 customElements.define("bd-carousel-item", CarouselItem);

package/src/components/checkbox/checkbox.css.js

@@ -1,132 +1,150 @@
 import { css } from "lit";
 
+/**
+ * Styled entirely from src/tokens/tokens.js — see CLAUDE.md, "The foundation
+ * rule". Measurements were matched to the ds-checkbox design by finding the
+ * token that already carries each value.
+ *
+ * The whole row is the control, not just the box. That makes clicking the
+ * label work (it did nothing before) and gives the target the 24px minimum
+ * WCAG 2.5.8 asks for, which a 20px box alone cannot reach.
+ */
 export default css`
   :host {
     display: inline-block;
   }
 
-  .bd-checkbox,
-  .bd-radio {
+  .bd-checkbox {
     display: inline-flex;
     align-items: center;
-    cursor: pointer;
     gap: var(--spacing-8);
-    font-family: sans-serif;
-    font-size: 14px;
+    /* padding rather than a min-height: a min-height adds its slack only
+       above and below, which left the focus ring 2px from the content at the
+       sides and 4px at the top and bottom. Padding insets all four edges
+       equally, and still carries the row past the 24px WCAG 2.5.8 asks for. */
+    padding: var(--spacing-2);
+    cursor: pointer;
+    font-family: var(--typography-fontFamily-sans);
+    /* body-small: sm / normal / 1.5, which is what this already rendered on all
+       three axes. Only the axes this rule declares are adopted -- the role also
+       carries a family and a tracking, and importing those would change text
+       the rule never spoke for. */
+    font-size: var(--typography-body-small-fontSize);
+    line-height: var(--typography-body-small-lineHeight);
+    color: var(--color-text-primary);
     vertical-align: middle;
+    outline: none;
   }
 
-  .bd-checkbox.disabled,
-  .bd-radio.disabled {
-    cursor: not-allowed;
-    opacity: 0.6;
-  }
-
-  .checkbox-label,
-  .radio-label {
-    font-size: 14px;
-    color: black;
+  .bd-checkbox:focus-visible {
+    /* the one focus ring — see Foundations/Focus. A two-colour ring whose
+       white inner band keeps it visible on a coloured or dark surface, which a
+       single-colour outline cannot do. */
+    outline: none;
+    box-shadow: var(--focus-outline-primary);
+    border-radius: var(--focus-outline-radius);
   }
 
-  /* Checkbox */
-  .bd-checkbox .bd-outer {
-    width: var(--spacing-22);
-    height: var(--spacing-22);
-    border: var(--spacing-2) solid var(--color-blue-500);
-    border-radius: 4px;
-    display: flex;
+  /* ---- the box ---------------------------------------------------------- */
+  .box {
+    flex: none;
+    width: var(--dimension-20);
+    height: var(--dimension-20);
+    box-sizing: border-box;
+    border: var(--border-width-2) solid var(--color-action-primary);
+    border-radius: var(--radius-sm);
+    background: var(--color-surface-default);
+    display: inline-flex;
     align-items: center;
     justify-content: center;
-    box-sizing: border-box;
-    transition: border-color 0.2s ease;
-    outline: none;
+    /* the mark is drawn in currentColor, so one declaration moves both. It is
+       ink on an action fill, not "the page colour" -- the two are both white
+       here, and only one of them stays white in a dark theme */
+    color: var(--color-action-on-fill);
+    transition: background-color var(--transition-duration-normal) var(--transition-easing-smooth),
+      border-color var(--transition-duration-normal) var(--transition-easing-smooth);
   }
 
-  .bd-checkbox .bd-inner {
-    width: var(--spacing-12);
-    height: var(--spacing-12);
-    background-color: var(--color-blue-500);
-    border-radius: var(--spacing-2);
-    transform: scale(0);
-    transition: transform 0.2s ease, background-color 0.2s ease;
+  .bd-checkbox:hover .box {
+    border-color: var(--color-action-primary-hover);
   }
 
-  .bd-checkbox .bd-inner.visible {
-    transform: scale(1);
+  /* ---- checked and indeterminate: the box fills, the mark is white ------ */
+  :host([checked]) .box,
+  :host([indeterminate]) .box {
+    background: var(--color-action-primary);
+    border-color: var(--color-action-primary);
   }
 
-  .bd-radio .bd-outer {
-    width: var(--spacing-22);
-    height: var(--spacing-22);
-    border: var(--spacing-2) solid var(--color-blue-500);
-    border-radius: 50%;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    box-sizing: border-box;
-    transition: border-color 0.2s ease;
-    outline: none;
+  :host([checked]) .bd-checkbox:hover .box,
+  :host([indeterminate]) .bd-checkbox:hover .box {
+    background: var(--color-action-primary-hover);
+    border-color: var(--color-action-primary-hover);
+  }
+
+  .mark {
+    width: var(--dimension-12);
+    height: var(--dimension-12);
+    display: block;
   }
 
-  .bd-radio .bd-inner {
-    width: var(--spacing-12);
-    height: var(--spacing-12);
-    background-color: var(--color-blue-500);
-    border-radius: 50%;
-    transform: scale(0);
-    transition: transform 0.2s ease, background-color 0.2s ease;
+  .mark path {
+    fill: none;
+    stroke: currentColor;
+    stroke-width: var(--border-width-2);
+    /* flat ends and a mitred vertex: the tick and the dash read as sharp,
+       matching the square corners of the box rather than softening them */
+    stroke-linecap: butt;
+    stroke-linejoin: miter;
   }
 
-  .bd-radio .bd-inner.visible {
-    transform: scale(1);
+  /* ---- disabled --------------------------------------------------------
+     Grey throughout, and the label greys too rather than the whole row
+     dropping to an opacity, which is what the design specifies. Exempt from
+     contrast under WCAG 1.4.3.
+
+     The disabled edge is --color-border-disabled, the role named for the
+     state it expresses. It was --color-border-subtle, a hierarchy role, and
+     the family carried two answers: five controls drew neutral-200 for a
+     disabled edge and four drew neutral-300, so a disabled checkbox and a
+     disabled text field did not agree on what one looks like. The state role
+     wins because the state is what the colour means, and because neutral-300
+     measures 2.27:1 against the page where neutral-200 measures 1.66. A
+     disabled control is exempt under 1.4.11, so this is perceptibility rather
+     than conformance -- but it moves the right way, and it stays subordinate
+     to every enabled edge.
+
+     The fills below still draw neutral-200. A fill is not an edge, and whether
+     a disabled checked box should darken along with its border is a separate
+     question that has not been put yet. */
+  :host([disabled]) .bd-checkbox {
+    cursor: not-allowed;
+    color: var(--color-text-subtle);
   }
 
-  .bd-checkbox .bd-outer:hover,
-  .bd-radio .bd-outer:hover {
-    border-color: var(--color-blue-700);
+  :host([disabled]) .box {
+    border-color: var(--color-border-disabled);
+    background: var(--color-surface-default);
   }
 
-  .bd-checkbox .bd-inner:hover,
-  .bd-radio .bd-inner:hover {
-    background-color: var(--color-blue-700);
+  :host([disabled][checked]) .box,
+  :host([disabled][indeterminate]) .box {
+    background: var(--color-border-subtle);
+    border-color: var(--color-border-disabled);
   }
 
-  .bd-checkbox.disabled .bd-outer.checked,
-  .bd-radio.disabled .bd-outer.checked {
-    border-color: #b0b0b0;
+  :host([disabled]) .bd-checkbox:hover .box {
+    border-color: var(--color-border-disabled);
   }
 
-  .bd-checkbox.disabled .bd-outer,
-  .bd-radio.disabled .bd-outer {
-    border-color: #b0b0b0;
+  :host([disabled][checked]) .bd-checkbox:hover .box,
+  :host([disabled][indeterminate]) .bd-checkbox:hover .box {
+    background: var(--color-border-subtle);
   }
 
-  .bd-checkbox.disabled .bd-inner,
-  .bd-radio.disabled .bd-inner {
-    background-color: #b0b0b0;
+  @media (prefers-reduced-motion: reduce) {
+    .box {
+      transition: none;
+    }
   }
- 
-
-.bd-checkbox .bd-outer:focus {
-  outline: none;
-}
-
-.bd-checkbox .bd-outer:focus-visible {
-  outline: var(--spacing-2) solid var(--color-blue-500);
-  outline-offset: var(--spacing-2);
-}
-.bd-checkbox .bd-outer.checked:focus-visible {
-  border-color: var(--color-blue-700);
-}
-
-.bd-checkbox .bd-outer.checked:focus-visible .bd-inner.visible {
-  background-color: var(--color-blue-700);
-}
-  .bd-checkbox .bd-outer.checked.kbd-activate {
-  border-color: var(--color-blue-700);
-}
-
-.bd-checkbox .bd-outer.checked.kbd-activate .bd-inner.visible {
-  background-color: var(--color-blue-700);
-}
 `;

package/src/components/checkbox/checkbox.js

@@ -1,129 +1,103 @@
 import { LitElement, html } from "lit";
-import { tokens } from "../../tokens/tokens.js";
-import checkboxCSS from "./checkbox.css";
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import "../../tokens/tokens.js";
+// the extension matters: "./checkbox.css" only resolved because Vite appends
+// .js for us, and failed outright under native ESM
+import checkboxCSS from "./checkbox.css.js";
 
 export class BdCheckbox extends LitElement {
-  static styles = [tokens, checkboxCSS];
+  static styles = [checkboxCSS];
 
   static properties = {
-    name    : { type: String },
-    value   : { type: String },
-    checked : { type: Boolean, reflect: true },
-    disabled: { type: Boolean, reflect: true },
-    label   : { type: String }
+    name         : { type: String },
+    value        : { type: String },
+    checked      : { type: Boolean, reflect: true },
+    indeterminate: { type: Boolean, reflect: true },
+    disabled     : { type: Boolean, reflect: true },
+    label        : { type: String }
   };
 
   constructor() {
     super();
     this.name = "";
     this.value = "";
+    // checked was left undefined, which rendered aria-checked="" — an invalid
+    // value, so an unchecked box announced no state at all
+    this.checked = false;
+    this.indeterminate = false;
     this.disabled = false;
     this.label = "";
-    this._hadKeyboardFocus = false;
-
-    this._handleDocumentKeydown = (e) => {
-      if (e.key === "Tab") {
-        this._hadKeyboardFocus = true;
-      }
-    };
-
-    this._handleDocumentMousedown = this._handleDocumentMousedown.bind(this);
-  }
-
-  _handleDocumentMousedown(e) {
-    const path = e.composedPath();
-    const target = path.find(
-      (el) =>
-        el instanceof HTMLElement &&
-        el.classList &&
-        el.classList.contains("bd-outer")
-    );
-    if (target) {
-      target.classList.remove("focus");
-    }
-    setTimeout(() => {
-      this._hadKeyboardFocus = false;
-    }, 0);
   }
 
-  connectedCallback() {
-    super.connectedCallback();
-    document.addEventListener("keydown", this._handleDocumentKeydown);
-    document.addEventListener("mousedown", this._handleDocumentMousedown);
+  /** true | false | mixed — mixed wins, as it does natively. */
+  get _ariaChecked() {
+    if (this.indeterminate) return "mixed";
+    return this.checked ? "true" : "false";
   }
 
-  disconnectedCallback() {
-    super.disconnectedCallback();
-    document.removeEventListener("keydown", this._handleDocumentKeydown);
-    document.removeEventListener("mousedown", this._handleDocumentMousedown);
-  }
-
-  handleClick() {
+  _toggle() {
     if (this.disabled) return;
-    this.checked = !this.checked;
+
+    // clicking an indeterminate box resolves it to checked, as it does natively
+    if (this.indeterminate) {
+      this.indeterminate = false;
+      this.checked = true;
+    } else {
+      this.checked = !this.checked;
+    }
 
     this.dispatchEvent(
       new CustomEvent("change", {
-        detail  : { value: this.checked ? this.value : null },
+        detail  : { checked: this.checked, value: this.checked ? this.value : null },
         bubbles : true,
         composed: true
       })
     );
   }
 
-  handleFocus(e) {
-    if (this._hadKeyboardFocus) {
-      e.target.classList.add("focus");
-    }
-  }
-
-  handleKeydown(e) {
-    if (this.disabled) return;
-
+  _handleKeydown(e) {
+    // Space is the native activation key. Enter is kept as a convenience: this
+    // control is not form-associated, so Enter has nothing else to do here.
     if (e.key === " " || e.key === "Enter") {
       e.preventDefault();
-      this.handleClick();
-
-      const outer = e.target;
-
-      if (this._hadKeyboardFocus) {
-        outer.classList.add("focus", "kbd-activate");
-
-        setTimeout(() => {
-          outer.classList.remove("kbd-activate");
-        }, 150);
-      }
+      this._toggle();
     }
   }
 
-
-  handleBlur(e) {
-    setTimeout(() => {
-      const active = this.shadowRoot.activeElement || document.activeElement;
-      if (active !== e.target) {
-        e.target.classList.remove("focus");
-      }
-    }, 0);
+  _renderMark() {
+    if (this.indeterminate) {
+      return html`<svg class="mark" viewBox="0 0 12 12" aria-hidden="true" focusable="false">
+        <path d="M2.5 6H9.5" />
+      </svg>`;
+    }
+    if (this.checked) {
+      return html`<svg class="mark" viewBox="0 0 12 12" aria-hidden="true" focusable="false">
+        <path d="M2.5 6.5L4.75 8.75L9.5 3.5" />
+      </svg>`;
+    }
+    return "";
   }
 
   render() {
+    // The row carries the role, the focus and the click target, so the label is
+    // part of the control rather than decoration beside it. The previous markup
+    // put role and tabindex on the box alone, which meant clicking the label
+    // did nothing and the only target was 20px — under the 24px WCAG 2.5.8 asks
+    // for. There is no native input to associate a <label> with, so <div> is
+    // honest about what this is.
     return html`
-      <label class="bd-checkbox ${this.disabled ? "disabled" : ""}">
-        <span
-          class="bd-outer ${this.checked && !this.disabled ? "checked" : ""}"
-          role="checkbox"
-          aria-checked="${this.checked}"
-          aria-disabled="${this.disabled}"
-          tabindex="${this.disabled ? -1 : 0}"
-          @click=${this.handleClick}
-          @keydown=${this.handleKeydown}
-          @focus=${this.handleFocus}
-          @blur=${this.handleBlur}
-        >
-          <span class="bd-inner ${this.checked ? "visible" : ""}"></span>
-        </span>
-        <span class="checkbox-label">${this.label}</span>
-      </label>
+      <div
+        class="bd-checkbox"
+        role="checkbox"
+        aria-checked="${this._ariaChecked}"
+        aria-disabled="${this.disabled ? "true" : "false"}"
+        tabindex="${this.disabled ? -1 : 0}"
+        @click=${this._toggle}
+        @keydown=${this._handleKeydown}
+      >
+        <span class="box" part="box">${this._renderMark()}</span>
+        <span class="label" part="label"><slot>${this.label}</slot></span>
+      </div>
     `;
   }
 }