fiftyone-voodo-design

用途

VOODO（@voxel51/voodo）是 FiftyOne 应用的官方 React 组件库，源码位于 https://github.com/voxel51/design-system。本技能用于在构建 FiftyOne 用户界面时提供规范指导，适用场景包括构建插件面板、创建交互式 UI 以及进行样式设计。

主要能力

VOODO 提供完整的 React 组件与设计令牌体系，涵盖：

设计令牌枚举，包含精确的成员值（Size、Spacing、Variant、Orientation 等）
每个组件的 props、类型、默认值及用法示例
常见布局的组合模式（表单、卡片、列表、选择器）
需要避免的反模式（例如使用原始 Tailwind 而非组件 props）

使用方式

关键指令

在编写任何 UI 代码之前，必须先获取 LLM 参考文档：

WebFetch(
    url="https://voodo.dev.fiftyone.ai/voodo-llm-reference.md",
    prompt="Read the complete VOODO component API, design tokens, and composition patterns"
)

工作流

获取参考文档：

WebFetch(
    url="https://voodo.dev.fiftyone.ai/voodo-llm-reference.md",
    prompt="What VOODO components and tokens are available for building [describe UI]?"
)

使用参考文档中的组件与设计令牌。始终从 @voxel51/voodo 导入，始终使用枚举值，绝不传入原始字符串：

import { Button, Input, Stack, Text, FormField } from "@voxel51/voodo";
import { Orientation, Size, Spacing, Variant, TextColor } from "@voxel51/voodo";

遵循组合模式。参考文档包含以下模式：

表单：将控件包裹在 <FormField> 中，使用 <FormFieldGroup> 分组
布局：使用 <Stack> 并配合 orientation、spacing、align、justify 属性，而非 Tailwind flex 类
卡片：使用 <Card> / <RichCard> 承载内容
列表：使用 Descriptor<T>[] 模式配合 <RichList> 或 <RichButtonGroup>
反馈：使用 <Toast>、<Tooltip>、<EmptyState>

安装

在依赖中加入：

{
  "dependencies": {
    "@voxel51/voodo": "latest"
  }
}

在应用入口点导入主题 CSS：

import "@voxel51/voodo/theme.css";

FiftyOne 模式

深色主题：FiftyOne App 默认使用深色模式
语义变体：使用 Variant.Success、Variant.Danger、Variant.Secondary 表示操作
设计令牌：始终使用枚举值（Spacing.Md、Size.Sm），绝不使用任意 CSS 值
布局：使用 <Stack> 的 align 和 justify 属性，而非 Tailwind 的 items-* / justify-* 类

与 FiftyOne SDK 集成

import { useRecoilValue } from "recoil";
import * as fos from "@fiftyone/state";  // Standard FiftyOne alias
import { Button, Text, Stack, FormField, Input } from "@voxel51/voodo";
import { Orientation, Spacing, Size, Variant, TextColor } from "@voxel51/voodo";

const MyPanel: React.FC = () => {
  const dataset = useRecoilValue(fos.dataset);
  return (
    <Stack orientation={Orientation.Column} spacing={Spacing.Md}>
      <Text color={TextColor.Secondary}>{dataset?.name}</Text>
      <FormField
        label="Filter"
        control={<Input size={Size.Sm} placeholder="Search..." />}
      />
      <Button variant={Variant.Primary} size={Size.Sm}>
        Process
      </Button>
    </Stack>
  );
};

资源

LLM 参考（需首先获取）：https://voodo.dev.fiftyone.ai/voodo-llm-reference.md
源码仓库：https://github.com/voxel51/design-system
交互式 Storybook：https://voodo.dev.fiftyone.ai/
npm 包：@voxel51/voodo

相关：完整插件设置请使用 fiftyone-develop-plugin 技能。

限制与故障排查

组件未找到：获取 LLM 参考以确认当前组件名称
属性值错误：使用枚举成员（如 Size.Md），而非字符串（如 "md"）
布局不生效：使用 <Stack> 并配合 orientation、spacing、align、justify 属性
样式未应用：确保已导入 @voxel51/voodo/theme.css，并在深色模式下测试