assembling-components

组装组件

目的

此技能可将 AI Design Components 技能的输出转换为可用于生产环境的应用程序。它为我们的令牌系统、组件模式和技能链工作流提供特定于库的上下文——这些知识是通用组装模式无法提供的。此技能会验证令牌集成、生成适当的脚手架，并正确连接组件。

何时使用

在以下情况下启用此技能：

• 完成技能链工作流（主题 → 布局 → 仪表板 → 数据可视化 → 反馈）
• 为 React/Vite、Next.js、FastAPI、Flask 或 Rust/Axum 生成新的项目脚手架
• 验证所有生成的 CSS 是否使用设计令牌（而非硬编码值）
• 创建汇总导出，并正确连接组件导入
• 将多个技能生成的组件组装成统一的应用程序
• 调试集成问题（缺少入口点、导入失效、主题无法切换）
• 为生产部署准备生成的代码

技能链上下文

此技能了解每个 AI Design Components 技能的输出：

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│ theming-         │────▶│ designing-       │────▶│ creating-        │
│ components       │     │ layouts          │     │ dashboards       │
└──────────────────┘     └──────────────────┘     └──────────────────┘
        │                        │                        │
        ▼                        ▼                        ▼
    tokens.css               Layout.tsx             Dashboard.tsx
    theme-provider.tsx       Header.tsx             KPICard.tsx
        │                        │                        │
        └────────────────────────┴────────────────────────┘
                                 │
                                 ▼
                    ┌──────────────────────┐
                    │ visualizing-data     │
                    │ providing-feedback   │
                    └──────────────────────┘
                                 │
                                 ▼
                         DonutChart.tsx
                         Toast.tsx, Spinner.tsx
                                 │
                                 ▼
                    ┌──────────────────────┐
                    │ ASSEMBLING-          │
                    │ COMPONENTS           │
                    │ (THIS SKILL)         │
                    └──────────────────────┘
                                 │
                                 ▼
                       WORKING COMPONENT SYSTEM

各技能的预期输出

技能	主要输出	令牌依赖项
theming-components	tokens.css、theme-provider.tsx	基础
designing-layouts	Layout.tsx、Header.tsx、Sidebar.tsx	--spacing-、--color-border-
creating-dashboards	Dashboard.tsx、KPICard.tsx	所有布局令牌 + 图表令牌
visualizing-data	图表组件、图例	--chart-color-、--font-size-
building-forms	表单输入、验证	--spacing-、--radius-、--color-error
building-tables	表格、分页	--color-、--spacing-
providing-feedback	Toast、Spinner、EmptyState	--color-success/error/warning

令牌验证

运行验证脚本（不使用令牌执行）

# Basic validation
python scripts/validate_tokens.py src/styles

# Strict mode with fix suggestions
python scripts/validate_tokens.py src --strict --fix-suggestions

# JSON output for CI/CD
python scripts/validate_tokens.py src --json

我们的令牌命名约定

/* Colors - semantic naming */
--color-primary: #FA582D;          /* Brand primary */
--color-success: #00CC66;          /* Positive states */
--color-warning: #FFCB06;          /* Caution states */
--color-error: #C84727;            /* Error states */
--color-info: #00C0E8;             /* Informational */

--color-bg-primary: #FFFFFF;       /* Main background */
--color-bg-secondary: #F8FAFC;     /* Elevated surfaces */
--color-text-primary: #1E293B;     /* Body text */
--color-text-secondary: #64748B;   /* Muted text */

/* Spacing - 4px base unit */
--spacing-xs: 0.25rem;   /* 4px */
--spacing-sm: 0.5rem;    /* 8px */
--spacing-md: 1rem;      /* 16px */
--spacing-lg: 1.5rem;    /* 24px */
--spacing-xl: 2rem;      /* 32px */

/* Typography */
--font-size-xs: 0.75rem;   /* 12px */
--font-size-sm: 0.875rem;  /* 14px */
--font-size-base: 1rem;    /* 16px */
--font-size-lg: 1.125rem;  /* 18px */

/* Component sizes */
--icon-size-sm: 1rem;      /* 16px */
--icon-size-md: 1.5rem;    /* 24px */
--radius-sm: 4px;
--radius-md: 8px;
--shadow-sm: 0 1px 2px rgba(0,0,0,0.05);

验证规则

必须使用令牌（错误）	修正示例
颜色	#FA582D → var(--color-primary)
间距（≥4px）	16px → var(--spacing-md)
字号	14px → var(--font-size-sm)

应使用令牌（警告）	修正示例
边框圆角	8px → var(--radius-md)
阴影	0 4px... → var(--shadow-md)
Z-index（≥100）	1000 → var(--z-dropdown)

框架选择

React/TypeScript

选择 Vite + React 的情况：

• 构建单页应用程序
• 需要轻量、快速的开发构建
• 希望最大限度地控制配置
• 不需要服务器端渲染

选择 Next.js 14/15 的情况：

• 需要服务器端渲染或静态生成
• 使用 API 路由构建全栈应用
• SEO 很重要
• 使用 React Server Components

Python

选择 FastAPI 的情况：

• 构建现代异步 API
• 需要自动生成 OpenAPI 文档
• 需要高性能
• 使用 Pydantic 进行验证

选择 Flask 的情况：

• 需要更简单、更灵活的设置
• 熟悉 Flask 生态系统
• 需要模板渲染（Jinja2）
• 构建较小的应用程序

Rust

选择 Axum 的情况：

• 采用现代的 tower 架构
• 使用类型安全的提取器
• 采用异步优先设计
• 需要不断发展的生态系统

选择 Actix Web 的情况：

• 需要最高性能
• Actor 模型适用于你的使用场景
• 需要更成熟的生态系统

实现方法

1. 验证令牌集成

组装前，检查所有 CSS 是否使用令牌：

python scripts/validate_tokens.py <component-directory>

继续之前，修复所有违规项。

2. 生成项目脚手架

React/Vite：

// src/main.tsx - Entry point
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { ThemeProvider } from '@/context/theme-provider'
import App from './App'
import './styles/tokens.css'   // FIRST - token definitions
import './styles/globals.css'  // SECOND - global resets

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ThemeProvider>
      <App />
    </ThemeProvider>
  </StrictMode>,
)

index.html：

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{{PROJECT_TITLE}}</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

3. 连接组件

主题提供程序：

// src/context/theme-provider.tsx
import { createContext, useContext, useEffect, useState } from 'react'

type Theme = 'light' | 'dark' | 'system'

const ThemeContext = createContext<{
  theme: Theme
  setTheme: (theme: Theme) => void
} | undefined>(undefined)

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>('system')

  useEffect(() => {
    const root = document.documentElement
    const systemTheme = window.matchMedia('(prefers-color-scheme: dark)').matches
      ? 'dark' : 'light'
    root.setAttribute('data-theme', theme === 'system' ? systemTheme : theme)
    localStorage.setItem('theme', theme)
  }, [theme])

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  )
}

export const useTheme = () => {
  const context = useContext(ThemeContext)
  if (!context) throw new Error('useTheme must be used within ThemeProvider')
  return context
}

汇总导出：

// src/components/ui/index.ts
export { Button } from './button'
export { Card } from './card'

// src/components/features/dashboard/index.ts
export { KPICard } from './kpi-card'
export { DonutChart } from './donut-chart'
export { Dashboard } from './dashboard'

4. 配置构建系统

vite.config.ts：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src"]
}

跨技能集成

使用主题组件

// Import tokens first, components inherit token values
import './styles/tokens.css'

// Use ThemeProvider at root
<ThemeProvider>
  <App />
</ThemeProvider>

使用仪表板组件

// Components from creating-dashboards skill
import { Dashboard, KPICard } from '@/components/features/dashboard'

// Wire with data
<Dashboard>
  <KPICard
    label="Total Threats"
    value={1234}
    severity="critical"
    trend={{ value: 15.3, direction: 'up' }}
  />
</Dashboard>

使用数据可视化

// Charts from visualizing-data skill
import { DonutChart } from '@/components/charts'

// Charts use --chart-color-* tokens automatically
<DonutChart
  data={threatData}
  title="Threats by Severity"
/>

使用反馈组件

// From providing-feedback skill
import { Toast, Spinner, EmptyState } from '@/components/feedback'

// Wire toast notifications
<ToastProvider>
  <App />
</ToastProvider>

// Use spinner for loading states
{isLoading ? <Spinner /> : <Dashboard />}

集成检查清单

交付前，请确认：

• Token 文件存在（tokens.css），且包含全部 7 个类别
• Token 导入顺序正确（tokens.css → globals.css → components）
• 无硬编码值（运行 validate_tokens.py）
• 主题切换正常（data-theme 属性可以切换）
• 支持减少动态效果（@media (prefers-reduced-motion)）
• 构建成功完成，无错误
• 类型检查通过（TypeScript 编译成功）
• 导入路径解析正常（无缺失模块）
• 每个组件目录都存在 Barrel 导出

打包的资源

脚本（无 Token 执行）

• scripts/validate_tokens.py - 验证 CSS 是否使用设计 Token
• scripts/generate_scaffold.py - 生成项目样板代码
• scripts/check_imports.py - 验证导入链
• scripts/generate_exports.py - 创建 Barrel 导出文件

无需将脚本加载到上下文中，可直接运行：

python scripts/validate_tokens.py demo/examples --fix-suggestions

参考资料（详细模式）

• references/library-context.md - AI Design Components 库相关说明
• references/react-vite-template.md - 完整的 Vite + React 配置
• references/nextjs-template.md - Next.js 14/15 模式
• references/python-fastapi-template.md - FastAPI 项目结构
• references/rust-axum-template.md - Rust/Axum 项目结构
• references/token-validation-rules.md - 完整的验证规则

示例（完整实现）

• examples/react-dashboard/ - 完整的 Vite + React 仪表板
• examples/nextjs-dashboard/ - Next.js App Router 仪表板
• examples/fastapi-dashboard/ - Python FastAPI 仪表板
• examples/rust-axum-dashboard/ - Rust Axum 仪表板

资源文件（模板）

• assets/templates/react/ - React 项目模板
• assets/templates/python/ - Python 项目模板
• assets/templates/rust/ - Rust 项目模板

应用组装工作流

1. 验证组件：对所有生成的 CSS 运行 validate_tokens.py
2. 选择框架：根据需求选择 React/Vite、Next.js、FastAPI 或 Rust
3. 生成脚手架：创建项目结构和配置
4. 连接导入：设置入口点、导入链和 Barrel 导出
5. 添加 Providers：在根目录添加 ThemeProvider、ToastProvider
6. 连接组件：导入并组合功能组件
7. 配置构建：配置 vite.config、tsconfig、package.json
8. 最终验证：构建、类型检查、Lint
9. 编写文档：README 中包含设置和使用说明

有关库特定模式和完整上下文，请参阅 references/library-context.md。