@refrakt-md/lumina 0.20.2 → 0.21.0

package/contracts/structures.json

@@ -1162,6 +1162,49 @@
 				"{content}"
 			]
 		},
+		"Section": {
+			"block": "section",
+			"root": ".rf-section",
+			"dataRune": "section",
+			"childOrder": [
+				"{content}"
+			],
+			"modifiers": {
+				"align": {
+					"source": "meta",
+					"default": "start",
+					"classPattern": ".rf-section--{value}",
+					"dataAttribute": "data-align"
+				}
+			},
+			"elements": {
+				"preamble": {
+					"tag": "header",
+					"selector": ".rf-section__preamble",
+					"source": "autoLabel"
+				},
+				"eyebrow": {
+					"tag": "eyebrow",
+					"selector": ".rf-section__eyebrow",
+					"source": "autoLabel"
+				},
+				"headline": {
+					"tag": "headline",
+					"selector": ".rf-section__headline",
+					"source": "autoLabel"
+				},
+				"blurb": {
+					"tag": "blurb",
+					"selector": ".rf-section__blurb",
+					"source": "autoLabel"
+				},
+				"image": {
+					"tag": "image",
+					"selector": ".rf-section__image",
+					"source": "autoLabel"
+				}
+			}
+		},
 		"Juxtapose": {
 			"block": "juxtapose",
 			"root": ".rf-juxtapose",
@@ -1266,7 +1309,7 @@
 			"modifiers": {
 				"media-position": {
 					"source": "meta",
-					"default": "top",
+					"default": "bottom",
 					"dataAttribute": "data-media-position"
 				},
 				"align": {
@@ -1286,6 +1329,18 @@
 				"collapse": {
 					"source": "meta",
 					"dataAttribute": "data-collapse"
+				},
+				"content-place": {
+					"source": "meta",
+					"dataAttribute": "data-content-place"
+				},
+				"height": {
+					"source": "meta",
+					"dataAttribute": "data-height"
+				},
+				"aspect": {
+					"source": "meta",
+					"dataAttribute": "data-aspect"
 				}
 			},
 			"elements": {
@@ -1323,6 +1378,100 @@
 			"inlineStyles": {
 				"valign": {
 					"prop": "--split-valign"
+				},
+				"aspect": "aspect-ratio"
+			},
+			"variants": {
+				"media-position": {
+					"cover": {
+						"block": "hero",
+						"root": ".rf-hero",
+						"dataRune": "hero",
+						"childOrder": [
+							"{content}"
+						],
+						"modifiers": {
+							"media-position": {
+								"source": "meta",
+								"default": "bottom",
+								"dataAttribute": "data-media-position"
+							},
+							"align": {
+								"source": "meta",
+								"default": "center",
+								"classPattern": ".rf-hero--{value}",
+								"dataAttribute": "data-align"
+							},
+							"media-ratio": {
+								"source": "meta",
+								"dataAttribute": "data-media-ratio"
+							},
+							"valign": {
+								"source": "meta",
+								"dataAttribute": "data-valign"
+							},
+							"collapse": {
+								"source": "meta",
+								"dataAttribute": "data-collapse"
+							},
+							"content-place": {
+								"source": "meta",
+								"dataAttribute": "data-content-place"
+							},
+							"height": {
+								"source": "meta",
+								"dataAttribute": "data-height"
+							},
+							"aspect": {
+								"source": "meta",
+								"dataAttribute": "data-aspect"
+							}
+						},
+						"staticModifiers": [
+							{
+								"name": "cover",
+								"selector": ".rf-hero--cover"
+							}
+						],
+						"elements": {
+							"preamble": {
+								"tag": "header",
+								"selector": ".rf-hero__preamble",
+								"source": "autoLabel"
+							},
+							"eyebrow": {
+								"tag": "eyebrow",
+								"selector": ".rf-hero__eyebrow",
+								"source": "autoLabel"
+							},
+							"headline": {
+								"tag": "headline",
+								"selector": ".rf-hero__headline",
+								"source": "autoLabel"
+							},
+							"blurb": {
+								"tag": "blurb",
+								"selector": ".rf-hero__blurb",
+								"source": "autoLabel"
+							},
+							"image": {
+								"tag": "image",
+								"selector": ".rf-hero__image",
+								"source": "autoLabel"
+							},
+							"media": {
+								"tag": "media",
+								"selector": ".rf-hero__media",
+								"source": "autoLabel"
+							}
+						},
+						"inlineStyles": {
+							"valign": {
+								"prop": "--split-valign"
+							},
+							"aspect": "aspect-ratio"
+						}
+					}
 				}
 			}
 		},
@@ -1472,7 +1621,7 @@
 			"modifiers": {
 				"media-position": {
 					"source": "meta",
-					"default": "top",
+					"default": "bottom",
 					"dataAttribute": "data-media-position"
 				},
 				"align": {
@@ -1553,7 +1702,7 @@
 						"modifiers": {
 							"media-position": {
 								"source": "meta",
-								"default": "top",
+								"default": "bottom",
 								"dataAttribute": "data-media-position"
 							},
 							"align": {
@@ -1639,7 +1788,7 @@
 						"modifiers": {
 							"media-position": {
 								"source": "meta",
-								"default": "top",
+								"default": "bottom",
 								"dataAttribute": "data-media-position"
 							},
 							"align": {
@@ -1773,7 +1922,7 @@
 			"modifiers": {
 				"media-position": {
 					"source": "meta",
-					"default": "top",
+					"default": "bottom",
 					"dataAttribute": "data-media-position"
 				},
 				"media-ratio": {

package/index.css

@@ -103,6 +103,7 @@
 @import './styles/runes/realm.css';
 @import './styles/runes/recipe.css';
 @import './styles/runes/reveal.css';
+@import './styles/runes/section.css';
 @import './styles/runes/sidenote.css';
 @import './styles/runes/steps.css';
 @import './styles/runes/storyboard.css';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@refrakt-md/lumina",
   "description": "Lumina theme for refrakt.md — design tokens, CSS, identity transform, and layout configs",
-  "version": "0.20.2",
+  "version": "0.21.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -83,9 +83,9 @@
     "build": "tsc"
   },
   "dependencies": {
-    "@refrakt-md/runes": "0.20.2",
-    "@refrakt-md/transform": "0.20.2",
-    "@refrakt-md/types": "0.20.2"
+    "@refrakt-md/runes": "0.21.0",
+    "@refrakt-md/transform": "0.21.0",
+    "@refrakt-md/types": "0.21.0"
   },
   "devDependencies": {
     "postcss": "^8.4.0"

package/styles/dimensions/cover.css

@@ -63,6 +63,24 @@
 	height: 100%;
 	object-fit: cover;
 }
+/* SPEC-101 — non-img/video guests (a sandbox, an embed) fill the well too.
+ * They can't be object-fit-cropped, so they get the well's box outright;
+ * display:block covers undefined custom elements (inline by default). */
+[data-media-position="cover"] [data-section="media"] > :not(img, video) {
+	display: block;
+	width: 100%;
+	height: 100%;
+}
+/* A backdrop sandbox sits flush in the well — the well's own radius/overflow
+ * does the clipping. The iframe height is pinned inline by the element in
+ * `fill` mode; this carries the fixed-height case visually until then. */
+[data-media-position="cover"] [data-section="media"] .rf-sandbox {
+	margin: 0;
+	border-radius: 0;
+}
+[data-media-position="cover"] [data-section="media"] .rf-sandbox iframe {
+	height: 100%;
+}
 /* The overlaid box (full: content; header: preamble) anchors via content-place. */
 [data-media-position="cover"]:not([data-cover-scope="header"]) > [data-name="content"],
 [data-cover-scope="header"] > [data-name="cover-band"] > [data-name="preamble"] {

package/styles/dimensions/density.css

@@ -9,12 +9,14 @@
 
 [data-density="full"] {
 	--rune-padding: var(--rf-spacing-md);
+	--rf-title-size: 1.5rem;
 }
 
 /* ─── Compact: truncated descriptions, tight spacing ──────────────── */
 
 [data-density="compact"] {
 	--rune-padding: var(--rf-spacing-sm);
+	--rf-title-size: 1.25rem;
 }
 
 [data-density="compact"] [data-section="description"] {
@@ -32,6 +34,7 @@
 
 [data-density="minimal"] {
 	--rune-padding: var(--rf-spacing-xs);
+	--rf-title-size: 1rem;
 }
 
 [data-density="minimal"] [data-section="description"] {

package/styles/dimensions/sections.css

@@ -25,24 +25,21 @@
 
 /* ─── Title: primary heading ──────────────────────────────────────── */
 
+/* The size rides --rf-title-size (set per density root in density.css) so a
+ * nested rune's own density re-declares it — a full-density hero inside a
+ * compact preview keeps its full-size title — and a rune's own title CSS
+ * (e.g. .rf-hero__headline) outranks the bare attribute selector. The old
+ * `[data-density="compact"] [data-section="title"]` descendant rule leaked
+ * through nested densities AND beat per-rune title sizes. */
 [data-section="title"] {
 	font-family: var(--rf-font-sans);
-	font-size: 1.5rem;
+	font-size: var(--rf-title-size, 1.5rem);
 	font-weight: 700;
 	line-height: 1.2;
 	color: var(--rf-color-text);
 	margin: 0;
 }
 
-/* Scale title with density */
-[data-density="compact"] [data-section="title"] {
-	font-size: 1.25rem;
-}
-
-[data-density="minimal"] [data-section="title"] {
-	font-size: 1rem;
-}
-
 /* ─── Description: secondary text ─────────────────────────────────── */
 
 [data-section="description"] {

package/styles/runes/feature.css

@@ -132,3 +132,15 @@
 .rf-feature--in-grid {
 	padding: 0;
 }
+
+/* BUG-001 — content-first DOM inverts the shared media-first stacked contract
+ * (layouts/split.css): counter it so the labels are truthful. `bottom` (the
+ * default) is plain block flow — media after the content, the historical
+ * look; an explicit `top` flips the visual order without touching the DOM. */
+.rf-feature[data-media-position="bottom"] {
+	display: block;
+}
+.rf-feature[data-media-position="top"] {
+	display: flex;
+	flex-direction: column-reverse;
+}

package/styles/runes/hero.css

@@ -181,6 +181,23 @@
 	margin-top: 3rem;
 	border-radius: var(--rf-radius-lg);
 }
+/* BUG-001 — hero DOM is content-first (headline before media: the right
+ * reading order for the classic hero), inverting the shared media-first
+ * stacked contract in layouts/split.css. Counter it so the labels are
+ * truthful: `bottom` (the hero default) is plain block flow — media renders
+ * after the content, exactly the historical look — and an explicit `top`
+ * flips the visual order without touching the DOM. */
+.rf-hero[data-media-position="bottom"] {
+	display: block;
+}
+.rf-hero[data-media-position="top"] {
+	display: flex;
+	flex-direction: column-reverse;
+}
+.rf-hero[data-media-position="top"] > .rf-hero__media {
+	margin-top: 0;
+	margin-bottom: 3rem;
+}
 .rf-hero__media img {
 	display: block;
 	width: 100%;
@@ -190,6 +207,90 @@
 	margin: 0;
 }
 
+/* ── Cover mode (SPEC-101) — `media-position="cover"` ───────────────────
+ * The shared cover layer (dimensions/cover.css) does the grid stacking, the
+ * default scrim, and the overlay anchoring; these rules supply the hero-band
+ * specifics. This file imports after cover.css, so equal-specificity rules
+ * here win. */
+
+/* The section's generous padding moves to the overlaid content — on the root
+ * it would inset the media well (the backdrop must be flush with the band). */
+.rf-hero--cover {
+	padding: 0;
+}
+.rf-hero--cover > [data-name="content"] {
+	--rune-padding: 7rem 2rem 6.5rem;
+}
+
+/* Band height authority: a hero is a full-width band, not a portrait tile.
+ * Height comes from a viewport-aware floor — deliberately NOT a default
+ * aspect-ratio: with `aspect-ratio` + `min-height`, the ratio transfers a
+ * winning min-height back into *width* on narrow screens (a 22rem-tall 21/9
+ * band computes ~820px wide on a 375px phone — the band marches off-screen).
+ * `--cover-aspect: auto` releases the shared 3/4 tile default; an explicit
+ * `aspect` knob still lands as an inline style and owns the shape. */
+.rf-hero--cover {
+	--cover-aspect: auto;
+	min-height: clamp(22rem, 55vh, 40rem);
+}
+/* An explicit aspect owns the shape — drop the floor so the same
+ * ratio-vs-min-height transfer can't reintroduce the overflow. */
+.rf-hero--cover[data-aspect] {
+	min-height: 0;
+}
+
+/* The shared cover layer applies `container-type: size` (size containment) for
+ * its orientation query — under it the band cannot grow with its content, so
+ * tall content clips at min-height. The hero band doesn't use the orientation
+ * query (the centred-band default below covers `auto` placement), so release
+ * the containment and let the band stretch to fit. */
+.rf-hero--cover[data-media-position="cover"][data-cover-scope="full"] {
+	container-type: normal;
+}
+
+/* Named height scale (`height="sm…xl"`): an explicit band height. */
+.rf-hero--cover[data-height="sm"] { min-height: 20rem; }
+.rf-hero--cover[data-height="md"] { min-height: 28rem; }
+.rf-hero--cover[data-height="lg"] { min-height: 36rem; }
+.rf-hero--cover[data-height="xl"] { min-height: 44rem; }
+
+/* Mobile: the desktop overlay padding (7rem bands) would eat most of the well
+ * on a phone — tighten it so the content fits the band. */
+@media (max-width: 640px) {
+	.rf-hero--cover > [data-name="content"] {
+		--rune-padding: 3.5rem 1.25rem 3rem;
+	}
+}
+
+/* A full-bleed band sits flush — no media radius on the well. */
+.rf-hero--cover > [data-section="media"] {
+	border-radius: 0;
+}
+
+/* Legibility over the scrim: the primary action hard-codes white text above,
+ * which inverts to white-on-near-white once the cover scheme flips
+ * --rf-color-primary on the dark overlay. Use the scheme's tokens instead. */
+.rf-hero--cover li:first-child a {
+	color: var(--rf-color-on-accent, var(--rf-color-bg));
+}
+
+/* Centre-band default: a hero overlay reads as a centred band, not the
+ * cover-card caption strip — seat it mid-well unless the author anchors it
+ * with an explicit `content-place`. */
+.rf-hero--cover[data-media-position="cover"]:is([data-content-place="auto"], :not([data-content-place])) > [data-name="content"] {
+	align-self: center;
+	justify-self: stretch;
+}
+
+/* The default cover scrim is edge-weighted (a caption-strip treatment); under
+ * the centred band it would leave the headline on undarkened media. With no
+ * explicit `content-place`, darken the well evenly (slightly bottom-weighted).
+ * An explicit `content-place` re-enters the shared content-edge scrim contract,
+ * and `scrim="none"` still opts out. */
+.rf-hero--cover:is([data-content-place="auto"], :not([data-content-place])):not([data-scrim="none"]) > [data-section="media"]::after {
+	background-image: var(--cover-scrim-image, linear-gradient(rgb(0 0 0 / 0.45), rgb(0 0 0 / 0.35) 50%, rgb(0 0 0 / 0.55)));
+}
+
 /* Mobile: stack actions full-width so the code block and button line up */
 @media (max-width: 640px) {
 	.rf-hero__actions {

package/styles/runes/sandbox.css

@@ -37,3 +37,53 @@
 	background: var(--rf-color-warning-bg, #fef3c7);
 	border-bottom: 1px solid var(--rf-color-warning, #b45309);
 }
+
+/* Deferred activation (WORK-381): poster shown until a non-eager sandbox
+   mounts. Rendered by the RfSandbox custom element from `data-poster`. */
+.rf-sandbox__poster {
+	position: relative;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	min-height: 150px;
+	background: var(--rf-color-surface-2, var(--rf-color-surface, #f4f4f5));
+}
+
+.rf-sandbox__poster-image {
+	position: absolute;
+	inset: 0;
+	width: 100%;
+	height: 100%;
+	object-fit: cover;
+}
+
+.rf-sandbox__activate {
+	position: relative;
+	z-index: 1;
+	display: inline-flex;
+	align-items: center;
+	gap: 0.5ch;
+	padding: 0.5rem 1rem;
+	font: inherit;
+	font-weight: 600;
+	color: var(--rf-color-on-accent, #fff);
+	background: var(--rf-color-accent, #2563eb);
+	border: none;
+	border-radius: var(--rf-radius-md);
+	cursor: pointer;
+	box-shadow: 0 2px 10px rgba(0, 0, 0, 0.25);
+}
+
+.rf-sandbox__activate::before {
+	content: "▶";
+	font-size: 0.85em;
+}
+
+.rf-sandbox__activate:hover {
+	background: var(--rf-color-accent-hover, var(--rf-color-accent, #1d4ed8));
+}
+
+.rf-sandbox__activate:focus-visible {
+	outline: 2px solid var(--rf-color-accent, #2563eb);
+	outline-offset: 2px;
+}

package/styles/runes/section.css

@@ -0,0 +1,70 @@
+/* Section — a generic page section: an eyebrow/headline/blurb header above
+   arbitrary body content. Header styling mirrors the shared page-section look
+   (reveal/feature); the body is content-agnostic and full width. */
+.rf-section {
+	display: flex;
+	flex-direction: column;
+	gap: 1.5rem;
+}
+
+/* Header */
+.rf-section__preamble {
+	display: flex;
+	flex-direction: column;
+	gap: 0.5rem;
+	max-width: var(--rf-measure, 65ch);
+	margin: 0;
+}
+.rf-section__eyebrow {
+	font-size: 0.8125rem;
+	font-weight: 600;
+	letter-spacing: 0.05em;
+	text-transform: uppercase;
+	color: var(--rf-color-primary);
+	margin: 0;
+}
+.rf-section__eyebrow:has(a) {
+	display: inline-block;
+	position: relative;
+	padding: 0.25rem 0.875rem;
+	border: 1px solid var(--rf-color-border);
+	border-radius: var(--rf-radius-full);
+	color: var(--rf-color-text);
+	font-weight: 400;
+	text-transform: none;
+	letter-spacing: 0;
+	transition: border-color 150ms ease;
+}
+.rf-section__eyebrow:has(a):hover { border-color: var(--rf-color-muted); }
+.rf-section__eyebrow:has(a) a { color: var(--rf-color-primary); font-weight: 600; text-decoration: none; }
+.rf-section__eyebrow:has(a) a::before { content: ''; position: absolute; inset: 0; border-radius: inherit; }
+.rf-section__headline {
+	margin: 0;
+}
+.rf-section__blurb {
+	color: var(--rf-color-muted);
+	margin: 0;
+}
+.rf-section__image {
+	margin: 0;
+	border-radius: var(--rf-radius-md);
+	max-width: 100%;
+	height: auto;
+}
+
+/* Body — content-agnostic; fills the section width regardless of header align. */
+.rf-section__body {
+	width: 100%;
+}
+
+/* Header alignment (the body stays full width). */
+.rf-section[data-align="center"] .rf-section__preamble {
+	align-items: center;
+	text-align: center;
+	margin-inline: auto;
+}
+.rf-section[data-align="end"] .rf-section__preamble {
+	align-items: flex-end;
+	text-align: end;
+	margin-inline-start: auto;
+}

package/styles/runes/steps.css

@@ -101,3 +101,15 @@
 	border-radius: var(--rf-radius-md);
 	overflow: hidden;
 }
+
+/* BUG-001 — content-first DOM inverts the shared media-first stacked contract
+ * (layouts/split.css): counter it so the labels are truthful. `bottom` (the
+ * default) is plain block flow — media after the content, the historical
+ * look; an explicit `top` flips the visual order without touching the DOM. */
+.rf-step[data-media-position="bottom"] {
+	display: block;
+}
+.rf-step[data-media-position="top"] {
+	display: flex;
+	flex-direction: column-reverse;
+}