Kobalte предоставляет headless-компоненты для Solid, включая числовые поля с отдельными исходными и форматированными значениями, составную анатомию флажка и кнопки с состоянием нажатия. В руководстве эти примитивы связаны с сигналами Solid на примере масштабатора рецепта с вычисляемыми количествами и сбрасываемыми флажками ингредиентов.
Kobalte 0.13.14 и Solid 1.9.15; нативные бессоставные примитивы и полная оригинальная CSS. · Справочник по реализации
02
Справочник по дизайн-системе Kobalte
Kobalte 0.13.14 предоставляет бессоставные примитивы Solid, но не задаёт эталонную визуальную шкалу. Все цвета и размеры recipe-* ниже — полная конфигурация оригинального приложения. Названия API и атрибуты состояний проверены по установленному пакету и официальной документации компонентов.
Дизайн-система Kobalte — подключение компонентов Kobalte к сигналам Solid
Подключите компоненты Kobalte к сигналам Solid
Компонент использует сигналы Solid для количества порций, собранных ингредиентов и закрепления. createMemo вычисляет валидность на основе числового сигнала, а For отображает стабильную коллекцию ингредиентов. Управляемые свойства Kobalte напрямую считывают эти сигналы; для обновлений не нужны отдельный провайдер формы или адаптер состояния в стиле React.
NumberField, Checkbox и ToggleButton импортируются из точек входа соответствующих компонентов. У каждого своя роль: числовое поле предназначено для редактирования числового значения, каждый флажок отмечает один собранный ингредиент, а переключатель закрепляет рецепт. Арифметика и правила сброса остаются в функциях приложения, а не встраиваются в визуальные селекторы.
Дизайн-система Kobalte — храните числовое значение отдельно от форматированного текста
Храните числовое значение отдельно от форматированного текста
В NumberField передаются rawValue={portions()} и onRawValueChange={update}. Числовой сигнал напрямую используется для умножения, а поле отвечает за форматирование и ввод данных пользователем. Если подставлять в расчёты отображаемый отформатированный текст, придётся делать допущения о разделителях и локали, тогда как нативный примитив уже решает эту задачу.
В этом примере допускается от одной до восьми целых порций, шаг равен единице, а maximumFractionDigits задан равным нулю. Отдельный вычисляемый предикат по-прежнему проверяет конечность, целочисленность и допустимые границы: при редактировании поле может временно содержать неполное или недопустимое значение. Пока значение недопустимо, вместо суммы отображается длинное тире, а флажки ингредиентов отключены. Интерфейс не выдаёт правдоподобное, но неверное количество за корректный ввод пользователя.
Дизайн-система Kobalte — составьте поле из нативной метки и сообщений
Составьте поле из нативной метки и сообщений
Числовое поле включает Label, DecrementTrigger, Input, IncrementTrigger, Description и ErrorMessage. Видимое описание поясняет диапазон и последствия изменения количества порций. Триггерам даны понятные названия — «Меньше порций» и «Больше порций», поэтому их условным знакам минуса и плюса не нужно самостоятельно обеспечивать полное доступное имя.
validationState переключается между valid и invalid в зависимости от предиката приложения. ErrorMessage относится к этому нативному полю, а не к отдельному абзацу в другой части страницы. Для отправляемой формы Kobalte также предоставляет HiddenInput для сериализации исходного значения; в этом примере его нет, поскольку здесь не предусмотрены ни конечная точка отправки, ни данные формы.
Дизайн-система Kobalte — храните выбор ингредиентов в неизменяемом множестве
Храните выбор ингредиентов в неизменяемом множестве
Для каждого ингредиента используется полная структура Checkbox: Input, Control, Indicator и Label. Настоящий элемент ввода сохраняет семантику и управление с клавиатуры, а видимый элемент управления получает галочку и оригинальные стили состояний. Метка включает и название ингредиента, и его количество, поэтому пользователь видит, сколько именно продукта нужно собрать.
mark создаёт новое Set на основе предыдущего выбора, прежде чем добавить или удалить ID. Простое изменение существующего Set не обеспечило бы столь же надёжного обновления сигнала. Отображаемый счётчик считывает размер Set, а каждый Checkbox проверяет наличие стабильного ID ингредиента. При изменении количества порций весь выбор сбрасывается: отметка о сборе 320 граммов не подтверждает, что выполнено новое требование в 400 граммов.
Связывайте каждое видимое название ингредиента с Checkbox.Label.
Сохраняйте Checkbox.Input, даже если видимый квадрат оформлен пользовательскими стилями.
Используйте стабильные ID для выбора и создавайте новое Set при каждом обновлении.
Дизайн-система Kobalte — используйте переключатель для сохранения локального выбора
Используйте переключатель для сохранения локального выбора
Для закрепления используется ToggleButton со свойствами pressed и onChange, а не обычная кнопка, которая только меняет подпись. Состояние нажатия отражается в нативной семантике и селекторе data-pressed. Метка меняется на «Закреплено» с галочкой, а расположенный рядом статус поясняет, что это влияет только на локальный предпросмотр.
Закрепление не меняет количество ингредиентов или их выбор. При изменении количества порций отметки ингредиентов сбрасываются, но закрепление сохраняется: рецепт остаётся тем же. Команда сброса рецепта по умолчанию одновременно восстанавливает все три части модели: четыре порции, пустое множество ингредиентов и ненажатый переключатель. Эти границы сброса определяются смыслом состояния, а не правилом сбрасывать всё при каждом взаимодействии.
Дизайн-система Kobalte — задайте воспроизводимую визуальную конфигурацию для бессоставных элементов управления
Задайте воспроизводимую визуальную конфигурацию для бессоставных элементов управления
Таблица стилей рецепта отдельно задаёт поверхность редактирования числового поля, триггеры счётчика и стили выбранных флажков. Приглушённый цвет текста ингредиента применяется только после выбора; количества остаются хорошо различимыми, чтобы пользователь мог сопоставить собранное количество с текущим числом порций.
В отступах используются значения 4, 8, 12, 16, 24 и 32 пикселя. В оригинальной иерархии шрифтов для элементов управления используется системный шрифт без засечек, а для заголовка рецепта — Georgia. Рядом с полной связанной меткой расположен визуальный флажок размером 21 пиксель; метка остаётся удобной областью для нажатия. Все эти точные значения указаны в полном CSS, чтобы воссоздать образец без догадок по скриншоту.
Дизайн-система Kobalte — адаптируйте композицию, не скрывая информацию
Адаптируйте композицию, не скрывая информацию
В широкой версии гибкая карточка рецепта расположена рядом с панелью порций шириной 280 пикселей. При ширине 760 пикселей блоки выстраиваются в одну колонку. Заголовок карточки и метки ингредиентов могут переноситься, а количество остаётся компактным значением без переноса. На самой узкой контрольной точке отступы панели и размер шрифта меток немного уменьшаются, а не скрывают количества.
Иллюстрация салата — оригинальная работа CSS, помеченная как декоративная. Смысл передают название рецепта, число порций и количества ингредиентов, независимо от изображения. При замене иллюстрации или сужении карточки сохраняйте полные названия ингредиентов и их количества: именно по ним пользователь собирает нужные продукты.
Дизайн-система Kobalte — обрабатывайте изменение количества как обновление зависимого состояния
Обрабатывайте изменение количества как обновление зависимого состояния
На каждую порцию приходится по 250 граммов каждого из пяти ингредиентов. При увеличении числа порций с четырёх до пяти общий вес меняется с 1 000 до 1 250 граммов, а количество апельсинов — с 320 до 400 граммов. Ранее собранные ингредиенты больше не отмечены, поскольку их количество соответствовало прежним значениям; закрепление рецепта сохраняется, так как сам рецепт не изменился.
Функция обновления сначала сравнивает входящее значение с текущим сигналом с помощью Object.is. Если значение не изменилось, обратный вызов не должен очищать список отметок или сообщать об изменении количества. Для недопустимых значений количества не отображаются, а сбор отключается; сообщение об ошибке объясняет допустимый диапазон. Эти правила позволяют отслеживать промежуточные изменения, не допуская, чтобы недопустимое число приводило к неверному итогу.
Выберите 4 порции апельсиновых долек.
Увеличьте количество до пяти и убедитесь, что апельсина нужно 400 г, всего ингредиентов — 1 250 г, а собрано 0 позиций.
Закрепите рецепт, затем восстановите значения по умолчанию и убедитесь, что всё локальное состояние сброшено.
Дизайн-система Kobalte: используйте Solid Build и подключайте таблицу стилей целиком
Используйте сборку Solid и подключайте таблицу стилей целиком
Настройка использует шаблон Vite Solid, фиксирует проверенные версии Solid и Kobalte и монтирует приложение в явно заданный корневой элемент. Приведённые выше компонент и таблица стилей — полные файлы. Для этого примера не нужны провайдер темы, пакет иконок, внешний шрифт или серверная часть.
При интеграции в другое приложение согласуйте компилятор фреймворка и генерацию компонентов. Трансформация React не преобразует JSX Solid в корректное приложение Kobalte. Аналогично, перед заменой закреплённой зависимости на будущую мажорную версию Kobalte API следует свериться с её документацией. Количества ингредиентов и палитра — примеры данных приложения, поэтому их адаптация не требует изменения контракта нативных примитивов.
Нативное числовое поле, структура флажка и кнопка-переключатель с явной логикой ошибок и сброса.
jsx
import {createSignal,createMemo,For} from 'solid-js';
import {NumberField} from '@kobalte/core/number-field';
import {Checkbox} from '@kobalte/core/checkbox';
import {ToggleButton} from '@kobalte/core/toggle-button';
export default function App(){
const[portions,setPortions]=createSignal(4),[checked,setChecked]=createSignal(new Set()),[pinned,setPinned]=createSignal(false),[notice,setNotice]=createSignal('');
const ingredients=[{id:'orange',name:'Orange segments',grams:80},{id:'beans',name:'Cooked white beans',grams:90},{id:'leaves',name:'Salad leaves',grams:25},{id:'fennel',name:'Thinly sliced fennel',grams:40},{id:'dressing',name:'Citrus dressing',grams:15}];
const valid=createMemo(()=>Number.isFinite(portions())&&Number.isInteger(portions())&&portions()>=1&&portions()<=8);
function update(value){if(Object.is(value,portions()))return;setPortions(value);setChecked(new Set());setNotice('Portions changed. Ingredient checks were cleared for the new quantities.')}
function mark(id,value){setChecked(previous=>{const next=new Set(previous);value?next.add(id):next.delete(id);return next})}
function reset(){setPortions(4);setChecked(new Set());setPinned(false);setNotice('Restored four portions and an unchecked ingredient list.')}
return <main class="recipe-shell"><header><p class="eyebrow">KITCHEN NOTEBOOK · REACTIVE RECIPE CARD</p><h1>A brighter bowl, sized for your table.</h1><p>Change the portions, check the scaled ingredients and pin the recipe locally. The quantities are original sample data for this interface.</p></header><div class="recipe-layout"><section class="recipe-card"><div class="salad-art" aria-hidden="true"><div class="plate"><i/><b/><em/><span/><strong/></div></div><div class="recipe-heading"><div><p class="eyebrow">CITRUS & WHITE BEAN SALAD</p><h2>Fresh, crisp, generous.</h2></div><ToggleButton class="pin" pressed={pinned()} onChange={value=>{setPinned(value);setNotice(value?'Recipe pinned in this local preview.':'Recipe unpinned in this local preview.')}} aria-label="Pin recipe">{pinned()?'Pinned ✓':'Pin recipe'}</ToggleButton></div><p class="recipe-description">Sweet citrus, tender beans and crisp fennel. Use the checklist to gather the amounts for your chosen portion count.</p><div class="ingredient-title"><h3>Ingredients</h3><span>{checked().size} / 5 gathered</span></div><div class="ingredients"><For each={ingredients}>{ingredient=><Checkbox class="ingredient" checked={checked().has(ingredient.id)} onChange={value=>mark(ingredient.id,value)} disabled={!valid()}><Checkbox.Input/><Checkbox.Control class="check-control"><Checkbox.Indicator>✓</Checkbox.Indicator></Checkbox.Control><Checkbox.Label class="ingredient-label"><span>{ingredient.name}</span><strong>{valid()?ingredient.grams*portions()+' g':'—'}</strong></Checkbox.Label></Checkbox>}</For></div></section><aside class="portion-panel"><h2>Make it yours</h2><NumberField rawValue={portions()} onRawValueChange={update} minValue={1} maxValue={8} step={1} formatOptions={{maximumFractionDigits:0}} validationState={valid()?'valid':'invalid'} class="portion-field"><NumberField.Label class="field-label">Portions</NumberField.Label><div class="stepper"><NumberField.DecrementTrigger aria-label="Fewer portions">−</NumberField.DecrementTrigger><NumberField.Input/><NumberField.IncrementTrigger aria-label="More portions">+</NumberField.IncrementTrigger></div><NumberField.Description class="field-description">Choose 1–8 whole portions. Changing the quantity clears ingredient checks.</NumberField.Description><NumberField.ErrorMessage class="field-error">Enter a whole number from 1 to 8.</NumberField.ErrorMessage></NumberField><div class="portion-total"><span>Total ingredients</span><strong>{valid()?ingredients.reduce((s,x)=>s+x.grams,0)*portions()+' g':'—'}</strong></div><h3>A simple preparation order</h3><ol><li>Gather the scaled amounts and drain the cooked beans.</li><li>Combine the orange, fennel and leaves in a bowl.</li><li>Add the beans and dressing, then toss gently.</li></ol><button class="reset" onClick={reset}>Restore default recipe</button><p role="status" class="notice">{notice()||(pinned()?'Recipe pinned in this local preview.':'No shopping order or account update is created.')}</p></aside></div></main>
}
Эти значения recipe-* — оригинальные решения приложения, а не официальные токены Kobalte.
Полная таблица стилей включает адаптивную компоновку и заметное оформление фокуса.
04
Kobalte Настройка агента дизайн-системы
Отправная точка для реализации
Шаблон Solid Vite предоставляет необходимый компилятор JSX для Solid. Примеры App.jsx и style.css выше содержат весь код приложения и стили; провайдер или внешний сервис не требуются.
javascript
// npm create vite@latest kobalte-recipe -- --template solid
// cd kobalte-recipe && npm install
// npm install [email protected] @kobalte/[email protected]
// Save the complete examples as src/App.jsx and src/style.css.
// src/index.jsx:
import {render} from 'solid-js/web';
import App from './App.jsx';
import './style.css';
render(() => <App />, document.getElementById('app'));
// index.html: <div id="app"></div><script type="module" src="/src/index.jsx"></script>
// npm run dev
Запрос для вашего проекта
Промпт для AI-агента
Используйте Kobalte 0.13.14 с Solid 1.9.15, чтобы воспроизвести реактивную карточку рецепта. Сохраните NumberField rawValue/onRawValueChange, диапазон от одного до восьми, проверку целого числа порций и полную структуру Label/Description/ErrorMessage. Рассчитывайте граммы ингредиентов и итоговые значения на основе сигнала количества порций; при фактическом изменении количества очищайте неизменяемый Set идентификаторов отмеченных позиций, но сохраняйте закрепление рецепта. Используйте нативные части Checkbox и ToggleButton с pressed/onChange, отключайте сбор при недопустимом количестве и при сбросе возвращайте четыре порции, отсутствие отметок и отсутствие закрепления. Добавьте полный оригинальный рецепт CSS; всё состояние остаётся локальным.
05
Kobalte Источники и область применения дизайн-системы
Проверено с Kobalte 0.13.14 и Solid 1.9.15. Все токены recipe-*, иллюстрация CSS и количества ингредиентов — оригинальные данные примера. Закрепление и сбор хранятся в локальном состоянии; приложение не подключено к учётной записи, сервису покупок или постоянному хранилищу рецептов.
