UX Toolkit: Come Creare Design System su Symfony con Componenti Riutilizzabili

Sapevi che è possibile creare componenti Twig riutilizzabili su Symfony come si farebbe in React? Possiamo aggiungere logica di business lato backend e design, ma c’è un problema: quando si tratta di frontend, noi sviluppatori backend spesso facciamo fatica.

Per risolvere questa difficoltà, tendiamo a utilizzare librerie come Bootstrap che offrono un insieme di classi CSS da applicare sui nostri elementi per ottenere un design accettabile.

Oggi sempre più spesso si usa Tailwind CSS, ma per avere un risultato soddisfacente con Tailwind è necessario impegnarsi e interessarsi realmente al design. Come sviluppatore backend, potrebbe non essere qualcosa che ci interessa particolarmente.

Ecco perché molte persone hanno proposto quello che chiamiamo librerie di componenti. Tra le più popolari c’è **shadcn/ui**.

Cos’è shadcn/ui?

Shadcn è una libreria di componenti che fornisce una base per creare il proprio design system. Un design system è semplicemente un insieme di regole che creano coerenza visiva per un design.

È per questo che riusciamo a distinguere uno stile Bootstrap, Material UI o Apple Liquid Glass: sono design system differenti che apportano una diversa coerenza visiva.

UX Toolkit: shadcn/ui per Symfony

Ma è possibile oggi su Symfony utilizzare una libreria di componenti come shadcn/ui, che originariamente è stata creata per React? La risposta è sì. Abbiamo un nuovo componente appena arrivato con l’iniziativa Symfony UX che ci permetterà di creare un design system: **UX Toolkit**.

Come Funziona UX Toolkit

Il principio del componente Toolkit è semplice: è davvero ispirato a shadcn/ui e permette di installare componenti direttamente nel proprio progetto.

• Abbiamo accesso al codice del componente e possiamo modificarlo a nostro piacimento.
• Non è obbligatorio usare Tailwind CSS: in futuro, permetterà di installare diversi kit basati su differenti design system, come può essere shadcn/ui, un kit personalizzato per la nostra azienda, ecc.

In questa prima versione è disponibile il kit shadcn/ui, ed è quello che esploreremo.

Setup del Progetto

Questo kit fornisce componenti UI Twig pronti all’uso e completamente personalizzabili, basati sul design dei componenti UI di Shadcn .

Installazione Base

Per iniziare, installiamo il componente Toolkit su un nuovo progetto Symfony. Questo kit richiede Tailwind CSS per funzionare:

• Se utilizziamo Symfony AssetMapper, è possibile installare Tailwind CSS con TailwindBundle
• Se utilizziamo Webpack Encore, possiamo seguire la guida all’installazione di TailwindCSS per Symfony

Nel secondo caso, poiché non si integra bene con Asset Mapper, inizieremo a disinstallare Asset Mapper per utilizzare Webpack Encore:

composer remove symfony/ux-turbo symfony/asset-mapper symfony/stimulus-bundle
composer require symfony/webpack-encore-bundle symfony/ux-turbo symfony/stimulus-bundle

Configurazione Tailwind CSS

Installiamo Tailwind CSS e PostCSS:

npm install tailwindcss @tailwindcss/postcss postcss postcss-loader

Creiamo un file postcss.config.js alla radice del progetto e aggiungiamo il plugin PostCSS:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Nel file webpack.config.js , attiviamo il loader PostCSS:

Encore
  .enablePostCssLoader()
;

Nel file assets/styles/app.css , aggiungiamo il CSS specifico che importa Tailwind CSS:

@import "tailwindcss";

Installazione UX Toolkit

composer require symfony/ux-toolkit

Installare i Componenti

Ora possiamo installare i componenti disponibili su shadcn/ui. Sulla documentazione ufficiale troveremo molti componenti, anche se attualmente non tutti sono ancora implementati nella versione Symfony.

Per installare un componente, ad esempio il button :

bin/console ux:install button --kit shadcn

Questo comando utilizza il principio delle ricette Flex per aggiungere codice al progetto. Sarà necessario installare le nuove dipendenze per gestire facilmente le classi e le varianti di Tailwind CSS.

Dove viene installato il codice?

Il componente Toolkit installa semplicemente il codice del componente button nel progetto. Nella directory templates/ , troveremo una nuova directory components/ contenente button.twig . È qui che si trova il codice del componente, con le stesse classi proposte da shadcn/ui, rispettando lo stesso design system.

Possiamo modificare questo codice se non siamo soddisfatti del design predefinito: cambiare i colori, le basi, ecc.

Esempio di Utilizzo

Creiamo un controller per testare il componente:

#[Route('/main', name: 'app_main')]
public function index(): Response
{
    return $this->render('main/index.html.twig');
}

Nel template, utilizziamo il componente come mostrato nella documentazione shadcn/ui:

<twig:Button variant="default">
    <twig:UX:Icon name="lucide:mail" />
    Login with Email
</twig:Button>

<twig:Button variant="outline">Button</twig:Button>

Nell’esempio sopra, è necessairio installare anche il componente UX Icons per utilizzare le icone:

composer require symfony/ux-icons

Prima di vedere il risultato, compiliamo gli asset:

npm run dev
# oppure per watch mode
npm run watch

Personalizzazione dei Colori

Una caratteristica molto interessante è la compatibilità con strumenti come **ui.shadcn.com/themes** che permettono di personalizzare i colori predefiniti. Una volta soddisfatti della personalizzazione, possiamo copiare i nuovi colori proposti e sostituire le variabili CSS in assets/style/app.css

:root {
  --background: 240 10% 3.9%;
  --foreground: 0 0% 98%;
  /* i tuoi nuovi colori */
}

Dopo aver ricompilato ( npm run dev ), lo stile del button cambierà automaticamente senza dover modificare il codice del componente. Questo rende molto facile rispettare il branding della nostra applicazione o azienda.

Stato Attuale e Futuro

Attualmente non tutti i componenti shadcn/ui sono stati implementati, soprattutto quelli che richiedono JavaScript, perché c’è ancora un lavoro di riflessione su come debbano essere implementati. L’idea è aggiungere codice nel progetto in modo molto semplice, senza una grande quantità di codice da gestire.

Penso che questa sia un’ottima iniziativa del team Symfony per permetterci di creare librerie di componenti riutilizzabili nelle nostre applicazioni Symfony. Questo nuovo componente cambierà il nostro modo di progettare interfacce con Symfony.

Buon lavoro 👨‍💻