shadcn-glass-ui: Glassmorphism поверх shadcn-ui без миграции

Привет! Представляю shadcn-glass-ui — React-библиотеку с glassmorphism-эффектами, которая устанавливается поверх существующих shadcn/ui проектов за 2 команды. Никакой миграции, никакого переписывания кода — просто добавьте glass-варианты ваших компонентов.

TL;DR

# Добавьте registry в components.json
npx shadcn@latest add @shadcn-glass-ui/button-glass

# Используйте рядом с обычными компонентами
import { Button } from '@/components/ui/button';
import { ButtonGlass } from '@/components/glass/ui/button-glass';

Ключевые фичи:

• 🔗 100% совместимость с shadcn/ui — одинаковые API, можно смешивать компоненты

• 🚀 Progressive enhancement — MVP на базовых компонентах → glassmorphism → кастомный бренд

• 🎨 57 production-ready компонентов — от кнопок до сложных составных компонентов

• 🔧 3-слойная токен-система — новая тема за 15 строк CSS, ноль хардкод-значений

• 🤖 AI-First документация — Context7 MCP, Claude Code, GitHub Copilot

• 📦 Два способа установки — через shadcn CLI или npm-пакет

• ♿ WCAG 2.1 AA — полная доступность, 1500+ автотестов

Проблема: как добавить glassmorphism в существующий проект?

Glassmorphism — это тренд из iOS/macOS: полупрозрачные элементы с backdrop-filter: blur(), создающие эффект матового стекла. Apple использует его с iOS 15, Microsoft — в Fluent Design.

Текущие решения:

• 📚 CSS-библиотеки (glass.css) — нет React-компонентов, нужно писать вручную

• 🔄 Полноценные UI-фреймворки — требуют полной миграции проекта

• ✍️ Кастомные компоненты — нужно писать всё с нуля и поддерживать

Что если у вас уже есть shadcn/ui проект? Переписывать всё на новый фреймворк? Копировать CSS из примеров и адаптировать каждый компонент?

Решение: Progressive Enhancement Workflow

shadcn-glass-ui реализует подход постепенного улучшения:

🏗️ Phase 1: MVP на базовых компонентах
   ↓ shadcn/ui — быстрый старт, проверка идеи
   
🎨 Phase 2: Добавление glassmorphism
   ↓ shadcn-glass-ui — визуальное улучшение без переписывания
   
🔧 Phase 3: Брендинг и кастомизация
   ↓ 3-слойная токен-система — тема под бренд за 15 строк

Для кого это идеально:

• Стартапы — быстрый MVP → потом полировка дизайна

• Агентства — шаблонный проект → кастомизация под клиента

• Enterprise — прототип на shadcn/ui → production-ready с брендингом

• Фрилансеры — один codebase → разные визуальные стили для клиентов

Drop-in совместимость

shadcn-glass-ui работает поверх существующих shadcn/ui проектов:

// ✅ Ваши существующие компоненты продолжают работать
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';

// ✅ Glass-варианты добавляются отдельно
import { ButtonGlass } from '@/components/glass/ui/button-glass';
import { InputGlass } from '@/components/glass/ui/input-glass';

function LoginForm() {
  return (
    <form className="space-y-4">
      {/* Стандартный shadcn/ui */}
      <Input placeholder="Email" />
      <Button variant="outline">Обычная кнопка</Button>
      
      {/* Glass-варианты с эффектами */}
      <InputGlass placeholder="Password" type="password" />
      <ButtonGlass variant="primary">Войти с glass-эффектом</ButtonGlass>
    </form>
  );
}

Никакой миграции:

• ✅ Те же пропсы: variant, size, className

• ✅ Те же коллбэки: onValueChange, onPressedChange

• ✅ Та же поддержка asChild для полиморфных компонентов

• ✅ Та же CLI-установка через npx shadcn add

Сравнение API

Дополнительно:

• 🎨 Glassmorphism-эффекты из коробки

• ⚙️ Дополнительные пропсы: loading, icon, intensity

• 🧩 Compound Components API для сложных компонентов

Установка: два способа

Способ 1: shadcn CLI (рекомендуется)

Библиотека добавлена в registry.directory.

Шаг 1: Добавьте registry в components.json:

{
  "registries": {
    "@shadcn-glass-ui": {
      "url": "https://raw.githubusercontent.com/Yhooi2/shadcn-glass-ui-library/main/public/r"
    }
  }
}

Шаг 2: Установите нужные компоненты:

# Одна команда — один компонент
npx shadcn@latest add @shadcn-glass-ui/button-glass
npx shadcn@latest add @shadcn-glass-ui/input-glass
npx shadcn@latest add @shadcn-glass-ui/modal-glass

# Или сразу несколько
npx shadcn@latest add @shadcn-glass-ui/button-glass @shadcn-glass-ui/input-glass

Преимущества:

• ✅ Минимальный бандл — только то, что используете

• ✅ Код копируется в проект — полный контроль

• ✅ Можно модифицировать под свои нужды

• ✅ Нет зависимости от npm-пакета

Способ 2: npm-пакет

npm install shadcn-glass-ui

import { ButtonGlass, InputGlass, ThemeProvider } from 'shadcn-glass-ui';
import 'shadcn-glass-ui/dist/styles.css';

function App() {
  return (
    <ThemeProvider defaultTheme="glass">
      <div className="p-8 space-y-4">
        <ButtonGlass variant="primary" size="lg">
          Кликни меня! ✨
        </ButtonGlass>
        <InputGlass placeholder="Введите текст..." />
      </div>
    </ThemeProvider>
  );
}

Преимущества:

• ✅ Быстрая установка одной командой

• ✅ Автоматические обновления через npm

• ✅ Tree-shaking — неиспользуемый код не попадёт в бандл

3-слойная токен-система: ноль хардкода

Главная архитектурная идея v2.0 — полное отсутствие хардкод-значений. Все цвета определяются через CSS variables на трёх уровнях:

┌─────────────────────────────────────────────────────────────┐
│ Layer 3: Component Tokens (280+ переменных)                 │
│ --btn-primary-bg, --modal-surface, --input-border           │
│         ↓ автоматически наследуют                           │
│ Layer 2: Semantic Tokens (~15 на тему)                      │
│ --semantic-primary, --semantic-surface, --semantic-border   │
│         ↓ ссылаются на                                      │
│ Layer 1: Primitive Tokens (225 OKLCH-цветов)                │
│ --oklch-purple-500, --oklch-slate-900                       │
└─────────────────────────────────────────────────────────────┘

Как это работает

Layer 1 — палитра из 225 OKLCH-цветов, определённая один раз для всех тем:

:root {
  --oklch-purple-500: oklch(0.55 0.25 270);
  --oklch-slate-900: oklch(0.15 0.02 250);
  --oklch-emerald-500: oklch(0.55 0.20 160);
  --oklch-cyan-400: oklch(0.70 0.15 195);
  /* ... ещё 221 цвет */
}

Layer 2 — каждая тема определяет ~15 семантических токенов:

[data-theme='glass'] {
  --semantic-primary: var(--oklch-purple-500);
  --semantic-surface: var(--oklch-slate-900);
  --semantic-text: var(--oklch-white-95);
  --semantic-border: var(--oklch-slate-700);
  --semantic-glow: var(--oklch-purple-500);
  /* ... ещё 10 токенов */
}

Layer 3 — компоненты автоматически наследуют из семантики:

:root {
  --btn-primary-bg: var(--semantic-primary);
  --btn-primary-glow: var(--semantic-glow);
  --modal-surface: var(--semantic-surface);
  --input-border: var(--semantic-border);
  /* ... 280+ компонентных токенов */
}

Новая тема за 15 строк CSS

Хотите создать неоновую тему? Переопределите только семантический слой:

[data-theme='neon'] {
  --semantic-primary: var(--oklch-cyan-400);
  --semantic-secondary: var(--oklch-purple-400);
  --semantic-surface: var(--oklch-black-10);
  --semantic-surface-elevated: var(--oklch-slate-950);
  --semantic-text: var(--oklch-white-98);
  --semantic-text-muted: var(--oklch-slate-400);
  --semantic-border: var(--oklch-cyan-500);
  --semantic-border-subtle: var(--oklch-slate-800);
  --semantic-glow: var(--oklch-cyan-400);
  --semantic-success: var(--oklch-emerald-500);
  --semantic-warning: var(--oklch-amber-500);
  --semantic-destructive: var(--oklch-red-500);
  --semantic-info: var(--oklch-blue-500);
}

Результат:

• ✅ Все 57 компонентов автоматически подхватят новые цвета

• ✅ Переключение темы мгновенное — меняется только CSS, без перерендера React

• ✅ 280+ компонентных токенов обновятся автоматически

Use Case: От MVP до Production

Сценарий: SaaS-стартап разрабатывает dashboard для аналитики.

Week 1-2: MVP на shadcn/ui

// Быстрый прототип с базовыми компонентами
import { Button, Input, Card } from '@/components/ui';

function Dashboard() {
  return (
    <div>
      <Card>
        <h2>Metrics</h2>
        <Input placeholder="Search..." />
        <Button>Export</Button>
      </Card>
    </div>
  );
}

Week 3: Добавляем glassmorphism

# Одна команда — visual upgrade
npx shadcn@latest add @shadcn-glass-ui/card-glass
npx shadcn@latest add @shadcn-glass-ui/button-glass
npx shadcn@latest add @shadcn-glass-ui/input-glass

// Меняем только импорты — API идентичный
import { ButtonGlass, InputGlass, CardGlass } from '@/components/glass/ui';

function Dashboard() {
  return (
    <div>
      <CardGlass> {/* Теперь с blur и glow эффектами */}
        <h2>Metrics</h2>
        <InputGlass placeholder="Search..." />
        <ButtonGlass>Export</ButtonGlass>
      </CardGlass>
    </div>
  );
}

Week 4: Брендинг под корпоративные цвета

/* 15 строк — вся компания в бренде */
[data-theme='company'] {
  --semantic-primary: var(--oklch-blue-600);      /* Корп. синий */
  --semantic-secondary: var(--oklch-orange-500);  /* Корп. оранжевый */
  --semantic-surface: var(--oklch-slate-900);     /* Тёмный фон */
  --semantic-glow: var(--oklch-blue-400);         /* Синее свечение */
  /* ... остальные 10 токенов */
}

Результат:

• ⚡ 0 переписанного кода — только замена импортов

• 🎨 Полный ребрендинг за 15 строк CSS

• 🚀 От идеи до production за месяц

До и после

AI-First: документация для ассистентов

В 2024–2025 разработчики активно используют AI-ассистенты (Claude, Copilot, ChatGPT). Проблема — большинство библиотек плохо индексируются: неявные API, устаревшая документация в обучающих данных.

shadcn-glass-ui оптимизирована для AI:

Пример работы с Context7 MCP

Context7 — это Model Context Protocol для индексации документации. AI-ассистенты запрашивают актуальную документацию в реальном времени вместо того, чтобы полагаться на устаревшие обучающие данные.

Типичный workflow:

Разработчик: "Добавь stepper в checkout flow с тремя шагами"

→ Claude Code запрашивает документацию через Context7 MCP
→ Context7 возвращает актуальную документацию StepperGlass
→ Claude видит: "compound API, linear mode для визардов, 3 варианта"
→ Claude генерирует корректный код:

<StepperGlass.Root mode="linear" currentStep={step}>
  <StepperGlass.Step value={0}>
    <StepperGlass.Trigger>
      <StepperGlass.Icon />
      Доставка
    </StepperGlass.Trigger>
    <StepperGlass.Content>
      <AddressForm />
    </StepperGlass.Content>
  </StepperGlass.Step>
  
  <StepperGlass.Step value={1}>
    <StepperGlass.Trigger>
      <StepperGlass.Icon />
      Оплата
    </StepperGlass.Trigger>
    <StepperGlass.Content>
      <PaymentForm />
    </StepperGlass.Content>
  </StepperGlass.Step>
  
  <StepperGlass.Step value={2}>
    <StepperGlass.Trigger>
      <StepperGlass.Icon />
      Подтверждение
    </StepperGlass.Trigger>
    <StepperGlass.Content>
      <OrderSummary />
    </StepperGlass.Content>
  </StepperGlass.Step>
</StepperGlass.Root>

Без Context7 AI пришлось бы:

1. Полагаться на устаревшую документацию из обучающих данных

2. Гадать по названию API (может step вместо value?)

3. Не знать про режим linear для визардов

4. Пропустить StepperGlass.Icon и другие подкомпоненты

Decision Trees для AI

Дополнительно в репозитории есть деревья решений — какой компонент выбрать для конкретной задачи:

Нужно показать метрику?
├─ Один показатель → MetricCardGlass
├─ Сравнение нескольких → MetricsGridGlass
├─ С динамикой (sparkline) → SparklineGlass
└─ Круговая диаграмма → CircularMetricGlass

Нужна модалка?
├─ Простое подтверждение → AlertGlass
├─ Форма с несколькими полями → ModalGlass.Root (compound)
└─ Toast-уведомление → NotificationGlass

Rich JSDoc для всех компонентов

Каждый компонент содержит детальную JSDoc с примерами:

/**
 * Glass-styled button with glassmorphism effect
 * 
 * @example
 * // Primary button with loading state
 * <ButtonGlass variant="primary" size="lg" loading>
 *   Загрузка...
 * </ButtonGlass>
 * 
 * @example
 * // As link with React Router (polymorphic)
 * <ButtonGlass asChild>
 *   <Link to="/profile">Профиль</Link>
 * </ButtonGlass>
 * 
 * @example
 * // With icon
 * <ButtonGlass icon={<CheckIcon />} variant="ghost">
 *   Сохранено
 * </ButtonGlass>
 * 
 * @accessibility 
 * - Keyboard navigation (Enter, Space)
 * - Focus visible ring (2px inner + 4px outer)
 * - Touch target minimum 44x44px (Apple HIG)
 * - Loading state disables interaction
 */
export const ButtonGlass: React.FC<ButtonGlassProps> = ({ 
  variant = "default",
  size = "md",
  loading = false,
  icon,
  asChild = false,
  ...props 
}) => { /* ... */ };

AI видит примеры прямо в типах и генерирует корректный код с первого раза.

Компоненты: 57 production-ready

shadcn-glass-ui предоставляет 57 компонентов в 6 категориях:

Три встроенные темы

• Glass (тёмная) — классический glassmorphism с фиолетовыми акцентами и glow-эффектами

• Light (светлая) — минималистичная светлая тема с тонкими стеклянными эффектами

• Aurora (градиенты) — яркие градиенты в стиле северного сияния

import { ThemeProvider, useTheme } from 'shadcn-glass-ui';

function ThemeSwitcher() {
  const { theme, cycleTheme } = useTheme();
  
  return (
    <button onClick={cycleTheme}>
      Текущая тема: {theme}
    </button>
  );
}

Compound Components API

Сложные компоненты используют паттерн Compound Components для максимальной гибкости:

<ModalGlass.Root open={isOpen} onOpenChange={setIsOpen}>
  <ModalGlass.Overlay />
  <ModalGlass.Content>
    <ModalGlass.Header>
      <ModalGlass.Title>Подтверждение действия</ModalGlass.Title>
      <ModalGlass.Description>
        Это действие нельзя будет отменить
      </ModalGlass.Description>
      <ModalGlass.Close />
    </ModalGlass.Header>
    
    <ModalGlass.Body>
      <p>Вы уверены, что хотите удалить этот элемент?</p>
    </ModalGlass.Body>
    
    <ModalGlass.Footer>
      <ButtonGlass variant="ghost" onClick={() => setIsOpen(false)}>
        Отмена
      </ButtonGlass>
      <ButtonGlass variant="destructive" onClick={handleDelete}>
        Удалить
      </ButtonGlass>
    </ModalGlass.Footer>
  </ModalGlass.Content>
</ModalGlass.Root>

Преимущества:

• 🧩 Гибкая композиция — можно пропустить Footer или добавить Description

• 📦 Tree-shaking — неиспользуемые части не попадают в бандл

• 📖 Понятная структура — DOM-иерархия видна без документации

Полиморфные компоненты (asChild)

Все интерактивные компоненты поддерживают паттерн asChild из Radix UI:

import { ButtonGlass } from 'shadcn-glass-ui';
import { Link } from 'react-router-dom';

// Рендерим button как React Router Link
<ButtonGlass asChild variant="primary">
  <Link to="/dashboard">Перейти в панель</Link>
</ButtonGlass>

// Рендерим button как обычный <a>
<ButtonGlass asChild variant="ghost">
  <a href="https://github.com" target="_blank" rel="noopener">
    GitHub
  </a>
</ButtonGlass>

// Рендерим button как кастомный компонент
<ButtonGlass asChild>
  <motion.button
    whileHover={{ scale: 1.05 }}
    whileTap={{ scale: 0.95 }}
  >
    Анимированная кнопка
  </motion.button>
</ButtonGlass>

Доступность и тестирование

Все компоненты соответствуют WCAG 2.1 уровня AA:

• ✅ Контраст — минимум 4.5:1 для текста

• ✅ Клавиатура — полная навигация через Tab, Enter, Arrow keys

• ✅ Touch target — минимум 44×44px (Apple Human Interface Guidelines)

• ✅ Screen readers — правильные ARIA-атрибуты и семантический HTML

• ✅ Focus indicators — 2px внутреннее + 4px внешнее кольцо

• ✅ Reduced motion — автоотключение анимаций при prefers-reduced-motion

Тестовое покрытие: 1500+ автотестов

Design System Compliance проверяет:

• Все компоненты используют токены (не хардкод)

• Touch targets минимум 44×44px

• Цветовой контраст 4.5:1+

• Правильная структура compound components

Visual Regression отлавливает:

• Случайные изменения в отображении

• Баги в темизации

• Проблемы с responsive-дизайном

CLI-утилиты

shadcn-glass-ui поставляется с CLI для быстрой работы:

# Информация о компоненте (fuzzy search)
npx shadcn-glass-ui info button
npx shadcn-glass-ui info modal

# Список всех компонентов
npx shadcn-glass-ui list

# Фильтр по категории
npx shadcn-glass-ui list --category=core
npx shadcn-glass-ui list --category=composite

Ссылки и ресурсы

• 🌐 Live Demo: Storybook

• 💻 GitHub: Repository

• 📦 npm: Package

• 📚 Документация:

  • Getting Started

  • AI Usage Guide

  • Token Architecture

  • Registry Usage

• 🤖 Context7: Автоиндексация

Заключение

shadcn-glass-ui решает четыре главные проблемы:

1. "Как добавить glassmorphism без переписывания проекта?"
   → Drop-in совместимость с shadcn/ui, установка через CLI

2. "Как быстро перейти от MVP к production-ready дизайну?"
   → Progressive enhancement: базовые компоненты → glassmorphism → брендинг

3. "Как создавать темы без копипасты сотен значений?"
   → 3-слойная токен-система, новая тема за 15 строк

4. "Как сделать библиотеку понятной для AI-ассистентов?"
   → Context7 MCP, rich JSDoc, decision trees

Типичный workflow:

Week 1-2: Прототип на shadcn/ui
    ↓
Week 3: Добавляем glassmorphism (npm install)
    ↓
Week 4: Кастомная тема под бренд (15 строк CSS)
    ↓
Production-ready за месяц 🚀

Буду рад фидбеку и контрибьюшенам! Вопросы — в комментариях или GitHub Issues.

---

P.S. Если статья была полезна — поставьте ⭐ на GitHub!