Regione Toscana Design System

Customizzazione Tema

Panoramica

Il sistema di design RT UI Kit utilizza un approccio basato su custom properties CSS per gestire l’intera configurazione del design system.

Questo sistema permette una customizzazione flessibile e centralizzata di tutti i token di design (colori, spaziatura, tipografia, gradienti, ecc.), rispecchiando i valori definiti dal Design System e fornendo una base solida per la configurazione di Tailwind CSS.

Struttura delle Custom Properties

File di Riferimento

  • Custom Properties (Sorgente): public/css/custom-properties.css
  • Custom Properties (Distribuzione): dist/css/custom-properties.css
  • Utility Semantiche: components/01-design-system/tokens/02-semantic-color-utilities/semantic-color.css

⚠️ Nota Importante: Il file semantic-color.css NON dovrebbe essere modificato direttamente. Questo file è un parziale che viene compilato automaticamente da Tailwind CSS nel file main.css finale. Le modifiche alle utility semantiche devono essere fatte attraverso le custom properties nel file custom-properties.css.

Path delle Custom Properties

Il sistema RT UI Kit mantiene le custom properties in due posizioni diverse per diversi scopi:

1. Sorgente (public/css/custom-properties.css)

  • Scopo: File principale per lo sviluppo
  • Utilizzo: Modifiche durante lo sviluppo del design system
  • Caratteristiche: Contiene tutte le custom properties complete e commentate

2. Distribuzione (dist/css/custom-properties.css)

  • Scopo: File distribuito con il build finale
  • Utilizzo: Versione finale ottimizzata e compressa
  • Caratteristiche: Generato automaticamente dal processo di build

Quando Utilizzare Ogni Path

Scenario Path Consigliato Motivazione
Sviluppo del Design System public/css/custom-properties.css File sorgente con tutti i commenti
Build di Produzione dist/css/custom-properties.css Versione finale compressa
Customizzazione Tema (Istanza Fractal) public/css/custom-properties.css Modifiche al file sorgente
Customizzazione Tema (Integrazione Diretta) File CSS separato o dist/css/custom-properties.css Override o modifica diretta distribuzione

Organizzazione delle Custom Properties

Le custom properties sono organizzate in sezioni semantiche che corrispondono ai token di design. Tutte le custom properties definite nel file (ad eccezione di quelle semantiche) sono utilizzate per la configurazione di Tailwind CSS.

1. Colori Base (Design Tokens) - Configurazione Tailwind

:root {
    /* Primary Colors - Tailwind Config */
    --color-primary-50: #FEDBDD;
    --color-primary-100: #F5B9BB;
    --color-primary-200: #E7898C;
    --color-primary-300: #E06266;
    --color-primary-400: #D83A40;
    --color-primary-500: #D0131A;
    --color-primary-600: #AD1016;
    --color-primary-700: #8B0D11;
    --color-primary-800: #680A0D;
    --color-primary-900: #450609;

    /* Secondary Colors - Tailwind Config */
    --color-secondary-50: #D6DFEC;
    --color-secondary-100: #BAC9DF;
    --color-secondary-200: #97AECF;
    --color-secondary-300: #7593BF;
    --color-secondary-400: #5378AF;
    --color-secondary-500: #305D9F;
    --color-secondary-600: #284E84;
    --color-secondary-700: #203E6A;
    --color-secondary-800: #182F50;
    --color-secondary-900: #101F35;

    /* Neutral Colors - Tailwind Config */
    --color-neutral-50: #F7F9FB;
    --color-neutral-100: #F1F4F9;
    --color-neutral-200: #EAEFF5;
    --color-neutral-300: #E4EAF2;
    --color-neutral-400: #DDE4EF;
    --color-neutral-500: #D6DFEC;
    --color-neutral-600: #B2BAC5;
    --color-neutral-700: #737B84;
    --color-neutral-800: #474A4F;
    --color-neutral-900: #2B2D2F;
}

2. Colori di Stato (Status Colors) - Configurazione Tailwind

/* Success Colors - Tailwind Config */
--color-success-dark: #166534;
--color-success: #16a34a;
--color-success-light: #bbf7d0;

/* Error Colors - Tailwind Config */
--color-error-dark: #991b1b;
--color-error: #ef4444;
--color-error-light: #fecaca;

/* Warning Colors - Tailwind Config */
--color-warn-dark: #9a3412;
--color-warn: #f97316;
--color-warn-light: #fed7aa;

/* Info Colors - Tailwind Config */
--color-info-dark: #075985;
--color-info: #0ea5e9;
--color-info-light: #bae6fd;

3. Colori Specializzati (Specialized Colors) - Configurazione Tailwind

/* Alert Colors - Tailwind Config */
--color-allerta-verde: #92D048;
--color-allerta-giallo: #FFFE54;
--color-allerta-arancione: #F2A83B;
--color-allerta-rosso: #EA3223;

/* Brand Colors - Tailwind Config */
--color-brand-00: #D0131A;
--color-brand-01: #2B2B2B;

/* Domain-specific Colors - Tailwind Config */
--color-salvia: #4A7769;
--color-bando-aperto: #A1CCB1;
--color-bando-in-attivazione: #FCD07B;
--color-archiviato: #1F2937;

/* Focus Ring - Tailwind Config */
--color-focusring: #025ECC;

/* Social Media Colors - Tailwind Config */
--color-social-facebook: #1877F2;
--color-social-instagram: #5851db;
--color-social-linkedin: #0077B5;
--color-social-x: #000000;
--color-social-youtube: #FF0000;

4. Sistema di Spaziatura (Spacing System) - Configurazione Tailwind

/* Spacing Base Unit - Tailwind Config */
--spacing-base: 0.25rem; /* 4px/16 = 0.25 - Valore base configurabile */

/* Spacing Scale - Tailwind Config */
--spacing-0: calc(var(--spacing-base) * 0);       /* 0x */
--spacing-0-5: calc(var(--spacing-base) * 0.5);   /* 0.5x */
--spacing-1: calc(var(--spacing-base) * 1);       /* 1x */
--spacing-1-5: calc(var(--spacing-base) * 1.5);   /* 1.5x */
--spacing-2: calc(var(--spacing-base) * 2);       /* 2x */
--spacing-2-5: calc(var(--spacing-base) * 2.5);   /* 2.5x */
--spacing-3: calc(var(--spacing-base) * 3);       /* 3x */
--spacing-3-5: calc(var(--spacing-base) * 3.5);   /* 3.5x */
--spacing-4: calc(var(--spacing-base) * 4);       /* 4x */
--spacing-5: calc(var(--spacing-base) * 5);       /* 5x */
--spacing-6: calc(var(--spacing-base) * 6);       /* 6x */
--spacing-7: calc(var(--spacing-base) * 7);       /* 7x */
--spacing-8: calc(var(--spacing-base) * 8);       /* 8x */
--spacing-9: calc(var(--spacing-base) * 9);       /* 9x */
--spacing-10: calc(var(--spacing-base) * 10);     /* 10x */
--spacing-11: calc(var(--spacing-base) * 11);     /* 11x */
--spacing-12: calc(var(--spacing-base) * 12);     /* 12x */
--spacing-14: calc(var(--spacing-base) * 14);     /* 14x */
--spacing-16: calc(var(--spacing-base) * 16);     /* 16x */
--spacing-20: calc(var(--spacing-base) * 20);     /* 20x */
--spacing-24: calc(var(--spacing-base) * 24);     /* 24x */
--spacing-28: calc(var(--spacing-base) * 28);     /* 28x */
--spacing-32: calc(var(--spacing-base) * 32);     /* 32x */
--spacing-36: calc(var(--spacing-base) * 36);     /* 36x */
--spacing-40: calc(var(--spacing-base) * 40);     /* 40x */
--spacing-44: calc(var(--spacing-base) * 44);     /* 44x */
--spacing-48: calc(var(--spacing-base) * 48);     /* 48x */
--spacing-52: calc(var(--spacing-base) * 52);     /* 52x */
--spacing-56: calc(var(--spacing-base) * 56);     /* 56x */
--spacing-60: calc(var(--spacing-base) * 60);     /* 60x */
--spacing-64: calc(var(--spacing-base) * 64);     /* 64x */
--spacing-72: calc(var(--spacing-base) * 72);     /* 72x */
--spacing-80: calc(var(--spacing-base) * 80);     /* 80x */
--spacing-96: calc(var(--spacing-base) * 96);     /* 96x */

5. Gradienti (Gradients) - Configurazione Tailwind

/* Gradient Definitions - Tailwind Config */
--gradient-01: linear-gradient(6deg, #FBFBFB 2.33%, #E7F3E4 92.69%);
--gradient-02: linear-gradient(26deg, #F2FAFF -0.02%, #D2E9FF 74.53%);
--gradient-03: linear-gradient(26deg, #FFFAF2 -0.02%, #FFEDD2 74.53%);
--gradient-04: linear-gradient(133deg, #FFF 1.61%, #EEF3FA 98.28%);
--gradient-05: linear-gradient(271deg, rgba(255, 153, 0, 0.00) -0.54%, rgba(134, 91, 7, 0.60) 48.53%, rgba(24, 15, 5, 0.60) 81.24%);

6. Tipografia (Typography) - Configurazione Tailwind

/* Font Family - Tailwind Config */
--fontfamily-sans: 'Open Sans';

/* Font Sizes - Tailwind Config */
--fontsize-text-xs: 0.75rem; /* 12px */
--fontsize-text-sm: 0.875rem; /* 14px */
--fontsize-text-base: 1rem; /* 16px */
--fontsize-text-lg: 1.125rem; /* 18px */
--fontsize-text-xl: 1.25rem; /* 20px */
--fontsize-text-2xl: 1.5rem; /* 24px */
--fontsize-text-3xl: 1.875rem; /* 30px */
--fontsize-text-4xl: 2.25rem; /* 36px */
--fontsize-text-5xl: 3rem; /* 48px */
--fontsize-text-6xl: 3.75rem; /* 60px */
--fontsize-text-7xl: 4.5rem; /* 72px */
--fontsize-text-8xl: 6rem; /* 96px */
--fontsize-text-9xl: 8rem; /* 128px */

/* Additional Typography Utilities - Tailwind Config */
--fontsize-text-40px: 2.5rem; /* 40px */
--fontsize-text-42px: 2.625rem; /* 42px */

7. Prose Typography (Custom Typography Properties) - Configurazione Tailwind

/* Prose Typography - Tailwind Config */
--custom-prose-body: var(--color-neutral-800);
--custom-prose-headings: var(--color-neutral-900);
--custom-prose-lead: var(--color-neutral-700);
--custom-prose-links: var(--color-secondary-500);
--custom-prose-bold: var(--color-neutral-900);
--custom-prose-counters: currentColor;
--custom-prose-bullets: currentColor;
--custom-prose-hr: var(--color-neutral-600);
--custom-prose-quotes: var(--color-neutral-900);
--custom-prose-quote-borders: var(--color-neutral-600);
--custom-prose-captions: var(--color-neutral-800);
--custom-prose-code: var(--color-neutral-900);
--custom-prose-pre-code: var(--color-neutral-100);
--custom-prose-pre-bg: var(--color-neutral-900);
--custom-prose-th-borders: var(--color-neutral-500);
--custom-prose-td-borders: var(--color-neutral-400);

/* Prose Invert Variants - Tailwind Config */
--custom-prose-invert-body: var(--color-neutral-200);
--custom-prose-invert-headings: var(--color-white);
--custom-prose-invert-lead: var(--color-neutral-300);
--custom-prose-invert-links: var(--color-white);
--custom-prose-invert-bold: var(--color-white);
--custom-prose-invert-counters: var(--color-neutral-400);
--custom-prose-invert-bullets: var(--color-neutral-600);
--custom-prose-invert-hr: var(--color-neutral-700);
--custom-prose-invert-quotes: var(--color-neutral-100);
--custom-prose-invert-quote-borders: var(--color-neutral-700);
--custom-prose-invert-captions: var(--color-neutral-400);
--custom-prose-invert-code: var(--color-white);
--custom-prose-invert-pre-code: var(--color-neutral-300);
--custom-prose-invert-pre-bg: rgba(0, 0, 0, 0.5);
--custom-prose-invert-th-borders: var(--color-neutral-600);
--custom-prose-invert-td-borders: var(--color-neutral-700);

8. Colori Semantici (Semantic Colors) - Utility Classes

/* SEMANTIC COLOR UTILITIES - CONTENT TEXT */
--color-content-01: var(--color-neutral-900);        /* Testo principale */
--color-content-02: var(--color-secondary-500);      /* Testo secondario */
--color-content-03: var(--color-neutral-800);        /* Testo terziario */
--color-content-placeholder: var(--color-secondary-500); /* Placeholder */
--color-input-placeholder: var(--color-secondary-500);   /* Placeholder input */
--color-content-05: var(--color-neutral-700);        /* Testo 05 */
--color-content-inverse: var(--color-neutral-50);    /* Testo su sfondo scuro */
--color-content-disabled: var(--color-neutral-600);  /* Testo disabilitato */
--color-content-primary: var(--color-primary-500);   /* Testo primario */
--color-content-primary-dark: var(--color-primary-900); /* Testo primario scuro */
--color-content-primary-light: var(--color-primary-100); /* Testo primario chiaro */
--color-content-secondary: var(--color-secondary-500); /* Testo secondario */
--color-content-secondary-dark: var(--color-secondary-900); /* Testo secondario scuro */
--color-content-secondary-light: var(--color-secondary-100); /* Testo secondario chiaro */
--color-content-error: var(--color-error-dark);      /* Testo errore */
--color-content-warn: var(--color-warn-dark);        /* Testo warning */
--color-content-info: var(--color-info-dark);        /* Testo info */
--color-content-success: var(--color-success-dark);  /* Testo successo */
--color-content-category: var(--color-primary-600);  /* Testo categoria */

/* SEMANTIC COLOR UTILITIES - BUTTON */
--color-button-primary: var(--color-primary-500);           /* Pulsante primario */
--color-button-primary-hover: var(--color-primary-600);     /* Pulsante primario hover */
--color-button-primary-active: var(--color-primary-700);    /* Pulsante primario attivo */
--color-button-secondary: var(--color-secondary-500);       /* Pulsante secondario */
--color-button-secondary-hover: var(--color-secondary-600); /* Pulsante secondario hover */
--color-button-secondary-active: var(--color-secondary-700); /* Pulsante secondario attivo */
--color-button-disabled: var(--color-secondary-300);        /* Pulsante disabilitato */
--color-button-outline: var(--color-primary-500);           /* Pulsante outline */
--color-button-outline-hover: var(--color-primary-600);     /* Pulsante outline hover */
--color-button-outline-active: var(--color-primary-700);    /* Pulsante outline attivo */
--color-button-only-text: var(--color-primary-500);         /* Pulsante solo testo */
--color-button-only-text-hover: var(--color-primary-600);   /* Pulsante solo testo hover */
--color-button-only-text-active: var(--color-primary-700);  /* Pulsante solo testo attivo */
--color-button-inverted: var(--color-neutral-50);           /* Pulsante invertito */
--color-button-inverted-hover: var(--color-neutral-50);     /* Pulsante invertito hover */
--color-button-inverted-focus: var(--color-neutral-50);     /* Pulsante invertito focus */
--color-button-inverted-active: var(--color-neutral-100);   /* Pulsante invertito attivo */
--color-button-inverted-text: var(--color-content-02);      /* Testo pulsante invertito */
--color-button-inverted-text-hover: var(--color-content-01); /* Testo pulsante invertito hover */
--color-button-inverted-text-focus: var(--color-content-02); /* Testo pulsante invertito focus */
--color-button-inverted-text-active: var(--color-content-02); /* Testo pulsante invertito attivo */
--color-button-text-inverted: transparent;                  /* Pulsante testo invertito */
--color-button-text-inverted-hover: rgba(0, 0, 0, 0.5);    /* Pulsante testo invertito hover */
--color-button-text-inverted-focus: transparent;            /* Pulsante testo invertito focus */
--color-button-text-inverted-active: rgba(0, 0, 0, 0.2);   /* Pulsante testo invertito attivo */
--color-button-text-inverted-text: var(--color-content-inverse); /* Testo pulsante testo invertito */
--color-button-text-inverted-text-hover: var(--color-content-inverse); /* Testo pulsante testo invertito hover */
--color-button-text-inverted-text-focus: var(--color-content-inverse); /* Testo pulsante testo invertito focus */
--color-button-text-inverted-text-active: var(--color-content-inverse); /* Testo pulsante testo invertito attivo */

/* SEMANTIC COLOR UTILITIES - LINK */
--color-link-primary: var(--color-primary-500);           /* Link primario */
--color-link-visited: var(--color-primary-900);           /* Link visitato */
--color-link-inverse: var(--color-primary-400);           /* Link invertito */
--color-link-primary-hover: var(--color-primary-600);     /* Link primario hover */
--color-link-inverse-hover: var(--color-primary-200);     /* Link invertito hover */
--color-link-inverse-visited: var(--color-primary-100);   /* Link invertito visitato */
--color-link-secondary: var(--color-secondary-500);       /* Link secondario */
--color-link-secondary-hover: var(--color-secondary-500); /* Link secondario hover */
--color-link-secondary-focus: var(--color-secondary-500); /* Link secondario focus */
--color-link-secondary-active: var(--color-neutral-900);  /* Link secondario attivo */

/* SEMANTIC COLOR UTILITIES - BACKGROUND */
--color-background-01: var(--color-neutral-50);           /* Sfondo 01 */
--color-background-02: var(--color-neutral-100);          /* Sfondo 02 */
--color-background-03: var(--color-neutral-300);          /* Sfondo 03 */
--color-background-04: var(--color-neutral-400);          /* Sfondo 04 */
--color-background-05: var(--color-neutral-700);          /* Sfondo 05 */
--color-background-06: var(--color-neutral-800);          /* Sfondo 06 */
--color-background-07: var(--color-neutral-900);          /* Sfondo 07 */
--color-background-08: var(--color-secondary-600);        /* Sfondo 08 */
--color-background-09: var(--color-secondary-800);        /* Sfondo 09 */
--color-background-primary: var(--color-primary-500);     /* Sfondo primario */
--color-background-primary-light: var(--color-primary-50); /* Sfondo primario chiaro */
--color-background-inverse: var(--color-neutral-50);      /* Sfondo invertito */
--color-background-primary-dark: var(--color-primary-900); /* Sfondo primario scuro */
--color-background-secondary: var(--color-secondary-500); /* Sfondo secondario */
--color-background-secondary-light: var(--color-secondary-200); /* Sfondo secondario chiaro */
--color-background-secondary-dark: var(--color-secondary-900); /* Sfondo secondario scuro */

/* SEMANTIC COLOR UTILITIES - BORDER */
--color-border-gray-01: var(--color-neutral-300);         /* Bordo grigio 01 */
--color-divide-gray-01: var(--color-neutral-300);         /* Divisore grigio 01 */
--color-border-gray-02: var(--color-neutral-400);         /* Bordo grigio 02 */
--color-divide-gray-02: var(--color-neutral-400);         /* Divisore grigio 02 */
--color-border-gray-03: var(--color-neutral-600);         /* Bordo grigio 03 */
--color-divide-gray-03: var(--color-neutral-600);         /* Divisore grigio 03 */
--color-border-gray-04: var(--color-neutral-800);         /* Bordo grigio 04 */
--color-divide-gray-04: var(--color-neutral-800);         /* Divisore grigio 04 */
--color-border-input: var(--color-neutral-700);           /* Bordo input */
--color-border-primary: var(--color-primary-500);         /* Bordo primario */
--color-divide-primary: var(--color-primary-500);         /* Divisore primario */
--color-border-secondary: var(--color-secondary-500);     /* Bordo secondario */
--color-divide-secondary: var(--color-secondary-500);     /* Divisore secondario */
--color-border-inverse: var(--color-neutral-50);          /* Bordo invertito */
--color-divide-inverse: var(--color-neutral-50);          /* Divisore invertito */

Corrispondenza con le Utility Classes

Content Text Utilities

Utility Class Custom Property Descrizione
.rtds-content-01 --color-content-01 Testo principale
.rtds-content-02 --color-content-02 Testo secondario
.rtds-content-03 --color-content-03 Testo terziario
.rtds-content-placeholder --color-content-placeholder Placeholder
.rtds-input-placeholder --color-input-placeholder Placeholder input
.rtds-content-05 --color-content-05 Testo 05
.rtds-content-inverse --color-content-inverse Testo su sfondo scuro
.rtds-content-disabled --color-content-disabled Testo disabilitato
.rtds-content-primary --color-content-primary Testo primario
.rtds-content-primary-dark --color-content-primary-dark Testo primario scuro
.rtds-content-primary-light --color-content-primary-light Testo primario chiaro
.rtds-content-secondary --color-content-secondary Testo secondario
.rtds-content-secondary-dark --color-content-secondary-dark Testo secondario scuro
.rtds-content-secondary-light --color-content-secondary-light Testo secondario chiaro
.rtds-content-error --color-content-error Testo errore
.rtds-content-warn --color-content-warn Testo warning
.rtds-content-info --color-content-info Testo info
.rtds-content-success --color-content-success Testo successo
.rtds-content-category --color-content-category Testo categoria

Button Utilities

Utility Class Custom Property Descrizione
.rtds-button-primary --color-button-primary Pulsante primario
.rtds-button-primary-hover --color-button-primary-hover Pulsante primario hover
.rtds-button-primary-active --color-button-primary-active Pulsante primario attivo
.rtds-button-secondary --color-button-secondary Pulsante secondario
.rtds-button-secondary-hover --color-button-secondary-hover Pulsante secondario hover
.rtds-button-secondary-active --color-button-secondary-active Pulsante secondario attivo
.rtds-button-disabled --color-button-disabled Pulsante disabilitato
.rtds-button-outline --color-button-outline Pulsante outline
.rtds-button-outline-hover --color-button-outline-hover Pulsante outline hover
.rtds-button-outline-active --color-button-outline-active Pulsante outline attivo
.rtds-button-only-text --color-button-only-text Pulsante solo testo
.rtds-button-only-text-hover --color-button-only-text-hover Pulsante solo testo hover
.rtds-button-only-text-active --color-button-only-text-active Pulsante solo testo attivo
.rtds-button-inverted --color-button-inverted Pulsante invertito
.rtds-button-inverted-hover --color-button-inverted-hover Pulsante invertito hover
.rtds-button-inverted-focus --color-button-inverted-focus Pulsante invertito focus
.rtds-button-inverted-active --color-button-inverted-active Pulsante invertito attivo
.rtds-button-inverted-text --color-button-inverted-text Testo pulsante invertito
.rtds-button-inverted-text-hover --color-button-inverted-text-hover Testo pulsante invertito hover
.rtds-button-inverted-text-focus --color-button-inverted-text-focus Testo pulsante invertito focus
.rtds-button-inverted-text-active --color-button-inverted-text-active Testo pulsante invertito attivo
.rtds-button-text-inverted --color-button-text-inverted Pulsante testo invertito
.rtds-button-text-inverted-hover --color-button-text-inverted-hover Pulsante testo invertito hover
.rtds-button-text-inverted-focus --color-button-text-inverted-focus Pulsante testo invertito focus
.rtds-button-text-inverted-active --color-button-text-inverted-active Pulsante testo invertito attivo
.rtds-button-text-inverted-text --color-button-text-inverted-text Testo pulsante testo invertito
.rtds-button-text-inverted-text-hover --color-button-text-inverted-text-hover Testo pulsante testo invertito hover
.rtds-button-text-inverted-text-focus --color-button-text-inverted-text-focus Testo pulsante testo invertito focus
.rtds-button-text-inverted-text-active --color-button-text-inverted-text-active Testo pulsante testo invertito attivo
Utility Class Custom Property Descrizione
.rtds-link-primary --color-link-primary Link primario
.rtds-link-visited --color-link-visited Link visitato
.rtds-link-inverse --color-link-inverse Link invertito
.rtds-link-primary-hover --color-link-primary-hover Link primario hover
.rtds-link-inverse-hover --color-link-inverse-hover Link invertito hover
.rtds-link-inverse-visited --color-link-inverse-visited Link invertito visitato
.rtds-link-secondary --color-link-secondary Link secondario
.rtds-link-secondary-hover --color-link-secondary-hover Link secondario hover
.rtds-link-secondary-focus --color-link-secondary-focus Link secondario focus
.rtds-link-secondary-active --color-link-secondary-active Link secondario attivo

Background Utilities

Utility Class Custom Property Descrizione
.rtds-background-01 --color-background-01 Sfondo 01
.rtds-background-02 --color-background-02 Sfondo 02
.rtds-background-03 --color-background-03 Sfondo 03
.rtds-background-04 --color-background-04 Sfondo 04
.rtds-background-05 --color-background-05 Sfondo 05
.rtds-background-06 --color-background-06 Sfondo 06
.rtds-background-07 --color-background-07 Sfondo 07
.rtds-background-08 --color-background-08 Sfondo 08
.rtds-background-09 --color-background-09 Sfondo 09
.rtds-background-primary --color-background-primary Sfondo primario
.rtds-background-primary-light --color-background-primary-light Sfondo primario chiaro
.rtds-background-inverse --color-background-inverse Sfondo invertito
.rtds-background-primary-dark --color-background-primary-dark Sfondo primario scuro
.rtds-background-secondary --color-background-secondary Sfondo secondario
.rtds-background-secondary-light --color-background-secondary-light Sfondo secondario chiaro
.rtds-background-secondary-dark --color-background-secondary-dark Sfondo secondario scuro

Border Utilities

Utility Class Custom Property Descrizione
.rtds-border-gray-01 --color-border-gray-01 Bordo grigio 01
.rtds-divide-gray-01 --color-divide-gray-01 Divisore grigio 01
.rtds-border-gray-02 --color-border-gray-02 Bordo grigio 02
.rtds-divide-gray-02 --color-divide-gray-02 Divisore grigio 02
.rtds-border-gray-03 --color-border-gray-03 Bordo grigio 03
.rtds-divide-gray-03 --color-divide-gray-03 Divisore grigio 03
.rtds-border-gray-04 --color-border-gray-04 Bordo grigio 04
.rtds-divide-gray-04 --color-divide-gray-04 Divisore grigio 04
.rtds-border-input --color-border-input Bordo input
.rtds-border-primary --color-border-primary Bordo primario
.rtds-divide-primary --color-divide-primary Divisore primario
.rtds-border-secondary --color-border-secondary Bordo secondario
.rtds-divide-secondary --color-divide-secondary Divisore secondario
.rtds-border-inverse --color-border-inverse Bordo invertito
.rtds-divide-inverse --color-divide-inverse Divisore invertito

Customizzazione del Tema

La customizzazione del tema può essere effettuata seguendo diversi approcci, a seconda della modalità di integrazione scelta:

Metodo 1: Override delle Custom Properties (Integrazione Diretta)

Per customizzare il tema quando si utilizza l’integrazione diretta, puoi sovrascrivere le custom properties nel tuo CSS:

:root {
    /* Override dei colori base */
    --color-primary-500: #FF0000; /* Rosso personalizzato */
    --color-secondary-500: #00FF00; /* Verde personalizzato */
    
    /* Override dei colori semantici */
    --color-content-primary: #FF0000; /* Testo primario personalizzato */
    --color-button-primary: #FF0000; /* Pulsante primario personalizzato */
}

File di override separato (Raccomandato):

/* file: my-custom-theme.css */
:root {
    --color-primary-500: #FF0000;
    --color-secondary-500: #00FF00;
    --spacing-base: 0.5rem; /* Modifica della spaziatura base */
}

Metodo 2: Tema Specifico con Selettori CSS

Puoi creare temi specifici utilizzando selettori CSS per supportare più varianti:

/* Tema scuro */
[data-theme="dark"] {
    --color-content-01: #FFFFFF;
    --color-content-02: #CCCCCC;
    --color-background-01: #1A1A1A;
    --color-background-02: #2A2A2A;
}

/* Tema aziendale */
[data-theme="corporate"] {
    --color-primary-500: #1E40AF;
    --color-secondary-500: #64748B;
    --color-content-primary: #1E40AF;
    --color-button-primary: #1E40AF;
}

/* Tema per brand specifico */
[data-brand="company-x"] {
    --color-primary-500: #10B981; /* Verde aziendale */
    --color-secondary-500: #6B7280; /* Grigio aziendale */
    --color-content-primary: #10B981;
    --color-button-primary: #10B981;
    --color-link-primary: #10B981;
}

Metodo 3: Modifica del File Sorgente (Istanza Fractal)

Per modifiche permanenti quando si lavora con l’istanza Fractal, modifica direttamente il file public/css/custom-properties.css:

⚠️ Nota: Per le customizzazioni del design system in modalità Fractal, modifica sempre il file sorgente public/css/custom-properties.css. I file in assets/ e dist/ vengono generati automaticamente dal processo di build.

:root {
    /* Modifica i colori base */
    --color-primary-50: #FEF2F2;
    --color-primary-100: #FEE2E2;
    --color-primary-200: #FECACA;
    --color-primary-300: #FCA5A5;
    --color-primary-400: #F87171;
    --color-primary-500: #EF4444; /* Colore primario modificato */
    --color-primary-600: #DC2626;
    --color-primary-700: #B91C1C;
    --color-primary-800: #991B1B;
    --color-primary-900: #7F1D1D;
    
    /* I colori semantici si aggiorneranno automaticamente */
}

Metodo 4: Modifica del File di Distribuzione (Integrazione Diretta)

Per modifiche dirette quando si utilizza l’integrazione diretta, puoi modificare dist/css/custom-properties.css:

⚠️ Attenzione: Questo metodo sovrascrive il file di distribuzione. Assicurati di fare un backup prima delle modifiche.

/* Modifica diretta di dist/css/custom-properties.css */
:root {
    --color-primary-500: #FF0000; /* Override del colore primario */
    --color-secondary-500: #00FF00; /* Override del colore secondario */
    --spacing-base: 0.5rem; /* Modifica della spaziatura base */
}

Scelta del Metodo

Modalità di Integrazione Metodo Raccomandato Alternativa
Integrazione Diretta Metodo 1 (Override con file separato) Modifica diretta distribuzione
Istanza Fractal Metodo 3 (Modifica file sorgente) Metodo 2 (Temi specifici)
Temi Multipli Metodo 2 (Selettori CSS) Metodo 1 (File separati)
Prototipazione Rapida Metodo 4 (Modifica diretta) Metodo 1 (Override)

Best Practices

1. Mantenere la Gerarchia

  • Modifica sempre i colori base prima dei colori semantici
  • I colori semantici dovrebbero sempre riferirsi ai colori base
  • Mantieni la coerenza tra i diversi stati (hover, active, focus)

2. Consistenza

  • Utilizza sempre le utility classes semantiche invece dei colori diretti
  • Mantieni la coerenza tra i diversi stati (hover, active, focus)
  • Documenta sempre le modifiche apportate

3. Accessibilità

  • Assicurati che il contrasto sia sufficiente per l’accessibilità
  • Testa i colori con strumenti di accessibilità
  • Verifica la leggibilità su diversi dispositivi

4. Performance

  • Evita di creare troppe varianti non necessarie
  • Utilizza la versione minificata (main.min.css) in produzione

5. Modalità di Integrazione

Per Integrazione Diretta:

  • Utilizza file CSS separati per le customizzazioni
  • Fai backup del file di distribuzione prima delle modifiche
  • Testa le modifiche in ambiente di sviluppo prima del deploy

Per Istanza Fractal:

  • Modifica sempre i file sorgente (public/css/custom-properties.css)
  • Esegui il build dopo ogni modifica per generare la distribuzione
  • Utilizza il versioning per tracciare le modifiche

6. Versioning e Backup

# Per modalità Fractal
cp public/css/custom-properties.css public/css/custom-properties.backup.css

# Per modalità diretta
cp dist/css/custom-properties.css dist/css/custom-properties.backup.css

7. Documentazione delle Modifiche

/* 
 * Customizzazioni per Progetto XYZ
 * Data: 2024-01-15
 * Autore: Team Design
 * Modalità: Integrazione Diretta
 * 
 * Modifiche:
 * - Colore primario cambiato da #D0131A a #FF0000
 * - Spaziatura base aumentata da 0.25rem a 0.5rem
 * - Aggiunto tema scuro per sezione admin
 */

Esempi di Utilizzo

Esempio 1: Customizzazione del Tema Primario

:root {
    /* Cambia il colore primario da rosso a blu */
    --color-primary-500: #3B82F6;
    --color-primary-600: #2563EB;
    --color-primary-700: #1D4ED8;
    
    /* I colori semantici si aggiorneranno automaticamente */
}

Esempio 2: Tema per Brand Specifico

[data-brand="company-x"] {
    --color-primary-500: #10B981; /* Verde aziendale */
    --color-secondary-500: #6B7280; /* Grigio aziendale */
    --color-content-primary: #10B981;
    --color-button-primary: #10B981;
    --color-link-primary: #10B981;
}

Esempio 3: Override di Utility Specifiche

/* Override di una utility specifica */
.rtds-content-primary {
    color: #FF6B6B; /* Colore personalizzato */
}

/* Oppure sovrascrivi la custom property */
:root {
    --color-content-primary: #FF6B6B;
}

Corrispondenza con le Utility Classes

Debugging

Verifica delle Custom Properties

// Verifica il valore di una custom property
const primaryColor = getComputedStyle(document.documentElement)
    .getPropertyValue('--color-primary-500');
console.log('Primary color:', primaryColor);

Ispezione nel Browser

  1. Apri gli strumenti di sviluppo
  2. Vai alla scheda “Computed”
  3. Seleziona un elemento con le utility classes
  4. Verifica che le proprietà CSS utilizzino le custom properties corrette

Note Importanti

  • Le custom properties sono supportate da tutti i browser moderni
  • Il fallback per browser legacy dovrebbe essere gestito separatamente
  • Le modifiche alle custom properties sono reattive e si applicano immediatamente
  • Mantieni sempre la documentazione aggiornata quando modifichi i colori

Utilizzo delle Custom Properties nella Configurazione Tailwind

Configurazione Tailwind CSS

Le custom properties definite nel file custom-properties.css vengono utilizzate per configurare Tailwind CSS. L’approccio varia a seconda della versione di Tailwind utilizzata:

Configurazione Attuale (Tailwind CSS v3.4.17)

Il RT UI Kit utilizza attualmente Tailwind CSS versione 3.4.17, che richiede la configurazione tramite file JavaScript (tailwind.config.js):

1. Colori (Colors)

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        // Colori base
        primary: {
          50: 'var(--color-primary-50)',
          100: 'var(--color-primary-100)',
          200: 'var(--color-primary-200)',
          300: 'var(--color-primary-300)',
          400: 'var(--color-primary-400)',
          500: 'var(--color-primary-500)',
          600: 'var(--color-primary-600)',
          700: 'var(--color-primary-700)',
          800: 'var(--color-primary-800)',
          900: 'var(--color-primary-900)',
        },
        secondary: {
          50: 'var(--color-secondary-50)',
          100: 'var(--color-secondary-100)',
          200: 'var(--color-secondary-200)',
          300: 'var(--color-secondary-300)',
          400: 'var(--color-secondary-400)',
          500: 'var(--color-secondary-500)',
          600: 'var(--color-secondary-600)',
          700: 'var(--color-secondary-700)',
          800: 'var(--color-secondary-800)',
          900: 'var(--color-secondary-900)',
        },
        neutral: {
          50: 'var(--color-neutral-50)',
          100: 'var(--color-neutral-100)',
          200: 'var(--color-neutral-200)',
          300: 'var(--color-neutral-300)',
          400: 'var(--color-neutral-400)',
          500: 'var(--color-neutral-500)',
          600: 'var(--color-neutral-600)',
          700: 'var(--color-neutral-700)',
          800: 'var(--color-neutral-800)',
          900: 'var(--color-neutral-900)',
        },
        // Colori di stato
        success: {
          DEFAULT: 'var(--color-success)',
          dark: 'var(--color-success-dark)',
          light: 'var(--color-success-light)',
        },
        error: {
          DEFAULT: 'var(--color-error)',
          dark: 'var(--color-error-dark)',
          light: 'var(--color-error-light)',
        },
        warn: {
          DEFAULT: 'var(--color-warn)',
          dark: 'var(--color-warn-dark)',
          light: 'var(--color-warn-light)',
        },
        info: {
          DEFAULT: 'var(--color-info)',
          dark: 'var(--color-info-dark)',
          light: 'var(--color-info-light)',
        },
        // Colori specializzati
        allerta: {
          verde: 'var(--color-allerta-verde)',
          giallo: 'var(--color-allerta-giallo)',
          arancione: 'var(--color-allerta-arancione)',
          rosso: 'var(--color-allerta-rosso)',
        },
        brand: {
          00: 'var(--color-brand-00)',
          01: 'var(--color-brand-01)',
        },
        salvia: 'var(--color-salvia)',
        'bando-aperto': 'var(--color-bando-aperto)',
        'bando-in-attivazione': 'var(--color-bando-in-attivazione)',
        archiviato: 'var(--color-archiviato)',
        focusring: 'var(--color-focusring)',
        social: {
          facebook: 'var(--color-social-facebook)',
          instagram: 'var(--color-social-instagram)',
          linkedin: 'var(--color-social-linkedin)',
          x: 'var(--color-social-x)',
          youtube: 'var(--color-social-youtube)',
        },
      },
    },
  },
}

2. Spaziatura (Spacing)

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      spacing: {
        // Utilizzo delle custom properties di spaziatura
        0: 'var(--spacing-0)',
        0.5: 'var(--spacing-0-5)',
        1: 'var(--spacing-1)',
        1.5: 'var(--spacing-1-5)',
        2: 'var(--spacing-2)',
        2.5: 'var(--spacing-2-5)',
        3: 'var(--spacing-3)',
        3.5: 'var(--spacing-3-5)',
        4: 'var(--spacing-4)',
        5: 'var(--spacing-5)',
        6: 'var(--spacing-6)',
        7: 'var(--spacing-7)',
        8: 'var(--spacing-8)',
        9: 'var(--spacing-9)',
        10: 'var(--spacing-10)',
        11: 'var(--spacing-11)',
        12: 'var(--spacing-12)',
        14: 'var(--spacing-14)',
        16: 'var(--spacing-16)',
        20: 'var(--spacing-20)',
        24: 'var(--spacing-24)',
        28: 'var(--spacing-28)',
        32: 'var(--spacing-32)',
        36: 'var(--spacing-36)',
        40: 'var(--spacing-40)',
        44: 'var(--spacing-44)',
        48: 'var(--spacing-48)',
        52: 'var(--spacing-52)',
        56: 'var(--spacing-56)',
        60: 'var(--spacing-60)',
        64: 'var(--spacing-64)',
        72: 'var(--spacing-72)',
        80: 'var(--spacing-80)',
        96: 'var(--spacing-96)',
      },
    },
  },
}

3. Gradienti (Gradients)

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      backgroundImage: {
        'gradient-01': 'var(--gradient-01)',
        'gradient-02': 'var(--gradient-02)',
        'gradient-03': 'var(--gradient-03)',
        'gradient-04': 'var(--gradient-04)',
        'gradient-05': 'var(--gradient-05)',
      },
    },
  },
}

4. Tipografia (Typography)

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: ['var(--fontfamily-sans)', 'sans-serif'],
      },
      fontSize: {
        'xs': 'var(--fontsize-text-xs)',
        'sm': 'var(--fontsize-text-sm)',
        'base': 'var(--fontsize-text-base)',
        'lg': 'var(--fontsize-text-lg)',
        'xl': 'var(--fontsize-text-xl)',
        '2xl': 'var(--fontsize-text-2xl)',
        '3xl': 'var(--fontsize-text-3xl)',
        '4xl': 'var(--fontsize-text-4xl)',
        '5xl': 'var(--fontsize-text-5xl)',
        '6xl': 'var(--fontsize-text-6xl)',
        '7xl': 'var(--fontsize-text-7xl)',
        '8xl': 'var(--fontsize-text-8xl)',
        '9xl': 'var(--fontsize-text-9xl)',
        '40px': 'var(--fontsize-text-40px)',
        '42px': 'var(--fontsize-text-42px)',
      },
    },
  },
}

5. Prose Typography

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      typography: {
        DEFAULT: {
          css: {
            '--tw-prose-body': 'var(--custom-prose-body)',
            '--tw-prose-headings': 'var(--custom-prose-headings)',
            '--tw-prose-lead': 'var(--custom-prose-lead)',
            '--tw-prose-links': 'var(--custom-prose-links)',
            '--tw-prose-bold': 'var(--custom-prose-bold)',
            '--tw-prose-counters': 'var(--custom-prose-counters)',
            '--tw-prose-bullets': 'var(--custom-prose-bullets)',
            '--tw-prose-hr': 'var(--custom-prose-hr)',
            '--tw-prose-quotes': 'var(--custom-prose-quotes)',
            '--tw-prose-quote-borders': 'var(--custom-prose-quote-borders)',
            '--tw-prose-captions': 'var(--custom-prose-captions)',
            '--tw-prose-code': 'var(--custom-prose-code)',
            '--tw-prose-pre-code': 'var(--custom-prose-pre-code)',
            '--tw-prose-pre-bg': 'var(--custom-prose-pre-bg)',
            '--tw-prose-th-borders': 'var(--custom-prose-th-borders)',
            '--tw-prose-td-borders': 'var(--custom-prose-td-borders)',
          },
        },
        invert: {
          css: {
            '--tw-prose-body': 'var(--custom-prose-invert-body)',
            '--tw-prose-headings': 'var(--custom-prose-invert-headings)',
            '--tw-prose-lead': 'var(--custom-prose-invert-lead)',
            '--tw-prose-links': 'var(--custom-prose-invert-links)',
            '--tw-prose-bold': 'var(--custom-prose-invert-bold)',
            '--tw-prose-counters': 'var(--custom-prose-invert-counters)',
            '--tw-prose-bullets': 'var(--custom-prose-invert-bullets)',
            '--tw-prose-hr': 'var(--custom-prose-invert-hr)',
            '--tw-prose-quotes': 'var(--custom-prose-invert-quotes)',
            '--tw-prose-quote-borders': 'var(--custom-prose-invert-quote-borders)',
            '--tw-prose-captions': 'var(--custom-prose-invert-captions)',
            '--tw-prose-code': 'var(--custom-prose-invert-code)',
            '--tw-prose-pre-code': 'var(--custom-prose-invert-pre-code)',
            '--tw-prose-pre-bg': 'var(--custom-prose-invert-pre-bg)',
            '--tw-prose-th-borders': 'var(--custom-prose-invert-th-borders)',
            '--tw-prose-td-borders': 'var(--custom-prose-invert-td-borders)',
          },
        },
      },
    },
  },
}

Configurazione Futura (Tailwind CSS v4+)

In Tailwind CSS v4, la configurazione si sposta da JavaScript a CSS nativo utilizzando la direttiva @config:

1. Colori (Colors)

/* tailwind.config.css */
@config {
  theme: {
    colors: {
      primary: {
        50: var(--color-primary-50);
        100: var(--color-primary-100);
        200: var(--color-primary-200);
        300: var(--color-primary-300);
        400: var(--color-primary-400);
        500: var(--color-primary-500);
        600: var(--color-primary-600);
        700: var(--color-primary-700);
        800: var(--color-primary-800);
        900: var(--color-primary-900);
      }
      secondary: {
        50: var(--color-secondary-50);
        100: var(--color-secondary-100);
        200: var(--color-secondary-200);
        300: var(--color-secondary-300);
        400: var(--color-secondary-400);
        500: var(--color-secondary-500);
        600: var(--color-secondary-600);
        700: var(--color-secondary-700);
        800: var(--color-secondary-800);
        900: var(--color-secondary-900);
      }
      neutral: {
        50: var(--color-neutral-50);
        100: var(--color-neutral-100);
        200: var(--color-neutral-200);
        300: var(--color-neutral-300);
        400: var(--color-neutral-400);
        500: var(--color-neutral-500);
        600: var(--color-neutral-600);
        700: var(--color-neutral-700);
        800: var(--color-neutral-800);
        900: var(--color-neutral-900);
      }
      success: {
        DEFAULT: var(--color-success);
        dark: var(--color-success-dark);
        light: var(--color-success-light);
      }
      error: {
        DEFAULT: var(--color-error);
        dark: var(--color-error-dark);
        light: var(--color-error-light);
      }
      warn: {
        DEFAULT: var(--color-warn);
        dark: var(--color-warn-dark);
        light: var(--color-warn-light);
      }
      info: {
        DEFAULT: var(--color-info);
        dark: var(--color-info-dark);
        light: var(--color-info-light);
      }
    }
  }
}

2. Spaziatura (Spacing)

/* tailwind.config.css */
@config {
  theme: {
    spacing: {
      0: var(--spacing-0);
      0.5: var(--spacing-0-5);
      1: var(--spacing-1);
      1.5: var(--spacing-1-5);
      2: var(--spacing-2);
      2.5: var(--spacing-2-5);
      3: var(--spacing-3);
      3.5: var(--spacing-3-5);
      4: var(--spacing-4);
      5: var(--spacing-5);
      6: var(--spacing-6);
      7: var(--spacing-7);
      8: var(--spacing-8);
      9: var(--spacing-9);
      10: var(--spacing-10);
      11: var(--spacing-11);
      12: var(--spacing-12);
      14: var(--spacing-14);
      16: var(--spacing-16);
      20: var(--spacing-20);
      24: var(--spacing-24);
      28: var(--spacing-28);
      32: var(--spacing-32);
      36: var(--spacing-36);
      40: var(--spacing-40);
      44: var(--spacing-44);
      48: var(--spacing-48);
      52: var(--spacing-52);
      56: var(--spacing-56);
      60: var(--spacing-60);
      64: var(--spacing-64);
      72: var(--spacing-72);
      80: var(--spacing-80);
      96: var(--spacing-96);
    }
  }
}

3. Gradienti (Gradients)

/* tailwind.config.css */
@config {
  theme: {
    backgroundImage: {
      'gradient-01': var(--gradient-01);
      'gradient-02': var(--gradient-02);
      'gradient-03': var(--gradient-03);
      'gradient-04': var(--gradient-04);
      'gradient-05': var(--gradient-05);
    }
  }
}

4. Tipografia (Typography)

/* tailwind.config.css */
@config {
  theme: {
    fontFamily: {
      sans: var(--fontfamily-sans), sans-serif;
    }
    fontSize: {
      xs: var(--fontsize-text-xs);
      sm: var(--fontsize-text-sm);
      base: var(--fontsize-text-base);
      lg: var(--fontsize-text-lg);
      xl: var(--fontsize-text-xl);
      '2xl': var(--fontsize-text-2xl);
      '3xl': var(--fontsize-text-3xl);
      '4xl': var(--fontsize-text-4xl);
      '5xl': var(--fontsize-text-5xl);
      '6xl': var(--fontsize-text-6xl);
      '7xl': var(--fontsize-text-7xl);
      '8xl': var(--fontsize-text-8xl);
      '9xl': var(--fontsize-text-9xl);
      '40px': var(--fontsize-text-40px);
      '42px': var(--fontsize-text-42px);
    }
  }
}

Vantaggi dell’Approccio con Custom Properties

  1. Centralizzazione: Tutti i valori di design sono definiti in un unico file
  2. Consistenza: Le custom properties garantiscono coerenza tra CSS e Tailwind
  3. Manutenibilità: Modifiche ai valori di design in un solo punto
  4. Flessibilità: Possibilità di override delle custom properties per temi specifici
  5. Preparazione per il Futuro: Le custom properties sono già in formato CSS nativo

Strategia di Migrazione verso Tailwind CSS v4

L’approccio con custom properties ci permette di:

  1. Mantenere la Compatibilità: Le custom properties funzionano in tutte le versioni
  2. Preparare il Terreno: La struttura è già pronta per configurazioni CSS-native
  3. Ridurre i Rischi: Meno dipendenza dalla sintassi JavaScript di configurazione
  4. Accelerare l’Adozione: Migrazione più rapida quando le nuove versioni saranno disponibili

Tailwind CSS v3.4.17 (JavaScript)

// tailwind.config.js 
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          500: 'var(--color-primary-500)',
          600: 'var(--color-primary-600)',
        },
      },
    },
  },
}

Tailwind CSS v4+ (CSS)

/* custom-properties.css - diventa l'unico file di configurazione */
@import "tailwindcss";
@theme {
    --color-primary-500: #D0131A;
    --color-primary-600: #AD1016;
}

Modalità di Integrazione dello UI Kit

Il RT UI Kit può essere utilizzato in due modalità principali, ognuna con approcci diversi per la customizzazione:

Modalità 1: Istanza Fractal (Sviluppo sui Sorgenti)

Caratteristiche:

  • Lavoro diretto sui file sorgente del design system
  • Utilizzo dei vari npm script per sviluppo e build
  • Generazione di una distribuzione personalizzata
  • Controllo completo su tutti i componenti e gli stili

Workflow:

  1. Setup: Clonare il repository e installare le dipendenze
  2. Sviluppo: Utilizzare npm start per avviare l’ambiente di sviluppo
  3. Customizzazione: Modificare public/css/custom-properties.css per personalizzare il tema
  4. Build: Eseguire npm run build per generare la distribuzione personalizzata
  5. Integrazione: Utilizzare i file generati dalla dist/ personalizzata

Vantaggi:

  • Controllo completo su tutto il design system
  • Possibilità di modificare componenti e logica
  • Ambiente di sviluppo integrato con Fractal
  • Documentazione automatica dei componenti

Comandi principali:

npm start          # Avvia l'ambiente di sviluppo
npm run build      # Genera la distribuzione
npm run clean      # Pulisce la cartella dist

Modalità 2: Integrazione Diretta (CSS e Componenti)

Caratteristiche:

  • Utilizzo diretto dei file CSS e componenti dalla distribuzione di default
  • Consultazione della web UI Fractal per la documentazione
  • Customizzazione tramite override delle custom properties

Opzioni di Integrazione:

A. Modifica Diretta del File di Distribuzione

/* Modifica diretta di dist/css/custom-properties.css */
:root {
    --color-primary-500: #FF0000; /* Override del colore primario */
    --color-secondary-500: #00FF00; /* Override del colore secondario */
}

B. Override con File CSS Separato

/* file: my-custom-theme.css */
:root {
    --color-primary-500: #FF0000;
    --color-secondary-500: #00FF00;
    --spacing-base: 0.5rem; /* Modifica della spaziatura base */
}

Inclusione nel progetto:

<!-- Includere prima il CSS del design system -->
<link rel="stylesheet" href="path/to/rt-ui-kit/dist/css/main.min.css">
<!-- Poi il file di override -->
<link rel="stylesheet" href="path/to/my-custom-theme.css">

Vantaggi:

  • Setup rapido e semplice
  • Nessuna dipendenza da Node.js/npm
  • Facile integrazione in progetti esistenti
  • Possibilità di avere più temi

Scelta della Modalità

Scenario Modalità Consigliata Motivazione
Sviluppo di un nuovo progetto Istanza Fractal Controllo completo e sviluppo integrato
Integrazione in progetto esistente Integrazione Diretta Setup rapido e minimo impatto
Customizzazioni complesse Istanza Fractal Possibilità di modificare componenti
Temi multipli Integrazione Diretta Facile gestione di override CSS
Prototipazione rapida Integrazione Diretta Setup immediato

Best Practices per l’Integrazione

1. Backup delle Modifiche

# Per modalità Fractal
cp public/css/custom-properties.css public/css/custom-properties.backup.css

# Per modalità diretta
cp dist/css/custom-properties.css dist/css/custom-properties.backup.css

2. Versioning delle Customizzazioni

/* Mantenere un file separato per le modifiche */
:root {
    /* Customizzazioni progetto-specifiche */
    --color-primary-500: #FF0000;
    --color-secondary-500: #00FF00;
}

3. Documentazione delle Modifiche

/* 
 * Customizzazioni per Progetto XYZ
 * Data: 2024-01-15
 * Autore: Team Design
 * Modalità: Integrazione Diretta
 * 
 * Modifiche:
 * - Colore primario cambiato da #D0131A a #FF0000
 * - Spaziatura base aumentata da 0.25rem a 0.5rem
 * - Aggiunto tema scuro per sezione admin
 */

Troubleshooting

Problemi Comuni

1. Le modifiche non si applicano:

  • Verificare che il file CSS di override sia caricato dopo il CSS del design system
  • Controllare la specificità CSS
  • Verificare che le custom properties siano definite correttamente

2. Conflitti con stili esistenti:

  • Utilizzare selettori più specifici
  • Considerare l’uso di !important solo se necessario
  • Verificare l’ordine di caricamento dei CSS

3. Performance degradate:

  • Utilizzare la versione minificata (main.min.css)
  • Considerare l’uso di CSS custom properties per override dinamici
  • Ottimizzare il caricamento dei file CSS