@stnd/styles 0.5.1 → 0.5.3

package/_standard-03-typography.scss

@@ -6,6 +6,27 @@
  * @description Fine-art typography system using variable fonts, OpenType features,
  * and mathematical scaling. Implements classical typography rules with modern web capabilities.
  * Supports multiple font families, optical sizing, and locale-specific rules.
+ *
+ * @property --font-sans Sans-serif font stack (`"Inter", "Instrument Sans Variable", system-ui, -apple-system, sans-serif`).
+ * @property --font-serif Serif font stack (`"Source Serif 4", "Newsreader", "Instrument Serif", serif`).
+ * @property --font-monospace Monospace font stack (`"IBM Plex Mono", ui-monospace, monospace`).
+ * @property --font-text Semantic body font family (defaults to `--font-sans`).
+ * @property --font-header Semantic heading font family (defaults to `"Inter"`).
+ * @property --font-interface Semantic UI font family (defaults to `--font-sans`).
+ * @property --font-inter-feature OpenType stylistic feature set for Inter font.
+ * @property --font-instrument-feature OpenType stylistic feature set for Instrument Sans.
+ * @property --font-weight Normal text font weight (`400`).
+ * @property --font-weight-bold Bold text font weight (`600`).
+ * @property --font-header-weight Heading font weight anchor (`700`).
+ * @property --font-weight-h1 Level 1 heading weight.
+ * @property --font-weight-h2 Level 2 heading weight.
+ * @property --font-weight-h3 Level 3 heading weight.
+ * @property --font-weight-h4 Level 4 heading weight.
+ * @property --font-weight-h5 Level 5 heading weight.
+ * @property --font-weight-h6 Level 6 heading weight.
+ * @property --font-letter-spacing Body letter spacing default (`normal`).
+ * @property --font-header-letter-spacing Heading letter spacing default (`normal`).
+ * @property --list-indent Default list item indentation (`var(--space)`).
  */
 
 #{$stnd-theme-scope} {
@@ -38,7 +59,11 @@
   --font-weight-bold: 600;
   --font-letter-spacing: normal;
   --font-header-letter-spacing: normal;
-  --font-header-line-height: 1;
+  /* Intentionally unset: leaving this undefined lets grid-line-height()'s
+     per-level $tightness (h1 1.05, h2/h3 1.15, h4-6 1.3) act as the real
+     default. A theme or note can still override by setting this explicitly —
+     but defining it here to a literal value would shadow every level's
+     tightness with the same number, which is the bug this avoids. */
   --font-header-weight: 700;
 
   /* Interface Tokens */
@@ -105,6 +130,11 @@ h6 {
   max-width: 100%;
 }
 
+/* Fixed 2026-07-14 — the mixin's --target-lh now reads
+   --font-header-line-height as an override. The line-height set below
+   for h1/h2/h3 is still always overridden further down by
+   @include grid-line-height(...) (~line 393), which is what actually
+   controls heading line-height now. */
 h1 {
   font-weight: var(--font-weight-h1);
   font-size: clamp(var(--size-xl), 5.5vw, var(--size-2xl));
@@ -141,7 +171,23 @@ h6 {
   line-height: var(--line-height);
 }
 
-/* Typography Patterns */
+/**
+ * @component Typography Elements & Patterns
+ * @category Typography
+ * @description Headings, inline styling, small-caps overlines, keycaps, marks, and blockquotes.
+ *
+ * @property .overline Small-caps letterspaced kicker label with top border rule.
+ * @property .bold Strong bold text weight utility.
+ * @property .menu UI interface font role application.
+ * @property .ui UI interface font role application.
+ * @property .interface UI interface font role application.
+ * @property .font-interface Explicit interface font family utility.
+ * @property .font-mono Monospace font family utility.
+ * @property mark Highlight mark element with optical trim padding and theme tinting.
+ * @property kbd Keyboard keycap with raised shadow and monospace font.
+ * @property a:hover Color and underline accent transition for hyperlinks.
+ * @property a[target="_blank"] External link with automatic arrow indicator (`↗`).
+ */
 .overline {
   font-variant-caps: small-caps;
   letter-spacing: 0.04em;
@@ -226,67 +272,11 @@ pre,
   font-variation-settings: var(--font-monospace-variation);
 }
 
-.stnd-code-block {
-  position: relative;
-  background: var(--color-surface-low);
-  border-radius: var(--radius-sm);
-  box-shadow: var(--shadow-inset), var(--shadow-ring);
-  transition: all var(--transition);
-
-  pre {
-    margin: 0 !important;
-    background: transparent !important;
-    box-shadow: none !important;
-    border: none !important;
-    padding: var(--space-d2);
-    overflow-x: auto;
-    position: static;
-  }
-
-  &:hover .copy-button {
-    opacity: 1;
-  }
-}
-
-.copy-button {
-  position: absolute;
-  top: var(--leading);
-  right: var(--leading);
-  opacity: 0;
-
-  &:hover {
-    opacity: 1 !important;
-    color: var(--color-on-accent);
-    background-color: var(--color-accent);
-  }
-
-  &.copied {
-    color: var(--color-success, #22c55e) !important;
-  }
-
-  &.failed {
-    color: var(--color-error, #ef4444) !important;
-  }
-}
-
-pre {
-  line-height: var(--line-height-compact);
-
-  code {
-    opacity: 0.75;
-    transition: opacity var(--transition);
-  }
-
-  &:hover code {
-    opacity: 1;
-  }
-}
-
 blockquote {
   font-style: italic;
   color: var(--color-muted);
   padding: var(--space);
-  border-left: var(--stroke-width-l) solid var(--color-border);
+  border-left: var(--stroke-width-lg, 2px) solid var(--color-border);
 
   cite {
     display: block;
@@ -295,7 +285,7 @@ blockquote {
   }
 }
 
-/* Utilities */
+/* Utilities & Inline Elements */
 small {
   font-size: var(--size-sm);
 }
@@ -314,84 +304,61 @@ sup {
   vertical-align: super;
 }
 
+/* Duplicate of the `em` rule at line 82 (same --color-italic), this copy
+   additionally sets font-style — harmless overlap, not a conflict. */
 em {
   color: var(--color-italic);
   font-style: italic;
 }
 
-.font-interface {
-  font-family: var(--font-interface), system-ui, sans-serif;
-  font-variation-settings: var(--font-interface-variation);
-  font-feature-settings: var(--font-interface-feature);
-  font-size: 12px;
+/* Mark highlighting */
+mark {
+  background: oklch(from var(--color-yellow) l c h / 0.3);
+  color: color-mix(in oklch, var(--color-yellow) 30%, var(--color-foreground));
+  padding: var(--trim);
+  padding-top: 0.1em;
 }
 
-/**
- * @component Design Tokens
- * @category Foundation
- * @description Primitive design tokens forming the foundation of the design system.
- * Includes "Self-Aware" fluid typography that scales based on the Optical Ratio.
- */
-
-#{$stnd-scope} {
-  /* ===== 2. THE META-COGNITION (Fluid Slopes) =====
-     Instead of magic numbers, we use the Ratio to determine "Physics".
-
-     Slope: (Ratio - 1).
-     - Golden (0.618) -> steep slope (fast growth).
-     - Silver (0.414) -> moderate slope.
-  */
-  --physics-slope: calc(var(--optical-ratio) - 1);
-
-  /* Growth Factor: How aggressive is the resizing?
-     We multiply the slope by 1vw to create a viewport-relative unit. */
-  --fluid-growth: calc(var(--physics-slope) * 0.8vw);
-
-  /* Tension Factor: How much do we tighten leading as we grow?
-     Higher ratios need more tension to keep large text readable. */
-  --fluid-tension: calc(var(--physics-slope) * 0.3vw);
-
-  /* ===== 3. FLUID TYPOGRAPHY =====
-     Base size starts at 1rem and grows according to the Physics Slope.
-  */
-  --base-size: var(--font-text-size, 1rem);
-  
-  --font-size: clamp(
-    var(--base-size),
-    calc(var(--base-size) + var(--fluid-growth)),
-    calc(var(--base-size) * 1.5)
-  );
-
-  /* ===== 4. FLUID LINE HEIGHT =====
-     This is the "Next Level" logic.
-     Start with the Optical Ratio as the base breathing room (in ems).
-     As the screen (and font) grows, SUBTRACT the Tension Factor.
-
-     Why? Large text (Desktop) needs TIGHTER leading than small text (Mobile).
-     A steep ratio (Golden) creates huge text, so it applies MORE tension.
-  */
-  --line-height: clamp(
-    1.15,
-    calc(var(--optical-ratio) - (var(--fluid-tension) / 1vw)),
-    1.65
-  );
+/* Keycaps */
+kbd {
+  background-color: var(--color-surface);
+  background-image: var(--effect-grain);
+  border: none;
+  border-radius: var(--radius);
+  box-shadow: var(--shadow-raised);
+  padding: var(--space-d6) var(--space-d3);
+  font-family: var(--font-monospace);
+  font-size: var(--size-xs);
+  pointer-events: none;
 }
 
-
+/**
+ * @component Heading Rhythm & Grid Snapping
+ * @category Typography
+ * @description Half-baseline rhythm snapping mixin for heading hierarchy.
+ *
+ * @property @mixin grid-line-height Heading line-height mixin snapping leading to half-baseline rhythm increments.
+ */
 
 @mixin grid-line-height($tightness: 1.1) {
-  /* The "Target" is simply the font-size * tightness */
-  --target-lh: calc(1em * #{$tightness});
-
-  /* The Snap: Force it to be a multiple of --baseline */
-  line-height: round(up, var(--target-lh), var(--baseline)) !important;
+  /* The "Target" is simply the font-size * tightness, unless a note
+     overrides it via --font-header-line-height in frontmatter */
+  --target-lh: calc(1em * var(--font-header-line-height, #{$tightness}));
+
+  /* The Snap: force it to be a multiple of *half* a baseline, not a whole
+     one. Whole-baseline snapping wastes up to ~1 baseline in the worst case
+     (target just above a multiple) — brutal on smaller headings whose
+     font-size is close to or under one baseline (e.g. h2/h3). Half-baseline
+     halves that worst case while still landing on the page's rhythm every
+     two headings. */
+  line-height: round(up, var(--target-lh), calc(var(--baseline) / 2)) !important;
 
   /* Why 'up'?
      'nearest' might snap down and cause letters to clash.
      'up' ensures we always have *at least* enough room. */
 }
 
-/* Usage in your Header sizes */
+/* Usage in Header sizes */
 h1 {
   /* Giant text needs very tight leading (1.05x), then snap up */
   @include grid-line-height(1.05);

package/_standard-04-grid.scss

@@ -8,14 +8,18 @@
  * asymmetric layouts, gap variants (compact/normal/wide), and responsive column changes.
  * All gaps align to the vertical rhythm system.
  *
- * @prop {class} .grid 12-column grid container
- * @prop {class} .grid-2 through .grid-12 Predefined grid layouts (2-12 columns)
- * @prop {class} .col-1 through .col-12 Column span modifiers
- * @prop {class} .col-sm-* Responsive columns at 768px+
- * @prop {class} .col-lg-* Responsive columns at 1024px+
- * @prop {class} .start-{n} Start column position (1-12)
- * @prop {class} .gap-compact compact gap (1/4 space)
- * @prop {class} .gap-wide Wide gap (1.5 space)
+ * @property .grid 12-column Swiss-style responsive grid container with automatic column flow.
+ * @property .grid-row Grid container with row flow.
+ * @property .grid-{n} Explicit n-column grid container (1 to 12 columns).
+ * @property .col-{n} Column span modifiers (1 to 12 columns, direct children of .grid).
+ * @property .start-{n} Column start position (1 to 12).
+ * @property .grid.no-gap Removes grid row gap.
+ * @property .grid.compact Compact gap variant aligned to `--trim`.
+ * @property .grid.relaxed Relaxed gap variant aligned to `--space`.
+ * @property .sm:col-{n} Responsive column spans at mobile viewport (<=768px).
+ * @property .sm:grid-{n} Responsive column grid count at mobile viewport (<=768px).
+ * @property .lg:col-{n} Responsive column spans at desktop viewport (>=1024px).
+ * @property .lg:grid-{n} Responsive column grid count at desktop viewport (>=1024px).
  *
  * @example
  * // Basic 12-column grid with equal width columns
@@ -28,8 +32,8 @@
  *
  * // Responsive grid layout
  * <div class="grid">
- *   <div class="col-12 col-sm-6 col-lg-3">Card</div>
- *   <div class="col-12 col-sm-6 col-lg-3">Card</div>
+ *   <div class="col-12 sm:col-6 lg:col-3">Card</div>
+ *   <div class="col-12 sm:col-6 lg:col-3">Card</div>
  * </div>
  *
  * // Main content + sidebar layout
@@ -47,10 +51,15 @@
    Relies on logical properties and Harmony tokens: --base, calc(var(--space) / 4), --base-2, borders, etc.
 */
 
-/* Grid container */
-.grid,
-[class^="grid-"],
-.grid-row {
+/* Fixed 2026-07-14 — was attribute selectors (order-dependent), now an
+   explicit selector list built once via $grid-selectors (order-independent). */
+$grid-selectors: ".grid, .grid-row";
+@for $i from 1 through 12 {
+  $grid-selectors: $grid-selectors + ", .grid-#{$i}";
+}
+
+/* Grid container. */
+#{$grid-selectors} {
   display: grid;
   grid-auto-columns: 1fr;
   grid-auto-flow: column;
@@ -58,8 +67,7 @@
   row-gap: var(--gap);
 }
 
-.grid,
-[class^="grid-"] {
+#{$grid-selectors} {
   > * {
     margin: 0;
   }
@@ -73,25 +81,26 @@
 /* TYPOGRAPHIC NUANCES         */
 /* =========================== */
 
-[class^="grid"] > * {
+#{$grid-selectors} > * {
   min-width: 0;
   /* ← Force items to shrink below content size */
   margin-block: 0;
 }
 
 @media (max-width: #{$mobile}) {
-  [class^="grid"] > * {
+  #{$grid-selectors} > * {
     min-width: 0;
   }
 }
 
-[class^="grid"] {
+#{$grid-selectors} {
   .card {
     margin: 0;
   }
 }
 
-/* Gap variants aligned to rhythm */
+/* Gap variants aligned to rhythm — this is the LIVE definition (sets --gap,
+   the property actually consumed by column-gap/row-gap above). */
 :is(.grid, [class^="grid-"]).compact {
   --gap: var(--trim);
 }
@@ -267,19 +276,11 @@ hr.col-row {
   z-index: 1;
 }
 
-/* Row gap utilities for grid system */
+/* Row gap utilities for grid system. */
 .grid.no-gap {
   row-gap: 0;
 }
 
-.grid.compact {
-  --grid-gap: var(--leading);
-}
-
-.grid.relaxed {
-  --grid-gap: var(--space-2);
-}
-
 /* Common layout containers inherit rhythm to cascade deeper */
 .box,
 .grid > .col-1,
@@ -309,6 +310,6 @@ hr.col-row {
   }
 }
 
-[class|="grid"] .container-hero {
+#{$grid-selectors} .container-hero {
   margin-inline: 0;
 }

package/_standard-05-rhythm.scss

@@ -1,5 +1,27 @@
 @use "standard-00-variables" as *;
 
+/**
+ * @component Rhythm
+ * @category Layout
+ * @description Vertical rhythm for any container: apply `.rhythm` and its
+ * children get consistent `margin-block-start` spacing with no per-element
+ * classes, heavier before headings and around block-level elements
+ * (tables, blockquotes, figures — the tags this cascades to are declared
+ * once in `_standard-00-variables.scss`, not here). `.flex > *` is zeroed
+ * out automatically so rhythm margins never stack with flex `gap`.
+ *
+ * @property .rhythm The container class. Sets `display: flow-root` so child margins cannot collapse out of it.
+ * @property .no-rhythm Zeroes `margin-block-start` on every descendant — a subtree-wide rhythm opt-out.
+ * @property --gap-multiplicator Rhythm multiplier factor for block-level spacing and heading exceptions.
+ * @property .flex > * Zeroes `margin-block-start` for flex children so margins do not stack with flex gap.
+ *
+ * @example html - Turn any container into a rhythm block
+ * <article class="rhythm">
+ *   <h2>Heading</h2>
+ *   <p>Spaced automatically — no margin utility classes needed.</p>
+ * </article>
+ */
+
 /* ===== BULLETPROOF RHYTHM SYSTEM ===== */
 /* Applied to any container — cascades to children via margin-block-start */
 
@@ -9,6 +31,24 @@
      Think of it as "overflow: hidden" but without clipping content. */
   display: flow-root;
 
+  /* Every selector below is wrapped in :where(), including .rhythm itself
+     — that's zero specificity everywhere, by design (easy for any other
+     rule to override). Which means SOURCE ORDER is the only tiebreaker
+     when more than one of these rules matches the same element (e.g. a
+     paragraph immediately before an h1 matches both the base 1x rule
+     below AND the heading exception further down — the exception wins
+     purely because it's declared later). Do not reorder this block
+     without checking every rule still resolves the way you expect. */
+
+  /* AUDIT FLAG (2026-07-14): this base rule has no `>` — it applies at
+     ANY nesting depth inside .rhythm, not just direct children. Every
+     other rule in this block (the double-tag 2x rule right below, and
+     all EXCEPTIONS) is `>`-scoped to direct children only. So a heading
+     nested two levels deep (inside a .callout, say) gets the base 1x
+     spacing but never the heading-specific 2x/3x exceptions a top-level
+     heading would get. Possibly intentional (exceptions are for
+     top-level document flow only) — flagging since the asymmetry itself
+     isn't declared anywhere, just falls out of one missing `>`. */
   :where(:is(#{$rhythm-tags})) + :where(:is(#{$rhythm-tags})) {
     margin-block-start: calc(var(--gap) * 1);
   }
@@ -46,6 +86,9 @@
 
   //*/
 
+  /* Flex children use `gap` for spacing, not margin (see cheat sheet:
+     "gap on the parent, not margin on children") — zero out any rhythm
+     margin that would otherwise stack with the flex gap. */
   .flex > * {
     margin-block-start: 0;
   }

package/_standard-06-prose.scss

@@ -8,16 +8,20 @@
  * responsive content columns for sidebars, accents, and featured content.
  * Inspired by fine-art typography and classical book design principles.
  *
- * @prop {class} .prose Main article/content container for readable prose
- * @prop {class} .small Narrow sidebar width container
- * @prop {class} .accent Accent container with background color
- * @prop {class} .feature Featured content with larger spacing
- * @prop {class} .hero Full-width container
- * @prop {variable} --line-width-xs Extra small (24rem / 384px)
- * @prop {variable} --line-width-sm Small (32rem / 512px)
- * @prop {variable} --line-width-md Medium (42rem / 672px) - default
- * @prop {variable} --line-width-lg Large (50rem / 800px)
- * @prop {variable} --line-width-xl Extra large (60rem / 960px)
+ * @property .prose Main article/content grid container for readable prose with named tracks.
+ * @property .prose.left Left-aligned prose variant hugging the left edge.
+ * @property .small Narrow sidebar breakout column track.
+ * @property .editorial Editorial column breakout track (`minmax(0, var(--space-2))`).
+ * @property .feature Feature callout breakout track (`minmax(0, var(--space-4))`).
+ * @property .hero Full-bleed viewport width hero track (`minmax(0, 1fr)`).
+ * @property .full Full viewport width breakout track.
+ * @property --line-width Active reading column measure.
+ * @property --line-width-xs Extra small reading measure (24rem / 384px).
+ * @property --line-width-sm Small reading measure (32rem / 512px).
+ * @property --line-width-md Medium reading measure (42rem / 672px) - default.
+ * @property --line-width-lg Large reading measure (50rem / 800px).
+ * @property --line-width-xl Extra large reading measure (60rem / 960px).
+ * @property --body-max-width Overall page max-width constraint (900px).
  *
  * @example
  * // Standard article with proper reading width
@@ -75,7 +79,7 @@
   transition: grid-template-columns var(--transition);
 
   position: relative;
-  max-width: var(--prose-max-width, var(--max-width));
+  max-width: var(--body-max-width);
   /*z-index: var(--z-base);*/
   /* Default content positioning */
 
@@ -88,6 +92,13 @@
       padding-inline var(--transition);
   }
 
+  /* Astro islands render as <astro-island> with display:contents, so their
+     children — not the island — are the grid items and need placement too. */
+  > astro-island > * {
+    grid-column: content;
+    min-width: 0;
+  }
+
   > .small,
   > .container-small,
   > .callout,
@@ -129,28 +140,6 @@
     }
   }
 
-  /* =========================== */
-  /* TYPOGRAPHIC NUANCES         */
-  /* =========================== */
-  .video-container {
-    position: relative;
-    padding-bottom: 56.25%;
-    /* 16:9 aspect ratio */
-    height: 0;
-    overflow: hidden;
-    border-radius: var(--radius);
-    box-shadow: var(--shadow-raised);
-
-    iframe {
-      position: absolute;
-      top: 0;
-      left: 0;
-      width: 100%;
-      height: 100%;
-      border: 0;
-    }
-  }
-
   /* Image gallery layout */
   &:not(.no-grid) {
     p:has(img),
@@ -196,9 +185,6 @@
     margin-inline: 0 !important;
   }
 
-  /* Note: Page's main title h1:first-child retains spacing via direct child selector */
-  /* The > h1:first-child selector in h1 rule ensures it overrides rhythm's > * margin-reset */
-
   /* Basic media styling */
   img,
   audio,
@@ -260,17 +246,19 @@
     overflow-wrap: break-word;
   }
 
+  /* Fixed 2026-07-14 — swapped undefined tokens for their real equivalents
+     (--color-muted, --color-accent, --color-surface-high). */
   .mycelial-graft {
     text-decoration: none;
-    border-bottom: 1px dotted var(--color-text-muted);
+    border-bottom: 1px dotted var(--color-muted);
     color: inherit;
     cursor: help;
     transition: all 0.2s ease;
 
     &:hover {
-      color: var(--color-primary);
-      border-bottom: 1px solid var(--color-primary);
-      background-color: var(--color-surface-hover);
+      color: var(--color-accent);
+      border-bottom: 1px solid var(--color-accent);
+      background-color: var(--color-surface-high);
     }
   }
 }