@cawalch/porchlight 0.1.0

package/src/06-components/avatar.css

@@ -0,0 +1,112 @@
+/*
+ * Porchlight  -  avatar component
+ * ===========================================================================
+ * A user identity chip  -  initials in a colored circle, or an image. Used in
+ * headers, lists, comments, and mentions. Three sizes via [data-size]:
+ * "sm" (1.5rem), default (2.5rem), "lg" (3rem).
+ *
+ * When no image is provided, initials render on a deterministic accent
+ * background derived from the name. The app sets the initials; the framework
+ * styles the circle. For an image, use <img class="c-avatar__img"> inside.
+ *
+ * Group stacking: .c-avatar-group overlaps multiple avatars with a negative
+ * margin and a ring for separation.
+ */
+@layer porchlight.components {
+  @scope (.c-avatar) {
+    :scope {
+      --c-avatar-size: 2.5rem;
+
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      flex-shrink: 0;
+      inline-size: var(--c-avatar-size);
+      block-size: var(--c-avatar-size);
+      border-radius: var(--pl-radius-pill);
+      background: var(--pl-color-accent);
+      color: var(--pl-color-accent-text);
+      font-size: calc(var(--c-avatar-size) * 0.4);
+      font-weight: var(--pl-font-weight-semibold);
+      line-height: 1;
+      overflow: hidden;
+      user-select: none;
+    }
+
+    :scope[data-size="sm"] {
+      --c-avatar-size: 1.5rem;
+
+      font-size: var(--pl-text-xs);
+    }
+
+    :scope[data-size="lg"] {
+      --c-avatar-size: 3rem;
+
+      font-size: var(--pl-text-lg);
+    }
+
+    .c-avatar__img {
+      inline-size: 100%;
+      block-size: 100%;
+      object-fit: cover;
+    }
+  }
+
+  /* Avatar group  -  overlapping stack. */
+  :where(.c-avatar-group) {
+    --c-avatar-group-size: 2.5rem;
+
+    display: inline-flex;
+    align-items: center;
+  }
+
+  :where(.c-avatar-group[data-size="sm"]) {
+    --c-avatar-group-size: 1.5rem;
+  }
+
+  :where(.c-avatar-group[data-size="lg"]) {
+    --c-avatar-group-size: 3rem;
+  }
+
+  :where(.c-avatar-group) .c-avatar {
+    --c-avatar-size: var(--c-avatar-group-size);
+
+    border: 2px solid var(--pl-color-surface);
+    margin-inline-start: calc(var(--c-avatar-group-size) * -0.35);
+  }
+
+  :where(.c-avatar-group) .c-avatar:first-child {
+    margin-inline-start: 0;
+  }
+
+  /* A count overflow chip at the end of a group. */
+  :where(.c-avatar-group__more) {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--c-avatar-group-size, 2.5rem);
+    block-size: var(--c-avatar-group-size, 2.5rem);
+    border-radius: var(--pl-radius-pill);
+    border: 2px solid var(--pl-color-surface);
+    background: var(--pl-color-surface-2);
+    color: var(--pl-color-text-muted);
+    font-size: calc(var(--c-avatar-group-size, 2.5rem) * 0.4);
+    font-weight: var(--pl-font-weight-semibold);
+    margin-inline-start: calc(var(--c-avatar-group-size, 2.5rem) * -0.35);
+  }
+
+  :where(.c-avatar-group[data-size="sm"]) .c-avatar-group__more {
+    font-size: var(--pl-text-xs);
+  }
+
+  :where(.c-avatar-group[data-size="lg"]) .c-avatar-group__more {
+    font-size: var(--pl-text-lg);
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-avatar) {
+      background: Highlight;
+      color: HighlightText;
+    }
+  }
+}

package/src/06-components/badge.css

@@ -0,0 +1,73 @@
+/*
+ * Porchlight  -  badge component
+ * ===========================================================================
+ * A compact label for statuses, counts, and tags. Inline-flex pill; tones via
+ * [data-tone]. Tones consume the semantic -bg/-text pairs (success/warning/
+ * danger) that were already made WCAG-AA, plus an accent and a neutral default.
+ *
+ * Density is fixed (badges shouldn't scale with [data-density]  -  they label,
+ * not actuate). Contrast is guaranteed by the token pairs, so the affordance
+ * check is covered by contrast.spec.ts; this adds a badge-specific check that
+ * each tone's label clears AA against its own bg.
+ */
+@layer porchlight.components {
+  @scope (.c-badge) {
+    :scope {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--pl-space-1);
+      min-block-size: var(--pl-space-6);
+      padding-inline: var(--pl-space-2);
+      border-radius: var(--pl-radius-pill);
+
+      /* Pill radius with a dot often looks better than 999rem for small
+         labels; pill is the framework's "fully rounded" token. */
+      font-size: var(--pl-text-xs);
+      font-weight: var(--pl-font-weight-semibold);
+      line-height: 1;
+
+      /* Optical alignment so the label sits centered without inline overshoot. */
+      text-wrap: nowrap;
+      background: var(--pl-color-surface-2);
+      color: var(--pl-color-text);
+    }
+
+    /* Accent  -  for primary/brand counts (unread, new). */
+    :scope[data-tone="accent"] {
+      background: var(--pl-color-accent);
+      color: var(--pl-color-accent-text);
+    }
+
+    /* Status tones  -  consume the WCAG-AA -bg/-text pairs. */
+    :scope[data-tone="success"] {
+      background: var(--pl-color-success-bg);
+      color: var(--pl-color-success-text);
+    }
+
+    :scope[data-tone="warning"] {
+      background: var(--pl-color-warning-bg);
+      color: var(--pl-color-warning-text);
+    }
+
+    :scope[data-tone="danger"] {
+      background: var(--pl-color-danger-bg);
+      color: var(--pl-color-danger-text);
+    }
+
+    /* Optional leading dot  -  a status indicator pip. */
+    .c-badge__dot {
+      inline-size: 0.375rem;
+      block-size: 0.375rem;
+      border-radius: var(--pl-radius-pill);
+      background: currentColor;
+      opacity: 0.9;
+    }
+
+    /* Forced colors: fall back to the system highlight so the tone still reads. */
+    @media (forced-colors: active) {
+      :scope {
+        border: 1px solid ButtonBorder;
+      }
+    }
+  }
+}

package/src/06-components/breadcrumb.css

@@ -0,0 +1,111 @@
+/*
+ * Porchlight  -  breadcrumb component
+ * ===========================================================================
+ * A trail of navigation links showing the user's location in the site/app
+ * hierarchy. The last item has aria-current="page" and is not a link.
+ *
+ * Separators are drawn via CSS (no extra DOM elements). Uses gap decorations
+ * where supported (@supports-gated), falls back to ::after on each item.
+ *
+ * Structure:
+ *   <nav class="c-breadcrumb" aria-label="Breadcrumb">
+ *     <ol class="c-breadcrumb__list">
+ *       <li class="c-breadcrumb__item">
+ *         <a class="c-breadcrumb__link" href="/">Home</a>
+ *       </li>
+ *       <li class="c-breadcrumb__item">
+ *         <a class="c-breadcrumb__link" href="/projects">Projects</a>
+ *       </li>
+ *       <li class="c-breadcrumb__item">
+ *         <span class="c-breadcrumb__current" aria-current="page">API Redesign</span>
+ *       </li>
+ *     </ol>
+ *   </nav>
+ */
+@layer porchlight.components {
+  @scope (.c-breadcrumb) {
+    .c-breadcrumb__list {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: var(--pl-space-1);
+      margin: 0;
+      padding: 0;
+      list-style: none;
+    }
+
+    .c-breadcrumb__item {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--pl-space-1);
+    }
+
+    /* Fallback separator: ::after on each item except the last.
+       Hidden where gap decorations are supported (replaced by rule). */
+    .c-breadcrumb__item:not(:last-child)::after {
+      content: "/";
+      color: var(--pl-color-text-muted);
+      font-size: var(--pl-text-sm);
+      opacity: 0.6;
+      margin-inline-start: var(--pl-space-1);
+    }
+
+    .c-breadcrumb__link {
+      color: var(--pl-color-text-muted);
+      font-size: var(--pl-text-sm);
+      text-decoration: none;
+      transition: color var(--pl-duration-1) var(--pl-ease-standard);
+    }
+
+    .c-breadcrumb__link:hover {
+      color: var(--pl-color-accent);
+      text-decoration: underline;
+    }
+
+    .c-breadcrumb__link:focus-visible {
+      outline: var(--pl-focus-size) solid var(--pl-focus-color);
+      outline-offset: var(--pl-focus-offset);
+      border-radius: var(--pl-radius-sm);
+    }
+
+    .c-breadcrumb__current {
+      color: var(--pl-color-text);
+      font-size: var(--pl-text-sm);
+      font-weight: var(--pl-font-weight-medium);
+    }
+
+    /* Long trail truncation: collapse middle items with ellipsis. */
+    .c-breadcrumb__item[data-truncate]
+      :is(.c-breadcrumb__link, .c-breadcrumb__current) {
+      display: inline-block;
+      max-inline-size: 8rem;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      vertical-align: bottom;
+    }
+  }
+
+  /* Gap decorations separator (progressive enhancement). */
+  @supports (rule: 1px solid CanvasText) {
+    :where(.c-breadcrumb__list) {
+      rule: 0 auto var(--pl-color-border);
+      rule-visibility-items: between;
+    }
+
+    /* Hide the fallback ::after separator where gap decorations work. */
+    :where(.c-breadcrumb__item:not(:last-child))::after {
+      content: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-breadcrumb__link) {
+      color: LinkText;
+    }
+
+    :where(.c-breadcrumb__current) {
+      color: CanvasText;
+    }
+  }
+}

package/src/06-components/button.css

@@ -0,0 +1,180 @@
+/*
+ * Porchlight  -  button component
+ * ===========================================================================
+ * The canonical action control. Native <button> (or <a> when it is genuinely
+ * navigation). Token-driven via component-local --c-button-* aliases that
+ * default to framework semantic tokens, so an app can theme one button or all
+ * of them without leaving the component.
+ *
+ * Variants: [data-variant="primary" | "secondary" | "ghost"] (default = none,
+ * white surface with border). States: hover, active, aria-pressed, disabled / aria-disabled,
+ * focus-visible (inherited outline from base, never removed). Density comes
+ * for free from --pl-control-* (set [data-density] on an ancestor).
+ *
+ * Modern polish: color-mix() hover derives a theme-aware shade from the
+ * button's own bg + the text color; a subtle inset top-highlight on filled
+ * variants gives depth without a heavy shadow; transform active gives tactile
+ * feedback. All motion respects --pl-motion-scale (zeroed under reduced
+ * motion). text-box optical alignment is gated behind @supports.
+ */
+@layer porchlight.components {
+  @scope (.c-button) {
+    :scope {
+      --c-button-bg: var(--pl-color-surface);
+      --c-button-fg: var(--pl-color-text);
+      --c-button-border: var(--pl-color-border);
+      --c-button-highlight: transparent;
+
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      gap: var(--pl-control-gap);
+      min-block-size: var(--pl-control-block-size);
+      min-inline-size: var(--pl-control-block-size);
+      padding-inline: var(--pl-control-padding-inline);
+      border: var(--pl-control-border-width) solid var(--c-button-border);
+      border-radius: var(--pl-control-radius);
+      background: var(--c-button-bg);
+      color: var(--c-button-fg);
+      font-family: inherit;
+      font-weight: var(--pl-font-weight-semibold);
+      line-height: 1;
+      text-align: center;
+      text-decoration: none;
+      white-space: nowrap;
+      cursor: default;
+      user-select: none;
+
+      /* Inset top catch gives filled controls a subtle lift; transparent by
+         default so outlined/ghost variants stay flat. */
+      box-shadow: inset 0 1px 0 var(--c-button-highlight);
+      transition:
+        background-color var(--pl-duration-1) var(--pl-ease-standard),
+        border-color var(--pl-duration-1) var(--pl-ease-standard),
+        color var(--pl-duration-1) var(--pl-ease-standard),
+        transform var(--pl-duration-1) var(--pl-ease-spring),
+        box-shadow var(--pl-duration-1) var(--pl-ease-standard);
+    }
+
+    /* Primary  -  the accent fill. Carries accent-text for WCAG-AA contrast. */
+    :scope[data-variant="primary"] {
+      --c-button-bg: var(--pl-color-accent);
+      --c-button-fg: var(--pl-color-accent-text);
+      --c-button-border: var(--pl-color-accent);
+      --c-button-highlight: oklch(100% 0 0deg / 14%);
+    }
+
+    /* Secondary  -  a raised surface (surface-2) with a border. */
+    :scope[data-variant="secondary"] {
+      --c-button-bg: var(--pl-color-surface-2);
+    }
+
+    /* Ghost  -  transparent; for low-emphasis actions in dense toolbars. */
+    :scope[data-variant="ghost"] {
+      --c-button-bg: transparent;
+      --c-button-border: transparent;
+    }
+
+    /* Default (outlined) variant  -  lighter border so it doesn't read as
+       heavy as a card edge at the same visual layer. */
+    :scope:not([data-variant]) {
+      --c-button-border: color-mix(
+        in oklab,
+        var(--pl-color-border),
+        transparent 20%
+      );
+    }
+
+    /* Hover: mix a little of the text color into the current fill. Done via
+       the background-color LONGHAND, NOT by reassigning --c-button-bg  - 
+       reassigning a custom property in terms of itself is a cycle, which CSS
+       resolves to guaranteed-invalid and collapses the fill to transparent.
+       Theme-aware by construction (darkens in light, lightens in dark). */
+    :scope:is(:hover, [data-hover]):not(:disabled, [aria-disabled="true"]) {
+      background-color: color-mix(
+        in oklab,
+        var(--c-button-bg),
+        var(--pl-color-text) 12%
+      );
+      cursor: pointer;
+    }
+
+    /* Ghost has no fill to mix into (transparent)  -  mixing text into
+       transparent yields a ~7%-alpha veil that reads as "barely there".
+       Give it a real, visible accent wash instead. */
+    :scope[data-variant="ghost"]:is(:hover, [data-hover]):not(
+        :disabled,
+        [aria-disabled="true"]
+      ) {
+      background-color: color-mix(
+        in oklab,
+        var(--pl-color-accent),
+        transparent 85%
+      );
+    }
+
+    /* Active + pressed: scale dip gives tactile feedback without the
+       skeuomorphic down-push of translateY. Spring easing makes the
+       snap-back feel lively. */
+    :scope:is(:active, [aria-pressed="true"]):not(
+        :disabled,
+        [aria-disabled="true"]
+      ) {
+      transform: scale(0.97);
+    }
+
+    /* Primary focus: accent glow instead of the generic outline. */
+    :scope[data-variant="primary"]:focus-visible {
+      outline: none;
+      box-shadow:
+        var(--pl-shadow-glow),
+        inset 0 1px 0 var(--c-button-highlight);
+    }
+
+    /* A pressed ghost/secondary also gets an accent tint so the selected/
+       pressed state reads clearly (a ~12%-alpha veil is too faint  -  see the
+       affordance test). */
+    :scope:is(
+        [data-variant="ghost"],
+        [data-variant="secondary"]
+      )[aria-pressed="true"] {
+      --c-button-bg: color-mix(
+        in oklab,
+        var(--pl-color-accent),
+        transparent 82%
+      );
+
+      /* Default text (not accent) on the accent tint: accent-text on an
+         accent-hue tint can't clear AA (same hue family, low ΔL). The TINT
+         is the selection signal; the default text guarantees contrast. */
+      --c-button-fg: var(--pl-color-text);
+    }
+
+    :scope:is(:disabled, [aria-disabled="true"]) {
+      opacity: var(--pl-opacity-disabled);
+      cursor: not-allowed;
+      box-shadow: none;
+    }
+
+    /* Optical alignment: trim the cap-height half-leading so the label sits
+       visually centered without the inline-box overshoot. Progressive only. */
+    @supports (text-box: trim-both cap alphabetic) {
+      :scope {
+        text-box: trim-both cap alphabetic;
+      }
+    }
+
+    /* Forced colors (Windows High Contrast): fall back to system colors. */
+    @media (forced-colors: active) {
+      :scope {
+        border-color: ButtonBorder;
+      }
+
+      :scope[data-variant="primary"] {
+        background: Highlight;
+        color: HighlightText;
+        border-color: Highlight;
+      }
+    }
+  }
+}

package/src/06-components/card.css

@@ -0,0 +1,186 @@
+/*
+ * Porchlight  -  card component
+ * ===========================================================================
+ * A raised surface grouping related content  -  the workhorse of SaaS dashboards
+ * (KPI tiles, list items, settings sections, detail panels). Header + body
+ * slots; the header adapts to the card's OWN width via a container query (not
+ * the viewport), so a card in a narrow split pane stacks its header even on a
+ * wide screen.
+ *
+ * Elevation comes from shadow, not bg contrast  -  surface is intentionally close
+ * to bg (a ~2% step); the border + a soft shadow define the card. This is the
+ * modern approach (subtle depth over heavy fill differences).
+ *
+ * Interactive variant: add [data-interactive] (or use an <a.c-card>) to get a
+ * hover lift + focus ring  -  for clickable cards (recent items, navigation
+ * tiles). Motion respects --pl-motion-scale.
+ *
+ * Token-driven via --c-card-* aliases. Density comes from --pl-space-*.
+ */
+@layer porchlight.components {
+  @scope (.c-card) {
+    :scope {
+      --c-card-padding: var(--pl-space-5);
+      --c-card-bg: var(--pl-color-surface);
+      --c-card-border: var(--pl-color-border);
+      --c-card-shadow: var(--pl-shadow-1);
+      --c-card-radius: var(--pl-radius-2xl);
+
+      container: c-card / inline-size;
+      display: grid;
+      gap: var(--pl-space-4);
+
+      /* When cards sit in an .l-grid (equal-height rows via align-items:
+         stretch), a shorter card gets stretched to match its tallest sibling.
+         Without this, the card's grid rows absorb the extra height  - 
+         inflating the header row and pushing the title down inconsistently. */
+      align-content: start;
+      padding: var(--c-card-padding);
+      border: 1px solid var(--c-card-border);
+      border-radius: var(--c-card-radius);
+      background: var(--c-card-bg);
+      box-shadow: var(--c-card-shadow);
+    }
+
+    /* Elevated variant  -  no border; shadow-2 + top-highlight do the lifting.
+       Use when the card floats over a busy background or in a hero context. */
+    :scope[data-elevated] {
+      --c-card-border: transparent;
+      --c-card-shadow: var(--pl-shadow-2);
+    }
+
+    /* Accent variant  -  left-edge brand bar + barely-there tinted surface.
+       Use for featured KPI tiles, selected states, upgrade CTAs. */
+    :scope[data-variant="accent"] {
+      --c-card-border: color-mix(
+        in oklab,
+        var(--pl-color-accent),
+        transparent 70%
+      );
+
+      background: color-mix(
+        in oklab,
+        var(--pl-color-accent),
+        var(--pl-color-surface) 94%
+      );
+      box-shadow:
+        inset var(--pl-accent-bar-width) 0 0 var(--pl-color-accent),
+        var(--pl-shadow-1);
+    }
+
+    /* :has() semantic rings  -  automatic state rings driven by child content.
+       A card containing a danger badge or [data-status="error"] element gets a
+       danger-hued ring; no extra wrapper attribute needed. */
+    :scope:has(.c-badge[data-variant="danger"]),
+    :scope:has([data-status="error"]) {
+      --c-card-border: color-mix(
+        in oklab,
+        var(--pl-color-danger),
+        transparent 55%
+      );
+
+      box-shadow:
+        0 0 0 1px color-mix(in oklab, var(--pl-color-danger), transparent 72%),
+        var(--pl-shadow-1);
+    }
+
+    :scope:has(.c-badge[data-variant="success"]),
+    :scope:has([data-status="success"]) {
+      --c-card-border: color-mix(
+        in oklab,
+        var(--pl-color-success),
+        transparent 55%
+      );
+
+      box-shadow:
+        0 0 0 1px color-mix(in oklab, var(--pl-color-success), transparent 72%),
+        var(--pl-shadow-1);
+    }
+
+    .c-card__header {
+      display: flex;
+      align-items: start;
+      justify-content: space-between;
+      gap: var(--pl-space-3);
+    }
+
+    .c-card__title {
+      margin: 0;
+      font-size: var(--pl-text-lg);
+      font-weight: var(--pl-font-weight-bold);
+      line-height: var(--pl-leading-tight);
+      text-wrap: balance;
+    }
+
+    .c-card__body {
+      color: var(--pl-color-text-muted);
+    }
+
+    .c-card__footer {
+      display: flex;
+      align-items: center;
+      justify-content: flex-end;
+      gap: var(--pl-space-2);
+      padding-block-start: var(--pl-space-3);
+
+      /* Hairline divider  -  whitespace does most of the work; the border is
+         a hint, not a structural element. */
+      border-block-start: 1px solid color-mix(
+        in oklab,
+        var(--c-card-border),
+        transparent 45%
+      );
+    }
+
+    /* Header collapses to a stack when the CARD is narrow (container query). */
+    @container c-card (inline-size < 28rem) {
+      .c-card__header {
+        align-items: stretch;
+        flex-direction: column;
+      }
+    }
+
+    /* Interactive cards  -  asymmetric hover: the default (resting/exit) state
+       uses the fast accelerate curve so moving away feels snappy; the :hover
+       state overrides the transition with the slower decelerate curve so
+       entering feels deliberate. This is the correct split-transition trick
+       for asymmetric CSS hover without JS. */
+    :scope[data-interactive],
+    :scope[href] {
+      cursor: pointer;
+      text-decoration: none;
+      color: inherit;
+
+      /* Exit transition: fast and clean. */
+      transition:
+        transform var(--pl-duration-exit) var(--pl-ease-accelerate),
+        box-shadow var(--pl-duration-exit) var(--pl-ease-accelerate);
+    }
+
+    :scope[data-interactive]:is(:hover, [data-hover]),
+    :scope[href]:is(:hover, [data-hover]) {
+      /* Enter transition: overrides the exit on hover. */
+      transition:
+        transform var(--pl-duration-enter) var(--pl-ease-decelerate),
+        box-shadow var(--pl-duration-enter) var(--pl-ease-decelerate);
+      transform: translateY(-3px);
+      box-shadow:
+        var(--pl-shadow-2),
+        0 0 0 1px color-mix(in oklab, var(--pl-color-accent), transparent 88%);
+    }
+
+    :scope[data-interactive]:focus-visible,
+    :scope[href]:focus-visible {
+      outline: none;
+      box-shadow:
+        0 0 0 var(--pl-focus-size) var(--pl-focus-color),
+        var(--pl-shadow-2);
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-card) {
+      border-color: ButtonBorder;
+    }
+  }
+}