# Sistema de design Oruga UI

## Prévia da interface do sistema de design Oruga UI

Pesquise um vocabulário controlado, adicione até três tópicos, remova uma etiqueta e salve uma descrição local da nota.

## Referência de design do sistema de design Oruga UI

Pacote Oruga para Vue 3 0.14.4 com @oruga-ui/theme-oruga 0.10.0. Os valores abaixo pertencem a esse tema padrão opcional, não a um núcleo headless imutável. Os ícones MDI 7.4.47 são fornecidos localmente. A composição do catálogo e a ilustração da pasta são originais.

### Cores semânticas do tema opcional do Oruga

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| --oruga-primary | #445e00 | Etiquetas selecionadas e ação principal. |
| --oruga-primary-invert | #fff | Texto nas etiquetas primárias. |
| --oruga-success | #006724 | Variante de sucesso. |
| --oruga-info | #005c98 | Variante informativa. |
| --oruga-warning | #f4c300 | Variante de aviso. |
| --oruga-danger | #b60000 | Variante de erro do campo. |
| --oruga-control-border-color | #dbdbdb | Borda padrão do campo. |
### Tipografia, espaçamento e geometria do tema opcional

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| --oruga-font-size | 1rem | Tamanho de texto padrão. |
| --oruga-line-height | 1.5 | Proporção padrão da altura da linha. |
| --oruga-border-radius | 4px | Cantos padrão dos controles. |
| --oruga-control-spacer | .5em | Espaçamento compartilhado entre controles. |
| --oruga-control-height | 2.25em | Altura do controle relativa à fonte. |
| --oruga-control-padding-vertical | calc(.375em - 1px) | Recuo vertical considerando a borda. |
| --oruga-control-padding-horizontal | calc(.8em - 1px) | Recuo horizontal considerando a borda. |
| --oruga-control-disabled-opacity | .5 | Estado visual desativado. |
| --oruga-animation-speed-fast | .15s | Duração de transição rápida. |
| --oruga-animation-speed | .3s | Duração de transição padrão. |
### Escalas originais explícitas da aplicação

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| Font stack | system-ui, sans-serif | Texto externo da aplicação; o tema opcional também usa uma pilha de fontes da plataforma. |
| Page title | 34px / 1.15; 29px narrow | Hierarquia original. |
| Catalog card title | Georgia, serif; 29px / 1.25 | Contraste editorial original, não um padrão do Oruga. |
| Supporting type | 10 / 11 / 12 / 13 / 14 / 15px | Legendas, definições e textos originais explícitos. |
| Spacing | 4 / 5 / 7 / 12 / 13 / 14 / 16 / 20 / 22 / 24 / 28 / 32px | Valores reais do layout; a biblioteca headless não fornece uma escala de grade. |
| Layout | Flexible editor + 330px catalog card; stack at 760px | Grade original. |
| Topic constraints | 1–3 unique existing labels | allow-new=false, allow-duplicates=false, maxitems=3. |
| Title constraint | 5–80 characters; minimum evaluated after trim | Validação da aplicação e limite de comprimento nativo. |
## Oruga UI Guia completo do sistema de design

Um guia prático para escolher, aplicar e avaliar este sistema em uma interface real.

Orientações completas, um ponto de partida para a implementação e links para o código-fonte.

## Sistema de design Oruga UI: separe o comportamento dos componentes do Oruga do tema opcional

### Separe o comportamento dos componentes do Oruga do tema opcional

> O Oruga fornece componentes Vue sem exigir uma estrutura CSS específica. Este exemplo combina o pacote para Vue 3 com o tema padrão separado do Oruga. As etiquetas verdes selecionadas e os campos contornados vêm desse tema, enquanto a pesquisa, a seleção e a remoção são comportamentos nativos dos componentes.

Essa distinção é útil ao avaliar a biblioteca. Uma equipe pode manter os componentes API e substituir a configuração de classes ou escolher outro tema compatível. Por isso, a tabela de referência identifica o pacote e a versão do tema, em vez de apresentar sua cor primária verde como requisito universal de todas as aplicações Oruga.

Consulte a especificação de apoio

## Sistema de design Oruga UI: use as variáveis reais do tema padrão

### Use as variáveis reais do tema padrão

O tema opcional instalado define --oruga-primary como #445e00 e --oruga-primary-invert como branco. A cor de perigo é #b60000, e as bordas dos controles usam #dbdbdb. A propriedade variant do componente seleciona a família semântica apropriada, sem exigir uma regra CSS separada para cada campo ou etiqueta.

O mesmo tema define um raio padrão de quatro pixels, uma altura de controle de 2.25em e fórmulas de preenchimento que subtraem a borda de um pixel. Como esses valores são relativos ao texto do controle, alterar a escala da fonte afeta a geometria. O espaçador de meio em do tema representa uma relação entre componentes, não uma escala completa de espaçamento para o layout da página.

Consulte a especificação de apoio

## Sistema de design Oruga UI: defina o layout que o Oruga intencionalmente não impõe

### Defina o layout que o Oruga intencionalmente não impõe

O catálogo usa uma coluna flexível para o editor e uma coluna de cartão de 330px, que se empilham abaixo de 760px. O título da página usa uma fonte sem serifa do sistema, enquanto o título do cartão usa Georgia para sugerir um registro editorial. Ambas as escolhas são originais e não exigem arquivos de fontes externos.

O Oruga não prescreve uma grade nem uma estrutura de utilitários. Por isso, a folha de estilos completa deixa visíveis o preenchimento dos painéis, os recuos em telas estreitas e as regras de quebra de linha. O contador de etiquetas mantém juntos o numerador e o denominador, e o título do cartão permite que nomes longos de notas quebrem em várias linhas, sem ampliar lateralmente a página incorporada.

Consulte a especificação de apoio

## Sistema de design Oruga UI: mantenha os valores selecionados separados da consulta de pesquisa

### Mantenha os valores selecionados separados da consulta de pesquisa

OTaginput vincula o array de tópicos selecionados usando v-model. O texto interno da conclusão automática filtra os rótulos candidatos sem substituir esse array. O vocabulário tem seis tópicos originais com definições concretas, e o cartão dinâmico repete apenas as definições dos tópicos selecionados.

A comparação padrão da pesquisa não diferencia maiúsculas de minúsculas. No teste local, Color foi digitado e aguardou-se a conclusão da filtragem antes de selecionar a opção resultante. Uma asserção imediata, durante o período de espera da entrada, sugeriria incorretamente que a filtragem falhou. Em seguida, a seleção limpa a consulta e preserva as etiquetas escolhidas anteriormente.

1. Pesquise Color e selecione a opção correspondente.

2. Adicione Forms para chegar a três tópicos, além de Navigation.

3. Remova uma etiqueta, confirme que o cartão foi atualizado e escolha uma substituta antes de salvar.

Consulte a especificação de apoio

## Sistema de design Oruga UI: controle o vocabulário, as duplicatas e a contagem de forma independente

### Controle o vocabulário, as duplicatas e a contagem de forma independente

allow-new=false impede que uma expressão digitada arbitrariamente se torne um rótulo. allow-duplicates=false impede que o mesmo rótulo existente seja adicionado duas vezes. maxitems=3 limita o total de seleções e exibe o contador. Cada configuração protege um aspecto diferente de um vocabulário controlado.

Ainda assim, a aplicação verifica se pelo menos um tópico está selecionado quando o usuário tenta salvar. O limite máximo de seleções não implica um requisito mínimo. A aplicação também verifica se o título, após a remoção dos espaços nas extremidades, tem cinco caracteres significativos, enquanto o atributo maxlength da entrada nativa limita o comprimento máximo a oitenta caracteres.

Consulte a especificação de apoio

## Sistema de design Oruga UI: use OField para rótulos e mensagens de validação específicas

### Use OField para rótulos e mensagens de validação específicas

OField fornece os rótulos visíveis Nota e Tópicos, além das respectivas mensagens. Depois de uma tentativa de salvar inválida, o campo correspondente recebe a variante de perigo e uma mensagem concreta indicando como corrigir o problema. A orientação sobre tópicos explica a faixa disponível e a restrição do vocabulário antes que ocorra um erro.

O menu suspenso de entrada de etiquetas nativo segue o padrão combobox/listbox. Nesta versão, a função combobox pertence a um elemento contêiner, e o campo de texto editável fica aninhado nele. Por isso, o teste de QA preenche a entrada Pesquisar tópicos em si, em vez de presumir que o elemento com a função combobox seja a própria entrada.

Consulte a especificação de apoio

## Sistema de design Oruga UI: um pacote de ícones padrão ainda precisa do arquivo de fonte

### Um pacote de ícones padrão ainda precisa do arquivo de fonte

O controle de remoção de etiquetas usa o pacote de ícones MDI padrão do Oruga. Carregar o tema dos componentes não carrega essa fonte automaticamente; por isso, a configuração completa inclui @mdi/font. A prévia independente mantém um arquivo WOFF2 local e as regras de ícones necessárias, sem depender de fontes remotas.

A remoção continua sendo um botão real com o rótulo acessível Remover tópico. A ilustração decorativa da pasta não tem relação com esses ícones de controle e fica oculta para tecnologias assistivas. Essa distinção evita que um elemento ornamental seja confundido com um controle acionável.

Consulte a especificação de apoio

## Sistema de design Oruga UI: invalide um registro salvo quando as entradas forem alteradas

### Invalide um registro salvo quando as entradas forem alteradas

A ação Salvar registra uma frase com o título sem espaços nas extremidades e a quantidade de tópicos selecionados. Um observador acompanha tanto o título quanto o array de tópicos em profundidade; por isso, remover um item limpa a confirmação, assim como alterar o título. Salvar só fica desativado enquanto o registro atual continua salvo.

Limpar nota redefine o título, todos os tópicos selecionados, a tentativa de validação e o estado salvo. O cartão passa a exibir Nota de pesquisa sem título e Nenhum tópico selecionado. O usuário pode percorrer todo o ciclo, de vazio a editado e salvo, sem backend, carregamento de arquivos ou operação de publicação por trás do botão.

- Preserve o modelo de array selecionado enquanto a consulta muda.

- Limpe a confirmação de salvamento quando houver alterações em elementos aninhados do array.

- Descreva o resultado como estado local, não como publicação.

Consulte a especificação de apoio

## Sistema de design Oruga UI: importe componentes usando o registro atual do Oruga

### Importe componentes usando o registro atual do Oruga

A configuração verificada da versão 0.14.4 cria uma instância do Oruga e a instala no aplicativo Vue. App.vue importa explicitamente OField, OInput, OTaginput, OTag e OButton. Isso segue o modelo atual de registro; confiar em exemplos antigos que pressupunham o registro global de todos os componentes pode deixar o aplicativo incompleto.

O README do tema informa que esse tema padrão usa os nomes de classe existentes do Oruga e precisa da folha de estilos, sem um objeto adicional de configuração do tema. O arquivo de entrada importa essa folha de estilos, o recurso MDI e o layout original, nessa ordem. Os exemplos completos de código-fonte acima e a raiz do Vite abaixo contêm todos os elementos necessários.

Consulte a especificação de apoio

## Exemplos de componentes do sistema de design Oruga UI

### SFC completo do catálogo de tópicos

OTaginput, OField, OInput, OTag e OButton conectam um vocabulário restrito a um cartão de catálogo atualizado em tempo real.

```
<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>
```

Referência de código

- O modelo de array selecionado é diferente do texto de busca interno.

- A seleção se limita a rótulos existentes, sem duplicatas.

- Um observador profundo limpa a confirmação salva quando um tópico é removido.

### Layout original completo do catálogo

Grade responsiva de editor e cartão, quebra de linha controlada e ilustração de pasta original 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}
```

Referência de código

- O Oruga não fornece um sistema de grade obrigatório; este layout é definido explicitamente pelo aplicativo CSS.

- O texto do contador permanece em uma única linha em larguras reduzidas.

## Configuração do agente de sistema de design Oruga UI

### Ponto de partida para implementação

Oruga 0.14.4, tema padrão opcional 0.10.0 e MDI 7.4.47 verificados. Os componentes são importados explicitamente; o tema padrão não exige configuração adicional de tema 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
```

### Um prompt para seu projeto

```
Comece com o catálogo de notas de pesquisa do Oruga 0.14.4 e seu tema 0.10.0. Mantenha a seleção controlada de OTaginput com o vocabulário de seis tópicos, a busca sem diferenciar maiúsculas de minúsculas, as novas tags e duplicatas desabilitadas e o limite de três tags. Mantenha as definições dos tópicos e a validação do título conectadas ao instantâneo salvo, limpando a confirmação salva após alterações. Inclua a configuração de createOruga, do tema CSS e do recurso MDI local. Redefina para um rascunho vazio; não invente dados de comparação de produtos nem uma atualização remota do catálogo.
```

## Fontes e escopo do sistema de design Oruga UI

Oruga 0.14.4 com tema padrão opcional 0.10.0. Vocabulário e ilustração do catálogo originais. As alterações salvas afetam apenas o estado local da página, sem envio, publicação ou persistência após recarregar.

- Introdução Plugin atual e registro explícito de componentes.

- Opções de tema Limite opcional de estilização.

- Configuração Personalização de classes globais e locais.

- Entrada de tags Restrições do vocabulário, modelo, limites e remoção.

- Preenchimento automático Filtragem, comportamento de combobox aninhado e popover nativo.

- Campo Rótulos visíveis e mensagens de validação.

- Ícone Configuração do pacote de ícones.

- Código-fonte do tema padrão Configuração oficial do tema e fonte dos tokens.

## Recursos relacionados ao sistema de design Oruga UI

### Pico CSS

Pico CSS aplica estilos a HTML semântico com uma escala tipográfica responsiva baseada em rem e variáveis de tema. Suas distribuições padrão, sem classes e condicionais têm escopos de integração diferentes; este guia usa a compilação padrão em um formulário de preferências de leitura, com comportamentos nativos de expansão e diálogo.

### Preline UI

Um planejador de sessões nativo do Preline, com guias vinculadas, um plugin de entrada numérica com restrições, aliases de tema instalados, escalas reais do Tailwind e uma estimativa local de materiais que se atualiza conforme a sessão selecionada.

### Prime UI

Uma implementação do PrimeVue com versão fixada do ecossistema Prime UI: uma árvore de documentos com tema Aura e referências reais de predefinição, expansão controlada, filtragem, seleção e fixação local.


- [Referência de implementação](https://oruga-ui.com/components/taginput)
- [Fonte](https://oruga-ui.com/documentation/themes)
- [Fonte](https://oruga-ui.com/components/taginput)
- [Consulte a especificação de apoio](https://oruga-ui.com/documentation/)
- [Consulte a especificação de apoio](https://oruga-ui.com/documentation/themes)
- [Consulte a especificação de apoio](https://oruga-ui.com/components/taginput)
- [Consulte a especificação de apoio](https://oruga-ui.com/components/field)
- [Consulte a especificação de apoio](https://oruga-ui.com/components/icon)
- [Consulte a especificação de apoio](https://oruga-ui.com/components/button)
- [Referência de código](https://oruga-ui.com/components/taginput)
- [Referência de código](https://oruga-ui.com/documentation/configuration)
- [Introdução Plugin atual e registro explícito de componentes.](https://oruga-ui.com/documentation/)
- [Opções de tema Limite opcional de estilização.](https://oruga-ui.com/documentation/themes)
- [Configuração Personalização de classes globais e locais.](https://oruga-ui.com/documentation/configuration)
- [Entrada de tags Restrições do vocabulário, modelo, limites e remoção.](https://oruga-ui.com/components/taginput)
- [Preenchimento automático Filtragem, comportamento de combobox aninhado e popover nativo.](https://oruga-ui.com/components/autocomplete)
- [Campo Rótulos visíveis e mensagens de validação.](https://oruga-ui.com/components/field)
- [Ícone Configuração do pacote de ícones.](https://oruga-ui.com/components/icon)
- [Código-fonte do tema padrão Configuração oficial do tema e fonte dos tokens.](https://github.com/oruga-ui/theme-oruga)