Konwencje nazewnictwa tokenów

Niespójne nazwy tokenów uniemożliwiają przewidzenie ich działania bez odczytania wartości. Jasna i przewidywalna konwencja nazewnictwa stanowi podstawę skalowalnego systemu tokenów.

Typowy wzorzec to: [category]-[property]-[variant]. Przykłady: color-text-primary, color-text-secondary, spacing-inset-sm. Każdy segment stopniowo zawęża znaczenie.

W komponentach należy unikać nazw palety, takich jak blue-500. Należy używać nazw semantycznych: color-action-default, color-feedback-error. Nazwy semantyczne pozostają aktualne po zmianie kolorów marki, bez konieczności aktualizowania komponentów.

Stan należy dodawać na końcu: color-button-bg-default, color-button-bg-hover, color-button-bg-disabled. Spójne przyrostki stanów sprawiają, że zestawy tokenów są przewidywalne i kompletne.

Należy konsekwentnie używać rozmiarów odzieżowych (xs, sm, md, lg, xl) albo skal numerycznych (100, 200...900). Skale numeryczne umożliwiają wstawianie wartości pośrednich, a rozmiary odzieżowe są czytelniejsze dla małych zestawów.

W systemach obsługujących wiele marek lub produktów należy poprzedzać tokeny przestrzenią nazw: brand-a-color-primary i brand-b-color-primary. Przestrzenie nazw zapobiegają kolizjom podczas łączenia zestawów tokenów.

Zapis kebab-case jest bezpośrednio przekształcany w niestandardowe właściwości CSS: color-text-primary staje się --color-text-primary. Tokeny w camel-case wymagają transformacji, a tokeny w kebab-case — nie.

Dobre nazwy dokumentują się same: spacing-stack-md (pionowy odstęp między ułożonymi elementami, średni) komunikuje przeznaczenie bez komentarza. Słabe nazwy, takie jak s3, wymagają zewnętrznej dokumentacji, aby można było je zrozumieć.

Gdy tokeny są już używane, zmiana ich nazw powoduje niezgodność. Należy używać aliasów wycofywania: zachować starą nazwę, ale sprawić, aby wskazywała nowy token. Konsumentom należy zapewnić okres migracji przed usunięciem wycofanych tokenów.

Nazwy tokenów można sprawdzać za pomocą niestandardowych reguł w Style Dictionary lub skryptu CI. Należy odrzucać tokeny, które nie pasują do wzorca nazewnictwa. Automatyczne egzekwowanie zapobiega rozbieżnościom w nazewnictwie w miarę rozwoju systemu.

Należy opublikować przewodnik po nazewnictwie z przykładami poprawnych i niepoprawnych nazw. Przed rozpoczęciem skalowania systemu warto przeprowadzić krótkie warsztaty, aby zespoły projektowe i programistyczne uzgodniły konwencje. Spójność wymaga wspólnego zrozumienia, a nie tylko dokumentacji.

Spójna konwencja nazewnictwa tokenów, wykorzystująca wzorce kategoria-właściwość-wariant, nazwy semantyczne, przyrostki stanów i prefiksy przestrzeni nazw, sprawia, że systemy tokenów są przewidywalne, samodokumentujące się i odporne na zmiany marki bez konieczności modyfikowania kodu komponentów.