@stnd/styles 0.5.2 → 0.5.4

package/_standard-13-components.scss

@@ -1,9 +1,41 @@
 @use "standard-00-variables" as *;
 
+/**
+ * @component Components & Buttons
+ * @category Components
+ * @description Interactive buttons, button groups, loaders, and keycaps.
+ * Buttons extend `%surface` and `%padding-text`, providing tactile hover states,
+ * focus outlines, and active feedback.
+ *
+ * @property button Zero-class interactive button element.
+ * @property a.btn Anchor styled identically to a button.
+ * @property .btn-primary Primary action button filled with accent color.
+ * @property .btn-secondary Secondary button with subtle surface background.
+ * @property .btn-outline Outlined button with hairline border.
+ * @property .btn-destructive Destructive action button using error red.
+ * @property .btn-ghost Ghost button transparent until hover.
+ * @property .btn-icon Square icon action button.
+ * @property .btn-group Segmented inline button group with shared borders.
+ * @property .loader Rotating circular spinner with accent glow.
+ */
+
 /* =========================== */
 /* BUTTONS                     */
 /* =========================== */
 
+/* Keycaps */
+kbd {
+  background-color: var(--color-surface);
+  border: none;
+  border-radius: 15%;
+  box-shadow: var(--shadow-raised);
+  padding: var(--space-d4) var(--space-d4);
+  font-family: var(--font-monospace);
+  font-size: var(--size-2xs);
+  color: var(--color-foreground);
+  pointer-events: none;
+}
+
 .loader {
   width: var(--size-lg);
   height: var(--size-lg);
@@ -33,19 +65,6 @@
   }
 }
 
-kbd {
-  background-color: var(--color-surface);
-  background-image: var(--effect-grain);
-  border: none;
-  border-radius: var(--radius);
-  /* Button-like raised effect */
-  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;
-}
-
 $types: "secondary", "outline", "destructive", "ghost", "icon";
 
 :where(button),
@@ -339,6 +358,17 @@ a.badge.secondary:hover,
   }
 }
 
+/**
+ * @name Alert Banners
+ * @group components-feedback
+ * @description Contextual feedback notifications with status colors and left accent borders.
+ *
+ * @property .alert Container banner using interface typography and status tinting.
+ * @property .alert.success Success alert themed with green status color.
+ * @property .alert.warning Warning alert themed with orange status color.
+ * @property .alert.error Error alert themed with red status color.
+ * @property .alert.info Informational alert themed with blue status color.
+ */
 .alert {
   font-family: var(--font-interface);
   --color-alert: var(--color-accent);
@@ -408,6 +438,13 @@ a.badge.secondary:hover,
  * - Dark mode shadow adjustments for better depth perception
  * - Optional card image hero with object-fit controls
  *
+ * @property .card Structured container with surface elevation, hairline borders, and rhythm padding.
+ * @property .card-header Header area for card title and metadata.
+ * @property .card-body Main content body with automatic vertical rhythm.
+ * @property .card-footer Bottom action bar for links and buttons.
+ * @property .card.clickable Interactive clickable card variant with hover lift.
+ * @property .card-grid Responsive grid container specifically designed for card multiples.
+ *
  * @see {class} .grid - Often used to layout multiple cards in columns
  * @see {variable} --base - Controls internal spacing rhythm
  * @see {class} .prose - Can be used inside card-body for rich content
@@ -496,9 +533,6 @@ a.badge.secondary:hover,
   background-color: var(--color-surface);
   transition: all var(--transition);
   border-radius: var(--radius);
-  /* --border currently resolves to `none` everywhere in this file
-     (card, card header/footer, .comment, .comment-content) — see the
-     AUDIT FLAG in _standard-02-color.scss. */
   border: var(--border);
 
   &.hero {
@@ -599,6 +633,16 @@ card.inset {
   box-shadow: inset var(--shadow) !important;
 }
 
+/**
+ * @name Callout Blocks
+ * @group components-layout
+ * @description Obsidian-style callout boxes with icons, titles, and collapsible folding.
+ *
+ * @property .callout Container callout card with raised shadow and ring border.
+ * @property .callout-title Header title for callout.
+ * @property .callout-content Body content within callout.
+ * @property details.callout Collapsible fold callout using native HTML details.
+ */
 .callout {
   /* Raised effect for callout cards */
   box-shadow: var(--shadow-raised), var(--shadow-ring);
@@ -799,7 +843,7 @@ details .callout-fold {
 }
 
 // Caption Callout (after an image)
-p:has(img) + .callout[data-callout="caption" i] {
+.callout[data-callout="caption"] {
   padding: 0;
   background: none;
   padding-block-start: var(--gap);
@@ -815,10 +859,10 @@ p:has(img) + .callout[data-callout="caption" i] {
     padding: 0;
     background: none;
     color: var(--color-muted);
-    border: none;
+    border: none !important;
 
     box-shadow: none;
-    text-align: center;
+    text-align: center !important;
     text-wrap: balance;
   }
 }
@@ -847,8 +891,14 @@ details .callout-fold {
 
 /**
  * @name Comments
- * @group comments
+ * @group components
  * @since 0.11.0
+ * @description Threaded discussion list with author names, timestamps, and quotes.
+ *
+ * @property #comments Root comments container.
+ * @property .comment Single comment card with surface background and elevation.
+ * @property .comment-header Author, date, and status metadata bar.
+ * @property .comment-content Indented comment message body.
  */
 
 #comments {
@@ -910,6 +960,8 @@ details .callout-fold {
  *
  * Actions within alerts (links, buttons) should be visually distinct but not
  * overwhelming. This provides subtle styling that inherits the alert's color.
+ *
+ * @property .alert-action Inline action link within an alert, inheriting `--color-alert`.
  */
 /* Fixed 2026-07-14 — was an undefined token (--alert-border-color),
    corrected to the real --color-alert, matching the docblock's stated

package/_standard-14-analog.scss

@@ -1,5 +1,24 @@
 @use "standard-00-variables" as *;
 
+/**
+ * @component Analog
+ * @category Effects
+ * @description The "analog atmosphere" layer: a fixed, full-viewport grain
+ * texture painted over every page with zero markup (`html::after`), plus a
+ * subtle ink-bleed text-shadow for text inside `.prose`/`.ink`/`.note`
+ * containers. Grain intensity and blend mode swap automatically in dark
+ * mode.
+ *
+ * @property .grain Applies grain overlay to a specific subtree container.
+ * @property --effect-grain Coarse noise texture SVG filter data URI used by page-wide overlay.
+ * @property --effect-noise Fine noise texture SVG filter data URI for high-density grain.
+ * @property --effect-opacity Overlay opacity (0.15 in light mode, 0.05 in dark mode).
+ * @property --effect-blend-mode Overlay blend mode (`multiply` in light mode, `screen` in dark).
+ * @property --effect-ink Subtle ink-bleed text-shadow applied to typography.
+ * @property .ink Container applying organic ink-bleed text-shadows to descendants.
+ * @property .note Note container applying ink-bleed text-shadows to content.
+ */
+
 #{$stnd-theme-scope} {
   /*
       This data URI is an SVG with a <feTurbulence> filter.
@@ -27,7 +46,7 @@
 
 #{$stnd-theme-scope}[data-color-mode="dark"] {
   --effect-blend-mode: screen;
-  --effect-opacity: 0.05;
+  --effect-opacity: 0.025;
 }
 
 /* 1. Global Atmosphere (The Desk) */

package/_standard-30-contrast.scss

@@ -1,5 +1,19 @@
 @use "standard-00-variables" as *;
 
+/**
+ * @component Accessibility Preferences
+ * @category Effects
+ * @description Responds to OS-level accessibility preferences with zero
+ * markup or opt-in classes: `prefers-contrast: high/more` slams every color
+ * token to pure black/white and hides the decorative grain texture;
+ * `prefers-reduced-motion: reduce` (also `update: slow` / `monochrome`,
+ * @property --color-surface Surface token forced to match background in high-contrast mode.
+ * @property --color-border Border token forced to pure foreground color.
+ * @property --color-muted Muted text token forced to pure foreground color.
+ * @property --shadow Shadow elevation disabled (`0`) to eliminate low-contrast blur.
+ * @property --transition Transition duration forced to `0s` under reduced-motion preferences.
+ */
+
 /* ===== ACCESSIBILITY SUPPORT ===== */
 /* High contrast mode support */
 @media (prefers-contrast: high), (prefers-contrast: more) {
@@ -29,8 +43,6 @@
 @media (prefers-reduced-motion: reduce), (update: slow), (monochrome) {
   #{$stnd-theme-scope} {
     --transition: 0s;
-    --toast-progress-duration: 0.5s;
-    --toast-progress-easing: linear;
   }
 
   *,
@@ -40,14 +52,4 @@
     animation: none !important;
     scroll-behavior: auto !important;
   }
-
-  /* Deliberate exception to the blanket transition:none above (wins via
-     higher specificity — .toast-progress beats the universal *). A toast's
-     countdown bar is functional motion (communicates time remaining), not
-     decorative, so it's exempted rather than disabled — just slowed to a
-     flat --toast-progress-duration instead of stopped outright. */
-  .toast-progress {
-    transition: width var(--toast-progress-duration)
-      var(--toast-progress-easing) !important;
-  }
 }

package/_standard-31-print.scss

@@ -1,5 +1,24 @@
 @use "standard-00-variables" as *;
 
+/**
+ * @component Print
+ * @category Effects
+ * @description The `@media print` stylesheet: forces black-on-white tokens,
+ * shrinks type and tightens spacing for paper, hides site chrome
+ * (`header`/`footer`/`nav`/`aside`) and the analog grain overlay, strips
+ * decorative shadows, expands external links into visible URL text, and
+ * adds page-break protection plus `@page` margins with a page counter.
+ *
+ * @property .no-print Hides the element and all its descendants only when printing.
+ * @property --color-foreground Forced to pure black for high print legibility.
+ * @property --color-background Forced to pure white for paper ink conservation.
+ * @property --font-size Adjusted root font size for printed text (`0.925rem`).
+ * @property --line-height Tightened line height for print reading (`1.4`).
+ *
+ * @example html - Hide something from the printed page
+ * <button class="no-print">Share</button>
+ */
+
 @media print {
   #{$stnd-theme-scope} {
     --color-foreground: black;

package/_standard-32-eink.scss

@@ -2,6 +2,21 @@
    other file in the package. */
 @use "standard-00-variables" as *;
 
+/**
+ * @component E-ink
+ * @category Effects
+ * @description The e-ink / monochrome-display layer (`update: slow` or
+ * `monochrome`): forces absolute black-and-white, removes all motion,
+ * shadows, filters and text-shadows, replaces shadows with hard 2px black
+ * borders, thickens headings to weight 900, and dithers images to
+ * high-contrast grayscale. Zero markup or opt-in classes required.
+ *
+ * @property --color-accent Forced to black — no chromatic accents on black-and-white screens.
+ * @property --color-foreground Forced to pure black.
+ * @property --color-background Forced to pure white.
+ * @property --color-border Forced to solid black, replacing fuzzy shadows with sharp contrast.
+ */
+
 @media screen and (update: slow), (monochrome) {
   #{$stnd-theme-scope} {
     /* Force absolute contrast */

package/_standard-50-utilities.scss

@@ -3,8 +3,19 @@
 /**
  * @component Utility Classes
  * @category Utilities
- * @description Hybrid utility system supporting both Industrial T-shirt sizes
- * and Mathematical units (1-12).
+ * @description Hybrid utility system supporting both Industrial T-shirt sizes (3xs..6xl)
+ * and Mathematical rhythm units (1-12, half, trim, leading).
+ *
+ * @property .p-*, .pt-*, .pb-*, .pl-*, .pr-*, .px-*, .py-* Padding scale utilities.
+ * @property .m-*, .mt-*, .mb-*, .ml-*, .mr-*, .mx-*, .my-* Margin scale utilities.
+ * @property .gap-*, .gap-x-*, .gap-y-* Grid and flex gap utilities.
+ * @property .w-*, .h-*, .max-w-*, .min-w-*, .max-h-*, .min-h-* Sizing scale utilities.
+ * @property .text-muted, .text-subtle, .text-accent Foreground text color utilities.
+ * @property .bg-surface, .bg-background Background color utilities.
+ * @property .border, .border-accent, .border-transparent Border stroke utilities.
+ * @property .rounded, .rounded-sm, .rounded-lg, .rounded-full Border radius utilities.
+ * @property .shadow, .shadow-sm, .shadow-md, .shadow-lg, .shadow-xl Elevation shadow utilities.
+ * @property .flex, .inline-flex, .grid, .inline-grid, .block, .inline-block, .hidden Layout display utilities.
  */
 
 /* ============================================================ */
@@ -120,15 +131,15 @@
 }
 
 .max-w-small {
-  max-width: var(--small) !important;
+  max-width: var(--line-width-sm) !important;
 }
 
 .max-w-large {
-  max-width: var(--large) !important;
+  max-width: var(--line-width-lg) !important;
 }
 
-.max-w-wide {
-  max-width: var(--wide) !important;
+.max-w-medium {
+  max-width: var(--line-width-md) !important;
 }
 
 .max-w-line {
@@ -423,6 +434,11 @@
   font-weight: var(--font-weight-bold) !important;
 }
 
+
+.font-header {
+  font-family: var(--font-header) !important;
+}
+
 .font-normal {
   font-weight: var(--font-weight) !important;
 }
@@ -798,9 +814,6 @@
   border: 0 !important;
 }
 
-/* --border currently resolves to `none` — see the AUDIT FLAG in
-   _standard-02-color.scss. Affects .border/.border-accent/.border-t/-b/
-   -l/-r below too. */
 .border {
   border: var(--border) !important;
 }
@@ -918,8 +931,6 @@
   page-break-inside: avoid;
 }
 
-/* --border currently resolves to `none` — see the AUDIT FLAG in
-   _standard-02-color.scss. */
 .columns-rule {
   column-rule: var(--border);
 }

package/_standard-99-debug.scss

@@ -9,13 +9,16 @@
  * baseline rhythm, reading layout zones, and other layout metrics. Essential for
  * design system development and layout debugging. Automatically hidden in print.
  *
- * @prop {class} .stnd-debug Enable debug visualization
- * @prop {overlay} baseline-grid Horizontal baseline grid overlay
- * @prop {overlay} grid-columns Vertical grid column overlay
- * @prop {overlay} reading-zones Reading layout zone visualization
- * @prop {overlay} rhythm-spacing Margin/spacing outline visualization
- * @prop {indicator} breakpoint-indicator Current responsive breakpoint
- * @prop {indicator} debug-panel Fixed info panel with metrics
+ * @property .stnd-debug Enable debug visualization overlays on the page or container.
+ * @property .debug-baseline-grid Horizontal baseline rhythm grid overlay.
+ * @property .debug-grid-columns Vertical grid column guidelines overlay.
+ * @property .debug-reading-zones Reading layout column boundary highlights.
+ * @property .debug-rhythm-spacing Margin and padding bounding box visualizer.
+ * @property .debug-breakpoint-indicator Viewport responsive breakpoint tag indicator.
+ * @property .debug-panel Fixed status panel reporting active layout metrics.
+ * @property --stnd-lab-bg Debug HUD background color.
+ * @property --stnd-lab-text Debug HUD text color.
+ * @property --stnd-lab-accent Debug HUD accent highlight color.
  *
  * @example
  * // Enable debug mode on page

package/obsidian.scss

@@ -3,7 +3,7 @@
  *
  * This entry point is specifically for the Obsidian plugin.
  * It ONLY includes the core CSS variables (tokens, colors) scoped to
- * body.stnd-theme (not :root — Obsidian's window is shared with other
+ * body.stnd-adapter (not :root — Obsidian's window is shared with other
  * themes/plugins, so tokens are namespaced rather than declared globally),
  * without including any of the global element resets (*, html, body)
  * or layout/typography element selectors that would destroy Obsidian's UI.
@@ -13,7 +13,7 @@
  */
 
 @use "standard-00-variables" as * with (
-  $stnd-theme-scope: "body.stnd-theme"
+  $stnd-theme-scope: "body.stnd-adapter"
 );
 @use "standard-01-token";
 @use "standard-02-color";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stnd/styles",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "type": "module",
   "author": "Francis Fontaine",
   "license": "MIT",
@@ -34,9 +34,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "wrangler": "^4.105.0"
-  },
   "devDependencies": {
     "sass": "^1.70.0"
   },

package/standard.scss

@@ -1,9 +1,8 @@
 /*!
- * Standard Design — Fine-Art Typography Framework
- *
- * Classical design principles, mathematical precision with the golden ratio,
- * and micro-typography rules inspired by the masters of print design.
- * Built to be themable. Zero runtime dependencies.
+ * @component Introduction
+ * @category Overview
+ * @description Fine-art typography framework combining classical European design principles,
+ * mathematical precision with the golden ratio, and modern relative-color syntax.
  *
  * Based on research from:
  * - The Elements of Typographic Style (Robert Bringhurst)
@@ -14,6 +13,13 @@
  *
  * Philosophy: Respect classic typography rules, but readability always wins.
  *
+ * @property Foundation Layer Reset, variables, design tokens, OKLCH color engine, and typography system.
+ * @property Layout Layer 12-column Swiss grid, vertical rhythm engine, and fluid prose layouts.
+ * @property Elements Layer Base document root, responsive media/lightbox, styled lists, tables, forms, and syntax highlighting.
+ * @property Components Layer Button hierarchy, elevated cards, callouts, alerts, and analog atmospheric grain.
+ * @property Modes Layer High contrast accessibility, print stylesheets, and e-ink display adaptation.
+ * @property Utilities Layer T-shirt and mathematical scale utilities, and layout debugging overlays.
+ *
  * @version @VERSION_PLACEHOLDER@
  * @license MIT
  * @package @stnd/styles