Справочник по HeroUI v3 с настоящими семантическими переменными CSS, составными элементами управления React, светлыми и тёмными поверхностями и рабочим рецептом экспорта изображений.
Руководство OpenDesign9 глав30 справочных записейАвторское руководство по приложению
01
Предварительный просмотр интерфейса дизайн-системы HeroUI
Изменяйте качество с помощью встроенного слайдера, переключайте метаданные и оформление, применяйте локальный рецепт. Кодирование и загрузка не имитируются.
Скомпилировано с нативными @heroui/react 3.2.6 и @heroui/styles 3.2.6 CSS; оригинальные иллюстрация и макет. · Справочник по реализации
02
Справочник по дизайн-системе HeroUI
Тема по умолчанию HeroUI 3.2.6 проверена по @heroui/styles/dist/themes/default/variables.css. Приведённые ниже значения OKLCH дословно взяты из пакета. Цвета иллюстрации и типографика — решения приложения, а не токены бренда HeroUI.
Этот пример рассчитан на 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 интегрируется с утилитами 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 с шагом один. Универсальной надёжной зависимости между значением качества и размером файла нет, поэтому пояснение описывает компромисс, не выдумывая оценку размера файла. Чтобы использовать несколько ползунков, передайте массив чисел и задайте каждому ползунку правильный индекс.
Установите фокус на слайдере качества и нажмите клавишу со стрелкой, чтобы изменить значение на один шаг.
Убедитесь, что отображаемое значение и текущий рецепт обновляются одновременно.
Примените рецепт, а затем снова переместите слайдер, чтобы различить черновик и применённый снимок настроек.
Создание логического параметра в дизайн-системе 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.
Составные части Slider и Switch наследуют официальное оформление. Отдельный применённый снимок состояния наглядно различает черновик и применённые настройки.
jsx
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; цвета иллюстрации, шкала шрифтов и точка перелома — явно заданные решения приложения.
Подключите этот CSS после официальной таблицы стилей.
Класс dark у html изменяет семантические значения во всём документе.
04
HeroUI Настройка агента дизайн-системы
Отправная точка для реализации
Нативный предпросмотр проверен с React 19 и HeroUI 3.2.6. Предоставленные App и разметка CSS полностью готовы. Эта конфигурация Vite использует документированный процесс импорта Tailwind v4; в автономном примере для работы без подключения к сети встроена официальная предварительно скомпилированная таблица стилей.
jsx
// In a Vite React 19 project:
// npm install @heroui/[email protected] @heroui/[email protected] 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.
Запрос для вашего проекта
Промпт для AI-агента
Используйте предоставленные App.jsx для HeroUI 3.2.6, таблицу стилей и интеграцию с Tailwind, чтобы создать студию экспорта изображений. Свяжите состояние качества Slider и состояние метаданных Switch со сводкой экспорта; сохраните Switch.Content, Control и Thumb вместе с их подписями. При изменении качества или метаданных сохранённый снимок должен считаться устаревшим. Переключатель тёмного режима должен менять тот же класс документа, который использует таблица стилей. Сохраняйте явно обозначенный локальный рецепт экспорта; не создавайте впечатление, будто файл изображения был обработан или скачан.
05
Дизайн-система HeroUI: источники и границы охвата
Справочник по HeroUI 3.2.6. Официальные переменные отделены от оригинальной типографики, иллюстрации и разметки. Нативный предпросмотр изменяет только хранящиеся в памяти настройки и не кодирует изображения.
