Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/apursley2012/sys-core/llms.txt

Use this file to discover all available pages before exploring further.

The Starfield component renders a full-viewport animated starfield that sits behind every page in sys-core. It generates 500 individual star positions at mount time and distributes them across three independent CSS animation layers, producing a convincing sense of depth as each layer scrolls and drifts at a different speed. Because every star is a single CSS box-shadow value rather than an individual DOM node, the entire effect runs entirely on the GPU compositor thread with no layout cost.

​
Visual Role

The starfield establishes the foundational space environment for the entire site. Three distinct layers animate using the starfield-layer-1, starfield-layer-2, and starfield-layer-3 Tailwind/CSS keyframe classes, each running at a different scroll speed to simulate parallax depth — distant stars move slowly, nearby stars drift faster. All stars use the color rgba(224, 231, 255, ...) — an indigo-white — with randomised opacity between 0.2 and 1.0 to mimic the natural brightness variation of a real star field. A small random spread radius per layer adds a soft glow to brighter stars. The component is fixed to the viewport (fixed inset-0) and sits at z-index: -2, below the NebulaBackground layer (z-index: -1) and all page content, ensuring it is never interactive and never obscures anything.

​
Usage

Place <Starfield /> once at the application root, outside any scrollable container, so the fixed-position layers cover every page without re-mounting during navigation. 
// app/App.jsx (or the root layout component)
import Starfield from "../../components/cosmic/Starfield.js";
import NebulaBackground from "../../components/cosmic/NebulaBackground.js";

export default function App() {
  return (
    <>
      {/* Cosmic background stack — rendered once for the whole app */}
      <Starfield />
      <NebulaBackground />

      {/* Page content sits above both background layers */}
      <main>
        {/* ... */}
      </main>
    </>
  );
}

​
Props

Starfield is a zero-configuration component — it accepts no props. All star counts, sizes, speeds, and colors are defined internally. Drop it in once and the starfield takes care of itself.
Because Starfield is fixed-position and pointer-events are disabled (pointer-events-none), it never intercepts clicks, scrolls, or keyboard events. It is completely transparent to all user interactions.

​
Implementation Notes

​
Star generation with useMemo

Stars are generated by a helper that loops count times and builds a single comma-separated CSS box-shadow string. Each shadow entry is a pixel offset from a 2000 × 2000 grid: 
// Simplified version of the internal star generator
const generateStars = (count, spreadRadius) => {
  let value = "";
  for (let i = 0; i < count; i++) {
    const x = Math.floor(Math.random() * 2000); // px from left
    const y = Math.floor(Math.random() * 2000); // px from top
    const blur  = Math.random() * spreadRadius; // 0 → spreadRadius
    const alpha = Math.random() * 0.8 + 0.2;   // 0.2 → 1.0
    value += `${x}px ${y}px 0 ${blur}px rgba(224, 231, 255, ${alpha})`;
    if (i < count - 1) value += ", ";
  }
  return value;
};
Each layer’s shadow string is wrapped in React.useMemo(() => generateStars(...), []), so stars are positioned only once at initial render and never recalculated on re-renders.

​
Three-layer star counts and sizes

Layer CSS classStar countSpread radiusVisual role
starfield-layer-13001 pxDistant background stars
starfield-layer-21501.5 pxMid-distance stars
starfield-layer-3502 pxNearby, brighter stars

​
Seamless tiling

Each layer is rendered twice — one <div> at top: 0 and an identical twin at top: 2000px. As the CSS animation scrolls the first copy off the top of the screen, the duplicate below slides into view without any visible seam, creating an infinite scrolling starfield.

​
box-shadow as a rendering strategy

Each star is not a DOM element. The 2 × 2 px <div> acts as a template; the actual star pixels are painted purely through box-shadow. This reduces the DOM to 6 elements (3 layers × 2 copies) regardless of star count, keeping layout and paint cost negligible even at 500 stars.
If you extend the site with additional pages that significantly increase document height, increase the top: 2000px offset on the duplicate layers and the 2000 grid bound in the generator to match your tallest page height. Otherwise the tiling seam may become visible on very tall pages.

Build docs developers (and LLMs) love

Get started for freeTalk to us