# USWDSデザインシステム

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

架空の記録を検索・絞り込みし、該当結果がない場合は復旧して、ネイティブの要件パネルを展開できます。

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

USWDS 3.14.0のネイティブコンポーネント一式を使用。デフォルトのトークンは公式ドキュメントに基づいています。プレビューのフォント変更は、ローカルで明示的に指定しています。

### スペーシング単位

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| 0.5 / 05 | 4px | 半単位のスペーシングとユーティリティの書式 |
| 1 | 8px | 基本スペーシング単位 |
| 1.5 / 105 | 12px | 中間スペーシング |
| 2 | 16px | コンパクトな内側の余白 |
| 3 | 24px | 関連コンテンツ間の間隔 |
| 4 | 32px | セクション間の間隔 |
| 5 | 40px | 広めの間隔 |
| 6 | 48px | 大きな間隔 |
| tablet | 640px | 名前付き幅トークン |
| desktop | 1024px | 名前付き幅トークン |
### デフォルトの文字スタイル設定

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| sans | source-sans-pro | 文字種別に基づくファミリートークン |
| serif | merriweather | 文字種別に基づくファミリートークン |
| body / ui | sans | 役割に基づくマッピング |
| heading | serif | 役割に基づくマッピング |
| code | mono → roboto-mono | コードの役割マッピング |
### デフォルトのテーマカラー

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| primary | blue-60v / #005ea2 | プライマリエイリアス |
| primary-lighter | blue-10 / #d9e8f6 | プライマリの補助色 |
| primary-dark | blue-warm-70v / #1a4480 | 濃いプライマリエイリアス |
| ink | gray-90 / #1b1b1b | 本文テキストのエイリアス |
### コンポーネントの仕様

| 名前 / ルール | 値 / 設定 | 用途 |
| --- | --- | --- |
| aria-controls | Panel ID | 各アコーディオンボタンをコンテンツに関連付けます。 |
| aria-expanded | true / false | ネイティブJSが開閉状態を管理します。 |
| data-allow-multiple | Accordion root attribute | 複数のパネルを個別に開けるようにします。 |
| usa-accordion--bordered | Root modifier | 枠線付きのバリエーションを提供します。 |
## USWDSデザインシステム完全ガイド

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

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

## USWDSデザインシステム：設定可能なFoundation

### デフォルトのトークンは、設定の出発点です

> USWDSは、システムトークン、プロジェクトのテーマ設定、ユーティリティクラス、コンポーネントを分けて管理します。以下のリファレンスには、現行ドキュメントに記載されているデフォルトのテーマ設定をまとめています。連邦政府のプログラムでは、すべてのコンポーネントを置き換えることなく、異なる文字の役割やカラーエイリアスを設定できます。

このプレビューは、3.14.0 CSSとアコーディオンJavaScriptを使った、独自の研究機会比較です。政府バナーと識別マークは含まれていません。プログラム名と段階は架空のもので、絞り込みはすべてブラウザー内で行われます。

関連する仕様を確認する

## USWDSデザインシステム：スペーシングとテーマのトークン

### 数値ではなく単位を確認する

USWDSのスペーシング単位は1つで8pxです。units(2)は16px、units(3)は24pxを表します。スケールには小さな間隔用の半単位トークンもあり、ユーティリティでは半単位を05と表記します。margin-2ユーティリティは、2ピクセルのマージンを意味するものではありません。

スケールには、tabletやdesktopなど、名前付きの幅も含まれます。これらは再利用可能なトークンであり、幅ごとにすべてのページを再設計する必要があるという意味ではありません。この比較では、コンテンツの配置にgrid-containerを使い、表には専用のスクロール領域を設けています。

```
@use "uswds-core" as *;
.opportunity-meta {
  padding: units(2);
  margin-bottom: units(3);
}
```

コードリファレンス

関連する仕様を確認する

## USWDSデザインシステム：フォントの種類と役割

### コンポーネント名を変えずに役割を変更できます

デフォルトでは、sansトークンはSource Sans Proに、serifトークンはMerriweatherに対応します。bodyとUIの役割はsansに、headingの役割はserifに対応します。family("body")関数は、この対応関係をたどってフォントを解決します。プロジェクトのドキュメントでは、セマンティックな役割と最終的なフォントファミリーを区別してください。

このローカルプレビューでは、フォントのダウンロードが不要になるよう、本文にHelvetica/Arial、見出しにGeorgiaを明示的に使用しています。これは検討用の上書きであり、USWDSの標準的なタイポグラフィではありません。本番ビルドでは、uswds-coreの設定を通じてこれらの役割を指定するか、配布されているフォントアセットをコピーしてください。

```
@use "uswds-core" with (
  $theme-font-type-sans: "helvetica",
  $theme-font-type-serif: "georgia",
  $theme-font-role-body: "sans",
  $theme-font-role-heading: "serif"
);
```

コードリファレンス

関連する仕様を確認する

## USWDSデザインシステム：テーマカラーのエイリアス

### エイリアスを役割に対応させる

デフォルトのプライマリエイリアスはblue-60v（#005ea2）に対応します。primary-darkはblue-warm-70v（#1a4480）、inkはgray-90（#1b1b1b）に対応します。これらはテーマの値であり、すべてのUSWDSサイトが同じブランドカラーを使わなければならないという意味ではありません。

アクションや見出しのスタイルにはセマンティックエイリアスを使用し、システムカラーのトークンは、それが実際のデザイン上の選択である場合にのみ使用します。設定でプライマリエイリアスを置き換えるほうが、コンパイル済みのCSS内にある一致するすべての16進カラーコードを置き換えるよりも、制御しやすくなります。

関連する仕様を確認する

## USWDSデザインシステム：比較可能な機会の行

### 表のセマンティクスを維持する

この例では、キャプション、scope="col"を指定した列見出し、scope="row"を指定した機会名を使用しています。読者が複数のレコード間で同じトピックや段階の項目を比較するため、表として構成しています。領域をスクロールしても、こうした関連性は維持されます。

スクロール可能なラッパーにはtabindex="0"が設定されており、キーボードユーザーがフォーカスを移動できます。幅の広いデータをその領域内に収めるため、ドキュメント全体の幅が広がることはありません。プレビューには通常のテキストセルを使用しています。プログラムのデータが欠けている場合は、数値を作り出すのではなく、明示的なコンテンツ状態を用意する必要があります。

関連する仕様を確認する

### 並べ替えは別途追加する機能です

USWDSでは、data-sortableを使用して見出しの並べ替えに対応できます。並べ替え可能な表には、aria-live="polite"を指定したusa-table__announcement-regionも必要です。数値の表示形式によっては、整形済みの金額が文字列順ではなく数値として並べ替えられるよう、data-sort-valueが必要になる場合があります。今回の比較では、3行のトピックフィルターをデモすることが目的のため、並べ替えは有効にしていません。

関連する仕様を確認する

## USWDSデザインシステム：要件を開閉パネルで表示する

### ボタンとパネルのIDを関連付ける

各usa-accordion__buttonのaria-controlsは、対応するusa-accordion__contentを指します。ネイティブのJavaScriptがaria-expandedと表示状態を更新します。borderedモディファイアは囲みのスタイルを変更し、data-allow-multipleを指定すると複数のセクションを同時に開いたままにできます。

見出しにボタンを含めることで、コンテンツの構造を把握しやすくしています。プログラムが自分に該当するか判断するために必要な要件は、開閉パネルの外側に表示したままにしてください。ここでは、パネルに補足的な準備メモと、架空のデータセットについての説明を含めています。

- 見出しでパネルのトピックを示します。

- ボタンに展開状態と対象IDを設定します。

- 表示状態が変わっても、パネルのIDは維持します。

関連する仕様を確認する

## USWDSデザインシステム：アセットツリー全体をインストールする

### コンパイル済みのCSSが使用するパスを維持する

@uswds/uswds@3.14.0をインストールし、distディレクトリ内のcss、js、img、fontsをひとつのフォルダーにまとめず、そのままコピーします。スタイルシートでは、アイコンやフォントへの相対パスを使用しています。正しく表示されているように見えても、開閉パネルの記号や書体が読み込まれないことがあります。

head内でuswds-init.min.jsを読み込み、その次にスタイルシートを読み込みます。uswds.min.jsは、bodyのマークアップの後に読み込んでください。バンドルされたライブラリがアコーディオンを拡張します。下にある検索入力欄とトピックフィルターは、アプリケーション独自のロジックです。リモート検索サービスには接続しません。

関連する仕様を確認する

## USWDSデザインシステム：絞り込みと検索結果がない場合の操作

### 検索結果をユーザーに知らせる

ネイティブのlabel、input、select、buttonのスタイルで各コントロールを表示し、アプリケーション側で検索語と選択されたトピックを3件の架空のレコードと照合します。結果件数は、丁寧な通知を行うライブリージョンです。一致する結果がない場合は、入力された検索語を維持したまま、説明とリセット操作を表示します。

このデモでは、機会を探すことと申請することを意図的に区別しています。準備用コンテンツを開いても、下書きが作成されたり、要件が完了扱いになったりすることはありません。実際の助成金申請には、プログラム独自の方針、認証、永続的な取引状態が必要です。

1. 環境に絞り込み、該当する機会を確認してください。

2. 該当しない語句で検索し、「フィルターをクリア」を使用してください。

3. 準備用のパネルを両方開き、それぞれの展開状態が独立していることを確認してください。

関連する仕様を確認する

## USWDSデザインシステム：コンポーネントの使用例

### 補足的な準備用アコーディオン

ボタンとパネルの関連付けを明示した、ネイティブのUSWDS開閉パネルです。

```
<div class="usa-accordion usa-accordion--bordered" data-allow-multiple>
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button"
      aria-expanded="false" aria-controls="preparation">Before you prepare a draft</button>
  </h3>
  <div id="preparation" class="usa-accordion__content usa-prose" hidden>
    <p>This fictional opportunity asks for a project summary and a named contact.</p>
  </div>
</div>
```

コードリファレンス

### 機会を比較する表

キャプションと行・列の見出しによって、比較の関連性を維持します。

```
<div class="usa-table-container--scrollable" tabindex="0">
  <table class="usa-table usa-table--borderless">
    <caption>Illustrative research opportunities</caption>
    <thead><tr><th scope="col">Opportunity</th><th scope="col">Topic</th><th scope="col">Stage</th></tr></thead>
    <tbody><tr><th scope="row">Community water study</th><td>Environment</td><td>Example draft</td></tr></tbody>
  </table>
</div>
```

コードリファレンス

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

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

```
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Research opportunities — OpenDesign study</title><script src="vendor/uswds-3.14.0/uswds-init.min.js"></script><link rel="stylesheet" href="vendor/uswds-3.14.0/css/uswds.min.css"><style>body,body *,body *:before,body *:after{font-family:Helvetica,Arial,sans-serif!important}h1,h2{font-family:Georgia,serif!important}body{color:#1b1b1b;margin:0}[hidden]{display:none!important}.study-head{background:#d9e8f6;padding:16px 0;border-bottom:4px solid #005ea2}.study-head p{margin:0}.study-form{display:flex;gap:24px;align-items:end;flex-wrap:wrap}.study-form>div{flex:1;min-width:200px}.study-form .usa-input,.study-form .usa-select{max-width:none}.usa-table{width:100%}.study-main{padding-top:32px;padding-bottom:48px}.usa-table th{min-width:120px}#count{margin-top:24px}.study-note{border-top:1px solid #a9aeb1;margin-top:32px;padding-top:16px;line-height:1.5}</style></head><body><header class="study-head"><div class="grid-container"><p><strong>OpenDesign · USWDS component study</strong><br>Fictional research records. No application is submitted.</p></div></header><main class="grid-container study-main"><h1>Research opportunities</h1><p class="usa-intro">Compare topics and read the preparation notes.</p><form class="study-form" id="filters"><div><label class="usa-label" for="query">Search opportunity names</label><input class="usa-input" id="query" type="search"></div><div><label class="usa-label" for="topic">Topic</label><select class="usa-select" id="topic"><option value="">All topics</option><option>Environment</option><option>Transport</option><option>Education</option></select></div><button type="submit" class="usa-button">Apply filters</button><button type="button" class="usa-button usa-button--outline" id="clear">Clear filters</button></form><p id="count" aria-live="polite">3 opportunities</p><div class="usa-table-container--scrollable" tabindex="0"><table class="usa-table usa-table--borderless"><caption>Illustrative research opportunities</caption><thead><tr><th scope="col">Opportunity</th><th scope="col">Topic</th><th scope="col">Stage</th></tr></thead><tbody><tr data-topic="Environment"><th scope="row">Community water study</th><td>Environment</td><td>Example draft</td></tr><tr data-topic="Transport"><th scope="row">Accessible transport research</th><td>Transport</td><td>Example review</td></tr><tr data-topic="Education"><th scope="row">Local skills survey</th><td>Education</td><td>Example draft</td></tr></tbody></table></div><p id="empty" hidden>No matching opportunities. Broaden the topic or clear the filters.</p><h2>Preparation notes</h2><div class="usa-accordion usa-accordion--bordered" data-allow-multiple>
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button"
      aria-expanded="false" aria-controls="preparation">Before you prepare a draft</button>
  </h3>
  <div id="preparation" class="usa-accordion__content usa-prose" hidden>
    <p>This fictional opportunity asks for a project summary and a named contact.</p>
  </div>
<h3 class="usa-accordion__heading"><button type="button" class="usa-accordion__button" aria-expanded="false" aria-controls="scope">What the example data means</button></h3><div id="scope" class="usa-accordion__content usa-prose" hidden><p>Draft and review are demonstration stages. They do not indicate an actual funding programme or eligibility decision.</p></div>
</div><p class="study-note">USWDS 3.14.0 native accordion and styles, with local Helvetica/Georgia font overrides. Filters are original application code. <a href="vendor/uswds-3.14.0/LICENSE.md">Distribution licence</a>.</p></main><script src="vendor/uswds-3.14.0/uswds.min.js"></script><script>const rows=[...document.querySelectorAll('tbody tr')],q=document.getElementById('query'),t=document.getElementById('topic');function filter(){let n=0;for(const row of rows){const show=(!t.value||row.dataset.topic===t.value)&&row.firstElementChild.textContent.toLowerCase().includes(q.value.trim().toLowerCase());row.hidden=!show;if(show)n++}document.getElementById('count').textContent=n+' '+(n===1?'opportunity':'opportunities');document.getElementById('empty').hidden=n!==0;}document.getElementById('filters').addEventListener('submit',e=>{e.preventDefault();filter()});document.getElementById('clear').addEventListener('click',()=>{q.value='';t.value='';filter();q.focus()});</script></body></html>
```

コードリファレンス

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

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

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

### 実装の出発点

CSSがフォントやアイコンを解決できるよう、distディレクトリの構造を維持してください。これはコンパイル済み配布物を使う方法です。テーマをカスタマイズするには、Sassでのビルドが必要です。「ソース」にある完全な動作例のZIPには、プレビューに必要な正確な依存関係とドキュメント一式も含まれています。展開後、そのディレクトリでpython3 -m http.server 8080を実行し、http://localhost:8080/uswds.htmlを開いてください。モジュールを使用する例をfile://経由で開かないでください。

```
npm install @uswds/uswds@3.14.0
mkdir -p public/assets/uswds
cp -R node_modules/@uswds/uswds/dist public/assets/uswds/

<!-- HTML head -->
<script src="/assets/uswds/dist/js/uswds-init.min.js"></script>
<link rel="stylesheet" href="/assets/uswds/dist/css/uswds.min.css">
<!-- After the component markup, before closing body -->
<script src="/assets/uswds/dist/js/uswds.min.js"></script>
```

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

```
USWDS 3.14.0を使用して、架空の研究機会を比較する画面を作成してください。distのアセットツリー全体、初期化スクリプト、コンポーネントのスタイルシート、JavaScriptを読み込みます。比較可能なレコードは、キャプションと列見出しを備えたセマンティックな表で提示してください。ラベル付きの検索とカテゴリフィルター、結果件数、役立つ検索結果なしの状態、リセット操作を用意します。補足的な要件にはネイティブのアコーディオンを使用し、比較に不可欠な情報は常に表示しておきます。ドキュメントに記載された間隔の単位とテーマの役割のマッピングを維持し、システムフォントの上書きを明示してください。このディレクトリを申請ワークフローに変えたり、実際の応募資格や採択を約束したりしないでください。
```

## USWDSデザインシステム：ソースと対象範囲

USWDS 3.14.0の独立したコンポーネント検証です。機会のレコードは架空のものであり、連邦政府の公式な身元を示すものでも、申請エンドポイントを備えるものでもありません。Helvetica/ArialとGeorgiaはローカルで代用したフォントで、USWDSのデフォルトのフォントアセットではありません。

- スペーシング単位 数値の単位と名前付き幅。

- フォントファミリーの役割 書体と役割トークンの解決。

- テーマカラー デフォルトのエイリアスと設定。

- 表 セマンティックな比較とスクロール。

- アコーディオン パネルの状態とマークアップ。

- 開発者向けセットアップ 配布物とアセットのパス。

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

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

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

VAのセマンティックトークンとネイティブのProcess Listを活用して、わかりやすいサービス利用フローを構築しましょう。各ステップの説明を見やすくし、意味の伝わるステータスラベルを付け、補足情報を整理してメインの流れを読みやすく保ちます。

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

可変フォント、セマンティックなカラーの役割、折りたたみ可能なネイティブコンテンツを活用して、JavaScriptがなくても読みやすさを保つ、堅牢な閲覧インターフェースを構築します。

### Codex

Codexの実際のSearchInputの構造、操作の優先順位、読書に適したトークンを使用してください。ローカルの記事インデックスを検索し、検索結果を確認してから、同じ読書位置に戻ります。


- [実装リファレンス](https://designsystem.digital.gov/components/accordion/)
- [ソース](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [ソース](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [ソース](https://designsystem.digital.gov/design-tokens/color/theme-tokens/)
- [ソース](https://designsystem.digital.gov/components/accordion/)
- [関連する仕様を確認する](https://designsystem.digital.gov/documentation/developers/)
- [コードリファレンス](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [関連する仕様を確認する](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [コードリファレンス](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [関連する仕様を確認する](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [関連する仕様を確認する](https://designsystem.digital.gov/design-tokens/color/theme-tokens/)
- [関連する仕様を確認する](https://designsystem.digital.gov/components/table/)
- [関連する仕様を確認する](https://designsystem.digital.gov/components/accordion/)
- [コードリファレンス](https://designsystem.digital.gov/components/accordion/)
- [コードリファレンス](https://designsystem.digital.gov/components/table/)
- [スペーシング単位 数値の単位と名前付き幅。](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [フォントファミリーの役割 書体と役割トークンの解決。](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [テーマカラー デフォルトのエイリアスと設定。](https://designsystem.digital.gov/design-tokens/color/theme-tokens/)
- [表 セマンティックな比較とスクロール。](https://designsystem.digital.gov/components/table/)
- [アコーディオン パネルの状態とマークアップ。](https://designsystem.digital.gov/components/accordion/)
- [開発者向けセットアップ 配布物とアセットのパス。](https://designsystem.digital.gov/documentation/developers/)