@stnd/styles 0.5.1 → 0.5.3

package/_standard-07-base.scss

@@ -1,5 +1,23 @@
 @use "standard-00-variables" as *;
 
+/**
+ * @component Base
+ * @category Foundation
+ * @description Document root and page chrome, zero classes required: html
+ * typography and font features, body padding/max-width/centering, a
+ * global reading-measure cap applied to text elements site-wide (not just
+ * inside `.prose`), theme-transition rules, and selection/mark highlights.
+ *
+ * @property html Root element establishing background color, foreground text color, font smoothing, and smooth scrolling.
+ * @property body Document container centered at `--body-max-width` with responsive padding and scroll margins.
+ * @property .no-body-margin Full-bleed helper applied to `<header>` or `<footer>` to extend edge-to-edge past body padding.
+ * @property .container-hero Hero section container with vertical padding and hairline borders.
+ * @property ::selection Custom highlight selection using subtle yellow background tint and accent text color.
+ *
+ * @example html - Full-bleed footer inside a normally-padded body
+ * <footer class="no-body-margin">Full-width footer content</footer>
+ */
+
 /* =========================== */
 /* BASE (HTML ROOT)            */
 /* =========================== */
@@ -64,7 +82,7 @@ body {
   padding: var(--gap-body);
   padding-top: var(--gap-header);
   padding-bottom: var(--gap-footer);
-  max-width: var(--body-max-width, var(--max-width));
+  max-width: var(--body-max-width);
   margin-inline: auto;
 
   transition:
@@ -75,8 +93,8 @@ body {
     margin var(--transition);
 
   [id] {
+    /* Keeps anchor-linked headings from landing under the sticky header. */
     scroll-margin-top: calc(var(--space-2) + var(--gap-header));
-    /* Adjust value as needed background: var(--color-surface-highest); background: var(--color-surface-highest); background: var(--color-surface-highest); background: var(--color-surface-highest); */
   }
 }
 
@@ -127,14 +145,6 @@ hr {
   block-size: var(--stroke-width, 1px);
 }
 
-/* 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;
-}
-
 /* =========================== */
 /* LAYOUT                      */
 /* =========================== */
@@ -165,24 +175,23 @@ dt {
 /* BODY PADDING NEGATION       */
 /* =========================== */
 
-/**
- * Utilities to negate body padding for full-width elements
- * Useful for footers, headers, or other elements that should extend to viewport edges
- *
- * .negate-body-padding — Negates horizontal body padding only
- * .negate-body-padding-full — Negates all body padding (horizontal + bottom)
- * .negate-body-padding-bottom — Negates extra bottom body padding (1.5× multiplier)
- *
- * Usage:
- * <footer class="negate-body-padding-full">
- *   Full-width footer content
- * </footer>
- */
-
-/**
- * Negate horizontal body padding (left/right)
- * Allows full-width backgrounds while keeping vertical padding
- */
+/* AUDIT NOTE (2026-07-14): this doc previously described a
+   .negate-body-padding / .negate-body-padding-full / .negate-body-padding-bottom
+   API — those class names don't exist anywhere in this file or the
+   codebase (grepped), never did as far as git history in this session
+   shows. The real, implemented class is .no-body-margin, and it's far
+   narrower than "footers, headers, or other elements" implied: it only
+   matches <footer>/<header> that are DIRECT children of <body> AND the
+   first/last element of that type. Neither the old (fictional) nor the
+   real class name is used anywhere in apps/ today — corrected the docs
+   to match reality rather than delete the utility. Moved into the
+   @component block above so its example HTML sits inside a fenced
+   @example instead of bare in a comment — the previous version was
+   valid enough HTML that it would have rendered live on the docs page,
+   not shown as a code sample. */
+
+/* Negate horizontal body padding (left/right) — allows full-width
+   backgrounds while keeping vertical padding. */
 
 body > footer.no-body-margin:last-of-type,
 body > header.no-body-margin:first-of-type {
@@ -194,11 +203,9 @@ body > header.no-body-margin:first-of-type {
   }
 }
 
-/**
- * Negate bottom body padding (extra 1.5× multiplier)
- * Removes the generous bottom padding applied to body elements
- * Useful when you want footer to sit flush at bottom
- */
+/* Negate bottom body padding (extra 1.5× multiplier) — removes the
+   generous bottom padding applied to body elements, for a footer that
+   should sit flush at the bottom. */
 body > footer.no-body-margin:last-of-type {
   margin-block-end: calc(var(--gap-body) * -1.5);
 
@@ -207,10 +214,13 @@ body > footer.no-body-margin:last-of-type {
   }
 }
 
+/* Fixed 2026-07-14 — was margin-block-end (wrong property, copy-paste
+   typo), now correctly overrides margin-block-start to match the footer's
+   symmetric pattern. */
 body > header.no-body-margin:first-of-type {
   margin-block-start: calc(var(--gap-body) * -1);
 
   @media (max-width: #{$small}) {
-    margin-block-end: calc(var(--gap-body-mobile) * -1);
+    margin-block-start: calc(var(--gap-body-mobile) * -1);
   }
 }

package/_standard-08-media.scss

@@ -1,15 +1,26 @@
 @use "standard-00-variables" as *;
 
-/* =========================== */
-/* MEDIA                       */
-/* =========================== */
+/**
+ * @component Media & Embeds
+ * @category Content
+ * @description Responsive media containers for images, native video, audio players,
+ * and iframes. Applies theme borders, elevation shadows, and rounded corners by default.
+ *
+ * @property img Responsive image with theme radius and raised surface shadow.
+ * @property video Native video element with border and elevation.
+ * @property .video-container Responsive 16:9 media embed container for videos and iframes.
+ * @property .stnd-icon Icon container unsetting default media borders and shadows to inherit currentColor.
+ * @property figure Grid container for media and associated captions.
+ * @property figcaption Centered italic caption text for figures.
+ * @property img.fx Image explicitly styled with theme border and radius.
+ * @property img.nofx Image stripping borders, shadows, and radii.
+ */
 
 img,
 video,
 audio,
 iframe,
-.video,
-.video-container {
+.video {
   max-width: 100%;
   border-radius: var(--radius);
   box-shadow: var(--shadow-raised);
@@ -19,29 +30,26 @@ iframe,
 }
 
 /* =========================== */
-/* TYPOGRAPHIC NUANCES         */
+/* VIDEO EMBEDS                */
 /* =========================== */
-.video-container:has(video) {
+.video-container {
   position: relative;
-  /* padding-bottom: 56.25%; /* 16:9 aspect ratio */
-  border: none;
-  box-shadow: none;
+  aspect-ratio: 16 / 9;
+  width: 100%;
+  max-width: 100%;
   overflow: hidden;
-  background: transparent;
+  border-radius: var(--radius);
+  box-shadow: var(--shadow-raised);
+  border: var(--border);
+  background: var(--color-surface);
 
+  iframe,
   video {
-    border-radius: var(--radius);
-    border: var(--border);
-    box-shadow: var(--shadow-raised);
-  }
-
-  iframe {
-    position: absolute;
-    top: 0;
-    left: 0;
     width: 100%;
     height: 100%;
     border: 0;
+    display: block;
+    object-fit: cover;
   }
 }
 
@@ -76,12 +84,17 @@ figcaption {
 }
 
 /**
- * @component Image System
+ * @component Image Zoom & Lightbox
+ * @category Content
  * @description Responsive image handling with interactive zoom functionality.
- * This system is progressively enhanced. Without JavaScript, it provides a
- * basic zoom-on-click-and-hold. With JavaScript, it provides a full
- * feature-rich lightbox experience.
+ * Progressively enhanced: without JavaScript, provides click-and-hold zoom.
+ * With JavaScript, provides a full frosted-glass lightbox experience.
  *
+ * @property html:not(.js-image-zoom-enabled) img:active Fallback CSS-only zoom on click-and-hold.
+ * @property .image-zoom-overlay Fullscreen glassmorphic lightbox overlay created dynamically by JS.
+ * @property .image-zoom-overlay.is-visible Active visible state for the lightbox overlay.
+ * @property html.image-zoomed-active Body scroll lock class applied when lightbox is active.
+ * @property [data-no-zoom] Attribute to prevent zoom interaction on icons or avatars.
  * @since 0.1.0
  */
 
@@ -160,11 +173,10 @@ html:not(.js-image-zoom-enabled):has(img:active)::before {
 /* lightbox experience with keyboard navigation, etc.               */
 /* ================================================================ */
 
-/* Lock the page scroll when the JS overlay is active
+/* Lock the page scroll when the JS overlay is active */
 html.image-zoomed-active {
-    overflow: hidden;
+  overflow: hidden;
 }
-*/
 /* The overlay container created by the JS */
 .image-zoom-overlay {
   position: fixed;
@@ -175,7 +187,6 @@ html.image-zoomed-active {
   display: flex;
   align-items: center;
   justify-content: center;
-  padding: var(--gap-body);
   padding: var(--space-4);
   margin: 0;
   opacity: 0;
@@ -208,7 +219,9 @@ html.image-zoomed-active {
   transform: scale(1);
 }
 
-@media (min-width: 768px) {
+/* Uses #{$small} — same breakpoint variable as everywhere else in the
+   framework. */
+@media (min-width: #{$small}) {
   /* Global zoomable image cursor */
   img:not([data-no-zoom]) {
     cursor: zoom-in !important;

package/_standard-09-lists.scss

@@ -1,5 +1,26 @@
 @use "standard-00-variables" as *;
 
+/**
+ * @component Lists
+ * @category Content
+ * @description Replaces native `<ul>`/`<ol>` markers with custom
+ * absolutely-positioned bullets and tabular-nums counters, and spaces items
+ * apart via `li + li`. Four density/marker classes are opt-in.
+ *
+ * @property .no-bullet Hides markers and removes inline padding; cascades to nested lists.
+ * @property .tight Tightens list item vertical spacing to `--space-d3`.
+ * @property .compact Tightens list item vertical spacing to `--space-d2`.
+ * @property .relaxed Widens list item vertical spacing to `--space-2`.
+ * @property .task-list-item Applied to task list items (`- [ ]`), displaying interactive or static checkbox.
+ * @property .task-field Inline badge representation for Dataview-style `[key:: value]` metadata.
+ *
+ * @example html - What `- [ ] Ship it [priority:: 1]` becomes
+ * <li class="task-list-item">
+ *   <input type="checkbox" disabled> Ship it
+ *   <span class="task-field" data-field="priority">priority: 1</span>
+ * </li>
+ */
+
 /* =========================== */
 /* LISTS                       */
 /* =========================== */
@@ -13,7 +34,7 @@ ol {
 /* Nested lists */
 li > ul,
 li > ol {
-  padding-inline-start: var(--space);
+  padding-inline: var(--space);
   margin-block-start: var(--space-d2);
   margin-block-end: 0;
 }
@@ -62,9 +83,11 @@ ol > li::before {
   font-size: var(--size-sm);
 }
 
+/* Fixed 2026-07-14 — was checking for .display-flex (not a real class
+   anywhere), now correctly checks .flex. */
 /* Inline lists override - protects layouts using flex */
-ul:where(.display-flex, [style*="display: flex"], [style*="display:flex"]) li,
-ol:where(.display-flex, [style*="display: flex"], [style*="display:flex"]) li {
+ul:where(.flex, [style*="display: flex"], [style*="display:flex"]) li,
+ol:where(.flex, [style*="display: flex"], [style*="display:flex"]) li {
   margin-block-end: 0;
 }
 
@@ -81,23 +104,55 @@ ol:where(.display-flex, [style*="display: flex"], [style*="display:flex"]) li {
   }
 }
 
-.compact {
-  --base-gap: var(--space-d2);
-  li + li {
-    margin-block-start: var(--space-d2);
-  }
+/* FIXED (2026-09-05) — was a bare, unnamespaced .compact/.relaxed that
+   collided with _standard-50-utilities.scss's line-height utilities of the
+   same name: any element with class="compact" containing <li> children got
+   this file's li+li spacing unconditionally, whether or not it was
+   actually a list. Qualified to :is(ul, ol) instead, matching the pattern
+   _standard-04-grid.scss already uses for its own .compact/.relaxed
+   (:is(.grid, [class^="grid-"]).compact) — same class name, each scope's
+   meaning applies only in its own context. A <ul class="compact"> now
+   picks up both this file's tight item spacing AND utilities.scss's
+   compact line-height, which is the combination you'd actually want. */
+:is(ul, ol).compact li + li {
+  margin-block-start: var(--space-d2);
 }
 
-.tight {
-  --base-gap: var(--space-d3);
-  li {
-    margin-block-end: var(--space-d3);
-  }
+:is(ul, ol).tight li {
+  margin-block-end: var(--space-d3);
+}
+
+:is(ul, ol).relaxed li {
+  margin-block-end: var(--space-2);
 }
 
-.relaxed {
-  --base-gap: var(--space-2);
-  li {
-    margin-block-end: var(--space-2);
+/* =========================== */
+/* TASK LISTS                  */
+/* =========================== */
+
+/* Rendered by @stnd/press's typography-tasks plugin from `- [ ]` / `- [x]` —
+   the checkbox replaces the bullet, it doesn't sit alongside it. */
+.task-list-item {
+  &::before {
+    display: none;
+  }
+
+  input[type="checkbox"] {
+    margin-inline-end: var(--space-d3);
+    vertical-align: -0.15em;
+    accent-color: var(--color-accent);
   }
 }
+
+/* Dataview-style `[key:: value]` inline fields, tagged by the same plugin. */
+.task-field {
+  display: inline-block;
+  font-family: var(--font-monospace);
+  font-size: var(--size-3xs);
+  color: var(--color-subtle);
+  background: var(--color-surface);
+  border: var(--border);
+  border-radius: var(--radius-sm);
+  padding: 0 var(--space-d4);
+  margin-inline-end: var(--space-d6);
+}

package/_standard-10-tables.scss

@@ -1,5 +1,30 @@
 @use "standard-00-variables" as *;
 
+/**
+ * @component Tables
+ * @category Content
+ * @description A bare `<table>` gets full styling with no class required:
+ * collapsed borders, uppercase small-caps headers, compact cell padding.
+ * `.striped` and `.numeric` are the only two opt-in classes.
+ *
+ * @property table Zero-class collapsed table layout with hairline borders and compact padding.
+ * @property th Uppercase small-caps table header with surface background and subtle tracking.
+ * @property caption Bold caption element positioned above table with rhythm padding.
+ * @property .striped Zebra-stripes even `<tbody>` rows with a 3% foreground tint.
+ * @property .numeric Right-aligns content and switches on tabular-nums for numeric columns.
+ * @property .properties Table variant keeping leading identifier/token columns unwrapped.
+ *
+ * @example html - Bare table, zero classes
+ * <table>
+ *   <thead>
+ *     <tr><th>Name</th><th class="numeric">Count</th></tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr><td>Widgets</td><td class="numeric">42</td></tr>
+ *   </tbody>
+ * </table>
+ */
+
 /* =========================== */
 /* TABLES                      */
 /* =========================== */
@@ -9,6 +34,9 @@ table {
   width: 100%;
 }
 
+/* padding/margin on <tr> have no effect — table rows don't support box
+   model properties in the CSS table layout spec, browsers ignore these.
+   Harmless no-op, not fixing since it's inert either way. */
 tr {
   padding: 0;
   margin: 0;
@@ -21,15 +49,21 @@ td {
   line-height: var(--line-height-compact);
   padding: var(--space-d2);
   font-size: var(--size-sm);
-  min-height: var(--line-height);
+  vertical-align: top;
+  /* Fixed 2026-07-14 — was an invalid unitless min-height, now derives a
+     real length from the line-height already set above. */
+  min-height: calc(1em * var(--line-height-compact));
 }
 
 th {
   font-weight: var(--font-weight-bold, 600);
   transition: background var(--transition);
-  background: var(--color-surface-low);
+  background: var(--color-surface);
   text-transform: uppercase;
-  letter-spacing: 0.05em;
+  letter-spacing: 0.06em;
+  font-size: var(--size-3xs);
+  color: var(--color-muted);
+  vertical-align: middle;
 }
 caption {
   font-weight: var(--font-weight-bold, bold);
@@ -47,3 +81,17 @@ caption {
 .striped tbody tr:nth-child(even) {
   background: oklch(from var(--color-foreground) l c h / 0.03);
 }
+
+/* Property & token dictionaries (prevents key column from wrapping) */
+.properties {
+  th:not(:last-child),
+  td:not(:last-child) {
+    white-space: nowrap;
+    width: 1%;
+  }
+
+  th:last-child,
+  td:last-child {
+    width: 100%;
+  }
+}

package/_standard-11-forms.scss

@@ -1,5 +1,35 @@
 @use "standard-00-variables" as *;
 
+/**
+ * @component Forms
+ * @category Content
+ * @description Zero-class styling for every native form control:
+ * `fieldset`/`legend` layout, text inputs, textarea, a custom-drawn select,
+ * checkbox/radio, an ARIA switch variant, and a range slider — plus the
+ * adjacency rules that space form parts apart from each other and from
+ * whatever follows them.
+ *
+ * @property fieldset Container grouping form controls with hairline border, radius, and subtle surface background tint.
+ * @property legend Bold legend label nested within fieldset.
+ * @property input, textarea Zero-class text controls with interface typography, raised shadow, and accent focus rings.
+ * @property select Custom styled dropdown with double-chevron indicator and rhythm-aligned padding.
+ * @property input[role=switch] Accessible toggle switch with animated sliding thumb.
+ * @property --switch-height Primary height sizing knob for toggle switch controls.
+ * @property --switch-width Width sizing token for toggle switches (`calc(var(--switch-height) * 2)`).
+ * @property --switch-padding Inset padding controlling the toggle switch thumb gap (`2px`).
+ * @property --slider-value Percentage value driving custom filled range slider tracks.
+ *
+ * @example html - A switch (role=switch on a checkbox)
+ * <input type="checkbox" role="switch">
+ *
+ * @example html - Fieldset with adjacent button spacing
+ * <fieldset>
+ *   <legend>Notifications</legend>
+ *   <label><input type="checkbox"> Email me</label>
+ * </fieldset>
+ * <button>Save</button>
+ */
+
 /* =========================== */
 /* FORMS                       */
 /* =========================== */
@@ -49,9 +79,12 @@ textarea {
   border-radius: var(--radius-sm);
   color: var(--color-foreground);
   background: var(--color-surface);
-  /* shadcn-style raised effect */
+  /* shadcn-style raised effect. */
   border: var(--border);
   box-shadow: var(--shadow-raised);
+  /* Transparent outline at full width reserves the space a real focus
+     outline (set on :focus below) will need — prevents layout shift when
+     the outline color actually appears. */
   outline: var(--stroke-width) solid transparent;
   outline-offset: var(--stroke-width);
   transition: all var(--transition-fast);
@@ -66,7 +99,6 @@ textarea {
 select {
   width: 100%;
   font-family: var(--font-interface), system-ui, sans-serif;
-  font-family: var(--font-interface), system-ui, sans-serif;
   font-weight: var(--font-weight);
   padding: var(--space-d8) var(--space-d4);
   font-size: 1em;
@@ -276,9 +308,11 @@ input[type="checkbox"][role="switch"] {
     }
   }
 
+  /* Fixed 2026-07-14 — was a typo (--color-on-cce), corrected to
+     --color-on-accent. */
   &:checked:hover {
     &::before {
-      background: var(--color-on-cce) !important;
+      background: var(--color-on-accent) !important;
     }
   }
 }
@@ -303,18 +337,17 @@ input[type="range"] {
   /* Crucial: removes text-input borders */
   background-origin: border-box;
 
-  /*
-   * THE FILL MAGIC
-   * uses the --slider-value variable passed in the style attribute
-   */
+  /* Fixed 2026-07-14 — this gradient is real and wired up by
+     Slider.astro's JS (sets --slider-value); the flat color below it was
+     silently overriding it. Removed the override so the fill effect
+     actually renders. */
   background: linear-gradient(
     to right,
     var(--color-background, var(--color-accent)) 0%,
-    var(--color-background, var(--color-accent)) var(--slider-value),
-    var(--color-red, var(--color-surface)) var(--slider-value),
+    var(--color-background, var(--color-accent)) var(--slider-value, 50%),
+    var(--color-red, var(--color-surface)) var(--slider-value, 50%),
     var(--color-red, var(--color-surface)) 100%
   );
-  background: var(--color-surface-lowest);
 }
 
 input[type="range"]::-webkit-slider-thumb {

package/_standard-12-code.scss

@@ -1,6 +1,88 @@
 @use "standard-00-variables" as *;
-/* Note: General color utilities (.text-muted, .text-subtle, .text-accent, .bg-surface, .border-*) */
-/* moved to standard-98-utilities.scss for better layer organization */
+
+/**
+ * @component Code Layout & Highlighting
+ * @category Content
+ * @description Code block container layout, copy buttons, and PrismJS syntax highlighting theme.
+ *
+ * @property .stnd-code-block Styled code block container with copy button and inset shadows.
+ * @property .copy-button Floating copy action button inside code blocks.
+ * @property pre Preformatted code block with compact leading and hover transitions.
+ * @property .token.keyword Keywords and control-flow statements (`--color-red`).
+ * @property .token.string Quoted strings and attribute values (`--color-green`).
+ * @property .token.number Numeric literals and boolean values (`--color-cyan`).
+ * @property .token.function Function declarations and method invocations (`--color-yellow`).
+ * @property .token.property Object keys and CSS property names (`--color-orange`).
+ * @property .token.punctuation Brackets, parens, delimiters, and operators (`--color-muted`).
+ * @property .token.comment Code comments rendered in muted italic typography (`--color-subtle`).
+ * @property .language-* Per-language syntax overrides for YAML, Markdown, Shell/Bash, and Nunjucks.
+ *
+ * @example html - Standard code block with copy button
+ * <div class="stnd-code-block">
+ *   <button class="copy-button">Copy</button>
+ *   <pre><code class="language-bash">npm install @stnd/core</code></pre>
+ * </div>
+ */
+
+/* =========================== */
+/* CODE BLOCK CONTAINER        */
+/* =========================== */
+
+.stnd-code-block {
+  position: relative;
+  background: var(--color-surface);
+  border-radius: var(--radius-sm);
+  box-shadow: var(--shadow-inset), var(--shadow-ring);
+  transition: all var(--transition);
+
+  pre {
+    padding: var(--space);
+    background: transparent;
+    box-shadow: none;
+    border: none;
+    margin: var(--stroke-width);
+    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.85;
+    transition: opacity var(--transition);
+  }
+
+  &:hover code {
+    opacity: 1;
+  }
+}
 
 /* PrismJS syntax highlighting - Language agnostic tokens */