border-beam

Files (2)

• SKILL.md
• THINKING_INDICATORS.md

SKILL.md (first lines)

# Border Beam & Optical Glows Engine

The single source of truth for **multi-tiered optical glows**, **boundary edge shimmers**, **aurora halos**, and **AI reasoning indicators** across the command center and projects.

Based on Jakub Antalík's open-source `Libraries.dev` architecture, this engine decouples illumination into three distinct optical tiers to achieve Apple-grade visual depth without pixel bleeding, crude conic gradient wheels, or mobile GPU thermal throttling.

Interactive visual catalog & live studio: [`docs/development_diagrams/ui_effects_and_thinking_icons.html`](../../docs/development_diagrams/ui_effects_and_thinking_icons.html).
Dedicated AI Thinking Indicators catalog: [`THINKING_INDICATORS.md`](THINKING_INDICATORS.md).

---

## 1. The Three-Tier Optical Architecture

Standard CSS borders or single-layer `box-shadow` effects appear flat and synthetic. Authentic optical presence requires three separate hardware-composited layers:

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                      BORDER BEAM THREE-TIER HIERARCHY                       │
├─────────────────────────────────────────────────────────────────────────────┤
│ TIER 1: HAIRLINE EDGE STROKE (DOM: ::after, z-index: 2)                     │
│ • 1px razor-sharp sub-pixel stroke                                          │
│ • Cut via mask-composite: intersect, exclude (or webkit-mask-composite: xor)│
│ • Renders 9-point radial-gradient coordinates with zero corner fuzziness   │
├─────────────────────────────────────────────────────────────────────────────┤
│ TIER 2: GLOW LAYER (DOM: ::before, z-index: 1) - the code calls it "core"   │
│ • Traveling beams and pulse-inner: the INNER GLOW, inset: 0, inside the edge│
│ • pulse-outside (the halo): the OUT GLOW, inset: -14px, behind the element, │
│   past the edge and in through the glass (strength: --beam-inner-opacity)   │
│ • Say "inner glow" or "out glow" to the operator, never "core"              │
├─────────────────────────────────────────────────────────────────────────────┤
│ TIER 3: OUTER ATMOSPHERIC BLOOM (DOM: [data-beam-bloom], z-index: 0)        │
│ • Soft 28px–36px Gaussian-dispersed aurora field                            │
│ • Spills volumetric light into dark backgrounds                             │
│ • Driven by a shared ~30fps requestAnimationFrame cosine pulse loop         │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 2. Presets Decision Matrix

| Preset Code | Prop Key | Primary Target Surfaces | Optical Behavior |
|:---:|---|---|---|
| **[Bottom Rim Sweep]** *(★ Operator Favorite)* | `size="line"` / `travel="sweep"` | Chat input bars, search inputs, docked headers | Oscillating back-and-forth glide along the bottom edge with anti-phase flicker and edge fading |
| **[Perimeter Shimmer Loop]** | `size="line"` / `travel="loop"` | Interactive focal cards, modal frames, feature cards | Continuous 360° perimeter travel with slender Northern Lights curtain rays and multi-color auroral flicker |
| **[Circle Orbit]** *(★ Operator Favorite)* | `size="circle"` / `travel="orbit"` | Agent avatar halos, round CTA buttons, audio dials | Continuous 1px hairline laser beam traveling 360° around circular shapes |
| **[Edge Shimmer]** | `size="edge-shimmer"` | Docked drawer top rims, panel dividers, search inputs | Sweeps along a single horizontal border edge without enclosing the container |
| **[Halo]** | `size="pulse-outside"` | Specialist chat dialogs, hero spotlight cards | Edge ring, out glow (~14px past the edge, seen through the glass) and outer bloom (~42px) spilling onto the page |
| **[Pill]** | `size="sm"` | Action pills, launcher buttons, high-priority CTAs | Compact 1px perimeter highlight with hugging inner luminance |
| **[Inner]** | `size="pulse-inner"` | Secondary cards, inactive panels, telemetry gauges | Breaths slowly (6.0s) strictly inside container boundaries |
| **[Glass]** | `fx-smoked-glass` | Specialist chat backdrop, login gates, modals | 72% obsidian smoked glass pane over statically blurred brand emblem watermark |

### Code Recipes: Traveling Line (Loop & Ping-Pong) & Circle Orbit

```css
/* Shared Angle Property & Rotation Keyframes */
@property --beam-angle {
  syntax: '<angle>';
  initial-value: 0deg;
  inherits: false;
}
@keyframes beam-travel-rotate {
  0% { --beam-angle: 0deg; }
  100% { --beam-angle: 360deg; }
}

/* Option 1: Traveling Perimeter Line (Full 360° Loop) */
.beam-travel-line {
  position: relative;
}
.beam-travel-line::after {
  content: "";
  position: absolute;
  inset: 0;
  border-radius: inherit;
  pointer-events: none;
  padding: 1.5px;
  background: conic-gradient(
    from var(--beam-angle, 0deg) at 50% 50%,
    transparent 0deg,
    transparent 270deg,
    var(--beam-secondary, #0072ff) 305deg,
    var(--beam-primary, #00c2ff) 345deg,
    #ffffff 360deg
  );
  -webkit-mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
  -webkit-mask-composite: xor;
  mask-composite: exclude;
  animation: beam-travel-rotate var(--beam-speed, 6.0s) linear infinite;
  z-index: 2;
}

/* Option 2: Back & Forth Ping-Pong Line (Horizontal Sweep) */
.beam-pingpong-line {
  position: relative;
}
.beam-pingpong-line::after {
  content: "";
  position: absolute;
  inset: 0;
  border-radius: inherit;
  pointer-events: none;
  padding: 1.5px;
  background: radial-gradient(
    ellipse 130px 45px at var(--pingpong-x, 50%) 50%,
    #ffffff 0%,
    var(--beam-primary, #00c2ff) 30%,
    var(--beam-secondary, #0072ff) 65%,
    transparent 85%
  );
  -webkit-mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
  -webkit-mask-composite: xor;
  mask-composite: exclude;
  z-index: 2;
}

/* Full Circle Orbit Beam (Avatars, Round CTAs) */
.beam-circle-orbit {
  position: relative;

From sudomadhatter/design-engineer-skills, MIT.

More from sudomadhatter/design-engineer-skills