@repobit/dex-system-design 1.0.0 → 2.0.0

package/src/components/carousel/carousel.css.js

@@ -12,7 +12,10 @@ export default css`
     display: block;
     align-items: center;
     position: relative;
-    margin-bottom: 100px;
+    /* 100px used to stand here, room for two arrows positioned absolutely
+       65px below the track. The dots are in the flow now, so the space below
+       the track is their margin, their 24px and this: 96. */
+    margin-bottom: var(--spacing-48);
     max-width: 100%;
     flex-direction: column;
   }
@@ -27,17 +30,16 @@ export default css`
      hand while leaving its line-height unset, which is how the title came to
      render at the browser's default leading and with the browser's default h2
      margins. LightCarousel and CardFeatures declare no such rule either. */
-  div.bd-arrow {
-    padding: var(--spacing-2);
-    visibility: visible;
-  }
-
   .bd-box:focus-visible,
-  .bd-arrow:focus-visible,
   .bd-plus-button:focus-visible,
   .bd-modal-content button:focus-visible {
     /* the one focus ring — see Foundations/Focus */
-    outline: none;
+    /* forced-colors mode does not paint box-shadow, so the ring
+       vanishes there; it does paint an outline, in a system colour. This one
+       is transparent everywhere else, and the offset lands it on the ring's
+       outer band. */
+    outline: var(--border-width-2) solid transparent;
+    outline-offset: var(--focus-outline-offset);
     box-shadow: var(--focus-outline-primary);
   }
 
@@ -59,90 +61,16 @@ export default css`
     gap: 1rem;
     padding: 1rem;
   }
-  .bd-arrow {
-    border-radius: 50%;
-    width: var(--spacing-44);
-    height: var(--spacing-44);
+  /* The dots: bd-pagination-dots, the package's one set of slide controls.
+     Two <img role="button"> arrows stood here, painted by eight data-URI SVGs
+     with the blues and the disabled grey baked in as hex -- invisible to every
+     colour check -- and positioned absolutely 65px under the track. Where they
+     sat, the dots sit now: under the track, at its end. */
+  .bd-carousel-controls {
     display: flex;
-    align-items: center;
-    justify-content: center;
-    cursor: pointer;
-    box-shadow: var(--spacing-0) var(--spacing-2) var(--spacing-4) rgba(0, 0, 0, 0.1);
-    position: absolute;
-    bottom: -65px;
-    background: var(--color-surface-brand);
-    color: var(--color-text-inverse);
-      /* no role: .bd-arrow is an <img> -- left-arrow.svg / right-arrow.svg in
-         carousel.js. It renders no text, so this styles nothing but the alt
-         text a browser shows when the SVG fails to load. Fallback typography
-         is not a role decision. */
-    font-size: var(--typography-fontSize-xl);
-      /* no role: .bd-arrow is an <img> -- left-arrow.svg / right-arrow.svg in
-         carousel.js. It renders no text, so this styles nothing but the alt
-         text a browser shows when the SVG fails to load. Fallback typography
-         is not a role decision. */
-    line-height: var(--typography-lineHeight-none);
-    text-align: center;
-  }
-
-.bd-left-arrow {
-  content: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" transform="matrix(-1 0 0 1 40 0)" fill="%23006DFF"/><path d="M23.3431 14.4142L21.9289 13L14.8579 20.071L16.2721 21.4853L23.3431 14.4142Z" fill="white"/><path d="M16.2721 18.6568L14.8579 20.071L21.9289 27.1421L23.3431 25.7279L16.2721 18.6568Z" fill="white"/></svg>');
-}
-
-
-.bd-left-arrow:hover {
-  content: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" transform="matrix(-1 0 0 1 40 0)" fill="%230059D6"/><path d="M23.3431 14.4142L21.9289 13L14.8579 20.071L16.2721 21.4853L23.3431 14.4142Z" fill="white"/><path d="M16.2721 18.6568L14.8579 20.071L21.9289 27.1421L23.3431 25.7279L16.2721 18.6568Z" fill="white"/></svg>');
-}
-
- .bd-left-arrow:active {
-  content: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" transform="matrix(-1 0 0 1 40 0)" fill="%230045AD"/><path d="M23.3431 14.4142L21.9289 13L14.8579 20.071L16.2721 21.4853L23.3431 14.4142Z" fill="white"/><path d="M16.2721 18.6568L14.8579 20.071L21.9289 27.1421L23.3431 25.7279L16.2721 18.6568Z" fill="white"/></svg>');
-}
-
-
-  .bd-left-arrow:disabled {
-  content: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" fill="%23F1F2F3"/><path d="M23.3431 14.4142L21.9289 13L14.8579 20.071L16.2721 21.4853L23.3431 14.4142Z" fill="%23A6ADB4"/><path d="M16.2721 18.6568L14.8579 20.071L21.9289 27.1421L23.3431 25.7279L16.2721 18.6568Z" fill="%23A6ADB4"/></svg>');
-  }
-
-.bd-right-arrow {
-  content: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" fill="%23006DFF"/><path d="M16.6569 14.4142L18.0711 13L25.1421 20.071L23.7279 21.4853L16.6569 14.4142Z" fill="white"/><path d="M23.7279 18.6568L25.1421 20.071L18.0711 27.1421L16.6569 25.7279L23.7279 18.6568Z" fill="white"/></svg>');
-}
-
-
-.bd-right-arrow:hover {
-  content: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" fill="%230059D6"/><path d="M16.6569 14.4142L18.0711 13L25.1421 20.071L23.7279 21.4853L16.6569 14.4142Z" fill="white"/><path d="M23.7279 18.6568L25.1421 20.071L18.0711 27.1421L16.6569 25.7279L23.7279 18.6568Z" fill="white"/></svg>');
-}
-
-
-.bd-right-arrow:active {
-  content: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" fill="%230045AD"/><path d="M16.6569 14.4142L18.0711 13L25.1421 20.071L23.7279 21.4853L16.6569 14.4142Z" fill="white"/><path d="M23.7279 18.6568L25.1421 20.071L18.0711 27.1421L16.6569 25.7279L23.7279 18.6568Z" fill="white"/></svg>');
-}
-
-
-  .bd-right-arrow:disabled {
-  content: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" fill="%23F1F2F3"/><path d="M16.6569 14.4142L18.0711 13L25.1421 20.071L23.7279 21.4853L16.6569 14.4142Z" fill="%23A6ADB4"/><path d="M23.7279 18.6568L25.1421 20.071L18.0711 27.1421L16.6569 25.7279L23.7279 18.6568Z" fill="%23A6ADB4"/></svg>');
-  }
-.bd-right-arrow.bd-disabled {
-  content: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" fill="%23F1F2F3"/><path d="M16.6569 14.4142L18.0711 13L25.1421 20.071L23.7279 21.4853L16.6569 14.4142Z" fill="%23A6ADB4"/><path d="M23.7279 18.6568L25.1421 20.071L18.0711 27.1421L16.6569 25.7279L23.7279 18.6568Z" fill="%23A6ADB4"/></svg>');
-  cursor: not-allowed;
-}
-
- .bd-left-arrow.bd-disabled {
-  content: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" fill="%23F1F2F3"/><path d="M23.3431 14.4142L21.9289 13L14.8579 20.071L16.2721 21.4853L23.3431 14.4142Z" fill="%23A6ADB4"/><path d="M16.2721 18.6568L14.8579 20.071L21.9289 27.1421L23.3431 25.7279L16.2721 18.6568Z" fill="%23A6ADB4"/></svg>');
-  cursor: not-allowed;
-}
-
-  .bd-disabled {
-    background: var(--color-neutral-50);
-    color: var(--color-text-muted-inverse);
-    cursor: not-allowed;
-  }
-
-  .bd-arrow:first-of-type {
-    right: 60px;
-  }
-
-  .bd-arrow:last-of-type {
-    right: var(--spacing-10);
+    justify-content: flex-end;
+    margin-top: var(--spacing-24);
+    padding-inline: var(--spacing-10);
   }
 
   .bd-carousel-track {
@@ -259,14 +187,6 @@ export default css`
   content: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40" fill="none"><circle cx="20" cy="20" r="19" fill="%23006DFF" stroke="%23006DFF" stroke-width="2"/><path d="M19 11H21V29H19V11Z" fill="white"/><path d="M29 19V21L11 21L11 19L29 19Z" fill="white"/></svg>');
 }
 
-  .bd-left-arrow {
-    margin-right: var(--spacing-6);
-  }
-
-  .bd-right-arrow {
-    margin-left: var(--spacing-6);
-  }
-
   @media ${unsafeCSS(below('md'))} {
     .bd-carousel-track {
       flex-wrap: nowrap;
@@ -284,23 +204,6 @@ export default css`
       max-width: 90%;
       padding: 1.5em;
     }
-
-    .bd-arrow {
-      bottom: -75px;
-      /* no role: .bd-arrow is an <img> -- left-arrow.svg / right-arrow.svg in
-         carousel.js. It renders no text, so this styles nothing but the alt
-         text a browser shows when the SVG fails to load. Fallback typography
-         is not a role decision. */
-      font-size: var(--typography-fontSize-base);
-    }
-
-    .bd-arrow:first-of-type {
-      right: 50px;
-    }
-
-    .bd-arrow:last-of-type {
-      right: var(--spacing-6);
-    }
   }
 
   @media (max-width: 480px) {

package/src/components/carousel/carousel.js

@@ -4,6 +4,7 @@ import "../../tokens/tokens.js";
 import carouselCSS from "../carousel/carousel.css.js";
 import "../heading/heading.js";
 import "../modal/modal.js";
+import "../pagination-dots/pagination-dots.js";
 export class CarouselItem extends LitElement {
   static properties = {
     icon     : { type: String },
@@ -61,7 +62,9 @@ class CustomCarousel extends LitElement {
   static properties = {
     title       : { type: String },
     headingLevel: { type: Number, attribute: "heading-level" },
-    selectedItem: { type: Object }
+    selectedItem: { type: Object },
+    _pages      : { state: true },
+    _page       : { state: true }
   };
 
   constructor() {
@@ -69,6 +72,10 @@ class CustomCarousel extends LitElement {
     this.selectedItem = null;
     this.title = "";
     this.headingLevel = 2;
+    // scroll stops, 1-based, read from the track; see _measure
+    this._pages = 1;
+    this._page = 1;
+    this._seeking = 0;
   }
 
   /**
@@ -98,36 +105,22 @@ class CustomCarousel extends LitElement {
   firstUpdated() {
     this.track = this.shadowRoot.querySelector(".bd-carousel-track");
     this.slotElement = this.shadowRoot.querySelector("slot");
-    this.leftArrow = this.shadowRoot.querySelector(".bd-left-arrow");
-    this.rightArrow = this.shadowRoot.querySelector(".bd-right-arrow");
 
-    this.track.addEventListener("scroll", () => this.updateArrowStates());
+    this.track.addEventListener("scroll", () => this._measure(), { passive: true });
+    this.track.addEventListener("scrollend", () => { this._seeking = 0; this._measure(); });
+    // a visitor taking hold of the track ends any scroll a control started
+    for (const type of ["pointerdown", "touchstart", "wheel"]) {
+      this.track.addEventListener(type, () => { this._seeking = 0; }, { passive: true });
+    }
 
     this.slotElement.addEventListener("slotchange", () => {
-      this.waitForImagesToLoad().then(() => {
-        this.updateArrowStates();
-      });
+      this.waitForImagesToLoad().then(() => this._measure());
     });
 
-    setTimeout(() => {
-      this.waitForImagesToLoad().then(() => {
-        this.updateArrowStates();
-      });
-    }, 0);
-
-    const arrows = this.shadowRoot.querySelectorAll(".bd-arrow");
-    arrows.forEach((arrow) => {
-      arrow.addEventListener("mousedown", () =>
-        arrow.classList.add("bd-active")
-      );
-      arrow.addEventListener("mouseup", () =>
-        arrow.classList.remove("bd-active")
-      );
-      arrow.addEventListener("mouseleave", () =>
-        arrow.classList.remove("bd-active")
-      );
-      arrow.addEventListener("keydown", (e) => this._onArrowKeydown(e, arrow));
-    });
+    this._resizeObserver = new ResizeObserver(() => this._measure());
+    this._resizeObserver.observe(this.track);
+
+    this.waitForImagesToLoad().then(() => this._measure());
 
     this.addEventListener("open-modal", (e) => {
       this.openModal(e.detail);
@@ -135,6 +128,11 @@ class CustomCarousel extends LitElement {
     this.enableDragAndTouchScroll(this.track);
   }
 
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._resizeObserver?.disconnect();
+  }
+
   waitForImagesToLoad() {
     const assignedElements = this.slotElement.assignedElements({
       flatten: true
@@ -155,40 +153,47 @@ class CustomCarousel extends LitElement {
     return Promise.all(promises);
   }
 
-  scrollCarousel(direction) {
-    const assignedElements = this.slotElement.assignedElements({
-      flatten: true
-    });
-    if (!assignedElements.length) return;
-    const itemWidth = assignedElements[0].offsetWidth || 300;
-    if (!this.track) return;
-
-    this.track.scrollBy({
-      left    : direction === "left" ? -itemWidth : itemWidth,
-      behavior: "smooth"
-    });
-
-    setTimeout(() => this.updateArrowStates(), 300);
+  /* The distance from one item to the next: an item's width and the gap. A
+     scroll stop is one of these, and the controls count stops, not items --
+     the last stop is wherever the track ends, which is short of a full step
+     when the items do not divide the width evenly. */
+  _step() {
+    const first = this.slotElement?.assignedElements({ flatten: true })[0];
+    if (!first) return 0;
+    const gap = parseFloat(getComputedStyle(this.track).columnGap) || 0;
+    return first.offsetWidth + gap;
   }
 
-  updateArrowStates() {
-    const trackWidth = this.track.offsetWidth;
-    const totalWidth = this.track.scrollWidth;
-    const scrollPosition = this.track.scrollLeft;
-    if (!this.leftArrow || !this.rightArrow) return;
-
-    this.leftArrow.classList.toggle("bd-disabled", scrollPosition <= 0);
-    this.rightArrow.classList.toggle(
-      "bd-disabled",
-      scrollPosition + trackWidth >= totalWidth - 1
-    );
+  /* How many stops the track has and which one it is at, from where it has
+     scrolled to -- by a control, a drag, a wheel or a keyboard. While a
+     control's smooth scroll is on its way, the dot it asked for stays current
+     rather than stepping through every stop it passes. */
+  _measure() {
+    if (!this.track) return;
+    const max = this.track.scrollWidth - this.track.clientWidth;
+    const step = this._step();
+    if (max <= 1 || step <= 0) {
+      this._pages = 1;
+      this._page = 1;
+      return;
+    }
+    this._pages = Math.ceil((max - 1) / step) + 1;
+    const left = this.track.scrollLeft;
+    const page = left >= max - 1 ? this._pages : Math.min(this._pages, Math.round(left / step) + 1);
+    if (this._seeking && page !== this._seeking) return;
+    this._seeking = 0;
+    this._page = page;
   }
 
-  _onArrowKeydown(e, arrow) {
-    if (e.key === "Enter" || e.key === " ") {
-      e.preventDefault();
-      arrow.click();
-    }
+  _goToPage(n) {
+    const max = this.track.scrollWidth - this.track.clientWidth;
+    const reduce = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+    this._seeking = n;
+    this._page = n;
+    this.track.scrollTo({
+      left    : Math.min((n - 1) * this._step(), max),
+      behavior: reduce ? "auto" : "smooth"
+    });
   }
 
   openModal(item) {
@@ -256,27 +261,18 @@ class CustomCarousel extends LitElement {
             </div>`
           : ""}
 
-        <img
-          src="left-arrow.svg"
-          alt="Left Arrow"
-          class="bd-arrow bd-left-arrow"
-          role="button"
-          aria-label="Scroll left"
-          @click="${() => this.scrollCarousel("left")}"
-          tabindex="0"
-        />
         <div class="bd-carousel-track">
           <slot></slot>
         </div>
-        <img
-          src="right-arrow.svg"
-          alt="Right Arrow"
-          class="bd-arrow bd-right-arrow"
-          role="button"
-          aria-label="Scroll right"
-          @click="${() => this.scrollCarousel("right")}"
-          tabindex="0"
-        />
+        <div class="bd-carousel-controls">
+          <bd-pagination-dots
+            count=${this._pages}
+            current=${this._page}
+            label=${this.title || "Slides"}
+            item-label="Go to item"
+            @bd-change=${e => this._goToPage(e.detail.current)}
+          ></bd-pagination-dots>
+        </div>
       </div>
 
       ${this.selectedItem

package/src/components/carousel/carousel.stories.js

@@ -10,7 +10,7 @@ export default {
         component: `
 **CustomCarousel** and **CarouselItem** are Lit components for a scrollable, draggable card carousel with modal support.
 
-- \`<bd-carousel-section>\` — scrollable container with left/right arrows and optional title
+- \`<bd-carousel-section>\` — scrollable container with optional title, and the package's slide dots (\`bd-pagination-dots\`) under the track
 - \`<bd-carousel-item>\` — individual card with icon, slotted content, and a \`+\` button to open a modal
 
 ### Usage
@@ -23,14 +23,15 @@ export default {
 \`\`\`
 
 ### Behavior
-- Left/right arrows scroll by one item width with smooth scroll
-- Arrows disable automatically at scroll boundaries
-- Click and drag (mouse + touch) supported for scrolling
+- One dot per scroll stop: a stop is one item's width plus the gap, and the last is wherever the track ends
+- A dot scrolls there smoothly (instantly under \`prefers-reduced-motion\`)
+- When every item fits, there is nowhere to go and no controls render
+- Click and drag (mouse + touch) supported for scrolling; the dots follow any scroll
 - Clicking \`+\` on an item fires \`open-modal\` custom event, caught by the carousel to show \`<bd-modal>\`
 - Modal closes via \`close-modal\` event
 
 ### Keyboard Support
-- Arrow buttons respond to Enter/Space
+- The dots are real buttons
 - \`+\` button on items responds to Enter/Space
         `
       }
@@ -84,7 +85,7 @@ export const Default = {
       ${sampleItems.map(renderItem)}
     </bd-carousel-section>
   `,
-  parameters: { docs: { description: { story: '6-item carousel with title. Scroll with arrows or drag.' } } }
+  parameters: { docs: { description: { story: '6-item carousel with title. Move with the dots under the track, or drag.' } } }
 };
 
 export const NoTitle = {
@@ -104,7 +105,7 @@ export const FewItems = {
       ${sampleItems.slice(0, 2).map(renderItem)}
     </bd-carousel-section>
   `,
-  parameters: { docs: { description: { story: 'Only 2 items — right arrow should be disabled if all items fit in view.' } } }
+  parameters: { docs: { description: { story: 'Only 2 items. When every item fits there is nowhere to scroll, so no dots render.' } } }
 };
 
 export const SingleItem = {
@@ -114,7 +115,7 @@ export const SingleItem = {
       ${renderItem(sampleItems[0])}
     </bd-carousel-section>
   `,
-  parameters: { docs: { description: { story: 'Edge case with a single item. Both arrows should be disabled.' } } }
+  parameters: { docs: { description: { story: 'Edge case with a single item: nothing to scroll, so no dots render.' } } }
 };
 
 export const NoIcon = {

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

@@ -40,7 +40,12 @@ export default css`
     /* 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;
+    /* forced-colors mode does not paint box-shadow, so the ring
+       vanishes there; it does paint an outline, in a system colour. This one
+       is transparent everywhere else, and the offset lands it on the ring's
+       outer band. */
+    outline: var(--border-width-2) solid transparent;
+    outline-offset: var(--focus-outline-offset);
     box-shadow: var(--focus-outline-primary);
     border-radius: var(--focus-outline-radius);
   }

package/src/components/code/code.css.js

@@ -62,7 +62,12 @@ export const codeCSS = css`
     /* 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;
+    /* forced-colors mode does not paint box-shadow, so the ring
+       vanishes there; it does paint an outline, in a system colour. This one
+       is transparent everywhere else, and the offset lands it on the ring's
+       outer band. */
+    outline: var(--border-width-2) solid transparent;
+    outline-offset: var(--focus-outline-offset);
     box-shadow: var(--focus-outline-primary);
   }
 `;

package/src/components/code/code.js

@@ -1,4 +1,4 @@
-import { LitElement, html } from 'lit';
+import { LitElement, html, nothing } from 'lit';
 // Installs the design tokens into document scope; see src/tokens/tokens.js
 import '../../tokens/tokens.js';
 import { codeCSS } from './code.css.js';
@@ -17,20 +17,61 @@ export class BdCode extends LitElement {
     this.label = '';
   }
 
+  /* Whether the block is wider than its box. Only then is there anything to
+     scroll, and only then does it need to be a tab stop. The box changes
+     size with the page, and the content with the light DOM, so both are
+     watched. */
+  _measure() {
+    const pre = this.shadowRoot?.querySelector('pre');
+    const scrollable = !!pre && pre.scrollWidth > pre.clientWidth;
+    if (scrollable !== this._scrollable) {
+      this._scrollable = scrollable;
+      this.requestUpdate();
+    }
+  }
+
+  updated() {
+    const pre = this.shadowRoot.querySelector('pre');
+    if (pre && pre !== this._observed) {
+      this._resize?.disconnect();
+      this._resize = new ResizeObserver(() => this._measure());
+      this._resize.observe(pre);
+      this._observed = pre;
+    }
+    if (!pre) { this._resize?.disconnect(); this._observed = null; }
+    this._measure();
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this._content = new MutationObserver(() => this._measure());
+    this._content.observe(this, { childList: true, characterData: true, subtree: true });
+  }
+
+  disconnectedCallback() {
+    this._content?.disconnect();
+    this._resize?.disconnect();
+    this._observed = null;
+    super.disconnectedCallback();
+  }
+
   render() {
     // Block mode nests <code> inside <pre>: <pre> carries the preformatted
     // whitespace, <code> carries "this is code". A bare <pre> is only
     // preformatted text, so assistive tech got no signal it was code at all,
     // even though the inline variant gave one.
     //
-    // The <pre> scrolls horizontally, and a scrollable region that cannot be
-    // focused cannot be scrolled from the keyboard (WCAG 2.1.1). tabindex
-    // makes it reachable; role and label give it something to announce, since
-    // a focusable element with no accessible name says nothing.
+    // A <pre> that scrolls horizontally has to be focusable, or it cannot be
+    // scrolled from the keyboard (WCAG 2.1.1), and a focusable element needs
+    // a name. It is a group, not a region: a named region is a landmark, so
+    // every code block on a page joined the landmark list a screen reader
+    // navigates by, beside header, main and footer. And it is a tab stop only
+    // while it overflows; a snippet that fits has nothing to scroll and was a
+    // stop that did nothing.
     return this.block
       ? html`<pre
-          tabindex="0"
-          role="region"
+          tabindex="${this._scrollable ? '0' : nothing}"
+          role="group"
           aria-label="${this.label || 'Code'}"
         ><code><slot></slot></code></pre>`
       : html`<code><slot></slot></code>`;

package/src/components/code/code.stories.js

@@ -33,10 +33,13 @@ Inline renders a single \`<code>\` with a tinted background. Block nests
 \`<code>\` carries "this is code", which is the spec's pairing for a code block.
 
 ### The block is keyboard-scrollable
-A long line scrolls horizontally, and a scrollable region that cannot be
-focused cannot be scrolled from the keyboard. The block therefore takes
-\`tabindex="0"\` with \`role="region"\` and an accessible name from \`label\`,
-defaulting to "Code", and shows a focus ring when reached by Tab.
+A long line scrolls horizontally, and a scrollable box that cannot be focused
+cannot be scrolled from the keyboard. So while the block is wider than its box
+it takes \`tabindex="0"\` and shows a focus ring when reached by Tab; a block
+that fits has nothing to scroll and is not a tab stop. It is a
+\`role="group"\` named by \`label\`, defaulting to "Code" — a group rather
+than a region, because a named region is a landmark, and a page of code
+samples would otherwise fill the landmark list a screen reader navigates by.
 
 ### Notes
 The inline variant sets its colour explicitly rather than inheriting, so it

package/src/components/divider/divider-horizontal.js

@@ -2,7 +2,7 @@ import { LitElement, html } from "lit";
 // Installs the design tokens into document scope; see src/tokens/tokens.js
 import "../../tokens/tokens.js";
 import { dividerHorizontal } from "./divider.css.js";
-import { borderColor } from "../shared/token-scales.js";
+import { borderColor, opacity } from "../shared/token-scales.js";
 
 export class BdDividerHorizontal extends LitElement {
   static styles = [dividerHorizontal];
@@ -27,7 +27,14 @@ export class BdDividerHorizontal extends LitElement {
        ask for `brand-subtle`. The ink vocabulary is still accepted as a
        fallback for the names already in the markup. */
     this.color = "";
-    this.opacity = "0.25";
+    /* No opacity by default. It was 0.25, laid over --color-border-default,
+       and that composite -- rgb(225,227,230), 1.286:1 on the page -- is
+       --color-border-container to within one unit (225,227,229, 1.287:1). So
+       every bare divider was spelling a role that exists by dimming a
+       different one. The stylesheet now draws that role at full strength,
+       which renders the same rule, and opacity is only what a caller asks
+       for. */
+    this.opacity = "";
   }
 
   render() {
@@ -35,13 +42,14 @@ export class BdDividerHorizontal extends LitElement {
     // stylesheet's --color-border-default stands rather than being overridden
     // with an empty value.
     const ink = borderColor(this.color);
+    const fade = opacity(this.opacity);
     return html`
       <hr
         class="hr-line"
         style="
           width: ${this.width};
           ${ink ? `border-top-color: ${ink};` : ''}
-          opacity: ${this.opacity};
+          ${fade ? `opacity: ${fade};` : ''}
         "
       />
     `;

package/src/components/divider/divider-vertical.js

@@ -2,7 +2,7 @@ import { LitElement, html } from "lit";
 // Installs the design tokens into document scope; see src/tokens/tokens.js
 import "../../tokens/tokens.js";
 import { dividerVertical } from "./divider.css.js";
-import { borderColor, spacing } from "../shared/token-scales.js";
+import { borderColor, spacing, opacity, borderWidth } from "../shared/token-scales.js";
 
 export class BdDividerVertical extends LitElement {
   static styles = [dividerVertical];
@@ -18,13 +18,19 @@ export class BdDividerVertical extends LitElement {
   constructor() {
     super();
     this.height = "16";   // a spacing step; was a 15px literal, off every scale
-    this.thickness = "1px";
+    /* A border-width step, resolved to var(--border-width-N); "1px" and the
+       other px spellings are read as their step. It was the literal "1px",
+       written into the style as given -- out of lint:tokens' reach, so any
+       length, or any string at all, could stand in for a hairline. An
+       unknown value falls back to the 1px step. */
+    this.thickness = "1";
     /* No colour by default — see the note in divider-horizontal.js. The
        stylesheet's --color-border-default is the role for a hairline; "subtle"
        was a text role that happened to resolve to the same step. The prop
        resolves through BORDER_ROLES first; see token-scales.js. */
     this.color = "";
-    this.opacity = "1.00";
+    // none by default, so none is written; a value is kept only from 0 to 1
+    this.opacity = "";
 
   }
 
@@ -32,14 +38,15 @@ export class BdDividerVertical extends LitElement {
     // See divider-horizontal.js: no colour means no declaration, so the
     // stylesheet's --color-border-default stands.
     const ink = borderColor(this.color);
+    const fade = opacity(this.opacity);
     return html`
       <div
         class="divider"
         style="
-          width: ${this.thickness};
+          width: ${borderWidth(this.thickness) || borderWidth('1')};
           height: ${spacing(this.height)};
           ${ink ? `background-color: ${ink};` : ''}
-          opacity: ${this.opacity};
+          ${fade ? `opacity: ${fade};` : ''}
         "
       ></div>
     `;