p5.js 与 shadcn 集成

文档站点在 Starlight 之上挂载了两套互补的渲染层：

p5.js 采用 instance mode，由 P5Sketch 组件封装。草图仅在客户端运行，SSR 安全（服务端渲染阶段不访问 window / document），并在卸载时通过 p.remove() 释放资源。
shadcn/ui 组件源码本地化于 src/components/ui/，通过 src/styles/global.css 中的 @theme inline 桥接块与 Starlight 共享同一套 Tailwind v4 主题 token。

Astro MDX 会把交互式 React 组件作为 island 水合。不要在 MDX 主体中直接把原始 function 传给 <P5Sketch>；请把每个草图封装为一个 demo 组件（参见 src/components/p5/demos/），再在 MDX 中用 client directive 水合。

内联草图示例

下方草图实现于 src/components/p5/demos/ring-sketch-demo.tsx，是一个客户端组件，内部调用 <P5Sketch sketch={ringSketch} />。MDX 导入该包装器并以 <RingSketchDemo client:load /> 渲染。

首页 hero —— Organic Turbulence

站点首页由全屏流场 hero 驱动，实现位于 src/components/p5/hero-sketch.tsx。其算法哲学记录于 src/components/p5/ORGANIC_TURBULENCE.md —— 分层 Perlin 噪声、循场而行的粒子、累积的轨迹、速度映射的色彩与缓慢的时间漂移。下方静态参考图呈现了该美学，首页则将其以实时动画渲染。

Organic Turbulence 静态美学参考

编写注意事项

sketch prop 接收 p5 instance mode 回调 (p: p5) => void。不要自行调用 new p5()，P5Sketch 负责管理生命周期。
草图通过 import("p5") 在客户端动态导入，p5 运行时不会进入服务端 bundle。
若需全屏 hero 动效，请使用 Astro client directive 水合专用组件；内容中的内联演示应封装在 client island 中。
shadcn 组件读取的 --color-* token 镜像自 Starlight 主题变量，因此暗色模式与主题切换会统一生效。

shadcn/ui Dialog 演示

Badge 与 Alert

Badge 和 Alert 是无依赖的 shadcn 风格展示型组件。它们渲染为静态 HTML（无需 client directive），并读取 Starlight 主题 token，自动适配明暗模式。

用 Badge 在正文中标注状态、版本或生命周期标签：

启用中v0.1.0已弃用

用 Alert 表达需要与 Starlight Aside 区分权重的提示：

适配器已选定

OneBot V11 是默认且唯一启用的适配器，需通过 LINGCHUAdapter 显式切换。

组合展示

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.

在 MDX 中引入

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

<Badge variant="accent">启用中</Badge>

<Alert variant="destructive">
  <AlertTitle>已弃用的适配器</AlertTitle>
  <AlertDescription>
    Milky、QQ、OneBot V12 已弃用并被完全移除。
  </AlertDescription>
</Alert>

Badge 的 variant 可选 default、accent、outline、destructive。Alert 的 variant 可选 default、accent、destructive，并可通过 icon prop 覆盖默认的 lucide 图标。