Продвинутый

design-system

Алексей Кузнецов
Алексей Кузнецов
Системный администратор2 ноября 2026 г.12 мин чтения

Коллекция файлов DESIGN.md, проанализированная по системам дизайна популярных брендов. Позволяет внедрить соответствующий UI в проект с помощью VoltAgent.

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 может развертываться в контейнерах:

dockerfile
FROM 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

Ограничения и советы

Технические ограничения

  1. Версионность токенов: DESIGN.md файлы могут быстро устареть. Всегда указывайте версию дизайн-системы в вашем конфигурационном файле:
json
{
  "design_system": {
    "name": "Company Design System",
    "version": "2.4.1",
    "last_updated": "2024-01-15",
    "tokens": {
      "colors": {
        "primary": "#0066CC",
        "secondary": "#666666"
      }
    }
  }
}
  1. Ограничения 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 в ваш репозиторий дизайн-системы

Распространенные ошибки

  1. Недостаточная валидация: Пропуск проверки типов токенов приводит к "битым" UI компонентам. Всегда используйте строгую валидацию:
bash
# Установите и используйте валидатор токенов
npm install -D joi
node scripts/validate-tokens.js
  1. Игнорирование темной темы: Многие 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 формате. Это позволяет разработчикам быстро импортировать токены в любые проекты и использовать их как базу для адаптации под свои нужды. Процесс полностью автоматизирован, и изменения применяются без участия человека.

Поделиться:TelegramX / TwitterVK

Читайте также