Esamina i token semantici effettivi di Web Awesome nei suoi elementi personalizzati nativi, comprese le modifiche circoscritte di raggio e spaziatura, lo stile dello shadow DOM, il comportamento di select e la convalida degli input.
Sistema di design Web Awesome Riferimento di progettazione del sistema
Tema predefinito CSS di Web Awesome 3.14.0, esaminato nel pacchetto installato. Le voci dei colori qui sotto sono alias semantici; i riferimenti alla palette sono mantenuti, senza sostituirli con codici esadecimali ipotizzati. Gli esempi in pixel derivati dalle scale presuppongono una radice di 16 px e scale=1.
Sistema di design Web Awesome Elementi personalizzati con un proprio confine di componente nel sistema di progettazione
Elementi personalizzati con un proprio confine di componente
Web Awesome fornisce elementi personalizzati HTML registrati, senza richiedere un’applicazione React. Una volta importato wa-input o wa-select, è possibile inserirlo in un normale HTML e controllarlo tramite le proprietà e gli eventi documentati. Questo ambiente di lavoro include la versione 3.14.0 e usa solo componenti disponibili nel pacchetto pubblico.
I controlli visibili sono gli elementi personalizzati effettivi, inclusa la loro implementazione nel shadow root. L’intestazione, le sezioni e il riquadro dei valori circostanti sono contenuti originali di HTML. L’esempio permette così di osservare quali scelte di stile attraversano il confine del componente tramite le proprietà personalizzate ereditate e quali appartengono alla composizione della pagina.
Sistema di design Web Awesome Mantieni intatti gli alias semantici dei colori del sistema di progettazione
Mantieni intatti gli alias semantici dei colori
Il tema predefinito distingue superfici rialzate, standard e ribassate, testo normale e tenue, nonché diverse coppie di riempimenti del brand e relativi colori del testo. Il riquadro dei token usa la superficie ribassata, l’esempio principale usa la superficie standard e il piccolo badge abbina brand-fill-quiet a brand-on-quiet. Questi ruoli mantengono il loro significato anche quando cambia l’aspetto.
Il riferimento mantiene alias come var(--wa-color-neutral-10) invece di tradurre ogni ruolo in un valore esadecimale ipotetico. La palette può cambiare senza alterare la validità dell’assegnazione semantica. Se personalizzi un’azione con un colore del brand intenso, considera sia il riempimento sia il relativo colore del testo. Modificarne uno senza l’altro può rendere difficile la lettura del testo del pulsante.
Sistema di design Web Awesome Modifica la scala senza riscrivere ogni componente del sistema di progettazione
Modifica la scala senza riscrivere ogni componente
Il selettore del raggio modifica --wa-border-radius-scale solo nell’esempio. Con scala uno, i raggi predefiniti piccolo, medio e grande diventano rispettivamente tre, sei e dodici pixel, con una radice da sedici pixel. Impostando la scala a zero, gli angoli scalabili diventano quadrati; con scala due, raddoppiano. I token per forme a pillola e cerchi sono concetti distinti: non si deve dare per scontato che seguano questo moltiplicatore.
Il selettore della spaziatura modifica --wa-space-scale. Imbottitura, spazi e spaziatura del riquadro nell’esempio usano i token ufficiali di spazio, quindi le loro proporzioni cambiano insieme. Ciò non significa che scalino tutte le dimensioni di ogni componente: il dimensionamento dei controlli dei componenti segue relazioni tra token proprie. Il pannello di modifica è fuori dall’ambito della scala, così il confronto resta stabile mentre cambia l’esempio.
Scegli Quadrati e osserva gli angoli dell’input, del contenitore e del riquadro dei valori.
Scegli Spaziatura ampia e confronta gli spazi dell’esempio con il pannello di modifica, che non cambia.
Ripristina i valori predefiniti per riportare insieme ai valori iniziali entrambi i moltiplicatori e l’aspetto.
Sistema di design Web Awesome Token tipografici e scelte originali per le intestazioni del sistema di progettazione
Token tipografici e scelte originali per le intestazioni
La famiglia predefinita del testo del corpo è ui-sans-serif, system-ui, sans-serif. La famiglia dei titoli è un alias di quella del testo del corpo, mentre per il codice si usa ui-monospace. Il token dell’interlinea normale è 1.6; quello dell’interlinea compatta è 1.2. Il token tipografico medio corrisponde a un rem moltiplicato per font-size-scale, mentre per le dimensioni maggiori si usano calcoli arrotondati. La tabella mostra queste espressioni senza nasconderne le dipendenze.
L’ambiente di lavoro usa un titolo da 34px e un titolo di sezione da 23px, riducendo le dimensioni del titolo di pagina a un punto di interruzione locale di 700px. Si tratta di regole originali esplicite della pagina. I campi nativi mantengono gli stili di etichette e suggerimenti della libreria, così l’utente può confrontare una gerarchia tipografica personalizzata con la tipografia predefinita dei componenti.
Valori iniziali, proprietà ed eventi di modifica del sistema di progettazione sistema di design Web Awesome
Valori iniziali, proprietà ed eventi di modifica
Ogni select contiene elementi wa-option con valori stabili. Le opzioni predefinite usano selected, in linea con le indicazioni attuali dei componenti per la selezione iniziale. Le modifiche durante l’esecuzione leggono la proprietà value della select. I controlli del tema ascoltano gli eventi change e aggiornano le proprietà personalizzate di CSS; non analizzano il testo delle etichette delle opzioni visualizzate.
Il selettore della regione è un normale campo dimostrativo e non controlla un servizio di archiviazione esterno. Il valore selezionato viene riportato nel messaggio di azione locale. L’interfaccia evita di fingere che la scelta di Europa assegni spazio di archiviazione. Questa distinzione è importante quando una dimostrazione realistica di un componente usa termini propri del prodotto.
Stilizzazione del sistema di progettazione sistema di design Web Awesome con token e parti documentate
Applica gli stili tramite token e parti documentate
I selettori dei discendenti ordinari non possono accedere liberamente all’albero shadow di un componente. Questo esempio usa variabili del tema ereditate, così lo sfondo, il testo e il raggio del campo restano coordinati con gli elementi circostanti di HTML. Si tratta di una modalità di stilizzazione supportata, non di un tentativo di selezionare markup generato internamente.
Per modifiche specifiche a un componente, consulta le proprietà personalizzate e le parti documentate di CSS per quel componente. Un selettore globale per input non modifica necessariamente l’input interno di wa-input. Al contrario, una classe o una variabile del tema applicata a un antenato comune può influire intenzionalmente su molti elementi personalizzati discendenti: scegli quindi con attenzione l’ambito.
Aggiornamento, convalida e risultati locali del sistema di progettazione sistema di design Web Awesome
Aggiornamento, convalida e risultati locali
Dal punto di vista della pagina, la registrazione dei componenti è asincrona. L’esempio attende customElements.whenDefined per le API utilizzate, poi attende gli aggiornamenti delle select prima di leggere i valori iniziali. In questo modo si evita di applicare i valori predefiniti a un elemento che non è ancora stato aggiornato da tag HTML sconosciuto alla relativa classe di componente.
L’azione dell’ambiente di lavoro usa setCustomValidity e reportValidity su wa-input. Un nome, dopo aver rimosso gli spazi iniziali e finali, con meno di due caratteri viene rifiutato; un evento input cancella l’errore personalizzato per consentire un nuovo tentativo dopo la correzione. Il pulsante Invite later disabilitato mostra lo stato nativo disabilitato del componente. Il testo di stato riporta soltanto un nome applicato localmente e il codice completo non contiene richieste di creazione di spazi di lavoro o di assegnazione di spazio di archiviazione.
Le etichette accessibili sono fornite tramite gli attributi label.
I suggerimenti spiegano il vincolo sul nome prima che si verifichi un errore.
L’azione disabilitata non è interattiva, ma ne mostra comunque lo scopo.
Importa il tema e i componenti usati nel sistema di progettazione sistema di design Web Awesome
Importa il tema e i componenti che usi
Installa @awesome.me/[email protected] in un’applicazione Vite vanilla e usa main.js fornito come punto di ingresso. È necessario il foglio di stile del tema predefinito; l’esempio non carica volutamente il reset nativo più ampio né il bundle di utility, perché il layout della pagina è definito esplicitamente CSS. Le importazioni registrano i cinque tipi di componenti usati nel markup.
I moduli npm dist sono pensati per i bundler. La distribuzione dist-cdn è l’alternativa per il caricamento diretto dei moduli nel browser, perché le dipendenze vengono incluse in modo diverso. Non copiare un’importazione dist in un tag script semplice dando per scontato che le dipendenze non associate a un percorso vengano risolte. I componenti che richiedono risorse esterne necessitano della configurazione del percorso base documentata; questo esempio evita risorse per icone fornite dall’utente ed è incluso in un bundle per l’uso offline.
Componenti pubblici e limiti dichiarati del tema nel sistema di progettazione sistema di design Web Awesome
Componenti pubblici e limiti del tema dichiarati con chiarezza
L’ambiente di lavoro mostra il tema predefinito e i componenti pubblici. Alcuni componenti, modelli e risorse di progettazione Web Awesome sono offerte Pro, quindi la pagina non suggerisce che l’installazione del pacchetto pubblico dia accesso a ogni elemento del catalogo. Prima di rendere un componente una dipendenza obbligatoria in un sistema di progettazione condiviso, è opportuno verificarne la disponibilità.
Un tema di prodotto riutilizzabile dovrebbe documentare quali variabili vengono modificate, dove sono applicate e come vengono verificate entrambe le modalità di visualizzazione. L’ambiente di lavoro interattivo è un piccolo esempio di questo processo: chi legge può esaminare esattamente le variabili modificate e confrontare i componenti nativi risultanti, invece di affidarsi a un’immagine della tavolozza non collegata all’interfaccia.
Registra i componenti, attende l’aggiornamento, modifica le proprietà personalizzate con ambito circoscritto e applica la convalida locale.
javascript
import '@awesome.me/webawesome/dist/styles/themes/default.css';
import '@awesome.me/webawesome/dist/components/button/button.js';
import '@awesome.me/webawesome/dist/components/input/input.js';
import '@awesome.me/webawesome/dist/components/select/select.js';
import '@awesome.me/webawesome/dist/components/option/option.js';
import '@awesome.me/webawesome/dist/components/switch/switch.js';
import './style.css';
const $=id=>document.getElementById(id);function update(){const s=$('specimen');s.style.setProperty('--wa-border-radius-scale',$('radius').value);s.style.setProperty('--wa-space-scale',$('spacing').value);s.classList.toggle('wa-dark',$('dark').checked);s.classList.toggle('wa-light',!$('dark').checked);$('values').textContent=`--wa-border-radius-scale: ${$('radius').value};\n--wa-space-scale: ${$('spacing').value};`;}
Promise.all(['wa-select','wa-switch','wa-input','wa-button'].map(x=>customElements.whenDefined(x))).then(async()=>{await Promise.all([...document.querySelectorAll('wa-select')].map(e=>e.updateComplete));for(const id of ['radius','spacing','dark'])$(id).addEventListener('change',update);$('reset').addEventListener('click',()=>{$('radius').value='1';$('spacing').value='1';$('dark').checked=false;update()});$('create').addEventListener('click',()=>{const field=$('workspace');field.setCustomValidity(field.value.trim().length<2?'Use at least two non-space characters.':'');if(!field.reportValidity())return;$('result').textContent=`Applied “${field.value.trim()}” in the ${$('region').value} specimen. No workspace or storage allocation was created.`});$('workspace').addEventListener('input',()=>$('workspace').setCustomValidity(''));update()});
Crea un progetto Vite vanilla e usa main.js e style.css completi mostrati sopra.
04
Configurazione dell’agent per il sistema di progettazione sistema di design Web Awesome
Punto di partenza per l’implementazione
Gli esempi completi di main.js, CSS e body riproducono l’ambiente di lavoro in un bundler. La demo offline è un bundle esbuild con il tema CSS incorporato. Non è richiesto alcun provider React.
javascript
// Create a Vite vanilla project, then install:
// npm install @awesome.me/[email protected]
// index.html: paste the complete workbench markup in body,
// then add <script type="module" src="/main.js"></script>.
// main.js: use the complete imports and token-controls example above.
// style.css: use the complete scoped specimen CSS above.
// Minimum registration pattern used by this example:
import '@awesome.me/webawesome/dist/styles/themes/default.css';
import '@awesome.me/webawesome/dist/components/button/button.js';
import '@awesome.me/webawesome/dist/components/input/input.js';
import '@awesome.me/webawesome/dist/components/select/select.js';
import '@awesome.me/webawesome/dist/components/option/option.js';
import '@awesome.me/webawesome/dist/components/switch/switch.js';
// Do not duplicate these imports if using the complete main.js above.
Un prompt per il tuo progetto
Prompt per l’agente
Usa l’ambiente di lavoro con token circoscritti di Web Awesome 3.14.0 e registra gli elementi wa-select, wa-option, wa-input, wa-button e wa-switch forniti. Attendi la definizione del componente e updateComplete prima di leggere le selezioni iniziali. Applica --wa-border-radius-scale e --wa-space-scale solo all’area dell’esempio e alterna la classe wa-light/wa-dark senza modificare i contenuti non correlati della pagina. Mantieni sincronizzata la visualizzazione dei token con i controlli nativi e conserva le etichette. Usa l’ambiente di lavoro come strumento di ispezione, non come interfaccia di gestione dei dispositivi.
05
Fonti e ambito del sistema di progettazione sistema di design Web Awesome
Componenti pubblici e tema predefinito di Web Awesome 3.14.0. Le scelte di layout sono originali; l’applicazione locale del nome non crea spazi di lavoro né assegna spazio di archiviazione.
