p5.js & shadcn Integration

p5.js & shadcn Integration

The docs site ships with two complementary rendering layers on top of Starlight:

• p5.js runs in instance mode, wrapped by the P5Sketch component. Sketches execute only on the client and are SSR-safe (no window / document access during server render). Each sketch releases resources via p.remove() on unmount.
• shadcn/ui component sources live in src/components/ui/ and share the same Tailwind v4 theme tokens as Starlight through the @theme inline bridge in src/styles/global.css.

Astro MDX hydrates interactive React components as islands. Do not pass a raw function directly to <P5Sketch> from the MDX body; wrap each sketch in a demo component (see src/components/p5/demos/) and hydrate it with a client directive.

Inline Sketch Example

The sketch below is implemented in src/components/p5/demos/ring-sketch-demo.tsx as a client component that internally calls <P5Sketch sketch={ringSketch} />. MDX imports the wrapper and renders <RingSketchDemo client:load />.

Home hero — Organic Turbulence

The site home page is fronted by a full-bleed flow-field hero driven by src/components/p5/hero-sketch.tsx. Its algorithmic philosophy is documented in src/components/p5/ORGANIC_TURBULENCE.md — layered Perlin noise, steered particles, accumulating trails, velocity-mapped color, and a slow temporal drift. The static reference below captures the aesthetic; the home page renders it live.

Authoring Notes

• The sketch prop accepts a p5 instance-mode callback (p: p5) => void. Do not call new p5() yourself — P5Sketch owns the lifecycle.
• The p5 runtime is dynamically imported on the client via import("p5"), so it never enters the server bundle.
• For full-bleed hero animations, hydrate a dedicated component with an Astro client directive; inline <P5Sketch> is intended for in-content demos wrapped in a client island.
• shadcn components read --color-* tokens mirrored from Starlight theme variables, so dark mode and theme switches apply uniformly.

shadcn/ui Dialog Demo

Open Dialog

Badge & Alert

Badge and Alert are dependency-free, shadcn-style presentational components. They render to static HTML (no client directive needed) and read Starlight theme tokens, so they adapt to light/dark mode automatically.

Use Badge for compact status, version, or lifecycle labels inline with prose:

activev0.1.0deprecated

Use Alert for callouts that need a different visual weight than Starlight’s Aside:

Adapter selected

OneBot V11 is the default and only active adapter. Switching is explicit through LINGCHUAdapter.

Combined showcase

defaultaccentoutlinedeprecatedv1.0.0

Adapter selected

OneBot V11 is the default and only active adapter. Switching is explicit through LINGCHUAdapter.

Deprecated adapters

Milky, QQ, and OneBot V12 are deprecated and fully removed. Configuring any of them exits with a clear PlatformAdapterUnknownError.

Importing in MDX

import { Badge } from "@/components/ui/badge";
import { Alert, AlertTitle, AlertDescription } from "@/components/ui/alert";

<Badge variant="accent">active</Badge>

<Alert variant="destructive">
  <AlertTitle>Deprecated adapters</AlertTitle>
  <AlertDescription>
    Milky, QQ, and OneBot V12 are deprecated and fully removed.
  </AlertDescription>
</Alert>

Badge accepts variant of default, accent, outline, or destructive. Alert accepts default, accent, or destructive, plus an optional icon prop to override the default lucide icon.