# Sistema di design Zendesk Garden ## Anteprima dell’interfaccia del sistema di design Zendesk Garden Modifica la visibilità della risposta, convalida una breve bozza, salva un’istantanea locale e prepara la bozza successiva. ## Riferimento di progettazione del sistema di design Zendesk Garden ThemeProvider, Buttons e Forms nativi di Garden 9.16.1 React; flusso originale di composizione locale. ### Raggio degli angoli | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | borderRadii.sm | 2px | Scegli la forma in base al ruolo del componente; l’angolo medio predefinito non è a pillola. | | borderRadii.md | 4px | Scegli la forma in base al ruolo del componente; l’angolo medio predefinito non è a pillola. | | borderRadii.lg | 8px | Scegli la forma in base al ruolo del componente; l’angolo medio predefinito non è a pillola. | ### Breakpoint responsive | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | breakpoints.xs | 0px | Breakpoint del tema; non garantiscono che l’applicazione cambi ogni area a ciascun passaggio. | | breakpoints.sm | 576px | Breakpoint del tema; non garantiscono che l’applicazione cambi ogni area a ciascun passaggio. | | breakpoints.md | 768px | Breakpoint del tema; non garantiscono che l’applicazione cambi ogni area a ciascun passaggio. | | breakpoints.lg | 992px | Breakpoint del tema; non garantiscono che l’applicazione cambi ogni area a ciascun passaggio. | | breakpoints.xl | 1200px | Breakpoint del tema; non garantiscono che l’applicazione cambi ogni area a ciascun passaggio. | ### Dimensioni del testo | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | fontSizes.xs | 10px | Mantieni distinti i ruoli del testo del corpo, delle etichette, dei metadati e dei titoli. | | fontSizes.sm | 12px | Mantieni distinti i ruoli del testo del corpo, delle etichette, dei metadati e dei titoli. | | fontSizes.md | 14px | Mantieni distinti i ruoli del testo del corpo, delle etichette, dei metadati e dei titoli. | | fontSizes.lg | 18px | Mantieni distinti i ruoli del testo del corpo, delle etichette, dei metadati e dei titoli. | | fontSizes.xl | 22px | Mantieni distinti i ruoli del testo del corpo, delle etichette, dei metadati e dei titoli. | | fontSizes.xxl | 26px | Mantieni distinti i ruoli del testo del corpo, delle etichette, dei metadati e dei titoli. | | fontSizes.xxxl | 36px | Mantieni distinti i ruoli del testo del corpo, delle etichette, dei metadati e dei titoli. | ### Altezze di riga | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | lineHeights.sm | 16px | Usalo insieme al ruolo tipografico; non ricavare tutte le altezze di riga dalla dimensione del carattere. | | lineHeights.md | 20px | Usalo insieme al ruolo tipografico; non ricavare tutte le altezze di riga dalla dimensione del carattere. | | lineHeights.lg | 24px | Usalo insieme al ruolo tipografico; non ricavare tutte le altezze di riga dalla dimensione del carattere. | | lineHeights.xl | 28px | Usalo insieme al ruolo tipografico; non ricavare tutte le altezze di riga dalla dimensione del carattere. | | lineHeights.xxl | 32px | Usalo insieme al ruolo tipografico; non ricavare tutte le altezze di riga dalla dimensione del carattere. | | lineHeights.xxxl | 44px | Usalo insieme al ruolo tipografico; non ricavare tutte le altezze di riga dalla dimensione del carattere. | ### Livelli di spaziatura | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | space.base | 4 | Valori di spaziatura del tema per un ritmo prevedibile. | | space.xxs | 4px | Valori di spaziatura del tema per un ritmo prevedibile. | | space.xs | 8px | Valori di spaziatura del tema per un ritmo prevedibile. | | space.sm | 12px | Valori di spaziatura del tema per un ritmo prevedibile. | | space.md | 20px | Valori di spaziatura del tema per un ritmo prevedibile. | | space.lg | 32px | Valori di spaziatura del tema per un ritmo prevedibile. | | space.xl | 40px | Valori di spaziatura del tema per un ritmo prevedibile. | | space.xxl | 48px | Valori di spaziatura del tema per un ritmo prevedibile. | ### Mappatura dei ruoli semantici chiari | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | colors.variables.light.background.default | palette.white | Alias di un ruolo del tema; risolvilo tramite la tonalità e la palette selezionate, invece di trattare l’alias come un colore CSS. | | colors.variables.light.background.subtle | neutralHue.100 | Alias di un ruolo del tema; risolvilo tramite la tonalità e la palette selezionate, invece di trattare l’alias come un colore CSS. | | colors.variables.light.background.danger | dangerHue.100 | Alias di un ruolo del tema; risolvilo tramite la tonalità e la palette selezionate, invece di trattare l’alias come un colore CSS. | | colors.variables.light.background.primaryEmphasis | primaryHue.700 | Alias di un ruolo del tema; risolvilo tramite la tonalità e la palette selezionate, invece di trattare l’alias come un colore CSS. | | colors.variables.light.foreground.default | neutralHue.900 | Alias di un ruolo del tema; risolvilo tramite la tonalità e la palette selezionate, invece di trattare l’alias come un colore CSS. | | colors.variables.light.foreground.subtle | neutralHue.700 | Alias di un ruolo del tema; risolvilo tramite la tonalità e la palette selezionate, invece di trattare l’alias come un colore CSS. | | colors.variables.light.foreground.onEmphasis | palette.white | Alias di un ruolo del tema; risolvilo tramite la tonalità e la palette selezionate, invece di trattare l’alias come un colore CSS. | | colors.variables.light.foreground.primary | primaryHue.700 | Alias di un ruolo del tema; risolvilo tramite la tonalità e la palette selezionate, invece di trattare l’alias come un colore CSS. | | colors.variables.light.foreground.danger | dangerHue.700 | Alias di un ruolo del tema; risolvilo tramite la tonalità e la palette selezionate, invece di trattare l’alias come un colore CSS. | | colors.variables.light.border.default | neutralHue.300 | Alias di un ruolo del tema; risolvilo tramite la tonalità e la palette selezionate, invece di trattare l’alias come un colore CSS. | | colors.variables.light.border.subtle | neutralHue.200 | Alias di un ruolo del tema; risolvilo tramite la tonalità e la palette selezionate, invece di trattare l’alias come un colore CSS. | | colors.variables.light.border.danger | dangerHue.300 | Alias di un ruolo del tema; risolvilo tramite la tonalità e la palette selezionate, invece di trattare l’alias come un colore CSS. | | colors.variables.light.border.primaryEmphasis | primaryHue.700 | Alias di un ruolo del tema; risolvilo tramite la tonalità e la palette selezionate, invece di trattare l’alias come un colore CSS. | ## Guida completa al sistema di design Zendesk Garden Una guida pratica per scegliere, applicare e valutare questo sistema in un’interfaccia reale. Indicazioni complete, un punto di partenza per l’implementazione e link alle fonti. ## Struttura dello spazio di assistenza del sistema di design Zendesk Garden ### Mantieni visibile la richiesta del cliente > Per evitare una risposta ben formulata ma fuori tema, chi redige un messaggio di assistenza deve avere abbastanza contesto. L’esempio mostra la richiesta del cliente sopra la bozza e, accanto, il richiedente, l’organizzazione e l’argomento. L’interfaccia è abbastanza densa da consentire di confrontare il nuovo testo con la domanda originale senza cambiare schermata. ### Tieni separati lo storico e la bozza attiva Le voci salvate localmente compaiono sopra l’editor con un’indicazione esplicita della visibilità. La bozza attiva resta nel componente Textarea nativo. Il salvataggio aggiunge un’istantanea e svuota il campo, così le modifiche successive non possono alterare silenziosamente una nota già salvata. ## Ruoli e palette del tema del sistema di design Zendesk Garden ### Esamina gli alias prima di copiare i colori In Garden 9, DEFAULT_THEME associa i ruoli semantici a famiglie di tonalità e valori numerati della palette. Un ruolo come background.primaryEmphasis non è un valore esadecimale letterale. La tabella di riferimento mantiene questi alias, così un tema personalizzato può cambiare la tonalità primaria senza lasciare frammenti blu codificati direttamente nei controlli nativi. ### Mantieni le aree personalizzate compatibili con il provider ThemeProvider fornisce lo stile dei componenti nativi. Questo esempio usa DEFAULT_THEME e uno spazio di lavoro personalizzato chiaro, coerente con il tema; non aggiunge un falso interruttore per la modalità scura che modifica solo lo sfondo circostante. Se aggiungi il supporto per gli schemi di colore, aggiorna i colori personalizzati dei messaggi e della barra laterale insieme a quelli del provider. ## Tipografia e densità del sistema di design Zendesk Garden ### Mantieni leggibile il testo di lavoro a 14px Il tema predefinito espone un ruolo medio da 14px con un’altezza di riga media di 20px, oltre a ruoli distinti da 12px per i contenuti di supporto e da 18px per i titoli. L’esempio usa un titolo del ticket da 26px e metadati di contesto più piccoli. Il messaggio originale del cliente e le note salvate restano in testo normale, non compresso in etichette. ### Lascia che le risposte lunghe vadano a capo naturalmente Il testo salvato mantiene le interruzioni di riga e manda a capo le parole lunghe. Anche su uno schermo mobile stretto, quindi, la nota resta interamente visibile senza richiedere lo scorrimento orizzontale. L’area di composizione si espande in verticale tramite il campo di testo, invece di trasformare tutto lo storico dei messaggi in un riquadro a scorrimento interno. ## Composizione di campi e pulsanti del sistema di design Zendesk Garden ### Collega etichetta, suggerimento ed errore Il componente Field nativo raggruppa Label, Hint, Textarea e Message condizionale. La proprietà di convalida modifica l’aspetto del campo di testo quando non viene rispettata la regola definita dall’applicazione sulla lunghezza minima. In questo modo si segue la composizione del componente, anziché applicare il colore di errore a un paragrafo non correlato all’esterno del campo. ### Dedica alla visibilità un controllo specifico Un componente Select nativo consente di scegliere Risposta pubblica o Nota interna. Etichetta e suggerimento si aggiornano in base alla modalità e l’istantanea salvata la mantiene. In entrambi i casi, l’azione resta «Salva bozza locale», chiarendo che selezionare Risposta pubblica non invia un messaggio. ## Stato delle bozze e storico locale del sistema di design Zendesk Garden ### Convalida prima di aggiungere un messaggio L’applicazione richiede almeno dodici caratteri dopo aver rimosso gli spazi iniziali e finali. Se l’invio non supera il controllo, la bozza resta intatta, viene mostrato un messaggio nel campo e il focus passa al campo di testo. La modifica del testo rimuove l’errore non più attuale; un invio successivo verifica di nuovo il testo corrente. Questa regola è un comportamento dell’applicazione, non un’impostazione predefinita di Garden non documentata. ### Distingui visivamente le note interne Le voci interne hanno uno sfondo caldo, creato appositamente, e l’etichetta «Bozza di nota interna». Le voci pubbliche usano la superficie normale. Entrambe riportano esplicitamente che non sono state inviate. La distinzione mostra il contesto di visibilità senza imitare una conversazione Zendesk attiva né suggerire che qualcun altro abbia ricevuto qualcosa. ## Aree di lavoro responsive del sistema di design Zendesk Garden ### Sposta il contesto sotto l’attività principale Al breakpoint dell’applicazione, il contesto del ticket si sposta sotto la conversazione e l’area di composizione. L’ordine del documento sottostante resta invariato. Su uno smartphone, il controllo della visibilità occupa tutta la larghezza disponibile e la riga delle azioni va a capo, così le etichette dei pulsanti non vengono compresse. ### Usa raggi moderati e divisori sottili I controlli nativi usano la scala dei raggi di 2px, 4px e 8px. I pannelli dei messaggi originali hanno angoli da 4px e bordi discreti. L’enfasi visiva maggiore va riservata all’azione attiva e allo stato di convalida, non alle ombre attorno a ogni messaggio. ## Convalida e ripristino da tastiera del sistema di design Zendesk Garden ### Verifica l’intero flusso delle bozze Una verifica utile parte da un tentativo non valido e controlla poi che digitazione, cambio di visibilità, salvataggio e cancellazione lascino l’interfaccia comprensibile. Il codice usa un ref React per ripristinare il focus dopo un errore o un’azione di cancellazione. Il conteggio dei risultati viene annunciato in un’area di stato. 1. Invia una bozza breve e segui l’errore del campo. 2. Seleziona Nota interna, inserisci una nota utile e salvala. 3. Cancella una bozza successiva e verifica che l’istantanea locale salvata resti disponibile. ### Mantieni stabile l’ordine di lettura La richiesta precede la bozza e le nuove istantanee locali salvate restano in ordine cronologico. I pulsanti nativi espongono le proprie azioni come testo. Nell’area di composizione non si nascondono scorciatoie da tastiera né comportamenti di invio automatico; la scelta della visibilità resta un menu Select con etichetta. ## Integrazione React del sistema di design Zendesk Garden ### Installa versioni compatibili dei pacchetti L’esempio fissa i pacchetti per temi, pulsanti e moduli alla versione 9.16.1 e usa React 18 con styled-components. Mescolare versioni meno recenti dei pacchetti Garden può creare aspettative incoerenti sul tema. La voce JSX completa include il provider, la composizione del campo e lo stato locale, mentre il file CSS contiene solo il layout personalizzato. - @zendeskgarden/react-theming 9.16.1 - @zendeskgarden/react-buttons 9.16.1 - @zendeskgarden/react-forms 9.16.1 ### Estendi solo il livello di servizio mancante Per trasformarlo in un vero strumento di assistenza, aggiungi dati dei ticket autorizzati, controlli delle autorizzazioni e un invio/una bozza verificati API, con gestione degli stati in sospeso e degli errori. Mantieni la semantica delle istantanee locali finché queste risposte non sono disponibili. Non cambiare l’etichetta del pulsante in «Invia» solo perché la convalida del modulo è riuscita. ## Esempi di componenti del sistema di design Zendesk Garden ### main.jsx — esempio completo funzionante Prepara una risposta mantenendo visibile il contesto del cliente. Il codice riportato sotto è la voce React completa, comprensiva di tutto lo stato e della convalida. ``` import React, { useState, useRef } from "react"; import { createRoot } from "react-dom/client"; import { ThemeProvider, DEFAULT_THEME } from "@zendeskgarden/react-theming"; import { Button } from "@zendeskgarden/react-buttons"; import { Field, Label, Textarea, Hint, Message, Select, } from "@zendeskgarden/react-forms"; import "./garden.css"; function App() { const [mode, setMode] = useState("public"), [text, setText] = useState(""), [error, setError] = useState(false), [items, setItems] = useState([]); const ref = useRef(); function submit(e) { e.preventDefault(); if (text.trim().length < 12) { setError(true); ref.current.focus(); return; } setItems([...items, { mode, text: text.trim() }]); setText(""); setError(false); } return (
SUPPORT WORKSPACE / FICTIONAL TICKET

Help with an invoice address

Ticket #1028 · Nadia Walker · Email channel

Nadia Walker Customer · example message

Could you update the company address on our next invoice? The billing contact has changed.

{items.map((i, n) => (
{i.mode === "public" ? "Public reply draft" : "Internal note draft"} Saved locally · not sent

{i.text}

))}

Compose a draft

{mode === "public" ? "Prepared for the customer; this demo will not send it." : "Internal context for the support team; saved only in this page."}