assembling-components

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Assembling Components

组件组装

Purpose

用途

This skill transforms the outputs of AI Design Components skills into production-ready applications. It provides library-specific context for our token system, component patterns, and skill chain workflow - knowledge that generic assembly patterns cannot provide. The skill validates token integration, generates proper scaffolding, and wires components together correctly.

本技能可将AI Design Components技能生成的输出转化为可投入生产的应用程序。它为我们的token系统、组件模式和技能链工作流提供了针对特定库的上下文信息——这些是通用组装模式所不具备的知识。本技能会验证token集成、生成规范的脚手架，并正确地将组件连接在一起。

When to Use

使用场景

Activate this skill when:

Completing a skill chain workflow (theming → layout → dashboards → data-viz → feedback)
Generating new project scaffolding for React/Vite, Next.js, FastAPI, Flask, or Rust/Axum
Validating that all generated CSS uses design tokens (not hardcoded values)
Creating barrel exports and wiring component imports correctly
Assembling components from multiple skills into a unified application
Debugging integration issues (missing entry points, broken imports, theme not switching)
Preparing generated code for production deployment

在以下场景中激活本技能：

完成技能链工作流（主题设置 → 布局 → 仪表盘 → 数据可视化 → 反馈组件）
为React/Vite、Next.js、FastAPI、Flask或Rust/Axum生成新的项目脚手架
验证所有生成的CSS是否使用设计token（而非硬编码值）
创建桶导出（Barrel Exports）并正确配置组件导入
将来自多个技能的组件组装为统一的应用程序
调试集成问题（缺失入口点、导入失败、主题切换异常）
为生产部署准备生成的代码

Skill Chain Context

技能链上下文

This skill understands the output of every AI Design Components skill:

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│ 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

本技能可理解所有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

Expected Outputs by Skill

各技能的预期输出

Skill	Primary Outputs	Token Dependencies
`theming-components`	tokens.css, theme-provider.tsx	Foundation
`designing-layouts`	Layout.tsx, Header.tsx, Sidebar.tsx	--spacing-, --color-border-
`creating-dashboards`	Dashboard.tsx, KPICard.tsx	All layout + chart tokens
`visualizing-data`	Chart components, legends	--chart-color-, --font-size-
`building-forms`	Form inputs, validation	--spacing-, --radius-, --color-error
`building-tables`	Table, pagination	--color-, --spacing-
`providing-feedback`	Toast, Spinner, EmptyState	--color-success/error/warning

技能	主要输出	Token依赖
`theming-components`	tokens.css, theme-provider.tsx	Foundation
`designing-layouts`	Layout.tsx, Header.tsx, Sidebar.tsx	--spacing-, --color-border-
`creating-dashboards`	Dashboard.tsx, KPICard.tsx	所有布局+图表token
`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

Token Validation

Token验证

Run Validation Script (Token-Free Execution)

运行验证脚本（无需加载上下文）

bash

undefined

bash

undefined

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

生成JSON输出用于CI/CD

python scripts/validate_tokens.py src --json

undefined

python scripts/validate_tokens.py src --json

undefined

Our Token Naming Conventions

我们的Token命名规范

css

/* 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);

css

/* 颜色 - 语义化命名 */
--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);

Validation Rules

验证规则

Must Use Tokens (Errors)	Example Fix
Colors	`#FA582D` → `var(--color-primary)`
Spacing (≥4px)	`16px` → `var(--spacing-md)`
Font sizes	`14px` → `var(--font-size-sm)`

Should Use Tokens (Warnings)	Example Fix
Border radius	`8px` → `var(--radius-md)`
Shadows	`0 4px...` → `var(--shadow-md)`
Z-index (≥100)	`1000` → `var(--z-dropdown)`

必须使用Token（错误项）	修复示例
颜色	`#FA582D` → `var(--color-primary)`
间距（≥4px）	`16px` → `var(--spacing-md)`
字体大小	`14px` → `var(--font-size-sm)`

建议使用Token（警告项）	修复示例
边框圆角	`8px` → `var(--radius-md)`
阴影	`0 4px...` → `var(--shadow-md)`
Z-index（≥100）	`1000` → `var(--z-dropdown)`

Framework Selection

框架选择

React/TypeScript

Choose Vite + React when:

Building single-page applications
Lightweight, fast development builds
Maximum control over configuration
No server-side rendering needed

Choose Next.js 14/15 when:

Need server-side rendering or static generation
Building full-stack with API routes
SEO is important
Using React Server Components

选择Vite + React的场景：

构建单页应用
轻量化、快速的开发构建
需要最大程度控制配置
无需服务端渲染

选择Next.js 14/15的场景：

需要服务端渲染或静态生成
构建带API路由的全栈应用
SEO需求较高
使用React Server Components

Python

Choose FastAPI when:

Building modern async APIs
Need automatic OpenAPI documentation
High performance is required
Using Pydantic for validation

Choose Flask when:

Simpler, more flexible setup
Familiar with Flask ecosystem
Template rendering (Jinja2)
Smaller applications

选择FastAPI的场景：

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

选择Flask的场景：

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

Rust

Choose Axum when:

Modern tower-based architecture
Type-safe extractors
Async-first design
Growing ecosystem

Choose Actix Web when:

Maximum performance required
Actor model benefits your use case
More mature ecosystem

选择Axum的场景：

基于Tower的现代架构
类型安全的提取器
优先异步设计
生态系统正在快速发展

选择Actix Web的场景：

需要极致性能
Actor模型对业务有帮助
生态系统更成熟

Implementation Approach

实现步骤

1. Validate Token Integration

1. 验证Token集成

Before assembly, check all CSS uses tokens:

bash

python scripts/validate_tokens.py <component-directory>

Fix any violations before proceeding.

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

bash

python scripts/validate_tokens.py <component-directory>

修复所有问题后再继续。

2. Generate Project Scaffolding

2. 生成项目脚手架

React/Vite:

tsx

// 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:

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>

React/Vite：

tsx

// 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'   // 第一步 - 导入Token定义
import './styles/globals.css'  // 第二步 - 导入全局样式重置

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

index.html：

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. Wire Components Together

3. 组件连接

Theme Provider:

tsx

// 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
}

Barrel Exports:

tsx

// 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'

主题提供者：

tsx

// 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
}

桶导出：

tsx

// 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. Configure Build System

4. 配置构建系统

vite.config.ts:

typescript

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:

json

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

vite.config.ts：

typescript

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：

json

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

Cross-Skill Integration

跨技能集成

Using Theming Components

主题组件的使用

tsx

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

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

tsx

// 先导入Token，组件将继承Token值
import './styles/tokens.css'

// 在根节点使用ThemeProvider
<ThemeProvider>
  <App />
</ThemeProvider>

Using Dashboard Components

仪表盘组件的使用

tsx

// 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>

tsx

// 导入creating-dashboards技能生成的组件
import { Dashboard, KPICard } from '@/components/features/dashboard'

// 绑定数据
<Dashboard>
  <KPICard
    label="Total Threats"
    value={1234}
    severity="critical"
    trend={{ value: 15.3, direction: 'up' }}
  />
</Dashboard>

Using Data Visualization

数据可视化组件的使用

tsx

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

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

tsx

// 导入visualizing-data技能生成的图表
import { DonutChart } from '@/components/charts'

// 图表会自动使用--chart-color-*系列Token
<DonutChart
  data={threatData}
  title="Threats by Severity"
/>

Using Feedback Components

反馈组件的使用

tsx

// 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 />}

tsx

// 导入providing-feedback技能生成的组件
import { Toast, Spinner, EmptyState } from '@/components/feedback'

// 配置Toast通知提供者
<ToastProvider>
  <App />
</ToastProvider>

// 在加载状态使用Spinner
{isLoading ? <Spinner /> : <Dashboard />}

Integration Checklist

集成检查清单

Before delivery, verify:

Token file exists (
```
tokens.css
```
) with all 7 categories
Token import order correct (tokens.css → globals.css → components)
No hardcoded values (run
```
validate_tokens.py
```
)
Theme toggle works (
```
data-theme
```
attribute switches)
Reduced motion supported (
```
@media (prefers-reduced-motion)
```
)
Build completes without errors
Types pass (TypeScript compiles)
Imports resolve (no missing modules)
Barrel exports exist for each component directory

交付前，请验证以下内容：

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

Bundled Resources

配套资源

Scripts (Token-Free Execution)

脚本（无需加载上下文）

```
scripts/validate_tokens.py
```
- Validate CSS uses design tokens
```
scripts/generate_scaffold.py
```
- Generate project boilerplate
```
scripts/check_imports.py
```
- Validate import chains
```
scripts/generate_exports.py
```
- Create barrel export files

Run scripts directly without loading into context:

bash

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

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

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

bash

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

References (Detailed Patterns)

参考文档（详细模式）

```
references/library-context.md
```
- AI Design Components library awareness
```
references/react-vite-template.md
```
- Full Vite + React setup
```
references/nextjs-template.md
```
- Next.js 14/15 patterns
```
references/python-fastapi-template.md
```
- FastAPI project structure
```
references/rust-axum-template.md
```
- Rust/Axum project structure
```
references/token-validation-rules.md
```
- Complete validation rules

```
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 (Complete Implementations)

示例（完整实现）

```
examples/react-dashboard/
```
- Full Vite + React dashboard
```
examples/nextjs-dashboard/
```
- Next.js App Router dashboard
```
examples/fastapi-dashboard/
```
- Python FastAPI dashboard
```
examples/rust-axum-dashboard/
```
- Rust Axum dashboard

```
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)

资源（模板）

```
assets/templates/react/
```
- React project templates
```
assets/templates/python/
```
- Python project templates
```
assets/templates/rust/
```
- Rust project templates

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

Application Assembly Workflow

应用组装工作流

Validate Components: Run
```
validate_tokens.py
```
on all generated CSS
Choose Framework: React/Vite, Next.js, FastAPI, or Rust based on requirements
Generate Scaffolding: Create project structure and configuration
Wire Imports: Set up entry point, import chain, barrel exports
Add Providers: ThemeProvider, ToastProvider at root
Connect Components: Import and compose feature components
Configure Build: vite.config, tsconfig, package.json
Final Validation: Build, type-check, lint
Document: README with setup and usage instructions

For library-specific patterns and complete context, see

references/library-context.md

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

如需了解库特定模式和完整上下文，请查看

references/library-context.md

。