Начало

Темы и токены

CSS-переменные, светлая и тёмная темы, своя палитра.

Вся тема — это плоский набор CSS-переменных. Компоненты читают только var() и собственных цветов не содержат, поэтому перекрасить их можно, не трогая ни строчки в пакете.

Токены

`--background`	Фон страницы
`--surface`	Карточки, панели, диалоги
`--surface-2`	Поля ввода, вложенные поверхности
`--border`	Границы (утилита называется border-edge)
`--foreground`	Основной текст
`--muted`	Второстепенный текст
`--accent`	Акцент: кнопки, ссылки, фокус
`--accent-hover`	Акцент при наведении
`--accent-2, --accent-3, --accent-pink`	Дополнительные акценты для градиентов
`--accent-foreground`	Текст на акцентной заливке
`--danger, --success, --warning, --info`	Семантика состояний

Кроме цветов есть радиусы (--radius-sm … --radius-2xl), тени (--shadow … --shadow-2xl), тайминги (--duration, --ease-out-expo) и шкала слоёв.

Светлая и тёмная

Тёмная тема — значение по умолчанию на :root. Светлая включается атрибутом на <html>:

html

<html data-theme="light">

Значение system отдаёт решение медиазапросу prefers-color-scheme. Всё это делает useTheme:

Выбор пользователя: dark
Что на экране: dark

Меняется тема всего сайта — состояние живёт в атрибуте на <html>, а не внутри компонента.

import { useTheme } from "@toimetdev/pathlogs-hooks";

const { preference, resolved, setTheme, toggle } = useTheme();

// preference — что выбрал пользователь: light | dark | system
// resolved   — что видно на экране: light | dark

Своя палитра

Переопределите переменные после импорта токенов — каскад сделает остальное. Ни один компонент об этом знать не должен:

css

@import "@toimetdev/pathlogs-tokens/styles/index.css";

:root {
  --accent: #0ea5e9;
  --accent-hover: #38bdf8;
  --accent-2: #06b6d4;
  --radius: 0.25rem;
}

[data-theme="light"] {
  --accent-hover: #0284c7;
}

Утилиты Tailwind

Мост tokens/styles/tailwind.css объявляет @theme inline, поэтому утилиты ссылаются на переменные, а не на значения — смена темы каскадирует в них без пересборки:

tsx

<div className="rounded-xl border border-edge bg-surface p-4 text-foreground">
  <p className="text-muted">Второстепенный текст</p>
  <button className="bg-accent text-accent-foreground hover:bg-accent-hover">
    Кнопка
  </button>
</div>

Граница называется border-edge, а не border-border: вторая утилита читалась бы как заикание.

Работа с цветом

Цвета меток и колонок задаёт пользователь, поэтому пакет умеет считать читаемость и прозрачность:

tsx

import { alpha, readableTextOn, luminance, backdropCss } from "@toimetdev/pathlogs-tokens";

alpha("#6366f1", 0.3);       // "#6366f14d" — восьмизначный hex, годится для градиентов
readableTextOn("#ffff00");   // "#000000" — белый текст на жёлтом не читается
luminance("#1b2233");        // относительная яркость по WCAG 2.1

backdropCss({ color: "#6366f1", colorTo: "#ec4899", angle: 45 });

Проп	Тип	По умолчанию	Описание
`alpha`	`(hex: string, opacity: number) => string`	—	Прозрачность восьмизначным hex, а не rgba(): такую строку можно склеивать в градиенты и класть в CSS-переменные без разбора.
`readableTextOn`	`(hex: string) => "#000000" \| "#ffffff"`	—	Чёрный или белый — тот, что контрастнее на этом фоне. Считается по яркости, а не по «на глаз тёмный».
`backdropCss`	`(bg: SurfaceBackdrop) => string`	—	Полупрозрачная подложка: одно пятно или градиент. Одна функция на саму подложку и на превью в настройках — они не разъедутся.
`BOARD_PALETTE`	`readonly string[]`	—	Приглушённая палитра для карточек, колонок и меток.
`SURFACE_PALETTE`	`readonly string[]`	—	Яркая палитра для подложек: фон полупрозрачный, приглушённые оттенки на нём не видны.

alpha(hex: string, opacity: number) => string

Прозрачность восьмизначным hex, а не rgba(): такую строку можно склеивать в градиенты и класть в CSS-переменные без разбора.

readableTextOn(hex: string) => "#000000" | "#ffffff"

Чёрный или белый — тот, что контрастнее на этом фоне. Считается по яркости, а не по «на глаз тёмный».

backdropCss(bg: SurfaceBackdrop) => string

Полупрозрачная подложка: одно пятно или градиент. Одна функция на саму подложку и на превью в настройках — они не разъедутся.

BOARD_PALETTEreadonly string[]

Приглушённая палитра для карточек, колонок и меток.

SURFACE_PALETTEreadonly string[]

Яркая палитра для подложек: фон полупрозрачный, приглушённые оттенки на нём не видны.

Слои

Общая шкала z-index важнее, чем кажется: без неё портал одного компонента перекрывает портал другого в случайном порядке.

css

--z-sticky: 20;    /* липкие панели */
--z-header: 30;    /* шапка, затемнение drawer */
--z-drawer: 40;    /* выезжающий сайдбар */
--z-dropdown: 50;  /* выпадающие панели, меню упоминаний */
--z-modal: 60;     /* диалоги и командная палитра */
--z-toast: 80;
--z-tooltip: 90;   /* подсказки — поверх всего */