Adaptive Luminescent Border

---
name: adaptive-luminescent-border
description: >-
  Replace flat grey `1px solid #ccc` borders and dividers with ambient boundaries that respond to
  their ground — a debossed groove (dark hairline + light highlight) on paper, a 0.5px glowing semi-
  transparent fiber line on obsidian — built as a masked gradient stroke on a pseudo-element with a
  per-ground blend mode, plus fading hairline rules and gap-dividers for grids. Use this whenever
  styling card edges, panel outlines, section dividers, <hr>, table rules, grid separators, sidebar
  boundaries, glass/frosted panels, or when the user says "the borders look cheap / flat / heavy",
  "premium edges", "subtle dividers", "glowing border", "gradient border", "glassmorphism", or asks
  for a card/panel design on a dark or mixed-ground page.
---

# Adaptive Luminescent Border

A `1px solid #ccc` line is a wall: the same grey whether it sits on cream or on near-black, indifferent to the image behind it, visibly a stroke painted *on top of* the layout. The boundaries in expensive interfaces don't read as lines — they read as *edges*: a slight groove where a panel meets paper, a thin thread of light where a card lifts off a dark ground. They're made of transparency and gradient rather than opaque colour, so they pick up what's behind them and change character when the ground changes.

Two profiles, one component: on light grounds the edge is a **debossed groove** — a faint dark hairline under the bottom edge and a light line just inside the top edge, drawn with an inset/outset `box-shadow` pair (a highlight can't come from a blend mode on a light ground: `multiply` can only darken, and white on cream is invisible); on dark grounds it's a **luminous fiber** (a 0.5px semi-transparent light line with a hint of the accent hue, `plus-lighter`-blended so it glows rather than sits). The switch is automatic because both are driven by the same tokens the ground system remaps.

## The masked-stroke technique

Draw the border as a gradient on a pseudo-element, then mask away everything except a ring the width of the stroke:

```css
.luminescent-panel { position: relative; border-radius: 8px; isolation: isolate; }
.luminescent-panel::after {
  content: ""; position: absolute; inset: 0; border-radius: inherit;
  padding: var(--edge-stroke);                                 /* 1px paper, 0.5px obsidian */
  background: linear-gradient(135deg, var(--edge-hi), var(--edge-lo) 50%, var(--edge-tint));
  -webkit-mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
  -webkit-mask-composite: xor;
          mask: linear-gradient(#fff 0 0) content-box exclude, linear-gradient(#fff 0 0);
  mix-blend-mode: var(--edge-blend);                           /* normal on paper, plus-lighter on obsidian */
  pointer-events: none;
}
```

Why a gradient: a single-colour ring is a border with extra steps. The 135° pass — highlight at the top-left, hairline in the middle, accent tint at the bottom-right — is what makes the edge read as lit from a direction, and a whisper of the accent hue is what ties the card to the brand without a coloured border.

Why the blend mode is a token: `plus-lighter` adds light, which is exactly right on a dark ground and does nothing useful on cream (it washes out to invisible). On paper the stroke blends `normal` and the groove comes from `--groove` (`inset 0 1px 0 highlight, 0 1px 0 hairline`). Setting `plus-lighter` for both grounds is the most common way this technique fails — on paper the edge simply isn't there.

`assets/luminous-borders.css` has the panel, a `.luminescent-rule` horizontal divider that fades at both ends, a `.luminescent-grid` that draws dividers in the *gaps* (one background on the grid, no per-cell borders — cleaner corners, no doubled lines), both ground token sets, and a `@supports` fallback to a solid border where mask compositing is missing.

## Glass, sparingly

`backdrop-filter: blur(12px)` on a semi-opaque panel turns the border's transparency into depth — media and gradients behind the panel diffuse through it and the edge picks up their tone. It's also a full-area filter that re-renders on every scroll frame. Opt in per panel (`.is-glass`) on a hero card or a sticky header — not on every card in a grid. Under `prefers-reduced-transparency: reduce`, drop the blur and raise the panel's alpha.

## Where a plain hairline is fine

This skill is about *outlines and dividers that read as edges*: card and panel perimeters, section dividers, full-width rules. Structural separators inside a component — table rows, accordion items, list rows, a rail's underline on mobile — are rhythm, not edges; a `1px solid var(--rule)` hairline there is correct and cheaper, and `html5-native-fallback`'s accordion and the rail template use exactly that. Don't retrofit the masked stroke onto every `border-bottom`.

## Where the line stays solid

Decorative dividers can be as faint as they like. **Functional** boundaries can't: an input's edge, a button's outline, a toggle's track — anything where the border is what tells the user an element exists or is interactive — needs ≥3:1 against its surroundings (WCAG 1.4.11). Keep those on a solid `--edge-functional` token (`#8a8a86` on paper = 3.35:1, `#666a73` on obsidian = 3.61:1 — verified with `ground-inversion-guard`'s contrast script; the faint `--edge-solid` is only the decorative fallback), and use the luminous treatment for cards, panels, rules, and grid separators where the content inside carries the meaning.

## Details that make or break it

- `isolation: isolate` on the panel so the blend mode composites against the panel, not the page.
- `pointer-events: none` on the pseudo — it covers the whole panel.
- `border-radius: inherit` so the ring follows the panel's corners exactly.
- `0.5px` on dark grounds renders as a true half-pixel on 2×+ screens and rounds to 1px on 1× — both correct.
- Don't stack this with a real `border` on the same element — you'll get a double edge. The fallback swaps, it doesn't add.
- Table rules and `<hr>`: use the fading `.luminescent-rule`; a hard line from margin to margin is the wall you're replacing.

## Quick check

1. No `border: 1px solid #ccc`-style opaque greys on decorative edges.
2. Edge tokens defined for both grounds; paper uses `normal` + the `--groove` shadow pair, obsidian `plus-lighter`.
3. Masked pseudo has `inset: 0`, `border-radius: inherit`, `pointer-events: none`; host has `isolation: isolate`.
4. `@supports` fallback present.
5. `backdrop-filter` only on opted-in panels.
6. Functional boundaries (inputs, buttons) solid and ≥3:1.