# Système de design Oruga UI

## Aperçu de l’interface du système de design Oruga UI

Recherchez dans un vocabulaire contrôlé, ajoutez jusqu’à trois sujets, supprimez une étiquette et enregistrez une description locale de la note.

## Référence de conception du système de design Oruga UI

Package Oruga pour Vue 3 0.14.4 avec @oruga-ui/theme-oruga 0.10.0. Les valeurs ci-dessous appartiennent à ce thème facultatif par défaut, et non à un cœur headless immuable. Les icônes MDI 7.4.47 sont fournies localement. La composition du catalogue environnant et les illustrations de dossiers sont originales.

### Couleurs sémantiques du thème facultatif Oruga

| Nom / règle | Valeur / configuration | Utilisation |
| --- | --- | --- |
| --oruga-primary | #445e00 | Étiquettes sélectionnées et action principale. |
| --oruga-primary-invert | #fff | Texte des étiquettes principales. |
| --oruga-success | #006724 | Variante de réussite. |
| --oruga-info | #005c98 | Variante d’information. |
| --oruga-warning | #f4c300 | Variante d’avertissement. |
| --oruga-danger | #b60000 | Variante de champ en erreur. |
| --oruga-control-border-color | #dbdbdb | Bordure de champ par défaut. |
### Typographie, espacement et géométrie du thème facultatif

| Nom / règle | Valeur / configuration | Utilisation |
| --- | --- | --- |
| --oruga-font-size | 1rem | Taille de texte par défaut. |
| --oruga-line-height | 1.5 | Rapport de hauteur de ligne par défaut. |
| --oruga-border-radius | 4px | Arrondi standard des contrôles. |
| --oruga-control-spacer | .5em | Espacement partagé des contrôles. |
| --oruga-control-height | 2.25em | Hauteur du contrôle par rapport à sa taille de police. |
| --oruga-control-padding-vertical | calc(.375em - 1px) | Marge intérieure verticale tenant compte de la bordure. |
| --oruga-control-padding-horizontal | calc(.8em - 1px) | Marge intérieure horizontale tenant compte de la bordure. |
| --oruga-control-disabled-opacity | .5 | État visuel désactivé. |
| --oruga-animation-speed-fast | .15s | Durée de transition rapide. |
| --oruga-animation-speed | .3s | Durée de transition standard. |
### Échelles explicites de l’application d’origine

| Nom / règle | Valeur / configuration | Utilisation |
| --- | --- | --- |
| Font stack | system-ui, sans-serif | Texte extérieur à l’application ; le thème facultatif utilise également une pile de polices système. |
| Page title | 34px / 1.15; 29px narrow | Hiérarchie originale. |
| Catalog card title | Georgia, serif; 29px / 1.25 | Contraste éditorial d’origine, qui n’est pas une valeur par défaut d’Oruga. |
| Supporting type | 10 / 11 / 12 / 13 / 14 / 15px | Légendes, définitions et texte descriptif d’origine explicites. |
| Spacing | 4 / 5 / 7 / 12 / 13 / 14 / 16 / 20 / 22 / 24 / 28 / 32px | Valeurs réelles de mise en page ; la bibliothèque headless ne fournit aucune échelle de grille. |
| Layout | Flexible editor + 330px catalog card; stack at 760px | Grille d’origine. |
| Topic constraints | 1–3 unique existing labels | allow-new=false, allow-duplicates=false, maxitems=3. |
| Title constraint | 5–80 characters; minimum evaluated after trim | Validation de l’application et limite de longueur native. |
## Guide complet du système de design Oruga UI

Un guide pratique pour choisir, appliquer et évaluer ce système dans une interface réelle.

Des conseils complets, un point de départ pour la mise en œuvre et des liens vers les sources.

## Système de design Oruga UI : séparer le comportement des composants d’Oruga de son thème facultatif

### Distinguer le comportement des composants d’Oruga de son thème facultatif

> Oruga fournit des composants Vue sans imposer de framework CSS particulier. Cet exemple associe le package Vue 3 au thème par défaut d’Oruga, qui est séparé. Les étiquettes vertes sélectionnées et les champs à contour proviennent de ce thème, tandis que la recherche, la sélection et la suppression relèvent du comportement natif des composants.

Cette distinction est utile pour évaluer la bibliothèque. Une équipe peut conserver les composants API et remplacer la configuration des classes, ou choisir un autre thème pris en charge. Le tableau de référence indique donc le nom et la version du package de thème, plutôt que de présenter son vert primaire comme une exigence universelle pour toutes les applications Oruga.

Consultez la spécification associée

## Système de design Oruga UI : utiliser les véritables variables du thème par défaut

### Utiliser les véritables variables du thème par défaut

Le thème facultatif installé définit --oruga-primary sur #445e00 et --oruga-primary-invert sur white. La couleur de danger est #b60000 et les bordures des champs utilisent #dbdbdb. La propriété de variante du composant sélectionne la famille sémantique appropriée, sans qu’il soit nécessaire de définir une règle CSS distincte pour chaque champ ou étiquette.

Le même thème définit un rayon standard de quatre pixels, une hauteur de champ de 2.25em et des formules de remplissage qui soustraient la bordure d’un pixel. Comme ces valeurs sont relatives au texte des champs, une modification de l’échelle typographique influe sur leur géométrie. L’espaceur d’un demi-em du thème décrit une relation entre composants ; il ne constitue pas une échelle complète d’espacement pour la mise en page.

Consultez la spécification associée

## Système de design Oruga UI : définir la mise en page qu’Oruga ne cherche délibérément pas à imposer

### Définir la mise en page qu’Oruga ne fournit volontairement pas

Le catalogue utilise une colonne d’édition flexible et une colonne de fiches de 330px, qui s’empilent sous 760px. Le titre de la page utilise la police sans empattement du système, tandis que celui de la fiche est en Georgia pour évoquer un document éditorial. Ces deux choix sont originaux et ne nécessitent aucun fichier de police externe.

Oruga ne prescrit ni grille ni framework utilitaire. La feuille de style complète rend donc visibles les marges intérieures des panneaux, les marges sur les écrans étroits et les règles de retour à la ligne. Le compteur d’étiquettes maintient son numérateur et son dénominateur ensemble, et le titre de la fiche peut passer sur plusieurs lignes si le nom d’une longue note l’exige, plutôt que de décaler la page intégrée horizontalement.

Consultez la spécification associée

## Système de design Oruga UI : séparer les valeurs sélectionnées de la requête de recherche

### Séparer les valeurs sélectionnées de la requête de recherche

OTaginput associe son tableau de sujets sélectionnés via v-model. Le texte de saisie interne à la saisie semi-automatique filtre les libellés proposés sans remplacer ce tableau. Le vocabulaire comprend six sujets originaux accompagnés de définitions concrètes, et la fiche en direct n’affiche les définitions que des sujets sélectionnés.

Par défaut, la comparaison lors de la recherche ne tient pas compte de la casse. Le test local a saisi Color et attendu la fin du filtrage avant de sélectionner l’option correspondante. Une assertion immédiate pendant le délai anti-rebond de la saisie donnerait à tort l’impression que le filtrage a échoué. La sélection efface ensuite la requête tout en conservant les étiquettes déjà choisies.

1. Recherchez Color et sélectionnez l’option correspondante.

2. Ajoutez Forms pour obtenir trois sujets avec Navigation.

3. Supprimez une étiquette, vérifiez que la fiche est mise à jour, puis choisissez-en une autre avant d’enregistrer.

Consultez la spécification associée

## Système de design Oruga UI : gérer séparément le vocabulaire, les doublons et le nombre d’éléments

### Gérer séparément le vocabulaire, les doublons et le nombre d’éléments

allow-new=false empêche de transformer une expression saisie arbitrairement en libellé. allow-duplicates=false empêche d’ajouter deux fois le même libellé existant. maxitems=3 limite le nombre total de sélections et affiche le compteur. Chaque paramètre protège un aspect différent d’un vocabulaire contrôlé.

L’application vérifie tout de même qu’au moins un sujet est sélectionné lorsque l’utilisateur tente d’enregistrer. La limite maximale de sélections n’implique pas de nombre minimal requis. Elle vérifie aussi que le titre contient au moins cinq caractères significatifs après suppression des espaces superflus, tandis que l’attribut maxlength du champ natif fixe la limite supérieure à quatre-vingts caractères.

Consultez la spécification associée

## Système de design Oruga UI : utiliser OField pour les libellés et les messages de validation spécifiques

### Utiliser OField pour les libellés et les messages de validation spécifiques

OField fournit les libellés visibles « Titre de la note » et « Sujets », ainsi que leurs messages. Après une tentative d’enregistrement invalide, le champ concerné reçoit une variante de danger et un message indiquant comment corriger le problème. Les indications sur les sujets expliquent la plage autorisée et la restriction du vocabulaire avant qu’une erreur ne se produise.

La liste déroulante native de saisie des étiquettes suit le modèle combobox/listbox. Dans cette version, le rôle combobox est attribué à un conteneur, et le champ de texte modifiable est imbriqué à l’intérieur. Les tests d’assurance qualité remplissent donc le champ de recherche « Sujets » réel, au lieu de supposer que l’élément ayant le rôle combobox est lui-même un champ de saisie.

Consultez la spécification associée

## Système de design Oruga UI : même un jeu d’icônes par défaut nécessite son fichier de police

### Même un pack d’icônes par défaut nécessite le fichier de police correspondant

Le contrôle de suppression des étiquettes utilise le jeu d’icônes MDI par défaut d’Oruga. Le chargement du thème des composants ne charge pas automatiquement cette police ; la configuration complète inclut donc @mdi/font. L’aperçu autonome utilise un fichier WOFF2 local et les règles d’icônes nécessaires, sans dépendance à une police distante.

La suppression reste un véritable bouton doté du libellé accessible « Supprimer le sujet ». L’illustration décorative du dossier n’a aucun lien avec ces icônes de contrôle et est masquée aux technologies d’assistance. Cette distinction évite de confondre un élément décoratif avec un contrôle actionnable.

Consultez la spécification associée

## Système de design Oruga UI : invalider un instantané enregistré lorsque ses entrées changent

### Invalider un instantané enregistré lorsque ses entrées changent

L’action d’enregistrement consigne une phrase indiquant le titre après suppression des espaces superflus et le nombre de sujets sélectionnés. Un observateur surveille le titre et le tableau des sujets en profondeur ; la suppression d’un élément efface donc la confirmation, tout comme la modification du titre. L’enregistrement est désactivé uniquement tant que l’instantané actuel reste enregistré.

Effacer la note réinitialise le titre, tous les sujets sélectionnés, la validation déclenchée et l’état d’enregistrement. La fiche affiche alors « Note de recherche sans titre » et « Aucun sujet sélectionné ». L’utilisateur peut suivre l’ensemble du cycle, de l’état vide à la modification puis à l’enregistrement, sans qu’une opération de backend, de téléversement ou de publication soit dissimulée derrière le bouton.

- Conservez le modèle fondé sur le tableau des éléments sélectionnés lorsque la requête change.

- Effacez le retour de confirmation après les mutations du tableau imbriqué.

- Présentez le résultat comme un état local, et non comme une publication.

Consultez la spécification associée

## Système de design Oruga UI : importer explicitement les composants avec l’enregistrement Oruga actuel

### Importer explicitement les composants avec l’enregistrement actuel d’Oruga

La configuration vérifiée d’Oruga 0.14.4 crée une instance Oruga et l’installe sur l’application Vue. App.vue importe explicitement OField, OInput, OTaginput, OTag et OButton. Cette approche suit le modèle d’enregistrement actuel ; s’appuyer sur d’anciens exemples qui supposaient que tous les composants étaient enregistrés globalement peut laisser une application incomplète.

Le README du thème indique que le thème par défaut utilise les noms de classes existants d’Oruga et nécessite sa feuille de style, sans objet de configuration de thème supplémentaire. Le point d’entrée importe cette feuille de style, l’asset MDI et la mise en page d’origine, dans cet ordre. Les exemples de code complets ci-dessus et la racine Vite ci-dessous contiennent tous les éléments nécessaires.

Consultez la spécification associée

## Exemples de composants du système de design Oruga UI

### SFC complet du catalogue de thèmes

OTaginput, OField, OInput, OTag et OButton relient un vocabulaire limité à une fiche de catalogue dynamique.

```
<script setup>
import {ref,computed,watch} from 'vue';
import {OField,OInput,OTaginput,OButton,OTag} from '@oruga-ui/oruga-next';
const title=ref('Finding a calmer navigation'),topics=ref(['Navigation']),attempted=ref(false),saved=ref('');
const definitions={'Navigation':'Menus, wayfinding and the path through a product.','Typography':'Type hierarchy, reading rhythm and legibility.','Color':'Semantic roles, contrast and theme behavior.','Forms':'Input labels, validation and correction.','Motion':'Transitions, reduced motion and continuity.','Accessibility':'Keyboard flow, semantics and assistive technology.'};
const options=Object.keys(definitions),valid=computed(()=>title.value.trim().length>=5&&topics.value.length>=1&&topics.value.length<=3);
watch([title,topics],()=>saved.value='',{deep:true});
function save(){attempted.value=true;if(valid.value)saved.value=`Saved locally: “${title.value.trim()}” with ${topics.value.length} ${topics.value.length===1?'topic':'topics'}.`}
function reset(){title.value='';topics.value=[];attempted.value=false;saved.value=''}
</script>
<template><main class="catalog-shell"><header><p class="eyebrow">RESEARCH CATALOG · LABEL A NOTE</p><h1>Give the next reader a useful starting point.</h1><p>Name a research note and choose up to three topics from a controlled vocabulary.</p></header><div class="catalog-layout"><section class="editor"><h2>Note details</h2><OField label="Note title" :variant="attempted&&title.trim().length<5?'danger':undefined" :message="attempted&&title.trim().length<5?'Use at least five meaningful characters.':undefined"><OInput v-model="title" maxlength="80" expanded placeholder="What did you learn?"/></OField><OField label="Topics" :variant="attempted&&!topics.length?'danger':undefined" :message="attempted&&!topics.length?'Choose at least one topic.':'Choose 1–3 existing topics; duplicate and new labels are not added.'"><OTaginput v-model="topics" :options="options" :allow-new="false" :allow-duplicates="false" :maxitems="3" open-on-focus :keep-open="false" expanded variant="primary" placeholder="Search topics" aria-close-label="Remove topic"><template #empty>No matching topic. Try Color, Forms or Motion.</template></OTaginput></OField><div class="actions"><OButton variant="primary" @click="save" :disabled="!!saved">Save local note</OButton><OButton @click="reset">Clear note</OButton></div><p role="status" class="result">{{saved||'The preview keeps only local page state.'}}</p><h3>Vocabulary guide</h3><dl class="vocabulary"><div v-for="(meaning,name) in definitions" :key="name"><dt>{{name}}</dt><dd>{{meaning}}</dd></div></dl></section><aside class="note-card"><div class="folder-art" aria-hidden="true"><i></i><b></b><span></span></div><p class="eyebrow">CATALOG CARD PREVIEW</p><h2>{{title.trim()||'Untitled research note'}}</h2><div class="topic-tags"><OTag v-for="topic in topics" :key="topic" variant="primary">{{topic}}</OTag><span v-if="!topics.length" class="empty-topics">No topics selected</span></div><p class="card-label">This note will appear under</p><ul><li v-for="topic in topics" :key="topic"><strong>{{topic}}</strong><span>{{definitions[topic]}}</span></li></ul><p class="card-foot">Original sample note · no upload or publishing</p></aside></div></main></template>
```

Référence du code

- Le modèle de tableau sélectionné est différent du texte de recherche interne.

- La sélection se limite aux libellés existants, sans doublons.

- Un observateur profond efface la confirmation enregistrée après la suppression d’un thème.

### Mise en page complète du catalogue d’origine

Grille adaptative d’éditeur et de cartes, retour à la ligne maîtrisé et illustration originale de dossier CSS.

```
html,body,#app{height:auto;min-height:0;margin:0}*{box-sizing:border-box}body{font-family:system-ui,sans-serif;background:#f4f4ed;color:#34392b}.catalog-shell{max-width:1100px;margin:auto;padding:32px}.eyebrow{font-size:10px;letter-spacing:.14em;font-weight:700;color:#6e775f}h1{font-size:34px;line-height:1.15;max-width:700px;margin:12px 0}header>p:last-child{font-size:15px;line-height:1.6;color:#727965;max-width:630px}.catalog-layout{display:grid;grid-template-columns:minmax(0,1fr) 330px;gap:24px;margin-top:28px}.editor,.note-card{background:white;border:1px solid #dfe3d4;border-radius:14px;padding:24px;min-width:0}.editor>h2{font-size:20px;margin:0 0 24px}.editor .o-field{margin-bottom:22px}.editor .o-field__message{font-size:12px;line-height:1.6}.actions{display:flex;gap:12px;flex-wrap:wrap}.result{font-size:12px;line-height:1.6;color:#596d2e;margin:16px 0 28px}.editor h3{font-size:14px}.vocabulary{margin:0}.vocabulary>div{padding:12px 0;border-bottom:1px solid #eaede3}.vocabulary dt{font-size:13px;font-weight:650}.vocabulary dd{font-size:12px;line-height:1.6;margin:4px 0 0;color:#707763}.note-card{align-self:start;background:#fcfcf5}.note-card h2{font-family:Georgia,serif;font-size:29px;line-height:1.25;font-weight:400;overflow-wrap:anywhere}.folder-art{height:145px;background:#e3e8cf;border-radius:8px;position:relative;overflow:hidden;margin-bottom:24px}.folder-art i{position:absolute;left:15%;top:40px;width:70%;height:100px;border-radius:7px;background:#7e8e52;transform:rotate(-8deg)}.folder-art b{position:absolute;left:21%;top:24px;width:60%;height:115px;background:#fffef5;transform:rotate(5deg);border-radius:4px}.folder-art span{position:absolute;left:16%;top:71px;width:70%;height:80px;background:#a6b57a;border-radius:7px}.topic-tags{display:flex;gap:7px;flex-wrap:wrap}.card-label{font-size:11px;color:#737b65;margin-top:24px}.note-card ul{list-style:none;padding:0}.note-card li{border-top:1px solid #e0e4d6;padding:13px 0}.note-card li strong{font-size:13px;display:block}.note-card li span{font-size:12px;color:#6c765b;line-height:1.6;display:block;margin-top:5px}.card-foot{font-size:10px;line-height:1.6;color:#7c846e;margin-top:20px}.empty-topics{font-size:12px;color:#7c846e}.o-taginput{max-width:100%}.o-taginput__container{min-width:0}.o-taginput .o-input{min-width:0}@media(max-width:760px){.catalog-layout{grid-template-columns:minmax(0,1fr)}.catalog-shell{padding:20px}h1{font-size:29px}}@media(max-width:360px){.catalog-shell{padding:14px}.editor,.note-card{padding:16px}.actions>*{width:100%}}
.o-taginput__counter{white-space:nowrap;flex-shrink:0}
```

Référence du code

- Oruga ne fournit pas de système de grille obligatoire ; cette mise en page est définie explicitement dans l’application CSS.

- Le texte du compteur reste sur une seule ligne aux petites largeurs.

## Configuration de l’agent IA du système de design Oruga UI

### Point de départ de l’implémentation

Oruga 0.14.4, le thème par défaut facultatif 0.10.0 et MDI 7.4.47 ont été vérifiés. Les composants sont importés explicitement ; le thème par défaut ne nécessite aucune configuration supplémentaire de thème JavaScript.

```
// npm create vite@latest oruga-catalog -- --template vue
// cd oruga-catalog && npm install
// npm install @oruga-ui/oruga-next@0.14.4 @oruga-ui/theme-oruga@0.10.0 @mdi/font@7.4.47
// Save the complete examples as src/App.vue and src/style.css.
// src/main.js:
import {createApp} from 'vue';
import {createOruga} from '@oruga-ui/oruga-next';
import '@oruga-ui/theme-oruga/style.css';
import '@mdi/font/css/materialdesignicons.css';
import './style.css';
import App from './App.vue';
createApp(App).use(createOruga()).mount('#app');
// index.html: <div id="app"></div><script type="module" src="/src/main.js"></script>
// npm run dev
```

### Un prompt pour votre projet

```
Commencez par le catalogue de notes de recherche Oruga 0.14.4 et son thème 0.10.0. Conservez la sélection contrôlée d’OTaginput parmi les six thèmes du vocabulaire, la recherche insensible à la casse, la désactivation des nouveaux tags et des doublons, ainsi que la limite de trois tags. Reliez les définitions de thèmes dynamiques et la validation du titre à l’instantané enregistré, en effaçant le retour de confirmation enregistré après toute modification. Incluez createOruga, le thème CSS et la configuration de l’asset MDI local. Réinitialisez le formulaire à l’état vide ; n’inventez pas de données de comparaison de produits ni de mise à jour de catalogue à distance.
```

## Sources et périmètre du système de design Oruga UI

Oruga 0.14.4 avec le thème par défaut facultatif 0.10.0. Vocabulaire et illustration du catalogue d’origine. Les modifications sont enregistrées uniquement dans l’état local de la page, sans envoi, publication ni persistance après rechargement.

- Introduction Enregistrement actuel du plugin et des composants explicites.

- Choix du thème Limite de style facultatif.

- Configuration Personnalisation des classes globales et locales.

- Saisie de tags Contraintes du vocabulaire, modèle, limites et suppression.

- Saisie semi-automatique Filtrage, comportement imbriqué de la combobox et popover natif.

- Field Libellés visibles et messages de validation.

- Icône Configuration du jeu d’icônes.

- Source du thème par défaut Configuration officielle du thème et source des jetons.

## Ressources connexes au système de design Oruga UI

### Pico CSS

Pico CSS applique des styles sémantiques à HTML avec une échelle typographique adaptative fondée sur les rem et des variables de thème. Ses versions standard, sans classes et conditionnelle ont des périmètres d’intégration différents ; ce guide utilise la version standard pour un formulaire de préférences de lecture avec des éléments natifs dépliables et des boîtes de dialogue.

### Preline UI

Un planificateur de sessions Preline natif avec des onglets liés, un plugin de saisie numérique à limites définies, les alias de thème installés, les véritables échelles Tailwind et une estimation locale du matériel qui se met à jour selon la session choisie.

### Prime UI

Une implémentation PrimeVue dont la version est figée dans l’écosystème Prime UI : un arbre de documents au thème Aura avec les références réelles aux préréglages, l’expansion contrôlée, le filtrage, la sélection et l’épinglage local.


- [Référence de mise en œuvre](https://oruga-ui.com/components/taginput)
- [Source](https://oruga-ui.com/documentation/themes)
- [Source](https://oruga-ui.com/components/taginput)
- [Consultez la spécification associée](https://oruga-ui.com/documentation/)
- [Consultez la spécification associée](https://oruga-ui.com/documentation/themes)
- [Consultez la spécification associée](https://oruga-ui.com/components/taginput)
- [Consultez la spécification associée](https://oruga-ui.com/components/field)
- [Consultez la spécification associée](https://oruga-ui.com/components/icon)
- [Consultez la spécification associée](https://oruga-ui.com/components/button)
- [Référence du code](https://oruga-ui.com/components/taginput)
- [Référence du code](https://oruga-ui.com/documentation/configuration)
- [Introduction Enregistrement actuel du plugin et des composants explicites.](https://oruga-ui.com/documentation/)
- [Choix du thème Limite de style facultatif.](https://oruga-ui.com/documentation/themes)
- [Configuration Personnalisation des classes globales et locales.](https://oruga-ui.com/documentation/configuration)
- [Saisie de tags Contraintes du vocabulaire, modèle, limites et suppression.](https://oruga-ui.com/components/taginput)
- [Saisie semi-automatique Filtrage, comportement imbriqué de la combobox et popover natif.](https://oruga-ui.com/components/autocomplete)
- [Field Libellés visibles et messages de validation.](https://oruga-ui.com/components/field)
- [Icône Configuration du jeu d’icônes.](https://oruga-ui.com/components/icon)
- [Source du thème par défaut Configuration officielle du thème et source des jetons.](https://github.com/oruga-ui/theme-oruga)