@cawalch/porchlight 0.1.0

package/src/03-themes.css

@@ -0,0 +1,79 @@
+/*
+ * Porchlight  -  themes
+ * ===========================================================================
+ * Theme, density, and accessibility-media overrides. These do NOT redefine the
+ * palette  -  they steer it:
+ *
+ *   - [data-theme]      sets color-scheme, which drives light-dark() in tokens.
+ *   - [data-density]    resizes controls via the control tokens.
+ *   - prefers-reduced-motion  zeroes the motion scale (and any transitions).
+ *   - forced-colors     remaps semantic tokens to Windows system colors so the
+ *                       UI stays legible under High Contrast mode.
+ *
+ * `:where()` keeps every selector at zero specificity, so an app can override
+ * any of this without a fight. The `!important` rules under reduced-motion are
+ * accessibility-critical (PLAN's allow-list): motion must stop regardless of
+ * component-level transition declarations.
+ */
+@layer porchlight.themes {
+  /* Explicit theme. Omit the attribute to inherit the system color-scheme. */
+  :where([data-theme="light"]) {
+    color-scheme: light;
+  }
+
+  :where([data-theme="dark"]) {
+    color-scheme: dark;
+  }
+
+  /* Density  -  control geometry only; spacing/type/radius are unchanged. */
+  :where([data-density="compact"]) {
+    --pl-control-block-size: 2rem;
+    --pl-control-padding-inline: var(--pl-space-3);
+    --pl-control-gap: var(--pl-space-1);
+  }
+
+  :where([data-density="comfortable"]) {
+    --pl-control-block-size: 2.5rem;
+  }
+
+  :where([data-density="touch"]) {
+    --pl-control-block-size: 2.75rem;
+    --pl-control-padding-inline: var(--pl-space-5);
+  }
+
+  /* Motion: respect the OS preference. Scale token kills framework motion;
+     the universal rule guarantees no stray transition outlasts it. */
+  @media (prefers-reduced-motion: reduce) {
+    :root {
+      --pl-motion-scale: 0;
+
+      scroll-behavior: auto;
+    }
+
+    *,
+    *::before,
+    *::after {
+      animation-duration: 1ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 1ms !important;
+    }
+  }
+
+  /* Forced colors (Windows High Contrast): remap to system colors. */
+  @media (forced-colors: active) {
+    :root {
+      --pl-color-bg: Canvas;
+      --pl-color-surface: Canvas;
+      --pl-color-surface-2: Canvas;
+      --pl-color-text: CanvasText;
+      --pl-color-text-muted: CanvasText;
+      --pl-color-border: ButtonBorder;
+      --pl-color-accent: Highlight;
+      --pl-color-accent-text: HighlightText;
+      --pl-focus-color: Highlight;
+      --pl-shadow-1: none;
+      --pl-shadow-2: none;
+      --pl-shadow-3: none;
+    }
+  }
+}

package/src/04-base.css

@@ -0,0 +1,78 @@
+/*
+ * Porchlight  -  base layer
+ * ===========================================================================
+ * Element defaults. These give bare HTML a sensible, on-token appearance so
+ * pages are usable before any component class is applied.
+ *
+ * Everything is `:where()` (zero specificity) so every rule is trivially
+ * overridable by a component or an application. Logical properties throughout.
+ * No `!important` here  -  the reset already handles the only a11y-critical case
+ * (`[hidden]`).
+ *
+ * Color and type come from the token layers; theme/density/forced-colors are
+ * handled by `03-themes`. This layer only assembles them onto elements.
+ */
+@layer porchlight.base {
+  :where(html) {
+    font-family: var(--pl-font-sans);
+    background: var(--pl-color-bg);
+    color: var(--pl-color-text);
+
+    /* Theme every native checkbox/radio/range/color/date input app-wide so the
+       brand accent is consistent without per-control styling. Inherits, so a
+       single root declaration covers the whole document. */
+    accent-color: var(--pl-color-accent);
+  }
+
+  :where(body) {
+    font-size: var(--pl-text-md);
+    line-height: var(--pl-leading-normal);
+    background: var(--pl-color-bg);
+    color: var(--pl-color-text);
+    text-rendering: optimizeLegibility;
+  }
+
+  :where(a) {
+    color: var(--pl-color-accent);
+    text-underline-offset: 0.18em;
+    text-decoration-thickness: 0.08em;
+  }
+
+  :where(a:hover) {
+    color: var(--pl-color-accent-hover);
+  }
+
+  :where(:focus-visible) {
+    outline: var(--pl-focus-size) solid var(--pl-focus-color);
+    outline-offset: var(--pl-focus-offset);
+  }
+
+  :where(h1, h2, h3, h4) {
+    line-height: var(--pl-leading-tight);
+    text-wrap: balance;
+    margin-block: 0;
+    letter-spacing: -0.02em;
+  }
+
+  :where(h1) {
+    font-weight: var(--pl-font-weight-black, 900);
+    letter-spacing: -0.03em;
+  }
+
+  :where(h2) {
+    font-weight: var(--pl-font-weight-bold, 700);
+    letter-spacing: -0.025em;
+  }
+
+  :where(p, ul, ol, dl, figure, blockquote) {
+    margin-block: 0;
+  }
+
+  :where(code, kbd, samp, pre) {
+    font-family: var(--pl-font-mono);
+  }
+
+  :where(::selection) {
+    background: color-mix(in oklab, var(--pl-color-accent), transparent 60%);
+  }
+}

package/src/05-layout.css

@@ -0,0 +1,209 @@
+/*
+ * Porchlight  -  layout primitives
+ * ===========================================================================
+ * Small, composable layout helpers for the regions AROUND components  -  not
+ * opinionated page designs. They are deliberately quiet: low specificity
+ * (:where), token-driven gaps, and local --l-* config tokens every primitive
+ * exposes for instance tuning (e.g. --l-stack-gap), each with a sensible
+ * framework default.
+ *
+ * Built for desktop SaaS / web-app surfaces: the default states assume
+ * comfortable desktop density; container queries adapt a layout to its PANEL
+ * width (a nested app region), not only to the viewport. Viewport media logic
+ * is reserved for the app shell (05 app-shell block, next PR).
+ *
+ * Naming: .l-* primitives; --l-* are instance-config tokens consumed only by
+ * the layout layer.
+ */
+@layer porchlight.layout {
+  /* Vertical flow  -  forms, settings sections, stacked panels. */
+  :where(.l-stack) {
+    display: flex;
+    flex-direction: column;
+    gap: var(--l-stack-gap, var(--pl-space-4));
+  }
+
+  /* Horizontal wrapping group  -  action bars, button rows, toolbar items. */
+  :where(.l-cluster) {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: var(--l-cluster-align, center);
+    justify-content: var(--l-cluster-justify, flex-start);
+    gap: var(--l-cluster-gap, var(--pl-space-3));
+  }
+
+  /* Auto-fitting grid  -  dashboard widgets, KPI cards, result tiles. Each
+     track is at least --l-grid-min wide (clamped to 100% so a single item
+     never overflows) and grows to fill. */
+  :where(.l-grid) {
+    display: grid;
+    gap: var(--l-grid-gap, var(--pl-space-4));
+    grid-template-columns: repeat(
+      auto-fit,
+      minmax(min(var(--l-grid-min, 16rem), 100%), 1fr)
+    );
+  }
+
+  /* Sidebar + main  -  settings/filter panels, master-detail regions. The
+     default is the desktop two-column layout. It collapses to a single
+     column when its nearest ANCESTOR query container is narrower than 48rem
+     (an element cannot query its own size). Note: .l-sidebar does NOT declare
+     container-type itself  -  that would be misleading (self-querying is
+     impossible) and adds containment side-effects. Wrap it in a
+     container-type: inline-size element, or nest it inside
+     .l-app-shell__main (which is a container) to get the collapse. */
+  :where(.l-sidebar) {
+    display: grid;
+    gap: var(--l-sidebar-gap, var(--pl-space-4));
+    grid-template-columns:
+      minmax(0, var(--l-sidebar-size, 16rem))
+      minmax(0, 1fr);
+  }
+
+  @media (width < 48rem) {
+    :where(.l-sidebar) {
+      grid-template-columns: 1fr;
+    }
+  }
+
+  @container (inline-size < 48rem) {
+    :where(.l-sidebar) {
+      grid-template-columns: 1fr;
+    }
+  }
+
+  /* Readable content column centered within a wide app surface. Default max
+     is generous (88rem) for dashboards; tighten via --l-page-max for prose. */
+  :where(.l-page) {
+    inline-size: min(100% - 2 * var(--pl-space-4), var(--l-page-max, 88rem));
+    margin-inline: auto;
+  }
+
+  /* Independent scroll region  -  data panes, log viewers, long lists. Stable
+     gutter prevents layout shift when scrollbars appear/disappear; contain
+     stops scroll chaining to the page. */
+  :where(.l-scroll-area) {
+    overflow: auto;
+    scrollbar-gutter: stable;
+    overscroll-behavior: contain;
+  }
+
+  /* --------------------------------------------------------------------- */
+
+  /* App shell  -  the one place viewport logic belongs. A desktop SaaS app
+     is typically: a sticky topbar, a persistent sidebar, and a scrolling
+     main work area. Below 60rem (a phone or a narrow split pane) the sidebar
+     drops out so the work surface stays usable.
+
+     .l-app-shell__main is a query container so any .l-sidebar nested inside
+     it collapses correctly at narrow app widths WITHOUT a manual wrapper
+     (closes the container-ancestor story from the audit fix). */
+  :where(.l-app-shell) {
+    min-block-size: 100dvb;
+    display: grid;
+    grid-template:
+      "topbar topbar" auto
+      "sidebar main" minmax(0, 1fr)
+      / auto minmax(0, 1fr);
+  }
+
+  :where(.l-app-shell__topbar) {
+    grid-area: topbar;
+    position: sticky;
+    inset-block-start: 0;
+    z-index: var(--pl-z-sticky);
+  }
+
+  /* Glass topbar  -  opt in via [data-glass]. Frosted backdrop replaces an
+     opaque fill; a hairline border-bottom anchors the bar visually. */
+  :where(.l-app-shell__topbar[data-glass]) {
+    background: color-mix(in oklab, var(--pl-color-surface), transparent 18%);
+    backdrop-filter: blur(16px) saturate(180%);
+    -webkit-backdrop-filter: blur(16px) saturate(180%);
+    border-block-end: 1px solid color-mix(
+      in oklab,
+      var(--pl-color-border),
+      transparent 50%
+    );
+  }
+
+  :where(.l-app-shell__sidebar) {
+    grid-area: sidebar;
+
+    /* Manual collapse: apps set data-sidebar="collapsed" to shrink the rail
+       to an icon strip without hiding it (PLAN only hid on narrow viewports).
+       --app-sidebar-size tunes the expanded width; --app-sidebar-collapsed
+       the icon width. */
+    inline-size: var(--app-sidebar-size, 16rem);
+    overflow-inline: clip;
+    transition: inline-size var(--pl-duration-2) var(--pl-ease-standard);
+  }
+
+  :where(.l-app-shell__sidebar[data-sidebar="collapsed"]) {
+    inline-size: var(--app-sidebar-collapsed, 3.5rem);
+  }
+
+  :where(.l-app-shell__main) {
+    grid-area: main;
+    min-inline-size: 0;
+
+    /* Main is the container .l-sidebar collapses against (see header note). */
+    container-type: inline-size;
+    overflow: auto;
+    scrollbar-gutter: stable;
+    overscroll-behavior: contain;
+  }
+
+  /* Viewport fallback: on a genuinely narrow viewport the sidebar is hidden
+     (the work surface takes priority). This is the ONLY viewport media query
+     in the layout layer  -  components adapt via container queries. */
+  @media (width < 60rem) {
+    :where(.l-app-shell) {
+      grid-template:
+        "topbar" auto
+        "main" minmax(0, 1fr)
+        / minmax(0, 1fr);
+    }
+
+    :where(.l-app-shell__sidebar) {
+      display: none;
+    }
+  }
+
+  /* --------------------------------------------------------------------- */
+
+  /* Multi-column masonry  -  card walls, search results, image grids. Uses
+     CSS multi-column layout (simpler than grid masonry and works in all
+     browsers). Items break-inside avoid so cards don't split across
+     columns. Tune column count via --l-columns-count or let it auto. */
+  :where(.l-columns) {
+    --l-columns-width: 16rem;
+
+    columns: var(--l-columns-width) var(--l-columns-count, auto);
+    column-gap: var(--l-columns-gap, var(--pl-space-4));
+  }
+
+  :where(.l-columns > *) {
+    break-inside: avoid;
+    margin-block-end: var(--l-columns-gap, var(--pl-space-4));
+  }
+
+  /* Centered max-width container  -  general-purpose wrapper for app
+     surfaces. Distinct from .l-page (which targets prose at 88rem).
+     Use for dashboards, settings, lists. */
+  :where(.l-container) {
+    inline-size: min(
+      100% - 2 * var(--l-container-pad, var(--pl-space-4)),
+      var(--l-container-max, 80rem)
+    );
+    margin-inline: auto;
+  }
+
+  /* Inset  -  constrained content inside a full-bleed parent. For captions,
+     forms, or text within a full-width hero/banner. Centers and constrains
+     without adding its own vertical rhythm. */
+  :where(.l-inset) {
+    inline-size: min(100%, var(--l-inset-max, 48rem));
+    margin-inline: auto;
+  }
+}

package/src/06-components/accordion.css

@@ -0,0 +1,161 @@
+/*
+ * Porchlight  -  accordion component
+ * ===========================================================================
+ * A collapsible disclosure built on native <details>/<summary>. Animates
+ * open/close to/from height: auto using interpolate-size: allow-keywords
+ * (declared globally in 08-enhancements). As a universal fallback, uses the
+ * grid-template-rows: 0fr -> 1fr technique which works without it.
+ *
+ * Structure:
+ *   <details class="c-accordion__item">
+ *     <summary class="c-accordion__header">
+ *       <span>Title</span>
+ *       <svg class="c-accordion__icon" ...>
+ *     </summary>
+ *     <div class="c-accordion__panel">
+ *       <div class="c-accordion__content">...</div>
+ *     </div>
+ *   </details>
+ *
+ * Wrap multiple items in .c-accordion. For single-open behavior, use
+ * [data-variant="single"] (implemented via :has()).
+ *
+ * The native <summary> marker is hidden and replaced with a custom chevron.
+ */
+@layer porchlight.components {
+  @scope (.c-accordion) {
+    :scope {
+      --c-accordion-border: var(--pl-color-border);
+      --c-accordion-bg: var(--pl-color-surface);
+      --c-accordion-radius: var(--pl-radius-xl);
+      --c-accordion-header-pad: var(--pl-space-4);
+      --c-accordion-content-pad: 0 var(--pl-space-4) var(--pl-space-4);
+      --c-accordion-gap: var(--pl-space-2);
+
+      display: flex;
+      flex-direction: column;
+      gap: var(--c-accordion-gap);
+    }
+  }
+
+  @scope (.c-accordion__item) {
+    :scope {
+      border: 1px solid var(--c-accordion-border, var(--pl-color-border));
+      border-radius: var(--c-accordion-radius, var(--pl-radius-lg));
+      background: var(--c-accordion-bg, var(--pl-color-surface));
+      overflow: hidden;
+    }
+
+    .c-accordion__header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: var(--pl-space-3);
+      padding: var(--c-accordion-header-pad, var(--pl-space-4));
+      font-weight: var(--pl-font-weight-semibold);
+      cursor: pointer;
+      list-style: none;
+      user-select: none;
+
+      /* Hide the native disclosure marker. */
+      &::-webkit-details-marker {
+        display: none;
+      }
+
+      &::marker {
+        content: "";
+      }
+    }
+
+    .c-accordion__header:hover {
+      background: var(--pl-color-surface-2);
+    }
+
+    .c-accordion__header:focus-visible {
+      outline: var(--pl-focus-size) solid var(--pl-focus-color);
+      outline-offset: calc(var(--pl-focus-offset) * -1);
+    }
+
+    .c-accordion__icon {
+      flex-shrink: 0;
+      inline-size: 1.25rem;
+      block-size: 1.25rem;
+      color: var(--pl-color-text-muted);
+      transition: rotate var(--pl-duration-2) var(--pl-ease-standard);
+    }
+
+    /* Rotate the chevron when open. */
+    :scope[open] .c-accordion__icon {
+      rotate: 180deg;
+    }
+
+    .c-accordion__panel {
+      /* Universal fallback: grid-row animation technique. Works in ALL
+         browsers (no interpolate-size needed). The wrapper collapses to
+         0fr (hidden) then expands to 1fr (visible). */
+      display: grid;
+      grid-template-rows: 0fr;
+      transition: grid-template-rows var(--pl-duration-3)
+        var(--pl-ease-standard);
+    }
+
+    :scope[open] .c-accordion__panel {
+      grid-template-rows: 1fr;
+    }
+
+    .c-accordion__content {
+      overflow: hidden;
+      padding: var(
+        --c-accordion-content-pad,
+        0 var(--pl-space-4) var(--pl-space-4)
+      );
+      color: var(--pl-color-text-muted);
+      line-height: var(--pl-leading-normal);
+    }
+
+    /* Where interpolate-size is supported: animate height: auto directly.
+       This produces smoother results than the grid technique. */
+    @supports (interpolate-size: allow-keywords) {
+      .c-accordion__panel {
+        display: block;
+        overflow: hidden;
+        grid-template-rows: initial;
+        block-size: 0;
+        transition: block-size var(--pl-duration-3) var(--pl-ease-standard);
+      }
+
+      :scope[open] .c-accordion__panel {
+        block-size: auto;
+      }
+
+      /* Starting state for the open transition. */
+      @starting-style {
+        :scope[open] .c-accordion__panel {
+          block-size: 0;
+        }
+      }
+    }
+  }
+
+  /* Single-open variant: close other items when one opens. Uses :has() to
+     detect which item is open and collapse siblings. */
+  :where(.c-accordion[data-variant="single"])
+    > .c-accordion__item:not([open]):has(~ .c-accordion__item[open]),
+  :where(.c-accordion[data-variant="single"])
+    > .c-accordion__item[open]
+    ~ .c-accordion__item:not([open]) {
+    /* These remain closed (default state). The :has() ensures only one
+       [open] item survives visually; JS should manage the actual [open]
+       attribute removal for full single-open behavior. */
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-accordion__item) {
+      border-color: ButtonBorder;
+    }
+
+    :where(.c-accordion__header:focus-visible) {
+      outline-color: Highlight;
+    }
+  }
+}

package/src/06-components/alert.css

@@ -0,0 +1,102 @@
+/*
+ * Porchlight  -  alert component
+ * ===========================================================================
+ * An inline notification  -  contextual feedback within the page flow (not an
+ * overlay like toast). Four tones via [data-tone]: info (default), success,
+ * warning, danger. Each consumes the semantic -bg/-text pairs for WCAG-AA.
+ *
+ * Structure: .c-alert > .c-alert__icon (optional) + .c-alert__title +
+ * .c-alert__body. A leading icon slot anchors the tone visually; the tone
+ * color on the icon + a tinted background carry the semantic without relying
+ * on color alone (the icon shape does the heavy lifting for colorblind users).
+ *
+ * Density-aware: [data-density] on an ancestor tightens the padding.
+ */
+@layer porchlight.components {
+  @scope (.c-alert) {
+    :scope {
+      --c-alert-tone: var(--pl-color-accent);
+      --c-alert-tone-bg: var(--pl-color-accent);
+      --c-alert-pad: var(--pl-space-4);
+      --c-alert-gap: var(--pl-space-3);
+
+      display: grid;
+      grid-template-columns: auto 1fr;
+      gap: var(--c-alert-gap);
+      padding: var(--c-alert-pad);
+      border: 1px solid var(--pl-color-border);
+      border-inline-start: var(--pl-accent-bar-width) solid var(--c-alert-tone);
+      border-radius: var(--pl-radius-xl);
+      background: color-mix(
+        in oklab,
+        var(--c-alert-tone-bg),
+        var(--pl-color-surface) 92%
+      );
+      color: var(--pl-color-text);
+    }
+
+    .c-alert__icon {
+      display: flex;
+      align-items: flex-start;
+      color: var(--c-alert-tone);
+      flex-shrink: 0;
+    }
+
+    .c-alert__icon svg {
+      inline-size: 1.25rem;
+      block-size: 1.25rem;
+    }
+
+    .c-alert__content {
+      display: flex;
+      flex-direction: column;
+      gap: var(--pl-space-1);
+      min-inline-size: 0;
+    }
+
+    .c-alert__title {
+      font-weight: var(--pl-font-weight-semibold);
+      font-size: var(--pl-text-sm);
+      color: var(--pl-color-text);
+    }
+
+    .c-alert__body {
+      font-size: var(--pl-text-sm);
+      color: var(--pl-color-text-muted);
+    }
+
+    /* Tone variants. */
+    :scope[data-tone="success"] {
+      --c-alert-tone: var(--pl-color-success);
+      --c-alert-tone-bg: var(--pl-color-success-bg);
+    }
+
+    :scope[data-tone="warning"] {
+      --c-alert-tone: var(--pl-color-warning);
+      --c-alert-tone-bg: var(--pl-color-warning-bg);
+    }
+
+    :scope[data-tone="danger"] {
+      --c-alert-tone: var(--pl-color-danger);
+      --c-alert-tone-bg: var(--pl-color-danger-bg);
+    }
+
+    /* A dismiss button in the top-right corner. */
+    .c-alert__close {
+      position: absolute;
+      inset-block-start: var(--pl-space-2);
+      inset-inline-end: var(--pl-space-2);
+    }
+  }
+
+  /* Make the alert position-relative so the close button can anchor. */
+  :where(.c-alert) {
+    position: relative;
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-alert) {
+      border-color: CanvasText;
+    }
+  }
+}