@stnd/styles 0.5.2 → 0.5.3

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
@@ -136,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),

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)            */
 /* =========================== */
@@ -127,24 +145,12 @@ 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                      */
 /* =========================== */
 
 section.container-hero {
   padding-block: var(--space-2);
-  /* --border currently resolves to `none` — see the AUDIT FLAG in
-     _standard-02-color.scss (duplicate --border declaration, "0 solid
-     transparent" then "none" wins). This section's top/bottom border is
-     invisible today as a result — real-world impact of that flag. */
   border-top: var(--border);
   border-bottom: var(--border);
   box-shadow: var(--shadow);
@@ -169,37 +175,23 @@ dt {
 /* BODY PADDING NEGATION       */
 /* =========================== */
 
-/**
- * AUDIT NOTE (2026-07-14): this docblock 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 (body > footer.no-body-margin:last-of-type
- * / body > header.no-body-margin:first-of-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.
- *
- * Utilities to negate body padding for a direct-child header/footer that
- * should extend to the viewport edges.
- *
- * .no-body-margin — on a <footer> or <header> that is a direct child of
- *   <body> and the last/first element of its type, respectively. Negates
- *   horizontal body padding (both variants); the footer variant also
- *   negates the extra 1.5× bottom padding, the header variant the top.
- *
- * Usage:
- * <footer class="no-body-margin">
- *   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 {
@@ -211,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);
 

package/_standard-08-media.scss

@@ -1,19 +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.
+ */
 
-/* --border currently resolves to `none` everywhere it's used in this file
-   (3 places) — see the AUDIT FLAG in _standard-02-color.scss (duplicate
-   --border declaration; the "none" copy wins). Media elements here get no
-   visible border as a result. */
 img,
 video,
 audio,
 iframe,
-.video,
-.video-container {
+.video {
   max-width: 100%;
   border-radius: var(--radius);
   box-shadow: var(--shadow-raised);
@@ -23,33 +30,26 @@ iframe,
 }
 
 /* =========================== */
-/* TYPOGRAPHIC NUANCES         */
+/* VIDEO EMBEDS                */
 /* =========================== */
-.video-container:has(video) {
+.video-container {
   position: relative;
-  /* Unlike the iframe variant in _standard-06-prose.scss, this one holds a
-     native <video> element, which has real intrinsic dimensions — the
-     legacy padding-bottom:56.25% aspect-ratio hack (disabled below) isn't
-     needed the way it is for iframes. */
-  /* padding-bottom: 56.25% — 16:9 aspect ratio, disabled, see above */
-  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;
   }
 }
 
@@ -84,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
  */
 

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;
 }
@@ -83,32 +104,55 @@ ol:where(.flex, [style*="display: flex"], [style*="display:flex"]) li {
   }
 }
 
-/* AUDIT FLAG (2026-07-14): .compact and .relaxed are bare, unnamespaced
-   class names also defined in _standard-50-utilities.scss (different
-   rules) and — for .compact/.relaxed specifically — in
-   _standard-04-grid.scss as .grid.compact/.grid.relaxed (qualified, so
-   that one doesn't collide). An element with class="compact" containing
-   <li> children gets BOTH this file's li+li spacing AND whatever
-   _standard-50-utilities.scss's .compact does, unconditionally — no way
-   to opt into one without the other. Flagging the collision rather than
-   renaming; not obvious which file should own the name. (The dead
-   --base-gap sub-issue previously flagged here has been cleaned up: the
-   declarations were removed from this file and from
-   _standard-50-utilities.scss.) */
-.compact {
-  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 {
-  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 {
-  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                      */
 /* =========================== */
@@ -20,12 +45,11 @@ tr {
 th,
 td {
   text-align: left;
-  /* --border currently resolves to `none` — see the AUDIT FLAG in
-     _standard-02-color.scss (duplicate --border declaration). */
   border: var(--border);
   line-height: var(--line-height-compact);
   padding: var(--space-d2);
   font-size: var(--size-sm);
+  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));
@@ -34,9 +58,12 @@ td {
 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);
@@ -54,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,8 +79,7 @@ textarea {
   border-radius: var(--radius-sm);
   color: var(--color-foreground);
   background: var(--color-surface);
-  /* shadcn-style raised effect. --border currently resolves to `none` —
-     see the AUDIT FLAG in _standard-02-color.scss. */
+  /* shadcn-style raised effect. */
   border: var(--border);
   box-shadow: var(--shadow-raised);
   /* Transparent outline at full width reserves the space a real focus

package/_standard-12-code.scss

@@ -1,7 +1,88 @@
 @use "standard-00-variables" as *;
-/* Note: General color utilities (.text-muted, .text-subtle, .text-accent, .bg-surface, .border-*) */
-/* moved to _standard-50-utilities.scss for better layer organization (comment said
-   "standard-98-utilities.scss" — that file doesn't exist, fixed the reference) */
+
+/**
+ * @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 */