@hanzo/ui

Темы

Токены разрешаются относительно темы, идентичность несут пользовательские свойства, а три регулятора позволяют человеку перенастроить всё целиком.

Библиотека не называет ни одного цвета. Компонент просит $background или $color12, тема отвечает, и ответ разный в тёмной и светлой теме — компоненту об этом знать не нужно. Бренд меняет ответ пользовательским свойством; человек меняет его, двигая регулятор, на который умножаются шкалы.

Токены

Значение пропа, которое начинается с $, — токен. Цветовая шкала идёт от поверхности к тексту: $color1 — самый тихий фон, $color12 — самый громкий текст.

ТокенЧто это
$backgroundФон страницы. Читает --background, так что на него отвечает таблица стилей бренда.
$colorЦвет текста по умолчанию.
$color1 – $color12Нейтральная шкала: $color2/$color3 — приподнятые поверхности, $color10/$color11 — приглушённый текст, $color12 — самый громкий.
$borderColorВолосяная линия. Полупрозрачная, поэтому читается как более светлая линия на любой поверхности, а не как посторонний серый.
$accentBackground / $accentColorЕдинственный громкий контрол, который странице позволен. Читают --primary, так что регулятор акцента до них доходит.
defaultsecondarydestructiveoutline

Лестницы

Размер, интервал и радиус — одни и те же числа на каждом хосте, и у каждой ступени есть регулятор.

Кегль. fontSize="$n", никогда число. Двенадцать ступеней читают шкалу дизайна, от --text-xs до --text-9xl, а четыре промежуточные интерполируют соседей, так что шкала человека двигает все шестнадцать, и лестница остаётся лестницей.

Ступень$1$2$3$4$5$6$7$8$9$10$11$14
px111314151517212626324064

$1 — подпись, $2 — навигация и плотный набор, $3 — база, $6 — заголовок раздела, $7 — заголовок страницы, $8 и выше — дисплей. Дисплейные ступени сжимают интерлиньяж и трекинг до −0.025em: в этом разница между набранным кеглем и кеглем, который просто крупный.

Интервал. Шкала в 4px, и только она: $1 4, $2 8, $3 12, $4 16, $5 24, $6 32, $8 48, $10 64. Каждый шаг умножается на --density.

Радиус. Четыре значения. $1 и $2 — это 6, контрол; $3 и $4 — 8, поле ввода или строка; $5–$9 — 12, панель; $10 и выше — пилюля. Всё, кроме пилюли, умножается на --radius-scale.

Пользовательские свойства

Идентичность — набор пользовательских свойств на :root, сначала тёмных, а .light их перенастраивает. Hanzo ставит на body .t_dark или .t_light, и CSS отвечает на оба написания, так что токены компонентов и таблица стилей называют одну тему.

:root {
  --background: #0a0a0a;
  --foreground: #e5e5e5;
  --primary: #fafafa;
  --border: rgb(255 255 255 / .10);
  --ring: rgb(255 255 255 / .40);
  --font-sans: 'Zen', ui-sans-serif, system-ui, sans-serif;
  --font-mono: 'Zen Mono', ui-monospace, monospace;
}

Полный набор — --background, --foreground, --card, --popover, --primary, --secondary, --muted, --accent, --destructive, у каждого есть свой -foreground, затем --border, --input, --ring, --radius, --chart-1–--chart-5 и семейство --sidebar-*. Они приходят из @hanzo/design и собираются в таблицу, которую импортирует корень; хост, который монтирует и собственную таблицу design, следует за ней вживую.

Бренд перенастраивает, объявляя те же имена позже в каскаде. Хост со своей гарнитурой привязывает --font-sans-provided, а не --font-sans: привязка пакета сидит в слое каскада, и объявление вне слоя побеждает при любой специфичности.

Регуляторы внешнего вида

@hanzo/design публикует три регулятора, на которые умножается каждая шкала, а @hanzo/appearance — панель, которая задаёт их для человека:

РегуляторЧто двигает
--type-scaleКаждую ступень --text-*, а с ней каждый fontSize="$n".
--type-ratioНасколько далеко ступени стоят друг от друга.
--densityКаждый шаг --space-* и каждый зазор и padding в gui.
--primary / --accentЕдинственный громкий цвет.
--font-sansГарнитура для чтения: бренда, системы, с засечками или моно.
--container-max / --container-prose / --container-wideТри меры, в которые укладывается страница.

Они садятся инлайновыми свойствами на html, а это :root, поэтому побеждают любую таблицу стилей без селектора, который надо перебить специфичностью, и доходят до компонентов, потому что gui разрешает размер в JavaScript как var(--text-base), а переменная всё ещё читает каскад на элементе. Ось, которую никто не задал, отсутствует, а не нейтральна: запись 1 выглядела бы так же и молча перекрыла бы бренд, который опубликовал свою шкалу.

import { Appearance } from '@hanzo/appearance'
import { bootScript } from '@hanzo/appearance/state'

// In <head>, so the first paint is already correct.
<script dangerouslySetInnerHTML={{ __html: bootScript() }} />

// Wherever the product keeps settings.
<Appearance />

Hanzo заново применяет сохранённое предпочтение при каждом монтировании, так что выбор на одной странице держится на следующей. Контрол в шапке этого сайта — та самая панель.