# Oruga UI デザインシステム

## Oruga UI デザインシステムのインターフェースプレビュー

管理された候補リストから検索し、トピックを最大3つ追加して、タグを削除し、メモの説明をローカルに保存します。

## Oruga UI デザインシステムのデザインリファレンス

Oruga Vue 3パッケージ0.14.4と@oruga-ui/theme-oruga 0.10.0を使用しています。以下の値は、このオプションのデフォルトテーマに属するもので、変更できないヘッドレスコアの値ではありません。MDI 7.4.47のアイコンはローカルで提供します。カタログの周辺レイアウトとフォルダーのイラストはオリジナルです。

### Orugaオプションテーマのセマンティックカラー

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| --oruga-primary | #445e00 | 選択済みタグとメインアクション。 |
| --oruga-primary-invert | #fff | プライマリタグ上のテキスト。 |
| --oruga-success | #006724 | 成功バリアント。 |
| --oruga-info | #005c98 | 情報バリアント。 |
| --oruga-warning | #f4c300 | 警告バリアント。 |
| --oruga-danger | #b60000 | フィールドエラーのバリアント。 |
| --oruga-control-border-color | #dbdbdb | デフォルトのフィールド境界線。 |
### オプションテーマの文字、スペーシング、形状

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| --oruga-font-size | 1rem | デフォルトの文字サイズ。 |
| --oruga-line-height | 1.5 | デフォルトの行高比。 |
| --oruga-border-radius | 4px | 標準コントロールの角丸。 |
| --oruga-control-spacer | .5em | 共通のコントロール間隔。 |
| --oruga-control-height | 2.25em | フォントサイズに対するコントロールの高さ。 |
| --oruga-control-padding-vertical | calc(.375em - 1px) | 境界線を考慮した縦方向の内側余白。 |
| --oruga-control-padding-horizontal | calc(.8em - 1px) | 境界線を考慮した横方向の内側余白。 |
| --oruga-control-disabled-opacity | .5 | 無効状態の表示。 |
| --oruga-animation-speed-fast | .15s | 短いトランジション時間。 |
| --oruga-animation-speed | .3s | 標準のトランジション時間。 |
### アプリケーションで明示的に定義したオリジナルのスケール

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| Font stack | system-ui, sans-serif | アプリケーション全体のテキスト。オプションテーマもプラットフォームのフォントスタックを使用します。 |
| Page title | 34px / 1.15; 29px narrow | オリジナルの階層構造。 |
| Catalog card title | Georgia, serif; 29px / 1.25 | Orugaのデフォルトではない、オリジナルのエディトリアル向けコントラスト。 |
| Supporting type | 10 / 11 / 12 / 13 / 14 / 15px | オリジナルのキャプション、定義、本文に明示的に指定した値。 |
| Spacing | 4 / 5 / 7 / 12 / 13 / 14 / 16 / 20 / 22 / 24 / 28 / 32px | 実際のレイアウト値。ヘッドレスライブラリにはグリッドのスケールがありません。 |
| Layout | Flexible editor + 330px catalog card; stack at 760px | オリジナルのグリッド。 |
| Topic constraints | 1–3 unique existing labels | allow-new=false、allow-duplicates=false、maxitems=3。 |
| Title constraint | 5–80 characters; minimum evaluated after trim | アプリケーションの検証と標準の文字数上限。 |
## Oruga UI デザインシステム完全ガイド

実際のインターフェースで、このデザインシステムを選び、適用し、レビューするための実践ガイドです。

詳しいガイダンス、実装の出発点、ソースへのリンクをまとめています。

## Oruga UI デザインシステム：Orugaのコンポーネント動作とオプションのテーマを分ける

### Orugaのコンポーネント動作とオプションのテーマを分ける

> Orugaは、特定のCSSフレームワークを必要とせずにVueコンポーネントを提供します。この例では、Vue 3パッケージと、別途提供されるOrugaのデフォルトテーマを組み合わせています。選択時の緑色のタグや枠線付きのフィールドはこのテーマによるもので、検索、選択、削除はコンポーネント標準の動作です。

ライブラリを評価する際は、この境界を把握しておくと役立ちます。チームはコンポーネントAPIを維持したまま、クラス設定を置き換えたり、別の対応テーマを選んだりできます。そのため、参照表ではテーマパッケージとバージョンを記載し、緑色のプライマリカラーを、すべてのOrugaアプリケーションに共通する必須要件として扱いません。

関連する仕様を確認する

## Oruga UIデザインシステム：実際のデフォルトテーマ変数を使う

### 実際のデフォルトテーマ変数を使用する

インストールしたオプションのテーマでは、--oruga-primaryに#445e00、--oruga-primary-invertにwhiteが定義されています。危険状態の色は#b60000、コントロールの境界線は#dbdbdbです。コンポーネントのvariantプロパティで適切なセマンティックカラーを選べるため、フィールドやタグごとに個別のCSSルールを用意する必要はありません。

同じテーマでは、標準の角丸を4ピクセル、コントロールの高さを2.25emとし、1ピクセルの境界線を差し引くパディングの計算式を定義しています。これらの値はコントロール内のテキストに対する相対値なので、フォントサイズを変更すると形状にも影響します。テーマにおける半emのスペーサーはコンポーネント間の関係を示すもので、ページ全体に適用される余白スケールがあることを意味しません。

関連する仕様を確認する

## Oruga UIデザインシステム：Orugaが意図的に規定していないレイアウトを用意する

### Orugaが意図的に規定していないレイアウトを用意する

カタログでは、幅が可変のエディター列と幅330pxのカード列を使い、760px未満では縦に並べます。ページタイトルにはシステムサンセリフ体、カードタイトルには編集記事のような印象を与えるGeorgiaを使用しています。いずれも独自の選択であり、外部フォントファイルは必要ありません。

Orugaはグリッドやユーティリティフレームワークを指定していません。そのため、スタイルシート全体を示し、パネルのパディング、狭い画面での内側余白、折り返しのルールがわかるようにしています。タグのカウンターでは分子と分母が分かれないようにし、カードタイトルは長いメモ名を折り返して表示することで、埋め込みページが横に押し広げられないようにしています。

関連する仕様を確認する

## Oruga UIデザインシステム：選択した値と検索クエリを分けて管理する

### 選択済みの値を検索クエリと分けて管理する

OTaginputでは、選択したトピックの配列をv-modelでバインドします。内部のオートコンプリート用テキストは候補ラベルの絞り込みに使われ、配列を置き換えることはありません。語彙には、具体的な定義を持つ独自のトピックが6つあります。ライブカードには、選択されたトピックの定義だけが表示されます。

デフォルトの検索では、大文字と小文字を区別しません。ローカルテストでは「Color」と入力し、絞り込みが完了するまで待ってから、該当する候補を選びました。入力のデバウンス中にすぐアサーションを行うと、絞り込みに失敗したと誤って判断されます。選択後は、すでに選んだタグを維持したままクエリがクリアされます。

1. Colorで検索し、一致する候補を選択します。

2. Formsを追加し、Navigationと合わせてトピックを3つにします。

3. タグを削除してカードが更新されたことを確認し、保存する前に代わりのタグを選びます。

関連する仕様を確認する

## Oruga UIデザインシステム：語彙、重複、件数を個別に管理する

### 候補の語彙、重複、件数をそれぞれ制御する

allow-new=falseにすると、任意の入力文字列をラベルとして追加できなくなります。allow-duplicates=falseにすると、同じ既存ラベルを重複して追加できません。maxitems=3は選択数の上限を設定し、カウンターを表示します。それぞれの設定が、管理された語彙の異なる側面を保護します。

それでもアプリケーション側では、保存時にトピックが1つ以上選択されていることを確認します。選択数の上限があっても、最低選択数が設定されるわけではありません。また、タイトルは前後の空白を除いて有効な文字が5文字以上あることを確認します。一方、ネイティブ入力のmaxlengthによって、最大文字数は80文字に制限されます。

関連する仕様を確認する

## Oruga UIデザインシステム：ラベルと個別の検証メッセージにOFieldを使う

### ラベルと個別の検証メッセージにはOFieldを使用する

OFieldで「メモのタイトル」と「トピック」のラベルおよびメッセージを表示します。無効な状態で保存しようとすると、該当フィールドにdangerバリアントを適用し、具体的な修正方法を示します。トピックの案内では、エラーが発生する前に、選択可能な範囲と語彙の制約を説明します。

ネイティブのタグ入力ドロップダウンは、combobox/listboxパターンに従っています。このバージョンでは、comboboxロールはラッパーに割り当てられ、その内側に編集可能なテキストボックスがあります。そのためQAでは、comboboxロールの要素自体が入力欄だと想定せず、実際の「トピックを検索」入力欄に値を入力します。

関連する仕様を確認する

## Oruga UIデザインシステム：デフォルトのアイコンパックにもフォントアセットが必要

### デフォルトのアイコンパックにもフォントアセットが必要

タグの削除コントロールには、OrugaのデフォルトMDIアイコンパックを使います。コンポーネントのテーマを読み込んでも、このフォントは自動的に読み込まれないため、セットアップには@mdi/fontも含めます。単体プレビューではローカルのWOFF2アセットと必要なアイコンルールを使用し、外部フォントへの依存を避けています。

削除操作には、「トピックを削除」というアクセシブルなラベルを持つ実際のボタンを使用します。装飾用のフォルダーイラストはこれらのコントロールアイコンとは無関係で、支援技術から隠されています。こうすることで、装飾的なマークが操作可能なコントロールと誤認されるのを防ぎます。

関連する仕様を確認する

## Oruga UIデザインシステム：入力値の変更時に保存済みスナップショットを無効にする

### 入力値が変わったら保存済みスナップショットを無効にする

保存操作では、前後の空白を除いたタイトルと選択中のトピック数を示す文を記録します。監視処理はタイトルとトピック配列をディープ監視するため、タイトルの変更だけでなく、項目の削除でも保存確認がクリアされます。保存ボタンが無効になるのは、現在のスナップショットが保存済みの間だけです。

「メモをクリア」を選ぶと、タイトル、選択中のトピックすべて、検証の試行状態、保存状態がリセットされます。カードには「無題のリサーチメモ」と「トピックが選択されていません」と表示されます。バックエンド、アップロード、公開処理をボタンの裏側で行うことなく、空の状態から編集、保存までの一連の流れを確認できます。

- クエリを変更しても、選択済み配列の状態を維持する。

- ネストされた配列が変更されたら、保存済みのフィードバックをクリアする。

- 公開ではなく、ローカルの状態として結果を説明する。

関連する仕様を確認する

## Oruga UIデザインシステム：現在のOruga登録方法に沿ってコンポーネントを明示的にインポートする

### 現在のOruga登録方法でコンポーネントを明示的にインポートする

検証済みの0.14.4のセットアップでは、Orugaインスタンスを作成してVueアプリに登録します。App.vueでは、OField、OInput、OTaginput、OTag、OButtonを明示的にインポートします。これは現在の登録方法に沿ったものです。すべてのコンポーネントがグローバル登録されると想定した古い例に頼ると、アプリケーションに必要なコンポーネントが不足することがあります。

テーマの README によると、このデフォルトテーマは Oruga の既存クラス名を使用し、追加のテーマ設定オブジェクトを使わずにスタイルシートを読み込む必要があります。エントリでは、スタイルシート、MDI アセット、元のレイアウトの順にインポートします。必要な要素はすべて、上記の完全なソース例と、以下の Vite ルートに含まれています。

関連する仕様を確認する

## Oruga UI デザインシステムのコンポーネント例

### トピックカタログの完全な SFC

OTaginput、OField、OInput、OTag、OButton を使って、選択肢を既存の語彙に制限し、カタログカードにリアルタイムで反映します。

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

コードリファレンス

- 選択した配列のモデルは、内部の検索テキストとは別です。

- 選択できるのは、既存の重複していないラベルのみです。

- トピックが削除されると、deep watcher によって保存済みの確認状態がクリアされます。

### 元のカタログレイアウト全体

レスポンシブなエディター／カードのグリッド、折り返しの制御、オリジナルの 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}
```

コードリファレンス

- Oruga には必須のグリッドシステムがないため、このレイアウトはアプリケーション内で明示的に定義しています CSS。

- カウンターのテキストは、幅の狭い画面でも1行に収まります。

## Oruga UI デザインシステムエージェントのセットアップ

### 実装の出発点

Oruga 0.14.4、任意のデフォルトテーマ 0.10.0、MDI 7.4.47 で動作を確認済みです。コンポーネントは明示的にインポートします。デフォルトテーマに追加の 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
```

### あなたのプロジェクト向けプロンプト

```
Oruga 0.14.4 のリサーチノートカタログと、そのテーマ 0.10.0 から始めます。6つのトピック語彙から選択する OTaginput の制御、英字の大文字・小文字を区別しない検索、新規タグと重複タグの無効化、最大3タグの制限を維持してください。トピックの定義とタイトルの検証を保存済みスナップショットに連動させ、変更後は保存済みのフィードバックをクリアします。createOruga、theme CSS、ローカルの MDI アセットのセットアップも含めてください。空の下書きにリセットし、製品比較データやリモートカタログの更新機能を作らないでください。
```

## Oruga UI デザインシステムのソースと対象範囲

Oruga 0.14.4 と任意のデフォルトテーマ 0.10.0。オリジナルの語彙とカタログイラストを使用します。変更の保存先はページのローカル状態のみです。アップロードや公開は行わず、ページの再読み込み後も状態を保持しません。

- 概要 現在のプラグインと、明示的なコンポーネント登録。

- テーマの選択肢 スタイル設定の任意の境界。

- 設定 グローバルおよびローカルのクラスのカスタマイズ。

- タグ入力 語彙の制約、モデル、上限、削除。

- オートコンプリート 絞り込み、入れ子になったコンボボックスの動作、ネイティブの popover。

- Field 表示ラベルと検証メッセージ。

- アイコン アイコンパックの設定。

- デフォルトテーマのソース 公式テーマのセットアップとトークンのソース。

## Oruga UI デザインシステム関連リソース

### Pico CSS

Pico CSSのスタイルは、レスポンシブなremベースの文字サイズスケールとテーマ変数を備えたセマンティックなHTMLです。標準版、クラスレス版、条件付き版では統合できる範囲が異なります。このガイドでは標準ビルドを使い、ネイティブの開閉要素とダイアログ動作を備えた読みやすさ設定フォームを作成します。

### Preline UI

タブを連動させたネイティブのPrelineセッションプランナー。入力数値を制限するプラグイン、インストール済みのテーマエイリアス、実際のTailwindスケールを備え、選択したセッションに応じてローカルの教材費見積もりが更新されます。

### Prime UI

Prime UI エコシステムをバージョン固定で実装した PrimeVue の例です。Aura テーマのドキュメントツリーで、実際のプリセット参照、展開状態の制御、絞り込み、選択、ローカルでのピン留めに対応します。


- [実装リファレンス](https://oruga-ui.com/components/taginput)
- [ソース](https://oruga-ui.com/documentation/themes)
- [ソース](https://oruga-ui.com/components/taginput)
- [関連する仕様を確認する](https://oruga-ui.com/documentation/)
- [関連する仕様を確認する](https://oruga-ui.com/documentation/themes)
- [関連する仕様を確認する](https://oruga-ui.com/components/taginput)
- [関連する仕様を確認する](https://oruga-ui.com/components/field)
- [関連する仕様を確認する](https://oruga-ui.com/components/icon)
- [関連する仕様を確認する](https://oruga-ui.com/components/button)
- [コードリファレンス](https://oruga-ui.com/components/taginput)
- [コードリファレンス](https://oruga-ui.com/documentation/configuration)
- [概要 現在のプラグインと、明示的なコンポーネント登録。](https://oruga-ui.com/documentation/)
- [テーマの選択肢 スタイル設定の任意の境界。](https://oruga-ui.com/documentation/themes)
- [設定 グローバルおよびローカルのクラスのカスタマイズ。](https://oruga-ui.com/documentation/configuration)
- [タグ入力 語彙の制約、モデル、上限、削除。](https://oruga-ui.com/components/taginput)
- [オートコンプリート 絞り込み、入れ子になったコンボボックスの動作、ネイティブの popover。](https://oruga-ui.com/components/autocomplete)
- [Field 表示ラベルと検証メッセージ。](https://oruga-ui.com/components/field)
- [アイコン アイコンパックの設定。](https://oruga-ui.com/components/icon)
- [デフォルトテーマのソース 公式テーマのセットアップとトークンのソース。](https://github.com/oruga-ui/theme-oruga)