radix-ui-design-system

Radix UI 设计系统

使用 Radix UI 原语构建可投入生产、可访问的设计系统，具备完全的自定义控制能力和零样式倾向。

详细指南

在执行此技能之前，请阅读详细指南。其中保留了完整的流程和参考资料。请将其安全性、前置条件和验证要求视为强制性要求。对于有针对性的工作，加载相关章节；对于端到端的工作，请完整阅读该指南。

何时使用此技能

• 从零开始创建自定义设计系统
• 构建可访问的 UI 组件库
• 实现复杂的交互式组件（Dialog、Dropdown、Tabs 等）
• 从带样式的组件库迁移到无样式原语
• 使用 CSS 变量或 Tailwind 设置主题系统
• 需要对组件行为和样式有完全控制
• 构建需要符合 WCAG 2.1 AA/AAA 标准的应用

何时不要使用此技能

• 你需要开箱即用的预样式组件（使用 shadcn/ui、Mantine 等）
• 构建没有交互性的简单静态页面
• 项目不使用 React 16.8+（Radix 需要 hooks）
• 你需要 React 以外框架的组件

---

实际示例

示例 1：命令面板（组合对话框）

import { useState, useEffect } from 'react';
import * as Dialog from '@radix-ui/react-dialog';
import { Command } from 'cmdk';

export function CommandPalette() {
  const [open, setOpen] = useState(false);

  useEffect(() => {
    const down = (e: KeyboardEvent) => {
      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
        e.preventDefault();
        setOpen((open) => !open);
      }
    };
    document.addEventListener('keydown', down);
    return () => document.removeEventListener('keydown', down);
  }, []);

  return (
    <Dialog.Root open={open} onOpenChange={setOpen}>
      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 bg-black/50" />
        <Dialog.Content className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2">
          <Dialog.Title>Commands</Dialog.Title>
          <Dialog.Description>Search available actions.</Dialog.Description>
          <Command>
            <Command.Input placeholder="Type a command..." />
            <Command.List>
              <Command.Empty>No results found.</Command.Empty>
              <Command.Group heading="Suggestions">
                <Command.Item>Calendar</Command.Item>
                <Command.Item>Search Emoji</Command.Item>
              </Command.Group>
            </Command.List>
          </Command>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

示例 2：带图标的下拉菜单

import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
import { DotsHorizontalIcon } from '@radix-ui/react-icons';

export function ActionsMenu() {
  return (
    <DropdownMenu.Root>
      <DropdownMenu.Trigger asChild>
        <button className="icon-button" aria-label="Actions">
          <DotsHorizontalIcon />
        </button>
      </DropdownMenu.Trigger>

      <DropdownMenu.Portal>
        <DropdownMenu.Content className="dropdown-content" align="end">
          <DropdownMenu.Item className="dropdown-item">
            Edit
          </DropdownMenu.Item>
          <DropdownMenu.Item className="dropdown-item">
            Duplicate
          </DropdownMenu.Item>
          <DropdownMenu.Separator className="dropdown-separator" />
          <DropdownMenu.Item className="dropdown-item text-red-500">
            Delete
          </DropdownMenu.Item>
        </DropdownMenu.Content>
      </DropdownMenu.Portal>
    </DropdownMenu.Root>
  );
}

示例 3：使用 Radix Select + React Hook Form 的表单

import * as Select from '@radix-ui/react-select';
import { useForm, Controller } from 'react-hook-form';

interface FormData {
  country: string;
}

export function CountryForm() {
  const { control, handleSubmit } = useForm<FormData>();

  return (
    <form onSubmit={handleSubmit((data) => console.log(data))}>
      <Controller
        name="country"
        control={control}
        render={({ field }) => (
          <Select.Root onValueChange={field.onChange} value={field.value}>
            <Select.Trigger ref={field.ref} onBlur={field.onBlur} aria-label="Country" className="select-trigger">
              <Select.Value placeholder="Select a country" />
              <Select.Icon />
            </Select.Trigger>
            
            <Select.Portal>
              <Select.Content className="select-content">
                <Select.Viewport>
                  <Select.Item value="us"><Select.ItemText>United States</Select.ItemText></Select.Item>
                  <Select.Item value="ca"><Select.ItemText>Canada</Select.ItemText></Select.Item>
                  <Select.Item value="uk"><Select.ItemText>United Kingdom</Select.ItemText></Select.Item>
                </Select.Viewport>
              </Select.Content>
            </Select.Portal>
          </Select.Root>
        )}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

---

限制

• 仅当任务明确匹配上述范围时才使用此技能。
• 不要将输出视为环境特定验证、测试或专家评审的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。