Examinez les véritables jetons sémantiques de Web Awesome dans des éléments personnalisés natifs, notamment les changements de rayon et d’espacement propres à chaque portée, le style du shadow DOM, le comportement des menus déroulants et la validation des champs de saisie.
Guide OpenDesign9 chapitres37 entrées de référenceGuide de l’application d’origine
01
Aperçu de l’interface du système de design Web Awesome
Modifiez les échelles de rayon et d’espacement, changez l’apparence de l’exemple, sélectionnez une région et validez le nom d’un espace de travail local.
Éléments personnalisés natifs Web Awesome 3.14.0 et thème par défaut, regroupés localement. · Référence de mise en œuvre
02
Référence de conception du système de design Web Awesome
Thème par défaut Web Awesome 3.14.0 CSS, examiné dans le package installé. Les entrées de couleur ci-dessous sont des alias sémantiques ; les références à la palette sont conservées au lieu d’être remplacées par des équivalents hexadécimaux supposés. Les exemples en pixels dérivés des échelles partent d’une racine de 16px et d’une échelle de 1.
Éléments personnalisés du système de design Web Awesome avec leur propre frontière de composant
Éléments personnalisés avec leur propre frontière de composant
Web Awesome fournit des éléments personnalisés HTML enregistrés, sans imposer l’utilisation d’une application React. Après l’importation de wa-input ou de wa-select, l’élément peut être placé dans du HTML ordinaire et contrôlé à l’aide de ses propriétés et événements documentés. Cet atelier regroupe la version 3.14.0 et utilise uniquement les composants disponibles dans le package public.
Les contrôles visibles sont les véritables éléments personnalisés, y compris leur implémentation dans le shadow DOM. L’en-tête, les sections et la zone de lecture qui les entourent sont propres à HTML. L’exemple permet ainsi d’observer quelles décisions de style franchissent la frontière du composant par l’intermédiaire des propriétés personnalisées héritées, et lesquelles relèvent de la composition de la page.
Conserver les alias sémantiques de couleur du système de design Web Awesome
Préserver les alias de couleurs sémantiques
Le thème par défaut distingue les surfaces surélevées, normales et abaissées, le texte normal et discret, ainsi que plusieurs paires d’aplats de marque et de couleurs de premier plan associées. La zone de lecture des jetons utilise la surface abaissée, l’exemple principal la surface normale et le petit badge associe brand-fill-quiet à brand-on-quiet. Ces rôles restent pertinents lorsque l’apparence change.
La référence conserve des alias tels que var(--wa-color-neutral-10) au lieu de convertir chaque rôle en valeur hexadécimale supposée. La palette peut changer tout en préservant la validité de l’affectation sémantique. Pour personnaliser une action de marque forte, tenez compte à la fois de l’aplat et de sa couleur de premier plan. Modifier l’un sans l’autre peut rendre le texte du bouton difficile à lire.
Modifier l’échelle du système de design Web Awesome sans réécrire chaque composant
Modifier l’échelle sans réécrire chaque composant
Le sélecteur de rayon modifie --wa-border-radius-scale uniquement sur l’exemple. Avec une échelle de un, les rayons petits, moyens et grands par défaut correspondent à trois, six et douze pixels avec une racine de seize pixels. Une échelle de zéro rend carrés ces angles adaptables ; une échelle de deux les double. Les jetons pilule et cercle sont des notions distinctes et ne doivent pas être considérés comme dépendant de ce multiplicateur.
Le sélecteur d’espacement modifie --wa-space-scale. Le rembourrage, les espacements et l’espace autour de la zone de lecture de l’exemple utilisent les jetons d’espacement officiels ; leurs proportions évoluent donc ensemble. Cela ne signifie pas que toutes les dimensions de chaque composant changent d’échelle : les dimensions des contrôles de composant suivent leurs propres relations entre jetons. Le panneau de réglage étant hors du périmètre, la comparaison reste stable pendant que l’exemple change.
Choisissez « Carré » et observez les angles du champ de saisie, du conteneur et de la zone de lecture.
Choisissez un espacement « Aéré » et comparez les espacements de l’exemple à ceux du panneau de réglage, qui restent inchangés.
Rétablissez les valeurs par défaut pour réinitialiser ensemble les deux multiplicateurs et l’apparence.
Jetons typographiques et choix originaux de titres du système de design Web Awesome
Jetons typographiques et choix de titres originaux
La famille par défaut du corps du texte est ui-sans-serif, system-ui, sans-serif. La famille des titres reprend celle du corps du texte, tandis que le code utilise ui-monospace. Le jeton de hauteur de ligne normale vaut 1.6 ; celui de la hauteur condensée, 1.2. Le jeton typographique moyen correspond à un rem multiplié par font-size-scale, et les tailles supérieures utilisent des calculs arrondis. Le tableau présente ces expressions au lieu d’en masquer les dépendances.
L’atelier utilise des titres de 34px et des titres de section de 23px ; le titre de la page est réduit lorsque le point de rupture local atteint 700px. Ces règles sont propres à la page. Les champs natifs conservent le style des libellés et des indications de la bibliothèque, ce qui permet de comparer une hiérarchie de page personnalisée à la typographie par défaut des composants.
Valeurs initiales, propriétés et événements de modification du système de design Web Awesome
Valeurs initiales, propriétés et événements de modification
Chaque sélecteur contient des éléments wa-option aux valeurs stables. Les options par défaut utilisent selected, conformément aux recommandations actuelles des composants pour la sélection initiale. Les changements à l’exécution lisent la propriété value du sélecteur. Les contrôles du thème écoutent les événements change et mettent à jour les propriétés personnalisées de CSS ; ils n’extraient pas le texte des libellés d’option affichés.
Le sélecteur de région est un champ de démonstration ordinaire ; il ne contrôle aucun service de stockage externe. La valeur sélectionnée est indiquée dans le message d’action local. L’interface ne laisse pas entendre que le choix de l’Europe alloue de l’espace de stockage. Cette distinction est importante lorsqu’une démonstration de composant réaliste reprend le vocabulaire d’un produit.
Styliser avec des jetons et des parties documentées dans le système de design Web Awesome
Appliquer des styles au moyen des jetons et des parties documentées
Les sélecteurs descendants ordinaires ne permettent pas d’accéder librement à l’arbre d’ombre d’un composant. Cet exemple utilise des variables de thème héritées afin de coordonner l’arrière-plan, le texte et le rayon du champ avec le reste de HTML. Il s’agit d’une surface de stylisation prise en charge, et non d’une tentative de cibler le balisage interne généré.
Pour les modifications propres à un composant, consultez les propriétés personnalisées CSS et les parties CSS documentées pour ce composant. Un sélecteur global ciblant les champs de saisie ne modifiera pas nécessairement le champ interne de wa-input. À l’inverse, placer une classe de thème ou une variable sur un ancêtre commun peut intentionnellement affecter de nombreux éléments personnalisés descendants ; il faut donc choisir soigneusement la portée.
Mise à niveau du système de design Web Awesome, validation et résultats locaux
Mise à niveau, validation et résultats locaux
Du point de vue de la page, l’enregistrement des composants est asynchrone. L’exemple attend que customElements.whenDefined soit résolu pour les API utilisées, puis attend la mise à jour des sélecteurs avant de lire leurs valeurs initiales. Cela évite d’appliquer des valeurs par défaut à un élément qui n’a pas encore été mis à niveau d’une balise HTML inconnue vers sa classe de composant.
L’action sur l’espace de travail utilise setCustomValidity et reportValidity sur wa-input. Un nom dont la longueur, après suppression des espaces superflus, est inférieure à deux caractères est refusé ; un événement input efface l’erreur personnalisée pour permettre une nouvelle tentative après correction. Le bouton Invite later désactivé utilise l’état natif désactivé du composant. Le texte d’état indique uniquement qu’un nom a été appliqué localement, et le code complet n’envoie aucune requête de création ou d’allocation d’espace de travail.
Les attributs label fournissent des libellés accessibles.
Les indications expliquent la contrainte sur le nom avant qu’une erreur ne survienne.
L’action désactivée reste inactive tout en indiquant son utilité.
Importer le thème et les composants utilisés dans le système de design Web Awesome
Importer le thème et les composants utilisés
Installez @awesome.me/[email protected] dans une application Vite vanilla et utilisez le main.js fourni comme point d’entrée. La feuille de style du thème par défaut est obligatoire ; l’exemple ne charge volontairement pas le reset natif plus étendu ni le lot d’utilitaires, car la mise en page de la page est explicite CSS. Les imports enregistrent les cinq types de composants utilisés dans le balisage.
Les modules npm dist sont destinés aux outils de bundling. La distribution dist-cdn est l’alternative pour le chargement direct de modules dans le navigateur, car les dépendances y sont regroupées différemment. Ne copiez pas un import dist dans une balise script classique en supposant que les dépendances bare seront résolues. Les composants qui nécessitent des ressources externes requièrent la configuration documentée du chemin de base ; cet exemple n’utilise pas d’icônes fournies par l’utilisateur et est regroupé pour fonctionner hors ligne.
Composants publics et limites explicites des thèmes dans le système de design Web Awesome
Composants publics et limites du thème clairement définies
L’atelier présente le thème par défaut et les composants publics. Certains composants, motifs et ressources de design Web Awesome sont proposés dans l’offre Pro ; la page ne laisse donc pas entendre que l’installation du package public donne accès à tous les éléments du catalogue. Avant d’ajouter un composant comme dépendance obligatoire dans un système de design partagé, vérifiez qu’il est disponible.
Un thème de produit réutilisable doit préciser les variables modifiées, leur portée et la manière dont les deux modes d’apparence sont vérifiés. L’atelier interactif illustre ce processus à petite échelle : le lecteur peut examiner les variables exactes qui ont été modifiées et comparer les composants natifs obtenus, plutôt que de se fier à une image de palette sans lien avec le résultat.
Les choix initiaux sont définis avec l’attribut selected sur wa-option.
Seuls des composants gratuits sont utilisés.
Imports complets et commandes de réglage des jetons
Enregistre les composants, attend leur mise à niveau, modifie les propriétés personnalisées à portée limitée et applique une validation 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()});
Créez un projet Vite vanilla et utilisez les fichiers main.js et style.css complets présentés ci-dessus.
04
Configuration de l’agent du système de design Web Awesome
Point de départ de l’implémentation
Les exemples complets de main.js, CSS et body reproduisent l’atelier avec un outil de bundling. La démo hors ligne est un bundle esbuild dans lequel le thème CSS est intégré. Aucun fournisseur React n’est requis.
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 pour votre projet
Prompt pour l’agent IA
Utilisez l’atelier de jetons à portée limitée Web Awesome 3.14.0 et enregistrez les éléments wa-select, wa-option, wa-input, wa-button et wa-switch fournis. Attendez la définition des composants et la résolution de updateComplete avant de lire les sélections initiales. Appliquez --wa-border-radius-scale et --wa-space-scale uniquement à la zone de l’exemple, et basculez sa classe wa-light/wa-dark sans modifier le reste de la page. Synchronisez l’affichage des valeurs des jetons avec les commandes natives et conservez les libellés. Utilisez l’atelier pour l’inspection, et non comme interface de gestion des appareils.
05
Sources et portée du système de design Web Awesome
Composants publics et thème par défaut Web Awesome 3.14.0. Les choix de mise en page sont originaux ; l’application locale d’un nom ne crée aucun espace de travail ni stockage.
