@dillingerstaffing/strand-ui 0.9.0 → 0.10.0

package/HTML_REFERENCE.md

@@ -8,7 +8,9 @@
 
 > **Principle 1 (Cognitive Economy):** Every element must earn its place. Test: remove an element. If the task still works, it was decoration. If you're not adding back 10% of what you delete, you're not deleting enough. See [DL L61-69](./DESIGN_LANGUAGE.md#L61).
 
-> **Principle 2 (Biosynthetic Restraint):** Max 12 distinct visual elements per screen. See [DL L71-79](./DESIGN_LANGUAGE.md#L71).
+> **Principle 2 (Biosynthetic Restraint):** Max 12 distinct visual elements per screen. Every composition must have exactly one visually dominant primary element. If all elements have equal visual weight, the composition has no focal point. An instrument without a focal point is a parts bin, not an instrument. See [DL L71-84](./DESIGN_LANGUAGE.md#L71).
+
+> **Principle 9 (Typography Carries the Room):** The largest text and smallest text on the same screen must have at least a 3:1 size ratio. Uniform typography is a spreadsheet. Hierarchical typography is an instrument panel. See [DL L165-178](./DESIGN_LANGUAGE.md#L165).
 
 ## Required CSS
 
@@ -265,6 +267,8 @@ All container components (Grid, Stack, Card, Container) enforce boundary integri
 
 > **Elevation:** Cards at rest use Level 1 shadow. On hover, Level 2. See [DESIGN_LANGUAGE.md Principle 5: Earned Elevation (L114-L125)](./DESIGN_LANGUAGE.md#L114) and [7.2: Container Elevation Contexts (L698-L708)](./DESIGN_LANGUAGE.md#L698).
 
+> **Cards are instrument panels, not generic containers.** Before placing multiple cards in a layout, apply [Principle 2 hierarchy test (L71-84)](./DESIGN_LANGUAGE.md#L71): which card is the primary instrument? It should be visually dominant. Apply [Principle 10 (L171-196)](./DESIGN_LANGUAGE.md#L171): describe the layout in laboratory vocabulary. If it sounds generic, redesign.
+
 ---
 
 ### Badge
@@ -407,6 +411,8 @@ All container components (Grid, Stack, Card, Container) enforce boundary integri
 
 > **The DataReadout pattern** is uniquely Strand: monospace overline + large light-weight value + tabular numerals. See [DESIGN_LANGUAGE.md 11.2: Data Display (L918-L955)](./DESIGN_LANGUAGE.md#L918).
 
+> **DataReadout has three sizes for hierarchy, not preference.** Use ONE default or lg readout as the primary focal point, with sm readouts as supporting secondaries. If all readouts on a screen are the same size, apply [Principle 2 hierarchy test (L71-84)](./DESIGN_LANGUAGE.md#L71) and [Principle 9 contrast ratio test (L165-178)](./DESIGN_LANGUAGE.md#L165).
+
 ---
 
 ### CodeBlock
@@ -429,6 +435,10 @@ All container components (Grid, Stack, Card, Container) enforce boundary integri
 
 > **Spacing rules:** 4px base unit, padding tiers, and the gap > padding hierarchy: [DESIGN_LANGUAGE.md Part V: Spacing (L410-L496)](./DESIGN_LANGUAGE.md#L410). Responsive breakpoints and container system: [Part X: Layout (L829-L877)](./DESIGN_LANGUAGE.md#L829).
 
+> **Before composing a layout, apply [Principle 2 (L71-84)](./DESIGN_LANGUAGE.md#L71) and [Principle 10 (L171-196)](./DESIGN_LANGUAGE.md#L171).** Identify the primary element. Describe the layout in laboratory vocabulary. If the description sounds generic ("a grid of data cards"), the composition doesn't embody the DL. An analytical readout panel has one dominant readout and supporting secondaries -- not four equal panels.
+
+> **Before sizing text, apply [Principle 9 (L165-178)](./DESIGN_LANGUAGE.md#L165).** Largest to smallest text on the same screen must be at least 3:1. If all text is the same size, the typography is uniform. Uniform typography is a spreadsheet, not an instrument panel.
+
 ### Stack
 
 ```html
@@ -876,3 +886,100 @@ Intro paragraph. Max 50 characters per line. Used after headlines.
 Caption/description text. text-sm, gray-500, relaxed leading. The `--xs` modifier reduces to text-xs for metadata and fine print.
 
 > **DL foundation:** [DESIGN_LANGUAGE.md Part III.8 Color Roles](./DESIGN_LANGUAGE.md#L290) defines gray-500 as the secondary text role. [Part IV.7 Named Text Patterns](./DESIGN_LANGUAGE.md#L408) specifies the Secondary pattern.
+
+---
+
+## Composition Molecules
+
+Named CSS classes for common compositions. Each implements one or more productions from the [DL Composition Grammar (Part XI-B)](./DESIGN_LANGUAGE.md#L1085).
+
+> **Composition rules:** [DL 11.10 Productions](./DESIGN_LANGUAGE.md#L1144) | [DL 11.11 Containment](./DESIGN_LANGUAGE.md#L1199) | [DL 11.12 Derivation](./DESIGN_LANGUAGE.md#L1215) | [DL 11.13 Tests](./DESIGN_LANGUAGE.md#L1246)
+
+### Card Section
+
+Production: `section-boundary`.
+
+```html
+<div class="strand-card strand-card--elevated strand-card--pad-md">
+  <div class="strand-card-section">
+    <span class="strand-overline">Section Label</span>
+  </div>
+  <!-- section content -->
+</div>
+```
+
+Multiple sections stack. Last section omits trailing border via `:last-child`.
+
+### Key-Value Row
+
+Productions: `inline-pair` + `ranked-sequence`.
+
+```html
+<div class="strand-kv">
+  <span class="strand-kv__label">Blend</span>
+  <span class="strand-kv__value">Ethiopian Yirgacheffe</span>
+</div>
+<div class="strand-kv">
+  <span class="strand-kv__label">Status</span>
+  <span class="strand-kv__value strand-kv__value--status">Active</span>
+</div>
+```
+
+**Modifier:** `strand-kv__value--status` applies semantic color.
+
+### Diagnostic Log Entry
+
+Productions: `inline-sequence` + `ranked-sequence`.
+
+```html
+<div class="strand-log">
+  <span class="strand-log__time">9:15</span>
+  <span class="strand-log__status strand-log__status--complete">Brewed</span>
+  <span class="strand-text-secondary">Pour over. 18g.</span>
+</div>
+<div class="strand-log">
+  <span class="strand-log__time">6:30</span>
+  <span class="strand-log__status strand-log__status--process">Brewing</span>
+  <span class="strand-text-secondary">Espresso. 18g.</span>
+</div>
+```
+
+**Status variants:** `--complete` (teal) | `--process` (blue) | `--warning` (amber) | `--error` (red)
+
+### Metric Row
+
+Production: `centered-group`.
+
+```html
+<div class="strand-metric-row">
+  <div class="strand-data-readout strand-data-readout--sm">
+    <span class="strand-data-readout__label">Daily</span>
+    <span class="strand-data-readout__value">36g</span>
+  </div>
+  <div class="strand-data-readout strand-data-readout--sm">
+    <span class="strand-data-readout__label">Days Left</span>
+    <span class="strand-data-readout__value">7.9</span>
+  </div>
+</div>
+```
+
+### Bar Chart
+
+Production: `column-array`.
+
+```html
+<div class="strand-bar-chart">
+  <div class="strand-bar-chart__col">
+    <span class="strand-bar-chart__amount">284</span>
+    <div class="strand-bar-chart__bar" style="height: 100%"></div>
+    <span class="strand-bar-chart__label">Thu</span>
+  </div>
+  <div class="strand-bar-chart__col">
+    <span class="strand-bar-chart__amount">248</span>
+    <div class="strand-bar-chart__bar" style="height: 87%"></div>
+    <span class="strand-bar-chart__label">Fri</span>
+  </div>
+</div>
+```
+
+Heights are inline styles (data-driven). Place inside `.strand-instrument-viewport` for dual-surface treatment.

package/dist/css/strand-ui.css

@@ -2646,6 +2646,16 @@
   letter-spacing: var(--strand-tracking-tighter);
 }
 
+/* ── Title (human voice display, DL Part IV.7) ── */
+.strand-title {
+  font-family: var(--strand-font-sans);
+  font-weight: var(--strand-weight-light);
+  letter-spacing: var(--strand-tracking-tighter);
+  color: var(--strand-blue-midnight);
+  font-size: clamp(1.5rem, 3vw + 0.5rem, 2.5rem);
+  line-height: var(--strand-leading-snug);
+}
+
 /* ── Lead (intro paragraph, DL Part IV.6) ── */
 .strand-lead {
   font-size: var(--strand-text-lg);
@@ -2665,4 +2675,151 @@
   font-size: var(--strand-text-xs);
 }
 
+/* ══════════════════════════════════════════════════
+   COMPOSITION MOLECULES (DL Part XI-B Grammar)
+   Named derivations of DL composition primitives.
+   Each molecule is a convenience class for a common
+   derivation chain. See DL 11.10 Productions for the
+   grammar rules; DL 11.12 Derivation for verification.
+   ══════════════════════════════════════════════════ */
+
+/* ── Card Section ──
+   Derivation: section-boundary production (DL 11.10).
+   OVERLINE + border-bottom + margin-bottom + padding-bottom */
+.strand-card-section {
+  margin-bottom: var(--strand-space-3);
+  padding-bottom: var(--strand-space-2);
+  border-bottom: 1px solid var(--strand-gray-200);
+}
+
+/* ── Key-Value Row ──
+   Derivation: inline-pair + ranked-sequence (DL 11.10).
+   identifier(OVERLINE) + quantifier(MONO_VALUE) + RANK_BORDER */
+.strand-kv {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding-block: var(--strand-space-2);
+}
+
+.strand-kv + .strand-kv {
+  border-top: 1px solid var(--strand-border-subtle);
+}
+
+.strand-kv__label {
+  font-family: var(--strand-font-mono);
+  font-size: var(--strand-text-xs);
+  font-weight: var(--strand-weight-medium);
+  letter-spacing: var(--strand-tracking-wider);
+  text-transform: uppercase;
+  color: var(--strand-gray-500);
+}
+
+.strand-kv__value {
+  font-family: var(--strand-font-mono);
+  font-size: var(--strand-text-xs);
+  color: var(--strand-gray-600);
+  font-variant-numeric: tabular-nums;
+}
+
+.strand-kv__value--status {
+  color: var(--strand-teal-vital);
+}
+
+/* ── Diagnostic Log Entry ──
+   Derivation: inline-sequence + ranked-sequence (DL 11.10).
+   time(OVERLINE) + status(OVERLINE+COLOR_SEMANTIC) + text(SECONDARY) + RANK_BORDER */
+.strand-log {
+  display: flex;
+  gap: var(--strand-space-3);
+  padding-block: var(--strand-space-2);
+}
+
+.strand-log + .strand-log {
+  border-top: 1px solid var(--strand-border-subtle);
+}
+
+.strand-log__time {
+  font-family: var(--strand-font-mono);
+  font-size: var(--strand-text-xs);
+  font-weight: var(--strand-weight-medium);
+  letter-spacing: var(--strand-tracking-wider);
+  text-transform: uppercase;
+  color: var(--strand-gray-400);
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+.strand-log__status {
+  font-family: var(--strand-font-mono);
+  font-size: var(--strand-text-xs);
+  font-weight: var(--strand-weight-semibold);
+  letter-spacing: var(--strand-tracking-wider);
+  text-transform: uppercase;
+  white-space: nowrap;
+}
+
+.strand-log__status--complete { color: var(--strand-teal-vital); }
+.strand-log__status--process { color: var(--strand-blue-primary); }
+.strand-log__status--warning { color: var(--strand-amber-caution); }
+.strand-log__status--error { color: var(--strand-red-alert); }
+
+/* ── Metric Row ──
+   Derivation: centered-group (DL 11.10).
+   self-contained(atom)* with center distribution + responsive gap */
+.strand-metric-row {
+  display: flex;
+  justify-content: center;
+  gap: clamp(2rem, 5vw, 4rem);
+  text-align: center;
+}
+
+/* ── Bar Chart ──
+   Derivation: column-array (DL 11.10).
+   column(amount? + bar + label)* with equal flex + flex-end alignment.
+   Blue Discipline: one color (--strand-blue-indicator). Part XIII viz rules. */
+.strand-bar-chart {
+  display: flex;
+  gap: var(--strand-space-2);
+  align-items: flex-end;
+  height: var(--strand-space-24);
+  padding: var(--strand-space-5);
+}
+
+.strand-bar-chart__col {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--strand-space-1);
+  height: 100%;
+  justify-content: flex-end;
+}
+
+.strand-bar-chart__bar {
+  width: 100%;
+  background: var(--strand-blue-indicator);
+  border-radius: var(--strand-radius-sm) var(--strand-radius-sm) 0 0;
+  min-height: var(--strand-space-1);
+}
+
+.strand-bar-chart__amount {
+  font-family: var(--strand-font-mono);
+  font-size: var(--strand-text-xs);
+  font-weight: var(--strand-weight-medium);
+  letter-spacing: var(--strand-tracking-wider);
+  text-transform: uppercase;
+  color: var(--strand-gray-300);
+  font-variant-numeric: tabular-nums;
+}
+
+.strand-bar-chart__label {
+  font-family: var(--strand-font-mono);
+  font-size: var(--strand-text-xs);
+  font-weight: var(--strand-weight-medium);
+  letter-spacing: var(--strand-tracking-wider);
+  text-transform: uppercase;
+  color: var(--strand-gray-400);
+}
+
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dillingerstaffing/strand-ui",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Strand UI - Preact/React component library built on the Strand Design Language",
   "author": "Dillinger Staffing <engineering@dillingerstaffing.com> (https://dillingerstaffing.com)",
   "license": "MIT",
@@ -60,7 +60,7 @@
     }
   },
   "dependencies": {
-    "@dillingerstaffing/strand": "^0.9.0"
+    "@dillingerstaffing/strand": "^0.10.0"
   },
   "devDependencies": {
     "@testing-library/preact": "^3.2.0",

package/src/static.css

@@ -77,6 +77,16 @@
   letter-spacing: var(--strand-tracking-tighter);
 }
 
+/* ── Title (human voice display, DL Part IV.7) ── */
+.strand-title {
+  font-family: var(--strand-font-sans);
+  font-weight: var(--strand-weight-light);
+  letter-spacing: var(--strand-tracking-tighter);
+  color: var(--strand-blue-midnight);
+  font-size: clamp(1.5rem, 3vw + 0.5rem, 2.5rem);
+  line-height: var(--strand-leading-snug);
+}
+
 /* ── Lead (intro paragraph, DL Part IV.6) ── */
 .strand-lead {
   font-size: var(--strand-text-lg);
@@ -95,3 +105,150 @@
 .strand-text-secondary--xs {
   font-size: var(--strand-text-xs);
 }
+
+/* ══════════════════════════════════════════════════
+   COMPOSITION MOLECULES (DL Part XI-B Grammar)
+   Named derivations of DL composition primitives.
+   Each molecule is a convenience class for a common
+   derivation chain. See DL 11.10 Productions for the
+   grammar rules; DL 11.12 Derivation for verification.
+   ══════════════════════════════════════════════════ */
+
+/* ── Card Section ──
+   Derivation: section-boundary production (DL 11.10).
+   OVERLINE + border-bottom + margin-bottom + padding-bottom */
+.strand-card-section {
+  margin-bottom: var(--strand-space-3);
+  padding-bottom: var(--strand-space-2);
+  border-bottom: 1px solid var(--strand-gray-200);
+}
+
+/* ── Key-Value Row ──
+   Derivation: inline-pair + ranked-sequence (DL 11.10).
+   identifier(OVERLINE) + quantifier(MONO_VALUE) + RANK_BORDER */
+.strand-kv {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding-block: var(--strand-space-2);
+}
+
+.strand-kv + .strand-kv {
+  border-top: 1px solid var(--strand-border-subtle);
+}
+
+.strand-kv__label {
+  font-family: var(--strand-font-mono);
+  font-size: var(--strand-text-xs);
+  font-weight: var(--strand-weight-medium);
+  letter-spacing: var(--strand-tracking-wider);
+  text-transform: uppercase;
+  color: var(--strand-gray-500);
+}
+
+.strand-kv__value {
+  font-family: var(--strand-font-mono);
+  font-size: var(--strand-text-xs);
+  color: var(--strand-gray-600);
+  font-variant-numeric: tabular-nums;
+}
+
+.strand-kv__value--status {
+  color: var(--strand-teal-vital);
+}
+
+/* ── Diagnostic Log Entry ──
+   Derivation: inline-sequence + ranked-sequence (DL 11.10).
+   time(OVERLINE) + status(OVERLINE+COLOR_SEMANTIC) + text(SECONDARY) + RANK_BORDER */
+.strand-log {
+  display: flex;
+  gap: var(--strand-space-3);
+  padding-block: var(--strand-space-2);
+}
+
+.strand-log + .strand-log {
+  border-top: 1px solid var(--strand-border-subtle);
+}
+
+.strand-log__time {
+  font-family: var(--strand-font-mono);
+  font-size: var(--strand-text-xs);
+  font-weight: var(--strand-weight-medium);
+  letter-spacing: var(--strand-tracking-wider);
+  text-transform: uppercase;
+  color: var(--strand-gray-400);
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+.strand-log__status {
+  font-family: var(--strand-font-mono);
+  font-size: var(--strand-text-xs);
+  font-weight: var(--strand-weight-semibold);
+  letter-spacing: var(--strand-tracking-wider);
+  text-transform: uppercase;
+  white-space: nowrap;
+}
+
+.strand-log__status--complete { color: var(--strand-teal-vital); }
+.strand-log__status--process { color: var(--strand-blue-primary); }
+.strand-log__status--warning { color: var(--strand-amber-caution); }
+.strand-log__status--error { color: var(--strand-red-alert); }
+
+/* ── Metric Row ──
+   Derivation: centered-group (DL 11.10).
+   self-contained(atom)* with center distribution + responsive gap */
+.strand-metric-row {
+  display: flex;
+  justify-content: center;
+  gap: clamp(2rem, 5vw, 4rem);
+  text-align: center;
+}
+
+/* ── Bar Chart ──
+   Derivation: column-array (DL 11.10).
+   column(amount? + bar + label)* with equal flex + flex-end alignment.
+   Blue Discipline: one color (--strand-blue-indicator). Part XIII viz rules. */
+.strand-bar-chart {
+  display: flex;
+  gap: var(--strand-space-2);
+  align-items: flex-end;
+  height: var(--strand-space-24);
+  padding: var(--strand-space-5);
+}
+
+.strand-bar-chart__col {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--strand-space-1);
+  height: 100%;
+  justify-content: flex-end;
+}
+
+.strand-bar-chart__bar {
+  width: 100%;
+  background: var(--strand-blue-indicator);
+  border-radius: var(--strand-radius-sm) var(--strand-radius-sm) 0 0;
+  min-height: var(--strand-space-1);
+}
+
+.strand-bar-chart__amount {
+  font-family: var(--strand-font-mono);
+  font-size: var(--strand-text-xs);
+  font-weight: var(--strand-weight-medium);
+  letter-spacing: var(--strand-tracking-wider);
+  text-transform: uppercase;
+  color: var(--strand-gray-300);
+  font-variant-numeric: tabular-nums;
+}
+
+.strand-bar-chart__label {
+  font-family: var(--strand-font-mono);
+  font-size: var(--strand-text-xs);
+  font-weight: var(--strand-weight-medium);
+  letter-spacing: var(--strand-tracking-wider);
+  text-transform: uppercase;
+  color: var(--strand-gray-400);
+}