design-system
Коллекция файлов DESIGN.md, проанализированная по системам дизайна популярных брендов. Позволяет внедрить соответствующий UI в проект с помощью VoltAgent.
Анализ дизайн-систем
Популярные бренды
Когда речь заходит о дизайн-системах, первым приходит в голову Figma — это как центральный рынок, где продавцы выставляют свои товары. Airbnb, например, используют дизайн-токены в SCSS, чтобы поддерживать единообразие цветов и типографики по всей вёрстке. Они хранят всё в репозитории, который обновляется автоматически при изменении базовых значений.
Spotify пошёл другим путём: их дизайн-система называется "Spotify Style". В ней используется CSS-in-JS подход с использованием Styled Components. Это позволяет им динамически изменять тему приложения без перезагрузки страницы — как зимний режим, который сам меняет цвета в зависимости от времени суток.
Airbnb не ограничиваются только SCSS — они также используют PostCSS плагины для автономного генерации дизайн-токенов. Вот пример конфигурации:
js// postcss.config.js
module.exports = {
plugins: {
'postcss-simple-vars': {},
'postcss-calc': {},
'cssnano': { preset: 'default' }
}
}
Google Material Design — это классика, которая доказывает, что простота иногда лучше всего. Они используют CSS переменные и генерируют дизайн-токены в JSON формате. Это позволяет разработчикам быстро импортировать токены в любой проект:
bash# Сгенерировать токены из Figma
npm install -g @figma/plugin-token-generator
figma-token-generator --file-id=YOUR_FILE_ID --output=design-tokens.json
Некоторые бренды, например, Uber, используют Figma как единую систему для хранения всех компонентов и токенов. Это как общая кухня, где каждый знает, где лежит ложка и вилка. Такой подход упрощает процесс редактирования и синхронизации изменений между дизайнерами и разработчиками.
Возможности VoltAgent
VoltAgent — это инструмент, который позволяет автоматически генерировать UI на основе DESIGN.md файлов из awesome-design-md. Это как умный помощник, который читает ваши дизайн-токены и создаёт компоненты без лишних действий.
Вот базовый пример использования:
bash# Установите VoltAgent
npm install -g voltagent-cli
# Инициализируйте проект
voltagent init
# Подключите DESIGN.md файл
voltagent connect ./DESIGN.md
VoltAgent поддерживает несколько форматов дизайн-токенов, включая Figma, JSON и SCSS. Он может автоматически генерировать компоненты для React, Vue и Angular. Это позволяет быстро создавать UI, который соответствует вашей дизайн-системе.
Одна из ключевых возможностей — это автоматическое обновление токенов. Когда вы изменяете дизайн-токены в Figma, VoltAgent синхронизирует изменения с вашим проектом:
js// Конфигурация VoltAgent
{
"source": "./DESIGN.md",
"targets": [
{
"framework": "react",
"output": "./src/components/ui"
},
{
"framework": "vue",
"output": "./src/components/ui"
}
],
"autoUpdate": true
}
VoltAgent также интегрируется с CI/CD пайплайнами, что позволяет автоматически проверять и деплоить UI компоненты. Это как автоматическая сборочная линия, которая никогда не спит.
Для тех, кто работает с Proxmox или другими виртуальными окружениями, VoltAgent может развертываться в контейнерах:
dockerfileFROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . EXPOSE 3000 CMD ["npm", "start"]
Если вам нужно генерировать дизайн-токены из Figma напрямую, VoltAgent может подключиться к Figma API и извлекать данные:
js// Пример использования Figma API через VoltAgent
const { FigmaConnector } = require('voltagent/connectors');
const connector = new FigmaConnector({
fileId: 'YOUR_FIGMA_FILE_ID',
token: process.env.FIGMA_API_TOKEN
});
connector.getTokens()
.then(tokens => {
console.log('Design tokens:', tokens);
})
.catch(err => {
console.error('Error fetching tokens:', err);
});
VoltAgent также поддерживает мониторинг изменений в DESIGN.md файлах. Он может автоматически запускать генерацию компонентов, когда вы изменяете дизайн-токены:
js// watch-design-md.js
const fs = require('fs');
const { VoltAgentGenerator } = require('voltagent');
const watchFile = './DESIGN.md';
const generator = new VoltAgentGenerator();
fs.watchFile(watchFile, async (curr, prev) => {
if (curr.mtime !== prev.mtime) {
console.log('DESIGN.md changed, regenerating UI...');
await generator.generateFromDesignMd(watchFile);
}
});
Для интеграции с системой мониторинга, VoltAgent может отправлять уведомления в Slack или Discord:
js// Отправка уведомления в Slack
const { WebhookClient } = require('slack-webhook');
const slackWebhook = new WebhookClient('https://hooks.slack.com/services/YOUR/WEBHOOK/URL');
slackWebhook.send({
text: 'UI components have been regenerated successfully!'
}).catch(err => {
console.error('Failed to send Slack notification:', err);
});
VoltAgent также поддерживает автоматическое создание документации для сгенерированных компонентов. Это позволяет быстро создавать документацию для новых функций:
js// Генерация документации
const { DocumentationGenerator } = require('voltagent');
const docGen = new DocumentationGenerator({
outputPath: './docs/components',
template: 'markdown'
});
docGen.generate(componentData)
.then(() => {
console.log('Documentation generated successfully');
})
.catch(err => {
console.error('Documentation generation failed:', err);
});
Все эти возможности делают VoltAgent универсальным инструментом для работы с дизайн-системами. Он позволяет быстро создавать UI компоненты, поддерживать их в актуальном состоянии и интегрировать их в существующие рабочие процессы. Это как иметь личного помощника, который знает всё о вашей дизайн-системе и может мгновенно создавать компоненты по вашему запросу.
VoltAgent/awesome-design-md: Анализ дизайн-систем для ген... Использование DESIGN.md из awesome-design-md для генерации UI через AI-агентов Использование DESIGN.md для генерации UI через AI-агентов Использование DESIGN.md из awesome-design-md для генерации UI через AI-агентов Использование DESIGN.md для генерации UI через AI
Интеграция в проект
Интеграция в проект
Подготовка кода
Перед тем как запускать генерацию UI, подготовьте структуру проекта так, чтобы VoltAgent мог легко найти и использовать DESIGN.md файлы. Минимальный набор:
project/
├── src/
│ ├── components/
│ │ ├── buttons/
│ │ │ └── index.tsx
│ │ └── cards/
│ │ └── index.tsx
│ ├── styles/
│ │ ├── tokens.css
│ │ └── variables.css
│ └── DESIGN.md
└── voltagent.config.ts
В DESIGN.md укажите токены, которые используете в проекте:
markdown# DESIGN.md
## Цвета
:root {
--color-primary: #0d6efd;
--color-secondary: #6c757d;
--color-success: #198754;
}
## Шрифты
--font-family-base: "Inter", system-ui, sans-serif;
--font-size-base: 16px;
--font-weight-normal: 400;
В конфигурации VoltAgent укажите путь к DESIGN.md и директорию с компонентами:
typescript// voltagent.config.ts
export default defineConfig({
project: {
root: "./src",
designSystem: "./src/DESIGN.md",
components: "./src/components"
}
});
Запуск генерации UI
После подготовки кода запустите генерацию:
bash# Установите зависимости, если ещё не установили
npm install @voltagent/core
# Запустите генерацию на основе DESIGN.md
npx voltagent generate-ui --watch
VoltAgent проанализирует DESIGN.md, сопоставит токены с вашими CSS переменными и сгенерирует компоненты, готовые к использованию:
bash# Ручная генерация без режима наблюдения
npx voltagent generate-ui
# Сгенерированные компоненты появятся в:
src/components/ui/
├── button.tsx
├── card.tsx
└── modal.tsx
Генерация создаст компоненты, которые соответствуют вашей дизайн-системе:
tsx// src/components/ui/button.tsx
import React from 'react';
import { cva, type VariantProps } from 'class-variance-authority';
const buttonVariants = cva(
'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors',
{
variants: {
variant: {
default: 'bg-primary text-primary-foreground hover:bg-primary/90',
destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
outline: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
ghost: 'hover:bg-accent hover:text-accent-foreground',
link: 'text-primary underline-offset-4 hover:underline',
},
size: {
default: 'h-10 px-4 py-2',
sm: 'h-9 rounded-md px-3',
lg: 'h-11 rounded-md px-8',
icon: 'h-10 w-10',
},
},
defaultVariants: {
variant: 'default',
size: 'default',
},
}
);
export interface ButtonProps
extends React.ButtonHTMLAttributes<HTMLButtonElement>,
VariantProps<typeof buttonVariants> {}
const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
({ className, variant, size, ...props }, ref) => {
return (
<button
className={buttonVariants({ variant, size, className })}
ref={ref}
{...props}
/>
);
}
);
Button.displayName = 'Button';
export { Button, buttonVariants };
После генерации вы можете сразу использовать эти компоненты в своих страницах:
tsx// src/pages/home.tsx
import { Button } from '@/components/ui/button';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
export default function HomePage() {
return (
<div className="p-6">
<h1 className="text-3xl font-bold mb-6">Добро пожаловать</h1>
<div className="grid grid-cols-1 md:grid-cols-2 gap-6">
<Card>
<CardHeader>
<CardTitle>Быстрое начало</CardTitle>
</CardHeader>
<CardContent>
<p className="mb-4">VoltAgent проанализировал DESIGN.md и сгенерировал компоненты, соответствующие вашей дизайн-системе.</p>
<Button variant="default">Начать работу</Button>
</CardContent>
</Card>
</div>
</div>
);
}
Для интеграции с Figma используйте коннектор дизайн-токенов:
typescript// voltagent.config.ts
export default defineConfig({
project: {
root: "./src",
designSystem: "./src/DESIGN.md",
components: "./src/components"
},
integrations: {
figma: {
tokenEndpoint: "https://api.figma.com/v1/files/{fileKey}/tokens",
apiKey: process.env.FIGMA_API_KEY
}
}
});
После успешной генерации UI вы получите полностью типизированную, готовую к использованию библиотеку компонентов, которая:
- Соответствует вашим дизайн-токенам из DESIGN.md
- Поддерживает тему оформления (светлая/тёмная)
- Имеет типизацию TypeScript
- Интегрируется с системой сборки вашего проекта
VoltAgent/awesome-design-md: Анализ дизайн-систем для ген... Использование DESIGN.md из awesome-design-md для генерации UI через AI-агентов Использование DESIGN.md для генерации UI через AI-агентов
Практическое применение
Практическое применение
Шаги внедрения
Шаг 1: Анализ DESIGN.md файлов
Начните с анализа коллекции DESIGN.md файлов, чтобы понять структуру дизайн-системы. Вот как это сделать с помощью VoltAgent:
bash# Клонируйте репозиторий с DESIGN.md файлами
git clone https://github.com/VoltAgent/awesome-design-md.git
cd awesome-design-md
# Проанализируйте файлы с помощью VoltAgent CLI
volt-agent analyze DESIGN.md --output structured-config.json
Результатом будет структурированный JSON-файл с токенами дизайна, компонентами и правилами стилизации. Это как IKEA-инструкцию для вашей дизайн-системы — всё под рукой, но нужно собирать по пунктам.
Шаг 2: Настройка VoltAgent агента
Создайте конфигурационный файл агента, который будет использовать ваши DESIGN.md токены:
yaml# volt-agent-config.yaml
agent:
name: "ui-generator"
version: "1.0"
design_system:
source: "./structured-config.json"
format: "design-tokens"
provider: "voltagent"
ui_generation:
framework: "react"
style_engine: "styled-components"
theme_extraction: true
validation:
strict_mode: true
lint_tokens: true
Шаг 3: Генерация UI компонентов
Используйте VoltAgent для автоматической генерации компонентов на основе DESIGN.md:
bash# Создайте директорию проекта
mkdir my-app && cd my-app
npm init -y
npm install react react-dom styled-components volt-agent
# Создайте генератор компонентов
cat > generate-ui.js << 'EOF'
const { VoltAgentGenerator } = require('volt-agent');
const generator = new VoltAgentGenerator({
configPath: '../volt-agent-config.yaml',
outputDir: './src/components',
template: 'functional-react'
});
async function generate() {
await generator.loadDesignSystem('./structured-config.json');
await generator.generateAllComponents();
console.log('UI компоненты сгенерированы успешно');
}
generate().catch(console.error);
EOF
node generate-ui.js
Шаг 4: Валидация и тестирование
Проверьте сгенерированные компоненты на соответствие дизайн-системе:
bash# Установите инструменты валидации
npm install -D stylelint @stylistic/eslint-parser
# Создайте файл валидации
cat > stylelint.config.js << 'EOF'
module.exports = {
plugins: ['@stylistic'],
rules: {
'@stylistic/no-unused-css-properties': true,
'@stylistic/color-hex-length': 'short',
'@stylistic/indent': ['error', 2],
'@stylistic/quotes': ['error', 'single']
}
};
EOF
# Запустите валидацию
npm run lint
Ограничения и советы
Технические ограничения
- Версионность токенов: DESIGN.md файлы могут быстро устареть. Всегда указывайте версию дизайн-системы в вашем конфигурационном файле:
json{
"design_system": {
"name": "Company Design System",
"version": "2.4.1",
"last_updated": "2024-01-15",
"tokens": {
"colors": {
"primary": "#0066CC",
"secondary": "#666666"
}
}
}
}
- Ограничения Figma API: При импорте токенов из Figma учитывайте лимиты API (100 запросов в час для бесплатного тарифа). Для крупных дизайн-систем используйте локальный кэш:
javascript// cache-tokens.js
const fs = require('fs');
const path = require('path');
class TokenCache {
constructor(cacheFile) {
this.cacheFile = cacheFile;
this.cache = this.loadCache();
}
loadCache() {
try {
return JSON.parse(fs.readFileSync(this.cacheFile, 'utf8'));
} catch {
return { tokens: {}, timestamp: 0 };
}
}
getTokens() {
const now = Date.now();
const hour = 3600000;
if (now - this.cache.timestamp > hour) {
return null; // Кэш устарел
}
return this.cache.tokens;
}
setTokens(tokens) {
this.cache = {
tokens,
timestamp: Date.now()
};
fs.writeFileSync(this.cacheFile, JSON.stringify(this.cache, null, 2));
}
}
module.exports = TokenCache;
Лучшие практики
- Используйте семантические имена токенов: Вместо
color-1используйтеprimary-action, чтобы сохранить предсказуемость конфигурации - Документируйте исключения: Отслеживайте токены, которые нужно переопределить для конкретных компонентов
- Настройте CI/CD: Автоматически проверяйте DESIGN.md файлы при каждом PR в ваш репозиторий дизайн-системы
Распространенные ошибки
- Недостаточная валидация: Пропуск проверки типов токенов приводит к "битым" UI компонентам. Всегда используйте строгую валидацию:
bash# Установите и используйте валидатор токенов
npm install -D joi
node scripts/validate-tokens.js
- Игнорирование темной темы: Многие DESIGN.md файлы включают токены темной темы, но разработчики часто забывают их подключить:
css/* src/components/ThemeWrapper.jsx */
import React from 'react';
import { ThemeProvider } from 'styled-components';
const theme = {
light: {
background: '#ffffff',
text: '#333333'
},
dark: {
background: '#1a1a1a',
text: '#ffffff'
}
};
export const AppTheme = ({ children, mode = 'light' }) => (
<ThemeProvider theme={theme[mode]}>
{children}
</ThemeProvider>
);
Советы по производительности
- Кэшируйте анализ DESIGN.md: Для больших коллекций DESIGN.md файлов кэшируйте результат анализа, чтобы избежать повторной парсинга
- Используйте сплит-бандл: Разделите генерацию UI на отдельные бандлы для компонентов, которые используются редко
- Настройте параллельную обработку: VoltAgent поддерживает параллельную генерацию компонентов:
bash# Установите parallel-processing
npm install -D npm-run-all
# Создайте скрипт параллельной генерации
cat > scripts/generate-parallel.js << 'EOF'
const { execSync } = require('child_process');
const components = ['Button', 'Input', 'Card', 'Modal'];
components.forEach(component => {
execSync(`volt-agent generate ${component} --output ./src/components/${component}`);
});
EOF
npm run generate-parallel
Заключение
Практическое применение DESIGN.md файлов с помощью VoltAgent превращает статическую документацию в динамичную, поддерживаемую систему генерации UI. Ключ к успеху — системный подход: валидация токенов, кэширование результатов и автоматизация CI/CD процессов. Помните, что предсказуемость конфигурации важнее скорости — хорошо настроенная система служит годами без особого вмешательства.
VoltAgent/awesome-design-md: Анализ дизайн-систем для ген... Использование DESIGN.md из awesome-design-md для генерации UI через AI-агентов Использование DESIGN.md для генерации UI через AI-агентов Использование DESIGN.md из awesome-design-md для генерации UI через AI-агентов Использование DESIGN.md для генерации UI через AI
Часто задаваемые вопросы
### Как популярные бренды реализуют свои дизайн-системы?
Airbnb хранит дизайн-токены в SCSS для единообразия цветов и типографики по всей вёрстке. Spotify использует CSS-in-JS с Styled Components для динамической темы приложения, которая меняет цвета в зависимости от времени суток. Google Material Design генерирует токены в JSON через CSS переменные. Uber объединяет Figma, компоненты и токены в единую систему, где каждый знает, где лежит нужный элемент.
### Что представляет собой VoltAgent и как он упрощает работу с дизайн-системами?
VoltAgent автоматически генерирует UI на основе DESIGN.md файлов. Инструмент синхронизирует изменения между дизайнерами и разработчиками, обеспечивая актуальность конфигураций. Это сокращает ручную работу и снижает риск рассинхрона между дизайн- и разработочными процессами.
### Как получить дизайн-токены из Figma для использования в проекте?
Используйте плагин @figma/plugin-token-generator для создания JSON-файла с токенами. Затем импортируйте токены через CSS переменные или другие методы. Так вы получите единообразие дизайна без ручного копирования и гарантированную синхронизацию изменений.
### Зачем нужны CSS переменные при работе с дизайн-системами?
CSS переменные позволяют легко менять цвета, шрифты и другие параметры везде в приложении. Они обеспечивают предсказуемость и упрощают поддержку: изменение одного токена автоматически обновляет все компоненты. Это значительно быстрее, чем редактировать стили вручную.
### Как Google Material Design генерирует дизайн-токены?
Google использует CSS переменные и создаёт токены в JSON формате. Это позволяет разработчикам быстро импортировать токены в любые проекты и использовать их как базу для адаптации под свои нужды. Процесс полностью автоматизирован, и изменения применяются без участия человека.