@konce-pt/theme 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 konce.pt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+<p align="center">
+  <img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI — Angular component library" width="100%" />
+</p>
+
+# @konce-pt/theme
+
+Rdzeń motywu [Koncept UI](https://gitlab.com/konce-pt/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`](https://www.npmjs.com/package/@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.
+
+```bash
+npm i @konce-pt/theme
+```
+
+```ts
+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`](https://ui.konce.pt/llms/theme/llms.txt) (EN)
+i [`llms-pl.txt`](https://ui.konce.pt/llms/theme/llms-pl.txt) (PL).
+
+## Testy
+
+```bash
+pnpm --filter @konce-pt/theme exec node --test "src/**/*.test.ts"
+```
+
+## Licencja
+
+MIT © [konce.pt](https://konce.pt)

package/dist/audit.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Audyt kontrastu.
+ *
+ * Mierzymy pary, które realnie występują w bibliotece — tekst na powierzchni, treść na wypełnieniu
+ * akcentowym, kreska na tle — a nie iloczyn kartezjański wszystkich tokenów. Lista jest krótka
+ * i konkretna, bo audyt ma wskazać miejsce do poprawienia, a nie wysypać sto liczb.
+ *
+ * Obie miary idą obok siebie: WCAG 2.1, bo na nim stoją wymagania formalne, i APCA, bo lepiej
+ * odpowiada temu, co widać, i uwzględnia biegunowość. Para może zdać jedną i oblać drugą — wtedy
+ * warto to zobaczyć, a nie uśredniać.
+ */
+import type { KptThemeDoc, KptThemeMode } from './schema.ts';
+/**
+ * Poziom wymagania: tekst podstawowy, tekst duży, element interfejsu, element dekoracyjny.
+ *
+ * `decorative` **nie jest** progiem WCAG i celowo nie udaje, że jest. Zwykła kreska rozdzielająca
+ * nie jest „komponentem interfejsu" w rozumieniu 1.4.11 i praktycznie żaden system projektowy nie
+ * trzyma jej na 3:1 — wymaganie tego produkowałoby ostrzeżenie, które każdy nauczy się ignorować,
+ * a razem z nim ignorować całą resztę. Pytanie jest tu inne i węższe: czy kreska w ogóle widać.
+ */
+export type KptContrastLevel = 'body' | 'large' | 'ui' | 'decorative';
+export interface KptContrastPair {
+    text: string;
+    background: string;
+    level: KptContrastLevel;
+    /** Po czym poznać tę parę w interfejsie — co to jest na ekranie. */
+    label: string;
+}
+/**
+ * Pary sprawdzane w obu motywach. `text` nie zawsze jest literami: dla `ui` to bywa kreska albo
+ * pierścień focus, czyli rzecz, która ma się odciąć od tła.
+ */
+export declare const KPT_CONTRAST_PAIRS: readonly KptContrastPair[];
+export interface KptContrastFinding extends KptContrastPair {
+    mode: KptThemeMode;
+    /** Wartości po rozwiązaniu — żeby interfejs mógł pokazać, co dokładnie zmierzono. */
+    textValue: string;
+    backgroundValue: string;
+    ratio: number;
+    lc: number;
+    requiredRatio: number;
+    requiredLc: number;
+    passesWcag: boolean;
+    passesApca: boolean;
+    /**
+     * Czy ta sama para nie zdaje już w motywie stockowym biblioteki. Edytor domyślnie chowa takie
+     * wyniki: użytkownik ma zobaczyć, co **on** popsuł, a nie odziedziczyć listy, na którą nie ma
+     * wpływu — ale ukryć to zupełnie też nie wolno, bo część z tych par to prawdziwe problemy
+     * (biały tekst na wypełnieniu ostrzeżenia trzyma 3,19 przy wymaganych 4,5).
+     */
+    inherited: boolean;
+}
+export interface KptAuditOptions {
+    /** Zwróć także pary, które zdały. Domyślnie wracają same problemy. */
+    all?: boolean;
+    /** Ogranicz do jednego motywu. Domyślnie sprawdzane są oba. */
+    mode?: KptThemeMode;
+}
+export declare function auditTheme(doc?: KptThemeDoc, options?: KptAuditOptions): KptContrastFinding[];

package/dist/audit.js

@@ -0,0 +1,102 @@
+/**
+ * Audyt kontrastu.
+ *
+ * Mierzymy pary, które realnie występują w bibliotece — tekst na powierzchni, treść na wypełnieniu
+ * akcentowym, kreska na tle — a nie iloczyn kartezjański wszystkich tokenów. Lista jest krótka
+ * i konkretna, bo audyt ma wskazać miejsce do poprawienia, a nie wysypać sto liczb.
+ *
+ * Obie miary idą obok siebie: WCAG 2.1, bo na nim stoją wymagania formalne, i APCA, bo lepiej
+ * odpowiada temu, co widać, i uwzględnia biegunowość. Para może zdać jedną i oblać drugą — wtedy
+ * warto to zobaczyć, a nie uśredniać.
+ */
+import { apcaLc, contrastRatio, oklchToSrgb, parseOklch } from '@konce-pt/color';
+import { resolveTheme } from "./resolve.js";
+const THRESHOLDS = {
+    body: { ratio: 4.5, lc: 75 },
+    large: { ratio: 3, lc: 60 },
+    ui: { ratio: 3, lc: 45 },
+    decorative: { ratio: 1.2, lc: 8 },
+};
+/**
+ * Pary sprawdzane w obu motywach. `text` nie zawsze jest literami: dla `ui` to bywa kreska albo
+ * pierścień focus, czyli rzecz, która ma się odciąć od tła.
+ */
+export const KPT_CONTRAST_PAIRS = [
+    { text: '--kpt-color-on-surface', background: '--kpt-color-surface', level: 'body', label: 'Tekst główny na stronie' },
+    { text: '--kpt-color-on-surface', background: '--kpt-color-surface-raised', level: 'body', label: 'Tekst na karcie' },
+    { text: '--kpt-color-on-surface', background: '--kpt-color-surface-variant', level: 'body', label: 'Tekst w nagłówku tabeli' },
+    { text: '--kpt-color-on-surface', background: '--kpt-color-surface-sunken', level: 'body', label: 'Tekst w sekcji zagłębionej' },
+    { text: '--kpt-color-on-surface-muted', background: '--kpt-color-surface', level: 'body', label: 'Tekst drugorzędny' },
+    { text: '--kpt-color-text-subtle', background: '--kpt-color-surface', level: 'ui', label: 'Placeholder i tekst wyłączony' },
+    { text: '--kpt-color-on-primary', background: '--kpt-color-primary', level: 'body', label: 'Etykieta przycisku głównego' },
+    { text: '--kpt-color-on-muted', background: '--kpt-color-muted', level: 'body', label: 'Etykieta przycisku tonalnego' },
+    { text: '--kpt-color-danger-contrast', background: '--kpt-color-danger', level: 'body', label: 'Treść na wypełnieniu błędu' },
+    { text: '--kpt-color-success-contrast', background: '--kpt-color-success', level: 'body', label: 'Treść na wypełnieniu powodzenia' },
+    { text: '--kpt-color-warning-contrast', background: '--kpt-color-warning', level: 'body', label: 'Treść na wypełnieniu ostrzeżenia' },
+    { text: '--kpt-color-info-contrast', background: '--kpt-color-info', level: 'body', label: 'Treść na wypełnieniu informacji' },
+    { text: '--kpt-color-on-surface', background: '--kpt-color-primary-subtle', level: 'body', label: 'Tekst na badge akcentu' },
+    { text: '--kpt-color-on-surface', background: '--kpt-color-danger-subtle', level: 'body', label: 'Tekst w alercie błędu' },
+    { text: '--kpt-color-on-surface', background: '--kpt-color-success-subtle', level: 'body', label: 'Tekst w alercie powodzenia' },
+    { text: '--kpt-color-on-surface', background: '--kpt-color-warning-subtle', level: 'body', label: 'Tekst w alercie ostrzeżenia' },
+    { text: '--kpt-color-on-surface', background: '--kpt-color-info-subtle', level: 'body', label: 'Tekst w alercie informacji' },
+    { text: '--kpt-color-border', background: '--kpt-color-surface', level: 'decorative', label: 'Kreska rozdzielająca' },
+    { text: '--kpt-color-border-strong', background: '--kpt-color-surface', level: 'ui', label: 'Obrys pola formularza' },
+    { text: '--kpt-color-focus-ring', background: '--kpt-color-surface', level: 'ui', label: 'Pierścień focus' },
+    { text: '--kpt-color-primary', background: '--kpt-color-surface', level: 'ui', label: 'Ikona i tekst akcentowy' },
+];
+const toRgb = (value) => {
+    const oklch = parseOklch(value);
+    return oklch ? oklchToSrgb(oklch) : null;
+};
+/**
+ * Pary o zbyt niskim kontraście, posortowane od najgorszej.
+ *
+ * Pary, których nie da się zmierzyć — bo wartość jest półprzezroczysta, jest `color-mix()` albo
+ * czymś, czego nie umiemy sprowadzić do składowych — są **pomijane**, nie zaliczane. Liczba
+ * wzięta z niepewnej wartości byłaby gorsza niż jej brak: audyt mówiłby „zdane" tam, gdzie nic
+ * nie sprawdził.
+ */
+const keyOf = (mode, pair) => `${mode}|${pair.text}|${pair.background}`;
+/** Pary nie zdające już w stocku. Liczone raz i bez flagi `inherited`, żeby nie zapętlić audytu. */
+let stockFailures;
+const inheritedFailures = () => (stockFailures ??= new Set(measure(undefined).filter((f) => !f.passesWcag || !f.passesApca).map((f) => f.key)));
+export function auditTheme(doc, options = {}) {
+    const baseline = inheritedFailures();
+    return measure(doc, options)
+        .map(({ key, ...finding }) => ({ ...finding, inherited: baseline.has(key) }))
+        .filter((finding) => options.all || !finding.passesWcag || !finding.passesApca)
+        .sort((a, b) => a.ratio - b.ratio);
+}
+function measure(doc, options = {}) {
+    const resolved = resolveTheme(doc);
+    const modes = options.mode ? [options.mode] : ['light', 'dark'];
+    const findings = [];
+    for (const mode of modes) {
+        const values = resolved[mode];
+        for (const pair of KPT_CONTRAST_PAIRS) {
+            const textValue = values[pair.text];
+            const backgroundValue = values[pair.background];
+            const text = textValue ? toRgb(textValue) : null;
+            const background = backgroundValue ? toRgb(backgroundValue) : null;
+            if (!text || !background)
+                continue;
+            const threshold = THRESHOLDS[pair.level];
+            const ratio = contrastRatio(text, background);
+            const lc = apcaLc(text, background);
+            findings.push({
+                ...pair,
+                key: keyOf(mode, pair),
+                mode,
+                textValue,
+                backgroundValue,
+                ratio: Number(ratio.toFixed(2)),
+                lc: Number(lc.toFixed(1)),
+                requiredRatio: threshold.ratio,
+                requiredLc: threshold.lc,
+                passesWcag: ratio >= threshold.ratio,
+                passesApca: Math.abs(lc) >= threshold.lc,
+            });
+        }
+    }
+    return findings;
+}

package/dist/dtcg.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Import z formatu W3C Design Tokens (DTCG) — jednokierunkowy, plikowy.
+ *
+ * To jest import, nie synchronizacja, i tak trzeba go nazywać. Odczyt zmiennych z narzędzia
+ * projektowego przez API bywa zarezerwowany dla planów firmowych, więc realną drogą jest plik
+ * wyeksportowany wtyczką. Nie ma tu OAuth, nie ma odpytywania, nie ma śledzenia zmian.
+ *
+ * Najtrudniejsze nie jest samo czytanie tokenów, tylko **tryby**: DTCG ich nie standaryzuje.
+ * Eksportery kodują je na trzy sposoby i każdy trzeba obsłużyć osobno — patrz `splitModes`.
+ *
+ * Zasada, od której nie ma odstępstwa: **importer nigdy niczego nie gubi po cichu.** Token, którego
+ * nie umiemy przypisać, trafia do raportu z powodem. Lepiej pokazać listę stu niedopasowań niż
+ * wczytać trzydzieści i nie powiedzieć o siedemdziesięciu.
+ */
+import type { KptThemeDoc, KptThemeMode } from './schema.ts';
+/** Jeden plik wejściowy. Nazwa bywa jedyną informacją o trybie, więc idzie razem z treścią. */
+export interface KptDtcgSource {
+    name: string;
+    content: unknown;
+}
+export interface KptDtcgOptions {
+    /**
+     * Ręczne wskazanie, co jest którym trybem — nazwa pliku albo grupy najwyższego poziomu.
+     * Podane, wygrywa z heurystyką; to jest wyjście awaryjne dla eksporterów, których nie znamy.
+     */
+    modes?: {
+        light?: string;
+        dark?: string;
+    };
+    /**
+     * Utrwalone mapowanie ze ścieżki DTCG na nazwę tokenu (`meta.importMap`). To ono zamienia
+     * jednorazowy import w element procesu pracy: po zmianie brandbooka wystarczy wczytać plik.
+     */
+    map?: Readonly<Record<string, string>>;
+}
+export type KptDtcgConfidence = 'exact' | 'synonym' | 'manual';
+export interface KptDtcgReport {
+    /** Dopasowane tokeny — `from` to ścieżka DTCG, `to` nazwa custom property. */
+    matched: {
+        from: string;
+        to: string;
+        mode: KptThemeMode;
+        confidence: KptDtcgConfidence;
+    }[];
+    /** Tokeny, których nie przypisaliśmy. Każdy z powodem — to jest sedno raportu. */
+    unmapped: {
+        path: string;
+        type: string;
+        value: string;
+        reason: KptDtcgReason;
+    }[];
+    /** Role biblioteki, których plik nie pokrył. Zostają na wartościach stockowych. */
+    missing: string[];
+    warnings: {
+        code: KptDtcgWarning;
+        detail: string;
+    }[];
+    /** Rampy rozpoznane w pliku — z nich bierze się ziarno koloru wiodącego. */
+    ramps: {
+        path: string;
+        steps: number;
+        seed?: string;
+    }[];
+}
+export type KptDtcgReason = 'no-target' | 'unsupported-type' | 'composite' | 'unreadable-value'
+/** Token nasz, ale **pochodny** — podąża za semantyką, więc nadpisanie zamroziłoby go. */
+ | 'derived';
+export type KptDtcgWarning = 'mode-guess' | 'no-modes' | 'alias-broken' | 'legacy-format' | 'empty';
+/** Nazwa ze ścieżki DTCG w kształcie, w którym da się ją porównać z nazwą roli. */
+export declare function normalizeDtcgPath(path: string): string;
+/**
+ * Czyta pliki DTCG i buduje z nich dokument motywu.
+ *
+ * Zwraca **parę**: motyw i raport. Raport nie jest dodatkiem — to on decyduje, czy import da się
+ * przyjąć, i to on pokazuje, czego plik nie pokrył. Interfejs ma go wyświetlić, a nie schować.
+ */
+export declare function fromDtcg(sources: readonly KptDtcgSource[], options?: KptDtcgOptions): {
+    theme: KptThemeDoc;
+    report: KptDtcgReport;
+};