# Codexデザインシステム

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

独自の3つの例を検索し、検索結果を確認して閉じるか、一致する結果がない検索語を試してください。

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

@wikimedia/codex 2.7.0のネイティブCSSと、最新の公式トークン／コンポーネントリファレンスです。単独プレビューでは、ドキュメントに記載されたCSSのみのルートを使用しています。コンテンツの幅と検索結果パネルのレイアウトは、アプリケーション側で設定しています。

### フォントの役割

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| font-family-base | sans-serif | 文書とコントロールの基本ロール。 |
| font-family-heading-main | Linux Libertine, Georgia, Times, Source Serif 4, serif | ローカルのフォールバックを指定した、最初の見出し専用ロール。 |
| font-size-small / medium / large | 0.875rem / 1rem / 1.125rem | 補助テキスト、デフォルトテキスト、大きめのテキスト。 |
| line-height-medium | 1.625rem | コンポーネント／機能の行高トークン。 |
| line-height-content | 1.625 | ユーザー生成コンテンツ向けの単位なしロール。 |
### スペーシング

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| spacing-25 / 50 / 75 | 4px / 8px / 12px | コンパクトな間隔。 |
| spacing-100 / 150 / 200 | 16px / 24px / 32px | 標準的なレイアウトのリズム。 |
| spacing-30 | 5px | デフォルトのコントロールの垂直パディングに関する、ドキュメント記載の例外。 |
| spacing-horizontal-button | 12px − 1px | ボタンの枠線を考慮します。 |
### ビューポートとコントロール

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| Mobile / tablet minima | 320px / 640px | ビューポートの境界。 |
| Desktop / desktop-wide minima | 1120px / 1680px | より大きなビューポートの境界。 |
| Button small / medium / large | 24px / 32px / 44px minimum | タッチ操作の状況に応じてlargeを使用してください。サイズはButtonのドキュメントに基づいています。 |
### コンパイル済みのデフォルト色のフォールバック

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| color-base | #202122 | 通常の読み取りに使うテキスト。 |
| color-progressive | #36c | 段階的に強調するアクション色。すべてのレコードに適用するステータスではありません。 |
## Codexデザインシステムの完全ガイド

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

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

## CodexデザインシステムのCSSのみのルートとVueルート

### 必要な実装を選択してください

> CodexはVueコンポーネントと、CSSのみで構成するコンポーネント構造のドキュメントを提供します。ライブサンプルでは後者を採用しています。検索コントロールには、Codexのドキュメントに記載されたラッパー、テキスト入力、末尾ボタンの各クラスをそのまま使用し、アプリケーション内のスクリプトで3件のオリジナル記事の概要を絞り込みます。別のVueの例では、同等のパッケージをインポートする方法を示します。

CSSのみで構成した検索は、見た目が似ているだけで予測入力コンボボックスになるわけではありません。この例ではクエリを送信し、結果リストを表示します。ARIAのlistboxパターンは使用しておらず、TypeaheadSearchを実装しているとも謳っていません。

関連する仕様を確認する

## Codexデザインシステム：読みやすさを支えるタイポグラフィ

### コンテンツとコントロールの役割を分ける

font-family-baseトークンはsans-serifに解決されます。利用可能なsystem-sansスタックは、これとは別の役割です。Codexには、Linux Libertineを基調とし、Georgia、Timesなどをフォールバックに指定したserifのheading-mainロールもあります。プレビューではフォントをダウンロードせずに、記事の見出しにserif、コントロールにsans-serifを使用しています。

以下のリファレンスでは、1remのfont-size-mediumと1.625remのline-height-mediumを別々に定義しています。単位なしのline-height-content値はユーザー生成コンテンツ向けです。すべてのコンポーネントの内部行高を一律に置き換える指示ではありません。ネイティブの入力欄やボタンなどのCSSには、それぞれのコントロール用メトリクスを適用してください。

関連する仕様を確認する

## Codexデザインシステム：スペーシングとブレークポイント

### 名前付きスケールと例外を使う

Codexのspacing-100は16px、spacing-150は24px、spacing-200は32pxです。このスケールには明示的な例外もあり、spacing-30は5pxで、標準のコントロール高32pxにおける縦方向のパディングに使われます。すべてのスペースを8pxグリッドに丸めると、ドキュメント化されたコンポーネントの設計判断が失われます。

この例では、ドキュメントに記載されたタブレットの境界値を使い、640px未満では結果リストを全幅にします。最大読み幅の56remは、アプリケーション側で設定しています。デスクトップのブレークポイントは1120px、desktop-wideは1680pxです。これらはビューポートの区分を示すしきい値であり、すべてのアプリケーションに自動的に提供されるグリッドではありません。

関連する仕様を確認する

## Codexデザインシステム：色とアクションの役割

### progressiveは、単なる青色の装飾ではない

Codexでは、アクションの種類とボタンのウェイトを区別します。progressiveアクションはプロセスを進め、primaryウェイトはその画面の主要なアクションを示します。このローカルインデックスの検索には、neutralのnormalボタンが適しています。quietコントロールを使えば、結果の妨げにならない形で検索をクリアできます。

コンパイル済みのCSSには、カスタムプロパティのフォールバックカラーが含まれています。たとえば、基本テキストは#202122、progressiveは#36cです。プレビューでは、これらの状態にネイティブのコンポーネントCSSを使用しています。淡色の結果パネルの背景はアプリケーションのレイアウトであり、新たに作られたCodexのステータストークンではありません。

関連する仕様を確認する

## Codexデザインシステム：SearchInputの構造

### 入力欄とボタンを意図的に一体化する

CSSのみで構成する場合は、ルートに.cdx-search-input--has-end-button、.cdx-search-input__input-wrapper、start-icon修飾子を持つ.cdx-text-input、そして.cdx-search-input__end-buttonを持つボタンが必要です。ラッパーを省略すると、入力欄とボタンの一体感やアイコンの配置が損なわれます。

表示ラベルで検索対象を示します。アイコンのspanは装飾用として、アクセシビリティAPIから隠しています。フォームでは1つのsubmitリスナーでEnterキーとボタンの操作を処理し、結果の更新後にはpoliteステータス領域で件数を通知します。入力欄が空の場合は、すべてのローカルサンプルが再表示されます。

- ページ内のコンテンツを探すにはSearchInputを使います。

- 予測入力によるナビゲーション候補が必要な場合はTypeaheadSearchを使います。

- フォームの値として選択肢を選ぶ場合はLookupを使います。

関連する仕様を確認する

## Codexデザインシステム：検索結果と詳細の閲覧

### 読者が閲覧していた位置を保つ

各結果には、見出し、オリジナルの短い説明、ローカルの閲覧パネルを開くボタンがあります。このパネルはアプリケーション側で構成したもので、CodexのDialogではありません。通常のドキュメントフロー内に表示され、モーダルの背景もなく、フォーカスも閉じ込めません。

サンプルを開くと、パネルの見出しにフォーカスが移ります。閉じると、開く操作を行ったボタンにフォーカスが戻ります。再検索時には、前の詳細を閉じて結果件数を再計算するため、古い記事が新しいクエリの結果に含まれているように見えることはありません。一致する結果がない場合は、説明文と明示的なクリア操作を表示します。

関連する仕様を確認する

## Codexデザインシステム：方向と入力動作

### 英語以外の言語にも対応できるようにする

コンポーネントのドキュメントには、左から右（LTR）と右から左（RTL）の例があります。Codexは多言語の知識エコシステムで使われるため、アプリケーションのレイアウトでは、アイコンや閲覧操作が常に左側にあると想定せず、インライン方向とブロック方向に応じたスペーシングを使う必要があります。このサンプルのカスタムレイアウトでは、方向性が関係する箇所にmargin-inlineとpadding-inlineを使用しています。

ここでの検索は、送信時にのみ実行されます。これにより、IMEの変換中のテキストを確定済みのクエリとして扱うことを避けられます。実際のオートコンプリートを実装するには、変換中の入力への対応、非同期リクエストのキャンセル、適切なメニュー操作モデルが必要です。CSSのみで構成したこのローカルサンプルでは、これらの機能を実装しているとは謳っていません。

関連する仕様を確認する

## Codexデザインシステムの統合と拡張

### ライブラリのバージョンを固定し、結果のロジックはアプリケーション側で管理する

確認済みのパッケージは@wikimedia/codex 2.7.0で、スタイルのエントリーポイントとしてdist/codex.style.cssを公開しています。CSSのみのデモは、すべてのコントロールがネイティブのHTMLであり、小規模なローカルスクリプトが絞り込みと閲覧パネルの状態を管理するため、Vueランタイムを必要としません。フレームワークで状態を管理する場合は、VueのバリエーションでCdxSearchInputとCdxButtonをインポートします。

コードバンドルはGPL-2.0-or-laterで提供され、ライセンスはローカルアセットに同梱されています。各例では、Wikipediaのブランドや記事コンテンツを複製していません。実際の検索エンドポイントに接続する前に、ローカルで結果がない状態を別の状態に置き換えるのではなく、ネットワークエラー、読み込み中、古い応答への対処をそれぞれ追加してください。

1. バージョンを固定したパッケージをインストールするか、ライセンスとともにスタイルシートをコピーします。

2. ドキュメントに記載されたCSSのみの構造を描画するか、エクスポートされたVueコンポーネントを使います。

3. クエリと結果のロジックをアプリケーションに実装し、検索の意味を保ちます。

4. 実際に翻訳したコンテンツを使って、キーボードフォーカスと狭い画面でのレイアウトを確認します。

関連する仕様を確認する

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

### 表示ラベル付きのCSSのみで構成した検索

ドキュメントに記載されたラッパー構造とネイティブフォームの送信処理。

```
<form id="article-search" role="search">
  <label for="query">Find an example article</label>
  <div class="cdx-search-input cdx-search-input--has-end-button">
    <div class="cdx-search-input__input-wrapper">
      <div class="cdx-text-input cdx-text-input--has-start-icon">
        <input id="query" class="cdx-text-input__input" type="search">
        <span class="cdx-text-input__icon cdx-text-input__start-icon" aria-hidden="true"></span>
      </div>
    </div>
    <button type="submit" class="cdx-button cdx-search-input__end-button">Search</button>
  </div>
</form>
<p id="result-count" role="status"></p>
```

コードリファレンス

### Vue検索のコンポジション

実際のCodexインポートとVueの状態を使用し、送信済みクエリのローカル出力で連携の境界を示します。

```
<script setup>
import { ref } from 'vue';
import { CdxSearchInput, CdxButton } from '@wikimedia/codex';
import '@wikimedia/codex/dist/codex.style.css';
const query = ref('');
const submitted = ref('');
function search() { submitted.value = String(query.value).trim(); }
</script>
<template>
  <form role="search" @submit.prevent="search">
    <CdxSearchInput v-model="query" aria-label="Find an example article" />
    <CdxButton action="progressive" weight="primary" type="submit">Search</CdxButton>
  </form>
  <p role="status">Submitted query: {{ submitted || 'All examples' }}</p>
</template>
```

コードリファレンス

### 単体で動作するサンプル一式

レイアウト、操作要素、初期化処理を含むドキュメント全体です。リンク先のサンプルアーカイブを展開すると、このプレビューで使用する正確な相対パスのベンダーアセットが得られます。その後、HTTP経由で配信してください。

```
<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Codex knowledge search</title><link rel="stylesheet" href="vendor/codex-2.7.0/codex.style.css"><style>*{box-sizing:border-box}body{font:16px/1.625 sans-serif;color:#202122;margin:0}main{max-width:56rem;margin:auto;padding:32px 24px}h1{font:normal 32px/1.3 Georgia,serif;border-bottom:1px solid #a2a9b1;padding-bottom:12px}h2{font-size:20px;margin:0 0 8px}label{display:block;font-weight:700;margin-bottom:8px}.top{font-size:14px;color:#54595d}.result{padding:24px 0;border-bottom:1px solid #c8ccd1}.result p{margin:8px 0 16px}.tools{display:flex;align-items:center;gap:16px;justify-content:space-between}.reading{padding:24px;background:#f8f9fa;border:1px solid #a2a9b1;margin-block:24px}.reading h2:focus{outline:2px solid #36c;outline-offset:4px}small{display:block;margin-top:32px;color:#54595d;font-size:14px}[hidden]{display:none!important}@media(max-width:639px){main{padding:24px 16px}.tools{align-items:stretch;flex-direction:column}.result .cdx-button{width:100%}}
</style><main><p class="top">Independent knowledge index · Codex CSS-only</p><h1>Explore the example collection</h1><p>Find an original topic summary and open its reading panel. This small index runs entirely in your browser.</p><form id="article-search" role="search">
  <label for="query">Find an example article</label>
  <div class="cdx-search-input cdx-search-input--has-end-button">
    <div class="cdx-search-input__input-wrapper">
      <div class="cdx-text-input cdx-text-input--has-start-icon">
        <input id="query" class="cdx-text-input__input" type="search">
        <span class="cdx-text-input__icon cdx-text-input__start-icon" aria-hidden="true"></span>
      </div>
    </div>
    <button type="submit" class="cdx-button cdx-search-input__end-button">Search</button>
  </div>
</form>
<p id="result-count" role="status"></p><div class="tools"><p id="empty" hidden>No matching topics. Try “river” or clear the search.</p><button type="button" class="cdx-button cdx-button--weight-quiet" id="clear">Clear search</button></div><div id="results"></div><section class="reading" id="reading" hidden><h2 id="reading-title" tabindex="-1"></h2><p id="reading-text"></p><button type="button" class="cdx-button" id="close">Close reading panel</button></section><small>Original example content. Wikimedia Codex 2.7.0 controls; application-owned results and inline panel. No external search request.</small></main><script>
const data=[{title:'River observation notes',text:'A field notebook can record water level, weather and observation time together. Repeated observations from the same location help readers compare conditions without confusing a new measurement with a changed method.',summary:'Organising repeated observations at a river station.'},{title:'Community archive descriptions',text:'An archive description records what an item is, when it was created and how it relates to other items. A clear description distinguishes an original document from a later copy and identifies uncertain dates without hiding that uncertainty.',summary:'Describing original documents and their context.'},{title:'Garden seed collection',text:'A seed record can distinguish the plant name, collection date and storage method. Keeping those attributes separate makes it easier to compare batches, while a free-text note preserves observations that do not fit a controlled field.',summary:'Keeping plant, date and storage information readable.'}];let opener;const results=document.querySelector('#results'),query=document.querySelector('#query'),reading=document.querySelector('#reading'),count=document.querySelector('#result-count');function render(){reading.hidden=true;results.replaceChildren();const found=data.filter(d=>(d.title+' '+d.summary).toLowerCase().includes(query.value.trim().toLowerCase()));count.textContent=found.length+' example topics';document.querySelector('#empty').hidden=found.length>0;for(const d of found){let a=document.createElement('article');a.className='result';let h=document.createElement('h2');h.textContent=d.title;let p=document.createElement('p');p.textContent=d.summary;let b=document.createElement('button');b.type='button';b.className='cdx-button';b.textContent='Read '+d.title;b.onclick=()=>{opener=b;document.querySelector('#reading-title').textContent=d.title;document.querySelector('#reading-text').textContent=d.text;reading.hidden=false;document.querySelector('#reading-title').focus()};a.append(h,p,b);results.append(a)}}document.querySelector('form').onsubmit=e=>{e.preventDefault();render()};document.querySelector('#clear').onclick=()=>{query.value='';render();query.focus()};document.querySelector('#close').onclick=()=>{reading.hidden=true;opener?.focus()};render();
</script></html>
```

コードリファレンス

- 完全なサンプルは「ソース」からダウンロードできます。READMEに正確なローカル起動コマンドが記載されています。

- ベンダーのパスはこのドキュメントからの相対パスのままにしてください。アーカイブには、このプレビューで使用するアセット一式が含まれています。

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

### 実装の出発点

単体プレビューでは、ネイティブのスタイルシートをローカルで検証しています。Vueコードは独立した連携例であり、プレビューの実行環境ではありません。Sourcesにある完全な動作例のZIPには、プレビューに必要な依存関係とドキュメント一式も含まれています。展開したディレクトリでpython3 -m http.server 8080を実行し、http://localhost:8080/wikimedia-codex.htmlを開いてください。モジュールを使う例はfile://経由で開かないでください。

```
npm install @wikimedia/codex@2.7.0
# CSS-aware entry for CSS-only HTML:
# import '@wikimedia/codex/dist/codex.style.css';
# For the Vue example, add Vue to the existing Vue application:
# import { CdxSearchInput, CdxButton } from '@wikimedia/codex';
```

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

```
Codex 2.7.0 CSS専用のSearchInputとボタンを使って、ローカルのナレッジインデックスを構築します。ドキュメントに記載された末尾ボタンのラッパーを維持し、検索ラベルを明示して、ネイティブのフォーム送信を使います。検索結果件数、該当なしのメッセージ、クリア操作を表示します。検索結果の詳細はインラインで開き、見出しにフォーカスを移動します。閉じると、操作を開始したボタンにフォーカスを戻します。TypeaheadSearchやモーダルのセマンティクスをうたわないでください。公式のフォントと余白の役割を使いながら、コンテンツ幅はアプリケーション側で決めた設定であることを明示します。
```

## Codexデザインシステムのソースと適用範囲

独自の要約を用いた、独立したOpenDesignの例です。Wikipediaのコンテンツやアイデンティティは複製していません。CSSのみのコントロールはネイティブのCodexです。検索フィルタリングとインラインの閲覧パネルはアプリケーションコードで実装しています。

- Codexの概要 Wikimediaの公式デザインシステムのエントリ。

- Codexへのアクセス デザインと開発に利用できるリソース。

- スタイルガイド ビジュアル、コンテンツ、インタラクションに関するガイダンス。

- 動作サンプル一式をダウンロード 完全なHTML、ローカルのCSS／JavaScript依存関係、付属ライセンス、正確な起動手順を含むZIPです。ビルド手順は不要です。

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

### Agriculture デザインシステム

AgDSの具体的なスペーシング、レスポンシブプロパティ、TaskListのステータスモデルを活用して、複数のステップからなる手続きを構築しましょう。前提条件がすべて完了するとレビューのステップが利用可能になる、準備フローを試せます。

### Alberta デザインシステム

AlbertaのネイティブWebコンポーネントと公開されているデザイントークンを使用して、アクセシブルな選択肢、算出される進捗、誠実なレビュー結果を備えた準備チェックリストを作成します。

### Amsterdam

Amsterdamの実際のオープンソースSwitchの仕様を、完全なニュートラルテーマ、アクセシブルなラベル、即時反映される閲覧設定とともに使用します。


- [実装リファレンス](https://doc.wikimedia.org/codex/latest/components/demos/search-input.html)
- [ソース](https://doc.wikimedia.org/codex/latest/design-tokens/font.html)
- [ソース](https://doc.wikimedia.org/codex/latest/design-tokens/spacing.html)
- [ソース](https://doc.wikimedia.org/codex/latest/design-tokens/breakpoint.html)
- [ソース](https://doc.wikimedia.org/codex/latest/design-tokens/color.html)
- [関連する仕様を確認する](https://doc.wikimedia.org/codex/latest/components/demos/search-input.html)
- [関連する仕様を確認する](https://doc.wikimedia.org/codex/latest/design-tokens/font.html)
- [関連する仕様を確認する](https://doc.wikimedia.org/codex/latest/design-tokens/spacing/)
- [関連する仕様を確認する](https://doc.wikimedia.org/codex/latest/components/demos/button.html)
- [関連する仕様を確認する](https://doc.wikimedia.org/codex/latest/components/overview.html)
- [関連する仕様を確認する](https://doc.wikimedia.org/codex/latest/using-codex/)
- [コードリファレンス](https://doc.wikimedia.org/codex/latest/components/demos/search-input.html)
- [Codexの概要 Wikimediaの公式デザインシステムのエントリ。](https://doc.wikimedia.org/codex/latest/)
- [Codexへのアクセス デザインと開発に利用できるリソース。](https://doc.wikimedia.org/codex/latest/using-codex/accessing-codex.html)
- [スタイルガイド ビジュアル、コンテンツ、インタラクションに関するガイダンス。](https://doc.wikimedia.org/codex/latest/style-guide/overview.html)