docyrus-app-ui-design

Docyrus 应用 UI 设计

使用 shadcn、diceui、animate-ui、docyrus-ui 和 reui 库精选的 159 个预构建组件，为 Docyrus React 应用构建精致、易于访问的 UI 组件。

组件库优先级

主要组件库（按优先级排序）：

1. shadcn — 43 个核心组件（按钮、表单、对话框、表格、图表）
2. diceui — 41 个高级组件（数据网格、看板、文件上传、颜色选择器）
3. animate-ui — 21 个动画组件（侧边栏、对话框、卡片、菜单）
4. docyrus — 51 个 Docyrus 专用组件（awesome dialog、awesome stats、数据网格、透视网格、表单字段、值渲染器、可编辑记录详情、甘特图、调度、聊天、AI Agent、定价、共享、邮件撰写器、日志活动表单、架构重复器、步进器）
5. reui — 2 个实用组件（文件上传、可排序）

可用组件总数：158 个

关键设计规则

1. 始终先检查优先组件 — 实现任何新组件前，先搜索优先组件参考，查看是否已有匹配组件。
2. 仪表板使用 AwesomeCard — 除非用户明确要求使用其他卡片设计，否则仪表板统计卡片和指标应使用 @docyrus/ui-awesome-card。
3. 布局使用 animate-ui Sidebar — 除非用户要求使用其他布局，否则应用导航应使用 @animate-ui/sidebar。
4. 图表优先使用 Recharts — 所有数据可视化需求都优先使用 Recharts。shadcn Chart 组件基于 Recharts 构建。
5. 图标库优先级：
   • 首选：hugeicons
   • 第二选择：fontawesome light
   • 第三选择：lucide-icons
6. 条目创建表单使用 AwesomeDialog — 所有条目的创建和编辑表单都使用 AwesomeDialog 系统。根据表单复杂程度选择容器类型：
   • 小型／简单表单 → container="sheet"，并设置 side="right"
   • 较长／复杂表单 → container="modal" 或 container="drawer"
7. 条目详情页策略 — 根据条目复杂程度选择合适的容器：
   • 大型条目（例如，项目、工作区）→ 创建具有完整布局的专用新页面
   • 小型条目（例如，任务、评论、联系人）→ 使用 container="sheet" 且 side="right" 的 AwesomeDialog 作为右侧抽屉
8. 始终使用 TanStack Form + Docyrus 表单系统 — 所有表单都必须使用 TanStack Form，以及 Docyrus 的 DynamicFormField 系统和 @docyrus/ui-form-fields。切勿直接使用原生 HTML 表单或 React Hook Form。
9. 内联编辑使用 EditableRecordDetail — 展示条目详情时，使用 EditableRecordDetail 和 EditableRecordDetailField，以便用户无需打开完整表单即可内联编辑字段。始终启用 trackChanges，以突出显示已更改字段，并显示带有保存／取消操作的浮动 ActionBar。在详情页页眉中添加**“全部编辑”**按钮，以切换到完整表单编辑模式。
10. 可编辑组件始终启用 trackChanges — 使用 EditableRecordDetail 或支持单元格编辑的 DataGrid 时，始终传入 trackChanges 属性。该属性会突出显示已修改的单元格／字段、显示待处理更改数量，并通过浮动 ActionBar 提供保存／取消操作。

快速入门模式

使用 AwesomeDialog 创建条目表单（小型表单 → Sheet）

import {
  AwesomeDialog, AwesomeDialogHeader, AwesomeDialogBody, AwesomeDialogFooter
} from '@docyrus/ui/components/awesome-dialog'

<AwesomeDialog open={open} onOpenChange={setOpen} container="sheet" side="right" size="default">
  <AwesomeDialogHeader title="Create Task" icon="far-plus" />
  <AwesomeDialogBody>
    <form.Field name="title">{(field) => <TextFormField field={field} label="Title" />}</form.Field>
    <form.Field name="status">{(field) => <SelectFormField field={field} label="Status" />}</form.Field>
  </AwesomeDialogBody>
  <AwesomeDialogFooter>
    <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
    <Button onClick={handleSubmit}>Create</Button>
  </AwesomeDialogFooter>
</AwesomeDialog>

使用 AwesomeDialog 创建条目表单（较长表单 → Modal）

<AwesomeDialog open={open} onOpenChange={setOpen} container="modal" size="lg" fullscreenable>
  <AwesomeDialogHeader title="Create Project" icon="far-folder-plus" />
  <AwesomeDialogBody>
    {/* Long form with many fields — body scrolls, header/footer stay fixed */}
  </AwesomeDialogBody>
  <AwesomeDialogFooter>
    <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
    <Button onClick={handleSubmit}>Create Project</Button>
  </AwesomeDialogFooter>
</AwesomeDialog>

在 AwesomeDialog 中查看条目详情（小型条目 → 右侧抽屉）

<AwesomeDialog open={open} onOpenChange={setOpen} container="sheet" side="right" size="lg" fullscreenable>
  <AwesomeDialogHeader
    title="Task Detail"
    description="Review and edit task fields inline"
    headerButtons={<Button variant="outline" size="sm" onClick={switchToFullForm}>Edit All</Button>}
  />
  <AwesomeDialogBody>
    <EditableRecordDetail fields={fields} record={record} onSave={handleSave} trackChanges>
      <EditableRecordDetailField slug="title" />
      <EditableRecordDetailField slug="status" />
      <EditableRecordDetailField slug="assignee" />
      <EditableRecordDetailField slug="due_date" />
    </EditableRecordDetail>
  </AwesomeDialogBody>
</AwesomeDialog>

使用 EditableRecordDetail 进行内联编辑

import {
  EditableRecordDetail, EditableRecordDetailField
} from '@docyrus/ui/components/editable-record-detail'

<EditableRecordDetail
  fields={fields}
  record={record}
  onSave={handleSave}
  onCancel={handleCancel}
  trackChanges  // Always enable — highlights changed fields and shows floating ActionBar with Save/Cancel
>
  <div className="space-y-3">
    <EditableRecordDetailField slug="company_name" />
    <EditableRecordDetailField slug="status" />
    <EditableRecordDetailField slug="priority" />
    <EditableRecordDetailField slug="email" />
  </div>
</EditableRecordDetail>
{/* With trackChanges: changed fields get amber highlight, ActionBar shows "N fields changed" with Save/Cancel */}

使用 AwesomeCard 构建仪表板

import { AwesomeCard } from '@/components/ui/awesome-card'
import { HugeIcon } from '@/components/ui/icons'

<AwesomeCard
  title="Total Revenue"
  value="$124,500"
  icon={<HugeIcon name="dollar-circle" />}
  trend={{ value: 12.5, direction: 'up' }}
/>

使用 animate-ui Sidebar 构建应用布局

import { Sidebar, SidebarContent, SidebarHeader } from '@/components/ui/sidebar'

<Sidebar>
  <SidebarHeader>
    <AppLogo />
  </SidebarHeader>
  <SidebarContent>
    <NavItems />
  </SidebarContent>
</Sidebar>

使用 diceui 构建数据表格

import { DataTable } from '@/components/ui/data-table'

<DataTable
  columns={columns}
  data={projects}
  enableFiltering
  enableSorting
  enablePagination
/>

使用 shadcn + Recharts 构建图表

import { ChartContainer, ChartTooltip } from '@/components/ui/chart'
import { LineChart, Line, XAxis, YAxis } from 'recharts'

<ChartContainer>
  <LineChart data={chartData}>
    <XAxis dataKey="month" />
    <YAxis />
    <ChartTooltip />
    <Line type="monotone" dataKey="revenue" />
  </LineChart>
</ChartContainer>

使用 CreateRecordDialog 快速创建记录

import { CreateRecordDialog } from '@docyrus/ui/components/create-record-dialog'

<CreateRecordDialog
  headerIcon={<PlusIcon />}
  headerLabel="New Task"
  headerFields={[
    { key: 'project', label: 'Project', options: projectOptions }
  ]}
  subjectPlaceholder="Task name..."
  descriptionPlaceholder="Add description..."
  footerFields={[
    { key: 'assignee', label: 'Assignee', options: userOptions },
    { key: 'priority', label: 'Priority', options: priorityOptions }
  ]}
  enableCreateMore
  onSubmit={handleSubmit}
  isPending={isPending}
>
  <Button variant="outline" size="sm"><PlusIcon /> New Task</Button>
</CreateRecordDialog>

使用 TeamChatChannel 构建团队聊天

import { TeamChatChannel } from '@docyrus/ui/components/team-chat-channel'

<TeamChatChannel
  posts={posts}
  currentUser={currentUser}
  users={users}
  channelName="General"
  onCreatePost={handleCreatePost}
  onDeletePost={handleDeletePost}
  onToggleReaction={handleToggleReaction}
  onUploadFile={handleUploadFile}
  onLoadReplies={handleLoadReplies}
  maxHeight={600}
/>

资源调度器

import { ResourceSchedulerPanel } from '@docyrus/ui/components/resource-scheduler-panel'

<ResourceSchedulerPanel
  resources={resources}
  events={events}
  onEventClick={handleEventClick}
  onEventMove={handleEventMove}
  onSlotClick={handleSlotClick}
  showTodayIndicator
  height={500}
/>

使用 AwesomeStats 展示仪表板统计数据

import { AwesomeStats } from '@docyrus/ui/components/awesome-stats'

const stats = [
  {
    id: 'revenue',
    title: 'Total Revenue',
    value: 124500,
    format: { style: 'currency', currency: 'USD', notation: 'compact' },
    icon: 'fal chart-line',
    color: 'blue',
    comparison: { previousValue: 110000 },
    miniChart: { type: 'sparkline', data: [80, 95, 110, 105, 120, 125] }
  },
  // ... more stats
]

// Grid layout (dashboard)
<AwesomeStats items={stats} layout="grid" columns={4} />

// Tabs layout (single card with animated transitions)
<AwesomeStats items={stats} layout="tabs" />

// With AwesomeCard styling
<AwesomeStats items={stats} layout="grid" cardVariant="awesome" />

用于分析的透视网格

import { usePivotGrid, PivotGridView, PivotGridToolbar } from '@docyrus/ui/components/pivot-grid'

const { pivotState, ...pivotProps } = usePivotGrid({
  data: salesData,
  dimensions: [
    { id: 'region', label: 'Region', getValue: (row) => row.region },
    { id: 'product', label: 'Product', getValue: (row) => row.product },
  ],
  measures: [
    { id: 'revenue', label: 'Revenue', aggregate: 'sum', getValue: (row) => row.revenue, formatValue: (v) => `$${v.toLocaleString()}` },
  ],
})

<PivotGridToolbar {...pivotProps} />
<PivotGridView {...pivotProps} />

记录活动表单（CRM）

import { LogActivityForm } from '@docyrus/ui/components/log-activity-form'

<LogActivityForm
  defaultActivityType="call"
  mentionUsers={users}
  events={calendarEvents}
  statusOptions={statusOptions}
  onSubmit={handleSubmit}
  isSubmitting={isPending}
/>

使用 DocyrusAgent 的 AI Agent

import { DocyrusAgent } from '@docyrus/ui/components/docyrus-agent'

<DocyrusAgent
  mode="chat"
  agent={{ name: 'Assistant', description: 'AI helper' }}
  messages={messages}
  chatStatus={status}
  onSendMessage={handleSendMessage}
  onStopGeneration={handleStop}
  allowAttachments
  suggestions={['Summarize this', 'Create a report']}
/>

定价引擎

import { PricingEnginePanel } from '@docyrus/ui/components/pricing-engine-panel'

<PricingEnginePanel
  title="Quote #1234"
  enableVat
  enableLineDiscount
  enableGlobalDiscount
  defaultVatRate={20}
  vatRates={[0, 10, 20]}
  productCatalog={products}
  onSave={handleSave}
  onTotalsChange={handleTotalsChange}
/>

丰富选择器 Mega Select

import { MegaSelect } from '@docyrus/ui/components/mega-select'

<MegaSelect
  items={templateItems}
  categories={categories}
  columns={3}
  size="large"
  searchable
  onChoose={(id, item) => handleChoose(item)}
/>

组件选择策略

当用户请求 UI 组件时：

1. 搜索参考资料 — 在 references/preferred-components-catalog.md 中按名称、类别或功能查找现有组件
2. 按使用场景匹配 — 如果有多个选项，优先选择：
   • 基础／常见组件使用 shadcn
   • 高级／专用组件使用 diceui
   • 需要动画／过渡效果的组件使用 animate-ui
   • 处理 Docyrus 专用数据的组件使用 docyrus
3. 安装组件 — 使用目录中的注册表安装命令
4. 查阅文档 — 指向组件的文档文件，了解详细用法

安装模式

组件遵循 shadcn 注册表模式。Docyrus 组件使用 @docyrus/cli：

# shadcn components
pnpm dlx shadcn@latest add button

# diceui components
pnpm dlx shadcn@latest add @diceui/data-table

# animate-ui components
pnpm dlx shadcn@latest add @animate-ui/sidebar

# docyrus components (use @docyrus/cli)
pnpm dlx @docyrus/cli add @docyrus/ui-awesome-card

# reui components
pnpm dlx shadcn@latest add @reui/file-upload-default

常见使用场景

使用场景	首选组件	库
创建条目表单	AwesomeDialog（侧边栏／模态框／抽屉）	docyrus
快速创建记录	CreateRecordDialog	docyrus
条目详情（小型）	AwesomeDialog（右侧侧边栏）	docyrus
条目详情（大型）	专用页面	—
行内编辑记录	EditableRecordDetail	docyrus
仪表板卡片	AwesomeCard	docyrus
应用导航	Sidebar	animate-ui
数据表格	DataTable	diceui
可编辑网格	Data Grid	docyrus
网格已保存视图	DataGridViewSelect	docyrus
表单	表单字段 + TanStack Form	docyrus
富条目选择器	MegaSelect	docyrus
单选卡片	RadioGroup（卡片变体）	docyrus
文件上传	File Upload	diceui
图表	Chart + Recharts	shadcn
确认对话框	Alert Dialog	animate-ui
日期选择器	Date Time Picker	docyrus
颜色选择器	Color Picker	diceui
看板	Kanban	docyrus
甘特图	Gantt	docyrus
资源排程	ResourceSchedulerPanel	docyrus
预约预订	TimeSlotScheduler	docyrus
时间线	Timeline	diceui
团队聊天	TeamChatChannel	docyrus
撰写邮件	EmailComposer	docyrus
Markdown 编辑	SimpleMarkdownEditor	docyrus
联系人活动	ContactActivityPanel	docyrus
AI Agent 界面	DocyrusAgent	docyrus
定价／报价	PricingEnginePanel	docyrus
记录共享	RecordSharing	docyrus
通知	NotificationStack	docyrus
搜索	SearchInput	docyrus
位置输入	PlaceAutocomplete	docyrus
地图显示	Map	docyrus
树形层级	TreeView	docyrus
仪表板统计	AwesomeStats	docyrus
数据透视表／分析	PivotGrid	docyrus
日期范围选择	DateTimeRangePicker	docyrus
活动记录（CRM）	LogActivityForm	docyrus
动态重复行	SchemaRepeater	docyrus
多步骤向导	Stepper	docyrus

参考资料

请阅读以下文件，了解组件详情：

• references/preferred-components-catalog.md — 全部 160 个组件的完整目录，包含描述、安装命令和文档路径（docyrus 文档位于 https://alpha-ui.docy.app/docs/web/components/<name>/llms.txt）
• references/component-selection-guide.md — 按使用场景选择合适组件的决策树和指南
• references/icon-usage-guide.md — hugeicons、fontawesome 和 lucide 的图标库集成模式和使用示例

Docyrus UI 指南文档

获取以下 llms.txt 端点以查看详细指南：

• 组件概览 — 使用 React、TypeScript、Tailwind CSS v4 和 CVA variants 构建的生产就绪 UI 组件
• 安装 — 如何在项目中安装和设置 Docyrus UI 组件
• 主题 — 使用 CSS 变量和主题生成器自定义外观和风格
• 分发包 — 为 Docyrus UI Web 组件提供支持的组件分发包和核心库
• 示例与配方 — 针对常见 UI 场景的实用多组件模式和配方
• 故障排除 — 使用 Docyrus UI Web 组件时的常见问题及解决方案
• 版本发布 — Docyrus UI Web 组件的最新版本和更新

与 docyrus-app-dev 集成

此技能与 docyrus-app-dev 协同工作，支持全栈应用开发：

• docyrus-app-dev 负责数据获取、集合、查询和身份验证
• docyrus-app-ui-design 负责组件选择、UI 设计和布局

构建功能时：

1. 使用 docyrus-app-dev 设置数据查询和变更
2. 使用 docyrus-app-ui-design 选择并实现 UI 组件
3. 将二者结合，打造完整、精致的功能