name: assembling-components description: 将AI设计组件技能的输出组装成统一、生产就绪的组件系统，具有验证的令牌集成、正确的导入链和框架特定的脚手架。在运行主题、布局、仪表板、数据可视化或反馈技能后，作为收官技能使用，将组件连接到工作的React/Next.js、Python或Rust项目中。

组装组件

目的

这个技能将AI设计组件技能的输出转化为生产就绪的应用程序。它为我们令牌系统、组件模式和技能链工作流程提供库特定的上下文知识，这是通用组装模式无法提供的。该技能验证令牌集成、生成正确的脚手架，并正确连接组件。

何时使用

在以下情况激活此技能：

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

技能链上下文

此技能理解每个AI设计组件技能的输出：

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│ 主题组件         │────▶│ 设计布局         │────▶│ 创建仪表板       │
└──────────────────┘     └──────────────────┘     └──────────────────┘
        │                        │                        │
        ▼                        ▼                        ▼
    tokens.css               Layout.tsx             Dashboard.tsx
    theme-provider.tsx       Header.tsx             KPICard.tsx
        │                        │                        │
        └────────────────────────┴────────────────────────┘
                                 │
                                 ▼
                    ┌──────────────────────┐
                    │ 数据可视化           │
                    │ 提供反馈             │
                    └──────────────────────┘
                                 │
                                 ▼
                         DonutChart.tsx
                         Toast.tsx, Spinner.tsx
                                 │
                                 ▼
                    ┌──────────────────────┐
                    │ 组装组件             │
                    │ （此技能）           │
                    └──────────────────────┘
                                 │
                                 ▼
                       工作组件系统

按技能预期输出

技能	主要输出	令牌依赖
`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

令牌验证

运行验证脚本（令牌无关执行）

# 基本验证
python scripts/validate_tokens.py src/styles

# 严格模式带修复建议
python scripts/validate_tokens.py src --strict --fix-suggestions

# JSON输出用于CI/CD
python scripts/validate_tokens.py src --json

我们的令牌命名约定

/* 颜色 - 语义命名 */
--color-primary: #FA582D;          /* 品牌主色 */
--color-success: #00CC66;          /* 积极状态 */
--color-warning: #FFCB06;          /* 警告状态 */
--color-error: #C84727;            /* 错误状态 */
--color-info: #00C0E8;             /* 信息状态 */

--color-bg-primary: #FFFFFF;       /* 主背景 */
--color-bg-secondary: #F8FAFC;     /* 高亮表面 */
--color-text-primary: #1E293B;     /* 正文文本 */
--color-text-secondary: #64748B;   /* 次要文本 */

/* 间距 - 4px基础单位 */
--spacing-xs: 0.25rem;   /* 4px */
--spacing-sm: 0.5rem;    /* 8px */
--spacing-md: 1rem;      /* 16px */
--spacing-lg: 1.5rem;    /* 24px */
--spacing-xl: 2rem;      /* 32px */

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

/* 组件大小 */
--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索引（≥100）	`1000` → `var(--z-dropdown)`

框架选择

React/TypeScript

选择Vite + React时：

构建单页应用程序
轻量级、快速开发构建
最大控制配置
无需服务器端渲染

选择Next.js 14/15时：

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

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 - 入口点
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { ThemeProvider } from '@/context/theme-provider'
import App from './App'
import './styles/tokens.css'   // 第一 - 令牌定义
import './styles/globals.css'  // 第二 - 全局重置

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必须用在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 './styles/tokens.css'

// 在根目录使用ThemeProvider
<ThemeProvider>
  <App />
</ThemeProvider>

使用仪表板组件

// 来自创建仪表板技能的组件
import { Dashboard, KPICard } from '@/components/features/dashboard'

// 连接数据
<Dashboard>
  <KPICard
    label="总威胁"
    value={1234}
    severity="critical"
    trend={{ value: 15.3, direction: 'up' }}
  />
</Dashboard>

使用数据可视化

// 来自数据可视化技能的图表
import { DonutChart } from '@/components/charts'

// 图表自动使用 --chart-color-* 令牌
<DonutChart
  data={threatData}
  title="按严重性威胁"
/>

使用反馈组件

// 来自提供反馈技能的组件
import { Toast, Spinner, EmptyState } from '@/components/feedback'

// 连接通知
<ToastProvider>
  <App />
</ToastProvider>

// 用于加载状态的旋转器
{isLoading ? <Spinner /> : <Dashboard />}

集成检查清单

交付前验证：

[ ] 令牌文件存在 (tokens.css) 包含所有7个类别
[ ] 令牌导入顺序 正确 (tokens.css → globals.css → components)
[ ] 无硬编码值 (运行 validate_tokens.py)
[ ] 主题切换工作 (data-theme 属性切换)
[ ] 支持减少运动 (@media (prefers-reduced-motion))
[ ] 构建完成 无错误
[ ] 类型通过 (TypeScript编译)
[ ] 导入解析 (无缺失模块)
[ ] 桶导出 每个组件目录存在

捆绑资源

脚本（令牌无关执行）

scripts/validate_tokens.py - 验证CSS使用设计令牌
scripts/generate_scaffold.py - 生成项目模板
scripts/check_imports.py - 验证导入链
scripts/generate_exports.py - 创建桶导出文件

直接运行脚本无需加载到上下文：

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

参考（详细模式）

references/library-context.md - AI设计组件库意识
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项目模板

应用程序组装工作流程

验证组件：在所有生成CSS上运行 validate_tokens.py
选择框架：根据需求选择React/Vite、Next.js、FastAPI或Rust
生成脚手架：创建项目结构和配置
连接导入：设置入口点、导入链、桶导出
添加提供者：在根目录添加ThemeProvider、ToastProvider
连接组件：导入并组合功能组件
配置构建：vite.config、tsconfig、package.json
最终验证：构建、类型检查、lint
文档：包含设置和使用说明的README

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