@3xhaust/oh-my-design 0.16.1

package/core/composition/section-inversion.md

@@ -0,0 +1,182 @@
+# Section inversion (dark ↔ light narrative turn)
+
+> Candidate hypothesis only. Revalidate its condition, values, and responsive transition
+> against the current composition contract; do not transfer this page recipe unchanged.
+
+A section inversion switches the page from a light surface to a dark one — or the
+reverse — at a specific point in the scroll narrative. The colour change is not
+decoration; it marks a conceptual pivot, a moment where what was light becomes weighty,
+or where accumulated tension releases. One inversion per page is usually correct. Two
+inversions become a rhythm. Three become a pattern with no meaning.
+
+`expressive.md`: "The inversion makes the change visible and felt, not just read. One
+inversion per page is usually correct; more than one is a rhythm, not a pivot."
+
+## When it earns its place / When it does not
+
+Condition: the scroll narrative has a genuine turn — a moment where the conceptual
+register shifts. Before the inversion, the user is in the exposition; after it, they are
+in the consequence. A product page that moves from benefit to proof, a case study that
+moves from problem to resolution, a campaign page that moves from question to answer.
+The inversion is structural punctuation.
+
+`core/theory/layout.md` — von Restorff isolation effect: a single element that breaks the
+pattern is remembered. A section with a different background is the layout equivalent of
+that differentiated element. Used once, it is the most remembered section on the page.
+
+Condition against: arbitrary visual variety — swapping colours because the page "needed
+something different" halfway down. `expressive.md`: "When the colour switches back
+without a corresponding conceptual return, the technique has been used as decoration and
+should be removed." Also: pages without a genuine narrative arc (tool UIs, dashboards,
+documentation) where sections are parallel containers, not sequential scenes.
+
+## Parameters
+
+```css
+:root {
+  /* Light surface tokens */
+  --surface-light: #ffffff;
+  --on-surface-light: #0f0f0f;
+  --surface-light-subtle: #f5f5f3;
+
+  /* Dark surface tokens — the inverted register */
+  --surface-dark: #0f0f0f;
+  --on-surface-dark: #f5f5f3;
+  --surface-dark-subtle: #1a1a1a;
+
+  /* Transition between sections.
+     Instant cut reads as deliberate and editorial.
+     A 40–80px overlap blend reads as atmospheric.
+     Most showpiece executions use the instant cut. */
+  --inversion-transition: none; /* or: use a gradient bleed on the section edge */
+}
+```
+
+## Implementation
+
+```html
+<!-- The narrative sections before the turn -->
+<section class="narrative-section narrative-section--light">
+  <div class="narrative-section__inner">
+    <h2>The problem was not the product.</h2>
+    <p>Four teams. Four definitions of done. Zero shared vocabulary.</p>
+  </div>
+</section>
+
+<!-- The inversion: this section marks the turn -->
+<section class="narrative-section narrative-section--dark">
+  <div class="narrative-section__inner">
+    <h2>The turn.</h2>
+    <p>One shared language changed what could ship.</p>
+  </div>
+</section>
+
+<!-- After the turn, the dark surface continues or returns to light intentionally -->
+<section class="narrative-section narrative-section--dark">
+  <div class="narrative-section__inner">
+    <h2>What changed.</h2>
+    <p>Velocity doubled. Not from more people — from fewer conversations.</p>
+  </div>
+</section>
+```
+
+```css
+/* ── Base section structure ─────────────────────────────────────────────────── */
+.narrative-section {
+  padding-block: var(--space-section, 8rem);
+  padding-inline: var(--space-page-margin, 5vw);
+}
+
+.narrative-section__inner {
+  max-width: var(--content-measure, 72ch);
+  margin-inline: auto;
+}
+
+/* ── Light surface ──────────────────────────────────────────────────────────── */
+.narrative-section--light {
+  background-color: var(--surface-light);
+  color: var(--on-surface-light);
+}
+
+/* ── Dark surface (the inversion) ──────────────────────────────────────────── */
+.narrative-section--dark {
+  background-color: var(--surface-dark);
+  color: var(--on-surface-dark);
+}
+
+/* ── Token inheritance: nested components must read their tokens from context ── */
+/* Buttons, links, cards inside inverted sections inherit from the surface token.
+   Do not hardcode light or dark values inside components — they will break here. */
+.narrative-section--dark .card {
+  background-color: var(--surface-dark-subtle);
+  border-color: rgba(255, 255, 255, 0.08);
+}
+
+/* ── Optional: gradient bleed at section boundary for atmospheric transitions ── */
+/* Use only when the concept benefits from ambiguity at the turn rather than clarity. */
+.narrative-section--dark.narrative-section--bleed-top {
+  border-top: none;
+  /* A subtle gradient overlay creates the bleed effect without JavaScript */
+  position: relative;
+}
+
+.narrative-section--dark.narrative-section--bleed-top::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  top: 0;
+  height: 80px;
+  background: linear-gradient(to bottom, var(--surface-light), transparent);
+  pointer-events: none;
+}
+
+/* ── Reduced-motion: no effect needed here — section inversion is a static
+   colour change, not an animation. The technique is inherently motion-free. ── */
+```
+
+## Responsive behavior
+
+**375px (mobile):** Section inversion works at all viewports — it is a colour property, not
+a spatial one. The primary concern at narrow widths is that the transition edge is clean.
+Verify that no component's border or shadow bleeds across the section boundary creating a
+visible seam; use `overflow: hidden` on the section if needed.
+
+Padding reduction on mobile: the vertical rhythm of the narrative may be compressed.
+Reduce `--space-section` to 4rem on mobile to maintain narrative pace without excessive
+scrolling between conceptual turns.
+
+```css
+@media (max-width: 600px) {
+  .narrative-section {
+    padding-block: var(--space-section-mobile, 4rem);
+  }
+}
+```
+
+**768px (tablet):** No structural change. Verify the inversion boundary falls at a clean
+scroll position — if a section begins mid-viewport on most tablet scroll positions, the
+turn may never land with impact. `min-height: 60vh` on the inverted section ensures the
+user arrives at the dark surface with the full viewport, not a sliver.
+
+**1280px (desktop):** At wide viewports, the full-width colour change reads as a hard
+architectural break. This is the register the technique is designed for — the inversion
+commands the full screen width, which is why it works as punctuation. No additional
+responsive changes needed; verify that imagery or tokens designed for the light surface
+are replaced with dark-surface equivalents inside inverted sections.
+
+## Do not combine with
+
+**bento-grid.md** inside an inverted section — the bento grid's cell backgrounds create
+a tertiary surface tier (light section → dark section → bento cell background). Three
+surface levels in sequence confuse the inversion signal; the turn is no longer readable
+as a conceptual pivot because it is preceded by background-switching at smaller scale.
+
+**section-inversion applied per-section to every section** — this is the most common
+misuse. If every section has a different background, no single inversion marks a turn.
+The technique requires contrast between the norm and the exception; if all sections are
+exceptions, there is no norm to deviate from.
+
+**gradient-mesh.md on the inverted surface** — a mesh gradient on the dark section
+introduces colour variation that competes with the starkness the inversion depends on.
+The dark surface's power is its flatness against the light sections; texture undermines
+the contrast signal.

package/core/composition/sidebar-margin-annotation.md

@@ -0,0 +1,184 @@
+# Sidebar / margin annotation layout
+
+> Candidate hypothesis only. Revalidate its condition, values, and responsive transition
+> against the current composition contract; do not transfer this page recipe unchanged.
+
+A Tufte-style margin layout places supplementary detail — a footnote, a source citation, a
+clarifying aside, an illustrative data point — in the margin column beside the text that
+references it. The main column reads without interruption; the margin column deepens for
+readers who want it. The vertical alignment between the annotation and its anchor in the
+body text is the structural contract: the annotation appears beside the sentence it
+qualifies, not at the bottom of the section.
+
+## When it earns its place / When it does not
+
+Condition: the content is prose-heavy and carries genuinely supplementary material that
+enriches the main argument without being essential to it. Long-form editorial content,
+research-style pages, case studies that cite sources, documentation that benefits from
+contextual notes without disrupting the reading flow. The technique embodies
+`core/theory/layout.md`'s closure principle: the spatial proximity between body text and
+annotation communicates the relationship without requiring visual connectors.
+
+Edward Tufte argues in *Visual Display of Quantitative Information* (1983) that placing
+supporting material beside the text that refers to it reduces the need for citations that
+interrupt reading — the footnote does not require a journey to the bottom of the page.
+The margin annotation is the print typographer's solution to this problem, applied to screen.
+
+Condition against: narrow viewports (the margin column disappears below 900px and the
+annotations must be inlined or dropped). Marketing pages where every word must hold
+attention — supplementary text in the margin costs reading focus even when it is not
+read; the eye registers its presence. Tool UIs and dashboards where sidebar content
+should be navigation or action, not annotation. And any layout where the body column is
+already narrow — if the reading measure drops below 50ch to accommodate a margin column
+at 768px, the main text has been sacrificed for the annotation, which inverts the hierarchy.
+
+`core/theory/layout.md` on information density: "Whitespace here is not wasted; it is
+the product." The margin annotation layout requires generous right-margin whitespace at
+medium densities; it is incompatible with high-density layouts where every column is
+earning its keep.
+
+## Parameters
+
+```css
+:root {
+  /* Main content column width.
+     Tufte's canonical measure: 55–65% of the text area.
+     Readable body text: 50–75ch is the research-validated range. */
+  --main-col-width: 60%;
+
+  /* Margin annotation column width.
+     Typically 25–30% of the text area; the remainder is gutter. */
+  --margin-col-width: 28%;
+
+  /* Gutter between main and margin columns. */
+  --margin-gutter: clamp(16px, 2vw, 32px);
+
+  /* Annotation font size.
+     Smaller than body to signal supplementary status. 80–85% of body size.
+     At 1rem body: 0.8rem annotation is legible and clearly secondary. */
+  --annotation-font-size: 0.8rem;
+  --annotation-line-height: 1.5;
+  --annotation-color: var(--text-secondary, rgba(0,0,0,0.55));
+}
+```
+
+## Implementation
+
+```html
+<!-- The layout uses a named CSS grid area: main + margin.
+     Each .margin-ref creates a vertical alignment anchor.
+     The annotation must be a sibling of the annotated paragraph, not a child — 
+     this keeps the DOM order correct for reading without CSS. -->
+<article class="margined-prose">
+  <div class="margined-prose__row">
+    <p class="margined-prose__body">
+      The spacing scale is not arbitrary.
+      <span class="margined-prose__anchor" id="note-1" aria-describedby="ann-1">¹</span>
+      Each step in the scale must have a reason that could not be the adjacent step.
+    </p>
+    <aside class="margined-prose__annotation" id="ann-1" aria-label="Note 1">
+      Müller-Brockmann, <em>Grid Systems in Graphic Design</em> (1981): shared
+      spacing units make disparate elements read as one system.
+    </aside>
+  </div>
+
+  <div class="margined-prose__row">
+    <p class="margined-prose__body">
+      The 8pt grid is a mechanical constraint with a perceptual benefit: values on the
+      grid land at whole pixel boundaries on most screen densities.
+    </p>
+    <!-- Row with no annotation: the margin column is empty whitespace here.
+         The empty right column is not a failure — it is the breathing room
+         that makes the annotated rows legible. -->
+  </div>
+</article>
+```
+
+```css
+/* ── Grid layout ──────────────────────────────────────────────────────────── */
+.margined-prose {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4, 1rem);
+  padding-inline: var(--space-page-margin, 5vw);
+  max-width: 100%;
+}
+
+.margined-prose__row {
+  display: grid;
+  grid-template-columns: var(--main-col-width) var(--margin-gutter) var(--margin-col-width);
+  align-items: start; /* top-align: annotation begins beside its anchor sentence */
+}
+
+.margined-prose__body {
+  grid-column: 1 / 2;
+  font-size: var(--text-base, 1rem);
+  line-height: var(--leading-body, 1.65);
+  max-width: 65ch; /* readable measure cap within the column */
+}
+
+.margined-prose__annotation {
+  grid-column: 3 / 4; /* skip the gutter column */
+  font-size: var(--annotation-font-size);
+  line-height: var(--annotation-line-height);
+  color: var(--annotation-color);
+  /* Vertical alignment: the annotation top-aligns with the row.
+     For precise alignment with a specific sentence, margin-top may be added
+     equal to the number of leading lines above the anchor word. */
+  padding-top: 0.15em; /* optically align with cap-height of body text */
+}
+
+/* Annotation number in body: superscript, same color as annotation. */
+.margined-prose__anchor {
+  font-size: 0.7em;
+  vertical-align: super;
+  color: var(--annotation-color);
+  text-decoration: none;
+}
+```
+
+## Responsive behavior
+
+**375px (mobile):** The margin column is not viable at this width — the body column would
+fall below readable measure to accommodate it. Stack the annotation below its paragraph,
+visually differentiated by font size and a left border.
+
+```css
+@media (max-width: 900px) {
+  .margined-prose__row {
+    display: block; /* collapse grid to single column */
+  }
+
+  .margined-prose__annotation {
+    display: block;
+    margin-top: var(--space-2, 0.5rem);
+    padding-left: var(--space-3, 0.75rem);
+    border-left: 2px solid var(--border-subtle, rgba(0,0,0,0.12));
+    /* Annotation is now inline, below the body paragraph, clearly secondary. */
+  }
+}
+```
+
+**768px (tablet):** The 900px breakpoint covers tablet portrait. At landscape tablet
+(1024px), the grid layout works; test that `--main-col-width: 60%` at 1024px produces a
+body column of at least 50ch. If not, widen the main column to 65% and narrow the margin
+column correspondingly.
+
+**1280px (desktop):** The full three-column grid. The empty margin column in un-annotated
+rows is intentional negative space — do not fill it with anything. The whitespace signals
+"more is available if you look" without demanding attention.
+
+## Do not combine with
+
+**asymmetric-diagonal-grid.md** — the diagonal layout breaks the column contract that the
+margin annotation depends on. The annotation cannot be vertically anchored to its body
+text if the body column is itself off-axis.
+
+**editorial-index-labels.md** in the same section — both add secondary visual elements
+in the peripheral field. The index number in the left background and the annotation in the
+right margin create a four-zone reading field (left-decoration, body, gutter, annotation)
+that costs more attention than it returns.
+
+**High-density layouts** where the body column is already maximised — the margin annotation
+technique is structural whitespace. It cannot be added to a dense layout without sacrificing
+reading measure.

package/core/composition/split-screen-hero.md

@@ -0,0 +1,224 @@
+# Split-screen hero
+
+> Candidate hypothesis only. Revalidate its condition, values, and responsive transition
+> against the current composition contract; do not transfer this page recipe unchanged.
+
+A split-screen hero divides the viewport vertically into two panels. One panel holds the
+primary statement — headline, copy, and CTA. The other holds a counterpart — an image,
+a graphic, a live demo, or a contrasting visual element. The division is the design
+decision: the two sides are in genuine tension or complementarity, and the user reads
+both as a complete argument.
+
+## When it earns its place / When it does not
+
+Condition: the content genuinely has two distinct poles that benefit from juxtaposition.
+A product with a before/after proposition, a dual-audience site, a brand with a visual
+and a verbal identity that are each strong enough to carry half the viewport. The
+split must express a relationship — contrast, comparison, dialogue — not simply divide
+available space in half because the designer had two things to place.
+
+`core/theory/layout.md` on scan patterns: the Z-pattern (sparse marketing pages) places
+the diagonal at centre-screen, which is exactly the vertical divider of a split-screen
+layout. The left panel captures the entry, the diagonal crosses to the right panel, and
+the eye completes the Z on whichever side holds the CTA. This makes the split-screen
+structurally aligned with the Z-pattern's natural scan — neither panel is out of the
+eye's path.
+
+Condition against: when there is one primary message. A split hero on a page with a
+single value proposition divides the viewport's attention budget without a reason; one
+side will always be weaker, and the weaker side dilutes the stronger. `core/theory/
+layout.md` visual hierarchy rule 1: "If you have one thing that matters most, it must
+be the largest." A split hero makes two things equal — choose this only when equality
+is accurate. Also: mobile viewports where the split collapses to a stack, making the
+panel order a design decision that the responsive logic must handle deliberately.
+
+## Parameters
+
+```css
+:root {
+  /* Column split ratio.
+     50/50 reads as pure duality — equal weight.
+     60/40 or 55/45 reads as a primary/supporting relationship.
+     Choose based on which side carries the primary message. */
+  --split-left: 55%;
+  --split-right: 45%;
+
+  /* Minimum height.
+     100svh ensures both panels fill the viewport on first load.
+     svh (small viewport height) accounts for mobile browser chrome. */
+  --split-min-height: 100svh;
+
+  /* The divider between panels.
+     Invisible divider: panels differentiated by background only.
+     Visible divider: a 1px line, a gap, or a decorative element. */
+  --split-gap: 0px; /* or var(--space-2) for a gap-based divider */
+
+  /* Padding within each panel. Both panels share the same internal padding
+     for visual consistency across the divider. */
+  --split-panel-padding: clamp(2rem, 5vw, 6rem);
+}
+```
+
+## Implementation
+
+```html
+<!-- The split hero contains exactly two panels.
+     Left panel: text, CTA — the verbal side.
+     Right panel: visual, image, graphic — the visual side.
+     DOM order: left-then-right mirrors the visual left-to-right reading order.
+     On mobile: left panel (text) appears first, right panel (visual) below. -->
+<section class="split-hero">
+  <div class="split-hero__panel split-hero__panel--left">
+    <div class="split-hero__panel-inner">
+      <p class="split-hero__eyebrow">Engineering tools</p>
+      <h1 class="split-hero__heading">
+        Write once.<br>
+        Ship everywhere.
+      </h1>
+      <p class="split-hero__body">
+        The deployment layer that reads your config and disappears.
+      </p>
+      <a href="#" class="split-hero__cta">Start building</a>
+    </div>
+  </div>
+
+  <div class="split-hero__panel split-hero__panel--right">
+    <!-- Visual panel: image, illustration, live code demo, gradient mesh, etc.
+         This panel is allowed to be full-bleed — no inner padding required
+         if the visual extends to all four edges of the panel. -->
+    <div class="split-hero__visual" role="img" aria-label="[describe the visual]">
+      <!-- Visual content goes here -->
+    </div>
+  </div>
+</section>
+```
+
+```css
+.split-hero {
+  display: grid;
+  grid-template-columns: var(--split-left) var(--split-right);
+  gap: var(--split-gap);
+  min-height: var(--split-min-height);
+}
+
+.split-hero__panel {
+  display: flex;
+  align-items: center; /* vertical centering within the viewport */
+  overflow: hidden;
+}
+
+.split-hero__panel--left {
+  background-color: var(--surface-primary, #ffffff);
+  padding: var(--split-panel-padding);
+}
+
+.split-hero__panel--right {
+  background-color: var(--surface-accent, #0f0f0f);
+  /* Right panel may be full-bleed visual — no padding applied here;
+     the visual content manages its own edges. */
+}
+
+.split-hero__panel-inner {
+  max-width: 40ch; /* constrains the text column within the left panel */
+}
+
+.split-hero__eyebrow {
+  font-size: var(--text-xs, 0.75rem);
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--text-secondary);
+  margin-bottom: var(--space-4, 1rem);
+}
+
+.split-hero__heading {
+  font-size: clamp(2rem, 4vw, 3.5rem);
+  font-weight: var(--weight-display, 700);
+  line-height: 1.05;
+  letter-spacing: -0.03em;
+  margin-bottom: var(--space-5, 1.25rem);
+}
+
+.split-hero__body {
+  font-size: var(--text-base, 1rem);
+  line-height: var(--leading-body, 1.6);
+  color: var(--text-secondary);
+  max-width: 38ch;
+  margin-bottom: var(--space-8, 2rem);
+}
+
+.split-hero__cta {
+  display: inline-block;
+  padding: var(--space-3, 0.75rem) var(--space-6, 1.5rem);
+  background-color: var(--color-accent);
+  color: var(--on-accent);
+  font-size: var(--text-sm, 0.875rem);
+  font-weight: var(--weight-medium, 500);
+  border-radius: var(--radius-button, 6px);
+  text-decoration: none;
+  /* 44×44px minimum touch target — verify the padding achieves this */
+  min-height: 44px;
+}
+
+.split-hero__visual {
+  width: 100%;
+  height: 100%;
+  object-fit: cover; /* for image content */
+}
+```
+
+## Responsive behavior
+
+**375px (mobile):** The two-column split collapses to a single column. The visual panel
+stacks below the text panel — the text remains first in the reading order and the
+visual follows. If the visual panel has a fixed height, reduce it to a reasonable
+proportion (40–50vh) rather than the full viewport height it occupied on desktop.
+
+```css
+@media (max-width: 768px) {
+  .split-hero {
+    grid-template-columns: 1fr;
+    min-height: auto;
+  }
+
+  .split-hero__panel--left {
+    padding: var(--split-panel-padding);
+    min-height: auto;
+  }
+
+  .split-hero__panel--right {
+    min-height: 45vw; /* generous proportion on mobile, not half the viewport */
+    max-height: 60vw;
+  }
+
+  .split-hero__heading {
+    /* At narrow width, the heading may grow via clamp without needing adjustment.
+       Verify it does not overflow at 375px before removing this. */
+    font-size: clamp(1.75rem, 8vw, 2.5rem);
+  }
+}
+```
+
+**768px (tablet):** The split works at tablet width. At 768px, `var(--split-left): 55%`
+gives the text panel ~422px — sufficient for the content column at `max-width: 40ch`.
+The visual panel receives ~346px. If the visual requires minimum width to read clearly,
+swap to a 50/50 split at this breakpoint.
+
+**1280px (desktop):** Full split. At 1280px the left panel at 55% is ~704px; the `max-
+width: 40ch` constraint means the text column occupies ~640px (at 16px base). Generous
+whitespace within the left panel; the text does not stretch to fill the panel width.
+
+## Do not combine with
+
+**bento-grid.md** inside either panel — a split hero establishes a two-panel spatial
+contract; a bento grid inside one panel introduces a third spatial system within a zone
+that already has compositional meaning.
+
+**typographic-hero.md** — both recipes make the hero the visual anchor. Using both in
+sequence (typographic hero, then split-screen) redundantly establishes the hero register
+twice; the page does not know which one is the primary statement.
+
+**A right panel with text-heavy content** — when the right panel carries comparable text
+volume to the left panel, the split reads as two columns of equal density, which is
+`core/theory/layout.md`'s multi-column form warning applied to a hero: the eye must
+decide where to start, and the Z-pattern scan that makes the split-screen structurally
+sound collapses.