# Дизайн-система HeroUI

## Предварительный просмотр интерфейса дизайн-системы HeroUI

Изменяйте качество с помощью встроенного слайдера, переключайте метаданные и оформление, применяйте локальный рецепт. Кодирование и загрузка не имитируются.

## Справочник по дизайн-системе HeroUI

Тема по умолчанию HeroUI 3.2.6 проверена по @heroui/styles/dist/themes/default/variables.css. Приведённые ниже значения OKLCH дословно взяты из пакета. Цвета иллюстрации и типографика — решения приложения, а не токены бренда HeroUI.

### Семантические поверхности и контраст

| Название / правило | Значение / конфигурация | Применение |
| --- | --- | --- |
| --background | oklch(0.9702 0 0) | Светлый фон страницы; в тёмной теме — oklch(12% 0.005 285.823). |
| --foreground | var(--eclipse) | Цвет текста для светлой темы; в тёмной теме используется --snow. |
| --surface | var(--white) | Светлый фон карточки; в тёмной теме — oklch(0.2103 0.0059 285.89). |
| --overlay | var(--white) | Фон плавающего слоя. Его роль отличается от поверхности, даже если в светлой теме значения совпадают. |
| --accent | oklch(0.6204 0.195 253.83) | Выбранное состояние переключателя, заливка слайдера и основная кнопка. |
| --accent-foreground | var(--snow) | Текст на сплошном акцентном фоне. |
| --muted | oklch(0.5517 0.0138 285.94) | Вторичный текст; в тёмной теме — oklch(70.5% 0.015 286.067). |
| --border | oklch(90% 0.004 286.32) | Границы для светлой темы; в тёмной теме — oklch(28% 0.006 286.033). |
| --focus | var(--accent) | Индикация клавиатурного фокуса. |
| --field-background | var(--white) | Поверхности полей для светлой темы; в тёмной теме используется значение eclipse. |
### Форма, отступы и состояния

| Название / правило | Значение / конфигурация | Применение |
| --- | --- | --- |
| --spacing | 0.25rem | Базовая единица отступа; 4px при корневом размере 16px. |
| --radius | 0.5rem | Примитив радиуса по умолчанию; 8px при корневом размере 16px. |
| --field-radius | calc(var(--radius) * 1.5) | Радиус полей по умолчанию — 12px. |
| --border-width | 1px | Толщина границы по умолчанию. |
| --field-border-width | 0px | Для полей по умолчанию не используется контурная граница. |
| --disabled-opacity | 0.5 | Визуальное оформление отключённого состояния; по-прежнему используйте свойство компонента isDisabled. |
| --ring-offset-width | 2px | Расстояние между элементом управления и кольцом фокуса. |
| --tooltip-delay | 1500ms | Начальная задержка перед появлением подсказки в пакете по умолчанию. |
| --tooltip-close-delay | 500ms | Задержка перед закрытием подсказки. |
### Типографика и компоновка приложения

| Название / правило | Значение / конфигурация | Применение |
| --- | --- | --- |
| body | 16px / 1.5, Arial, Helvetica, sans-serif | Явно выбранный для предпросмотра шрифт; это не обязательный шрифт HeroUI. |
| h1 | 32px / 1.15; 28px below 700px | Исходная шкала заголовков страницы. |
| h2 | 24px / 1.25 | Заголовок настроек экспорта. |
| helper text | 13px / inherited 1.5 | Пояснение к качеству и локальный результат. |
| desktop gap | 24px | Сетка из двух колонок для иллюстрации и настроек. |
| mobile breakpoint | 700px | Исходное адаптивное правило, а не токен контрольной точки HeroUI. |
| card radius | calc(var(--radius) * 3) | Композиция приложения размером 24px с использованием официального примитива. |
### Настройка встроенных элементов управления

| Название / правило | Значение / конфигурация | Применение |
| --- | --- | --- |
| quality range | minValue=10; maxValue=100; step=5 | Диапазон рецепта кодировщика приложения, а не значение по умолчанию HeroUI. |
| Slider | value + onChange | Управляемое числовое значение обновляет результат и рецепт. |
| Switch | isSelected + onChange | Управляемое логическое значение сохраняет единый источник данных. |
| Button | onPress | Обработчик события нажатия Aria в React поддерживает активацию указателем и клавиатурой. |
## Полное руководство по дизайн-системе HeroUI

Практическое руководство по выбору, применению и оценке этой системы для реального интерфейса.

Подробные рекомендации, отправная точка для реализации и ссылки на источники.

## Дизайн-система HeroUI v3 и Export Studio

### Компоненты React и семантическая таблица стилей

> Этот пример рассчитан на HeroUI 3.2.6. Элементы управления — компоненты React, использующие поведение React Aria, а визуальный слой задаётся через @heroui/styles. Для официального быстрого старта требуются React 19 и Tailwind CSS v4. В конфигурации v3 это приложение не оборачивается в устаревшую конструкцию HeroUIProvider. Смешение руководств по v2 с этим составным компонентом API часто приводит к отсутствующим или неправильно оформленным элементам управления.

В этом примере редактируется рецепт экспорта: слева находится иллюстрация, справа — настройки качества и метаданных. Иллюстрация нарисована с помощью оригинального CSS. Это не изображение, обработанное библиотекой. При применении рецепта выбранные настройки сохраняются в локальном состоянии React; размер файла и результат загрузки намеренно не выдумываются.

Прочитать вспомогательную спецификацию

## Семантические цвета и оформление дизайн-системы HeroUI

### Разделяйте холст, поверхности и плавающие слои

Используйте --background для внешнего холста, --surface — для карточек с иллюстрацией и настройками, а --overlay — для будущего всплывающего меню или диалогового окна. Это семантические роли, даже если в светлой теме две из них отображаются белым цветом. В тёмной теме холст и приподнятые поверхности различаются. В примере класс dark переключается у document.documentElement, чтобы все дочерние элементы использовали одну и ту же область действия темы.

Для заливки слайдера и выбранного состояния переключателя используется роль акцента. Элементы управления со сплошным акцентным фоном сочетают её с --accent-foreground. Для вторичного текста используется --muted, а не пониженная непрозрачность всей карточки. Иллюстрация сохраняет собственную тёплую палитру в обоих режимах оформления, поскольку это содержимое, а не интерактивный интерфейс.

Прочитать вспомогательную спецификацию

## Типографика и отступы дизайн-системы HeroUI

### Явно задавайте масштаб приложения

Стилизация HeroUI интегрируется с утилитами Tailwind, но на этой странице не вводится единый обязательный шрифт HeroUI. В оригинальном CSS выбраны Arial/Helvetica, основной шрифт размером 16px и межстрочный интервал 1.5. В узком макете размер заголовка уменьшается с 32px до 28px; заголовок настроек — 24px. В справочной таблице значения приложения отделены от переменных пакета.

Официальный примитив --spacing равен 0.25rem. В этой композиции используются отступ 16px внутри рецепта, 24px между колонками и вокруг карточек на настольных экранах, а также отступ 32px вокруг холста на настольном экране. Радиус поля рассчитан на основе официального примитива радиуса 8px. Радиус карточки намеренно втрое больше этого примитива, поэтому значение 24px — производное значение приложения, а не заявленное значение Card по умолчанию.

Прочитать вспомогательную спецификацию

## Создание полноценного слайдера в дизайн-системе HeroUI

### Объедините структуру и владение значением

Корневой Slider управляет свойствами value, onChange, minValue, maxValue и step. Его Label задаёт доступное имя. Slider.Output отображает то же значение, а Slider.Track содержит Slider.Fill и Slider.Thumb. Если не добавить эти видимые части, компонент может работать без ожидаемой дорожки или ползунка. В этом примере используется одно число, а не массив диапазона.

Качество ограничено диапазоном от 10 до 100 с шагом пять. Эти ограничения — локальные решения продукта. По умолчанию HeroUI использует диапазон от 0 до 100 с шагом один. Универсальной надёжной зависимости между значением качества и размером файла нет, поэтому пояснение описывает компромисс, не выдумывая оценку размера файла. Чтобы использовать несколько ползунков, передайте массив чисел и задайте каждому ползунку правильный индекс.

1. Установите фокус на слайдере качества и нажмите клавишу со стрелкой, чтобы изменить значение на один шаг.

2. Убедитесь, что отображаемое значение и текущий рецепт обновляются одновременно.

3. Примените рецепт, а затем снова переместите слайдер, чтобы различить черновик и применённый снимок настроек.

Прочитать вспомогательную спецификацию

## Создание логического параметра в дизайн-системе HeroUI

### Переключатель состоит из управляющей части и содержимого

Для настройки метаданных компонент Switch использует свойства isSelected и onChange. В установленной версии 3.2.6 Switch.Content оборачивает Switch.Control и Label; Switch.Control содержит Switch.Thumb. Description располагается рядом с Switch.Content и служит пояснением для всего поля. Такая структура соответствует установленному исходному коду: анатомия SwitchField/SwitchButton отличается от примеров в некоторых более ранних документах по v3. Описание поясняет значение логического параметра вместо того, чтобы полагаться на синюю дорожку переключателя в выбранном состоянии. Одно состояние метаданных управляет и встроенным элементом, и текстовым рецептом.

Не объединяйте этот логический параметр с операцией применения. Переключение метаданных сразу изменяет текущий черновик; нажатие «Применить для предпросмотра» сохраняет снимок настроек. Сброс восстанавливает качество 80, удаляет метаданные и очищает снимок. Индикатор сохранённого состояния не используется повторно для другого черновика. При подключении кодировщика передавайте ему применённый объект, а не считывайте неоднозначный текст формы.

Прочитать вспомогательную спецификацию

## Адаптивная компоновка поверхностей в дизайн-системе HeroUI

### Иллюстрация остаётся содержимым, а не фоном для элементов управления

На настольных экранах используется сетка 1.05fr/1fr: иллюстрации отводится немного больше места, а настройки остаются удобными для чтения. На исходной контрольной точке 700px сетка становится одноколоночной, заголовок располагается вертикально, а пропорции иллюстрации меняются с 4:5 на 4:3. Подпись находится за пределами иллюстрации, чтобы область чтения оставалась стабильной.

Все интерактивные элементы управления находятся на сплошной семантической поверхности. При нехватке места кнопки переносятся. Высота области предпросмотра зависит от содержимого, а не от минимальной высоты окна просмотра; это важно, когда документ встроен в iframe с автоматическим подбором размера. Фиксированный по высоте блок с прокруткой не скрывает форму или её результат.

Прочитать вспомогательную спецификацию

## Взаимодействие, фокус и достоверные результаты в дизайн-системе HeroUI

### Используйте нативные состояния, а не нарисованные имитации

Button использует onPress, а не пользовательское событие, работающее только с указателем. Slider поддерживает управление с клавиатуры и озвучивание значений. Switch предоставляет своё логическое состояние через встроенную реализацию доступности. Пользовательский макет CSS не отменяет стили фокуса. Для отключения компонента используйте isDisabled, а не только прозрачность; --disabled-opacity описывает лишь внешний вид.

Для абзаца состояния задана роль role=status: применённый снимок можно озвучить, не перемещая фокус клавиатуры. Текст кнопки тёмного оформления меняется и описывает следующее действие. У иллюстрации есть понятная метка области, а её формы считаются декоративными. Эта демонстрация не обещает сохранения данных после перезагрузки.

- Качество — числовой параметр с ограничениями и видимым значением.

- Метаданные — логический параметр с названием и пояснением.

- Кнопка «Применить» сохраняет локальный снимок; кнопка «Сбросить» очищает его и восстанавливает исходный черновик.

Прочитать вспомогательную спецификацию

## Установка и воспроизведение примера для дизайн-системы HeroUI

### Выберите один способ подключения таблицы стилей

В приложении Vite React установите закреплённые версии пакетов HeroUI и Tailwind CSS v4 с плагином для Vite. В основной таблице стилей сначала импортируйте tailwindcss, затем @heroui/styles, после чего подключите исходную разметку CSS. Отрисуйте App с помощью React createRoot; для такой композиции провайдер v2 не требуется. В блоке настройки приведены точка входа и конфигурация Vite, а полный код App и CSS доступен выше.

В загружаемом автономном примере используются предварительно скомпилированный heroui.min.css и сборка esbuild React, встроенные в страницу. Благодаря этому для предпросмотра не нужны зависимости от CDN. Пример демонстрирует те же нативные элементы управления, но не предписывает импортировать скомпилированные стили HeroUI вместе со стилями, созданными Tailwind, в одно production-приложение. Выберите один конвейер, чтобы избежать дублирования правил.

Прочитать вспомогательную спецификацию

## Дизайн-система HeroUI: расширьте рецепт, не создавая несуществующий кодировщик

### Не скрывайте границы возможностей

Чтобы добавить настоящее преобразование изображений, подключите поле выбора файла и реальный кодировщик — в браузере или на сервере — а затем свяжите с ним состояния ожидания, ошибки и завершения. Slider только задаёт значение: сжатие он не выполняет. Кнопка Apply не должна превращаться в Download, пока не создан настоящий выходной blob. Храните исходное изображение отдельно, чтобы повторные изменения рецепта не приводили к накоплению потерь при кодировании.

При настройке темы приложения переопределяйте семантические пары цветов вместе и проверяйте оформление в светлом и тёмном режимах. Если изменить только --accent, оставив неподходящий цвет текста, контраст кнопки может ухудшиться. Для более сложной настройки используйте документированные классы компонентов и состояния data-атрибутов, а не заменяйте доступный элемент ввода компонента визуально похожим div.

Прочитать вспомогательную спецификацию

## Дизайн-система HeroUI: примеры компонентов

### Полноценное приложение для экспорта рецепта

Составные части Slider и Switch наследуют официальное оформление. Отдельный применённый снимок состояния наглядно различает черновик и применённые настройки.

```
import React,{useState,useEffect} from 'react';
import {Button,Switch,Label,Description,Slider} from '@heroui/react';
import './style.css';
export default function App(){
const[quality,setQuality]=useState(80),[metadata,setMetadata]=useState(false),[dark,setDark]=useState(false),[saved,setSaved]=useState(null);
useEffect(()=>{document.documentElement.classList.toggle('dark',dark)},[dark]);
return <main className='export-app'><header><div><p className='eyebrow'>HeroUI · Export studio</p><h1>Make room for the image.</h1><p className='muted'>Inspect a local export recipe before handing it to an encoder.</p></div><Button variant='secondary' onPress={()=>setDark(!dark)}>{dark?'Light appearance':'Dark appearance'}</Button></header><div className='export-grid'><section className='art-panel' aria-label='Original CSS artwork preview'><div className='art'><div className='sun'/><div className='hill one'/><div className='hill two'/><span>FIELD NOTES<br/>COLLECTION 07</span></div><div className='art-caption'><strong>Morning in the dunes</strong><span>1600 × 1200 · sample composition</span></div></section><section className='settings'><p className='eyebrow'>WEBP PRESET</p><h2>Export settings</h2><p className='muted'>The controls update a recipe. They do not encode or upload an image.</p><Slider value={quality} onChange={setQuality} minValue={10} maxValue={100} step={5}><div className='slider-heading'><Label>Image quality</Label><Slider.Output/></div><Slider.Track><Slider.Fill/><Slider.Thumb/></Slider.Track></Slider><p className='helper'>Higher quality may preserve fine texture. File size depends on the source image and encoder.</p><Switch isSelected={metadata} onChange={setMetadata}><Switch.Content><Switch.Control><Switch.Thumb/></Switch.Control><Label>Keep metadata</Label></Switch.Content><Description>Include source metadata in the recipe.</Description></Switch><div className='recipe'><p className='eyebrow'>CURRENT RECIPE</p><code>format: webp<br/>quality: {quality}<br/>metadata: {metadata?'keep':'strip'}</code></div><div className='actions'><Button onPress={()=>setSaved({quality,metadata})}>Apply to preview</Button><Button variant='tertiary' onPress={()=>{setQuality(80);setMetadata(false);setSaved(null)}}>Reset</Button></div><p role='status' className='status'>{saved?`Preview recipe applied: quality ${saved.quality}, metadata ${saved.metadata?'kept':'stripped'}. No file was generated.`:'Adjust quality with the arrow keys, then apply the recipe.'}</p></section></div><footer>Native HeroUI 3.2.6 controls and official compiled styles. Artwork and page layout are original CSS.</footer></main>;
}
```

Справочник по коду

- Slider.Output отображает управляемое числовое значение.

- Для видимой структуры Switch необходимы Switch.Control и Switch.Thumb.

- Обработчик onPress применяет рецепт, но не заявляет, что изображение было закодировано.

### Исходная разметка CSS

В примерах поверхностей и радиусов используются переменные HeroUI; цвета иллюстрации, шкала шрифтов и точка перелома — явно заданные решения приложения.

```
*{box-sizing:border-box}body{margin:0;background:var(--background);color:var(--foreground);font-family:Arial,Helvetica,sans-serif;font-size:16px;line-height:1.5}.export-app{max-width:1120px;padding:32px;margin:auto}header{display:flex;justify-content:space-between;align-items:start;gap:24px;margin-bottom:28px}h1{font-size:32px;font-weight:700;letter-spacing:-.035em;line-height:1.15;margin:8px 0 12px}h2{font-size:24px;font-weight:650;line-height:1.25;margin:8px 0 12px}.eyebrow{font-size:11px;letter-spacing:.12em;font-weight:700}.muted,.helper,footer{color:var(--muted)}.muted{margin:0 0 24px}.export-grid{display:grid;grid-template-columns:1.05fr 1fr;gap:24px}.art-panel,.settings{background:var(--surface);border-radius:calc(var(--radius)*3);padding:24px;box-shadow:var(--surface-shadow)}.art{position:relative;aspect-ratio:4/5;background:#f0d8b8;border-radius:calc(var(--radius)*2);overflow:hidden}.sun{width:40%;aspect-ratio:1;background:#bf532f;position:absolute;top:13%;left:30%;border-radius:50%}.hill{position:absolute;width:180%;height:70%;border-radius:50%;transform:rotate(-24deg)}.one{top:50%;left:-60%;background:#c59162}.two{top:66%;left:-10%;background:#69402e}.art span{position:absolute;top:6%;left:8%;font-size:11px;letter-spacing:.2em;color:#563324}.art-caption{display:flex;flex-direction:column;gap:4px;margin-top:16px}.art-caption span{color:var(--muted);font-size:12px}.settings{display:flex;flex-direction:column;gap:16px}.settings .muted{margin-bottom:0}.slider-heading{display:flex;justify-content:space-between;gap:16px}.helper{font-size:13px;margin:0}.recipe{border:var(--border-width) solid var(--border);padding:16px;border-radius:var(--field-radius)}.recipe .eyebrow{margin-top:0}code{font-size:14px}.actions{display:flex;flex-wrap:wrap;gap:8px}.status{font-size:13px;margin:0}footer{font-size:12px;margin-top:20px}@media(max-width:700px){.export-app{padding:16px}header{flex-direction:column}h1{font-size:28px}.export-grid{grid-template-columns:1fr}.art{aspect-ratio:4/3}.art-panel,.settings{padding:20px}}
```

Справочник по коду

- Подключите этот CSS после официальной таблицы стилей.

- Класс dark у html изменяет семантические значения во всём документе.

## HeroUI Настройка агента дизайн-системы

### Отправная точка для реализации

Нативный предпросмотр проверен с React 19 и HeroUI 3.2.6. Предоставленные App и разметка CSS полностью готовы. Эта конфигурация Vite использует документированный процесс импорта Tailwind v4; в автономном примере для работы без подключения к сети встроена официальная предварительно скомпилированная таблица стилей.

```
// In a Vite React 19 project:
// npm install @heroui/react@3.2.6 @heroui/styles@3.2.6 tailwindcss@^4 @tailwindcss/vite@^4
// vite.config.js
import {defineConfig} from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({plugins:[react(),tailwindcss()]});

// globals.css: keep this import order
// @import "tailwindcss";
// @import "@heroui/styles";
// Paste the Original layout CSS after these imports.

// main.jsx
import React from 'react';
import {createRoot} from 'react-dom/client';
import './globals.css';
import App from './App.jsx';
createRoot(document.getElementById('root')).render(<App/>);
// App.jsx is the complete application above. Remove its './style.css'
// import when the same CSS is included in globals.css.
```

### Запрос для вашего проекта

```
Используйте предоставленные App.jsx для HeroUI 3.2.6, таблицу стилей и интеграцию с Tailwind, чтобы создать студию экспорта изображений. Свяжите состояние качества Slider и состояние метаданных Switch со сводкой экспорта; сохраните Switch.Content, Control и Thumb вместе с их подписями. При изменении качества или метаданных сохранённый снимок должен считаться устаревшим. Переключатель тёмного режима должен менять тот же класс документа, который использует таблица стилей. Сохраняйте явно обозначенный локальный рецепт экспорта; не создавайте впечатление, будто файл изображения был обработан или скачан.
```

## Дизайн-система HeroUI: источники и границы охвата

Справочник по HeroUI 3.2.6. Официальные переменные отделены от оригинальной типографики, иллюстрации и разметки. Нативный предпросмотр изменяет только хранящиеся в памяти настройки и не кодирует изображения.

- Быстрый старт Требования к React и Tailwind и порядок импорта.

- Цвета Семантические роли цветов.

- Настройка темы Настройка темы CSS.

- Slider Составная структура и управляемые числовые значения.

- Switch Логическая композиция и состояние.

- Оформление Подход к оформлению компонентов.

## Дизайн-система HeroUI: связанные ресурсы

### Ionic Framework

Нативный интерфейс Ionic для настройки чтения с проверенными цветовыми ролями, геометрией диапазонов iOS и Material, настоящим поведением сегментов и переключателей и статьёй, которая реагирует на выбор шрифта, размера и фона.

### Kobalte

Kobalte предоставляет headless-компоненты для Solid, включая числовые поля с отдельными исходными и форматированными значениями, составную анатомию флажка и кнопки с состоянием нажатия. В руководстве эти примитивы связаны с сигналами Solid на примере масштабатора рецепта с вычисляемыми количествами и сбрасываемыми флажками ингредиентов.

### Mantine

Справочник по Mantine 9 с нативной таблицей участников и боковой панелью планирования. Изучите настоящие шкалы темы, подключите useForm к TextInput, Select, Checkbox и DatePickerInput и проверьте валидацию перед добавлением локальной записи.


- [Справочник по реализации](https://heroui.com/en/docs/react/components/slider)
- [Источник](https://heroui.com/en/docs/react/handbook/colors)
- [Источник](https://heroui.com/en/docs/react/handbook/theming)
- [Источник](https://heroui.com/en/docs/react/handbook/styling)
- [Источник](https://heroui.com/en/docs/react/components/slider)
- [Прочитать вспомогательную спецификацию](https://heroui.com/en/docs/react/getting-started/quick-start)
- [Прочитать вспомогательную спецификацию](https://heroui.com/en/docs/react/handbook/colors)
- [Прочитать вспомогательную спецификацию](https://heroui.com/en/docs/react/handbook/theming)
- [Прочитать вспомогательную спецификацию](https://heroui.com/en/docs/react/components/slider)
- [Прочитать вспомогательную спецификацию](https://heroui.com/en/docs/react/components/switch)
- [Прочитать вспомогательную спецификацию](https://heroui.com/en/docs/react/handbook/styling)
- [Справочник по коду](https://heroui.com/en/docs/react/components/slider)
- [Справочник по коду](https://heroui.com/en/docs/react/handbook/styling)
- [Быстрый старт Требования к React и Tailwind и порядок импорта.](https://heroui.com/en/docs/react/getting-started/quick-start)
- [Цвета Семантические роли цветов.](https://heroui.com/en/docs/react/handbook/colors)
- [Настройка темы Настройка темы CSS.](https://heroui.com/en/docs/react/handbook/theming)
- [Slider Составная структура и управляемые числовые значения.](https://heroui.com/en/docs/react/components/slider)
- [Switch Логическая композиция и состояние.](https://heroui.com/en/docs/react/components/switch)
- [Оформление Подход к оформлению компонентов.](https://heroui.com/en/docs/react/handbook/styling)