@konce-pt/theme

Rdzeń motywu Koncept UI: format dokumentu kpt-theme.json, rampa OKLCH z jednego koloru marki, derywacja kompletu ról semantycznych, audyt kontrastu i emitery do CSS, SCSS, TS oraz W3C DTCG. Czysty TypeScript bez wiązania z frameworkiem; jedyna zależność to @konce-pt/color.

Motyw dla tej biblioteki to zestaw wartości --kpt-* — a policzenie tego zestawu jest arytmetyką, nie znacznikami. Ta sama arytmetyka musi chodzić w przeglądarce (podgląd na żywo) i w Node (eksport, testy), więc mieszka osobno od aplikacji, która ją renderuje.

npm i @konce-pt/theme

import { emitCss, auditTheme } from '@konce-pt/theme';

const theme = {
  kptTheme: 1,
  meta: { name: 'Acme' },
  recipe: { color: { seed: { primary: '#3b82f6' } }, radius: { base: '0.75rem' } },
} as const;

emitCss(theme);      // :root { … } + [data-theme="dark"] { … } — plik do wklejenia w aplikacji
auditTheme(theme);   // pary o zbyt niskim kontraście, w obu motywach, WCAG 2.1 + APCA

Różnica, nie zrzut

Dokument zapisuje wyłącznie to, co odbiega od stocku. Motyw waży kilka kilobajtów zamiast kilkudziesięciu, czyta się go w code review, a nowe tokeny w kolejnej wersji biblioteki dziedziczą się same, zamiast zamarzać na wartościach sprzed aktualizacji. Osobno trzymane są wejścia generatora (recipe) i ręczne poprawki (overrides): dzięki temu „przelicz paletę od nowa" nie kasuje ręcznej pracy, a suwaki dają się ponownie otworzyć.

Rampa czytana z palety, nie wymyślona

Jasność każdego stopnia pochodzi z rampy neutralnej biblioteki, kształt nasycenia — z uśrednienia czterech ramp akcentowych. Który stopień trafia na primary, -hover, -subtle i -border, też jest odczytane: cztery rodziny chromatyczne biblioteki mają identyczny układ i to on jest wzorcem. Generator pęka głośno, gdyby kiedykolwiek się rozjechały.

Audyt, który nie krzyczy bez powodu

Każdy wynik niesie inherited — czy ta sama para nie zdaje już w stockowym motywie biblioteki. Użytkownik widzi to, co on popsuł, zamiast dziedziczyć listę, na którą nie ma wpływu. Ukrywać ich zupełnie jednak nie wolno: część z nich to prawdziwe problemy.

Pełny opis: llms.txt (EN) i llms-pl.txt (PL).

Testy

pnpm --filter @konce-pt/theme exec node --test "src/**/*.test.ts"

Licencja

MIT © konce.pt