Μετάβαση στο περιεχόμενο

Αρχιτεκτονική Design-Token

Όλες οι οπτικές ιδιότητες της εφαρμογής ελέγχονται μέσω Design-Tokens (μεταβλητές CSS). Όποιος θέλει να αλλάξει τα χρώματα της εφαρμογής ή να φτιάξει ένα νέο theme, επεξεργάζεται ένα μόνο αρχείο theme-*.css και δεν αγγίζει καμία component. Αυτός ο κανόνας επιβάλλεται από tests, όχι απλώς από σύμβαση. Η πλήρης αναφορά token βρίσκεται στο docs/DESIGN-TOKENS.md.

Τα στρώματα token

  1. Tokens ανά theme — το κανονικό σύνολο των 44 tokens, οριζόμενα από μία φορά ανά theme στο frontend/src/styles/themes/theme-<id>.css (φόντα, κείμενο, περιγράμματα, διαδραστικά, τονισμός, κατάσταση, ανατροφοδότηση ασκήσεων, αστέρι, charts, σκιές). Μια αλλαγή του [data-theme] ανατρέπει όλα. Κάθε theme πρέπει να ορίζει ακριβώς το ίδιο σύνολο (καρφωμένο μέσω themes.test.ts).
  2. Tokens ανεξάρτητα από theme — τιμές που εκ κατασκευής είναι ίδιες σε κάθε theme (π.χ. παλέτα μάρκας, χρώματα σύνταξης, αποστάσεις διάταξης). Βρίσκονται στο global.css :root.
  3. Legacy-Aliase — παλιά ονόματα όπως --surface, --danger, που επιλύονται μέσω των κανονικών tokens.

Οι κανόνες (εν συντομία)

  • Καμία ωμή χρωματική τιμή (#hex, rgb(), hsl()) σε μια δήλωση κατανάλωσης. Μια κυριολεκτική τιμή επιτρέπεται μόνο ως τιμή ενός ορισμού --token:. Σε components και κανόνες CSS αναφέρεσαι σε tokens: color: var(--fg-primary).
  • Καμία Tailwind-Utility με σταθερή παλέτα (bg-blue-500). Χρησιμοποίησε utilities με υποστήριξη token (bg-accent → var(--accent)) ή ένα Arbitrary-Value πάνω από ένα token.
  • Κανένα Inline-Style με χρωματικές τιμές.
  • Οι σκιές, οι ακτίνες, οι αποστάσεις είναι επίσης tokens (--shadow-elevated, --radius-md, --space-4).

Δημιουργία ή προσαρμογή ενός theme

  1. Αντίγραψε ένα υπάρχον theme-<id>.css ως πρότυπο.
  2. Όρισε και τα 44 κανονικά tokens (η ισοτιμία είναι υποχρεωτική).
  3. Πρόσεξε την αντίθεση WCAG-AA — το contrast.test.ts ελέγχει όλα τα themes υπολογιστικά.
  4. Καταχώρισε το theme· ο picker στις Ρυθμίσεις → Εμφάνιση το αναλαμβάνει.

Αν ένα νέο feature χρειάζεται ένα νέο χρώμα: πρόσθεσε ένα token, όχι μια κυριολεκτική τιμή. Αν διαφέρει ανά theme, πρόσθεσέ το σε όλα τα theme-*.css· αν είναι παντού ίδιο, στο global.css :root.

Επιβολή

Τρεις guards εκτελούνται στο make test (no-hardcoded-colors.test.ts): χρωματικές τιμές σε .tsx (μέσω μιας μόνο συρρικνούμενης allowlist), χρωματικές τιμές σε μη-theme CSS και Tailwind-Utilities με σταθερή παλέτα (πρέπει να είναι μηδέν). Επιπλέον το themes.test.ts (ισοτιμία token) και το contrast.test.ts (AA σε όλα τα themes).

Σχετικές σελίδες