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は、システムトークン、プロジェクトのテーマ設定、ユーティリティクラス、コンポーネントを分けて管理します。以下のリファレンスには、現行ドキュメントに記載されているデフォルトのテーマ設定をまとめています。連邦政府のプログラムでは、すべてのコンポーネントを置き換えることなく、異なる文字の役割やカラーエイリアスを設定できます。
このプレビューは、3.14.0 CSSとアコーディオンJavaScriptを使った、独自の研究機会比較です。政府バナーと識別マークは含まれていません。プログラム名と段階は架空のもので、絞り込みはすべてブラウザー内で行われます。
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);
}デフォルトでは、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" );
デフォルトのプライマリエイリアスはblue-60v（#005ea2）に対応します。primary-darkはblue-warm-70v（#1a4480）、inkはgray-90（#1b1b1b）に対応します。これらはテーマの値であり、すべてのUSWDSサイトが同じブランドカラーを使わなければならないという意味ではありません。
アクションや見出しのスタイルにはセマンティックエイリアスを使用し、システムカラーのトークンは、それが実際のデザイン上の選択である場合にのみ使用します。設定でプライマリエイリアスを置き換えるほうが、コンパイル済みのCSS内にある一致するすべての16進カラーコードを置き換えるよりも、制御しやすくなります。
この例では、キャプション、scope="col"を指定した列見出し、scope="row"を指定した機会名を使用しています。読者が複数のレコード間で同じトピックや段階の項目を比較するため、表として構成しています。領域をスクロールしても、こうした関連性は維持されます。
スクロール可能なラッパーにはtabindex="0"が設定されており、キーボードユーザーがフォーカスを移動できます。幅の広いデータをその領域内に収めるため、ドキュメント全体の幅が広がることはありません。プレビューには通常のテキストセルを使用しています。プログラムのデータが欠けている場合は、数値を作り出すのではなく、明示的なコンテンツ状態を用意する必要があります。
USWDSでは、data-sortableを使用して見出しの並べ替えに対応できます。並べ替え可能な表には、aria-live="polite"を指定したusa-table__announcement-regionも必要です。数値の表示形式によっては、整形済みの金額が文字列順ではなく数値として並べ替えられるよう、data-sort-valueが必要になる場合があります。今回の比較では、3行のトピックフィルターをデモすることが目的のため、並べ替えは有効にしていません。
各usa-accordion__buttonのaria-controlsは、対応するusa-accordion__contentを指します。ネイティブのJavaScriptがaria-expandedと表示状態を更新します。borderedモディファイアは囲みのスタイルを変更し、data-allow-multipleを指定すると複数のセクションを同時に開いたままにできます。
見出しにボタンを含めることで、コンテンツの構造を把握しやすくしています。プログラムが自分に該当するか判断するために必要な要件は、開閉パネルの外側に表示したままにしてください。ここでは、パネルに補足的な準備メモと、架空のデータセットについての説明を含めています。
@uswds/[email protected]をインストールし、distディレクトリ内のcss、js、img、fontsをひとつのフォルダーにまとめず、そのままコピーします。スタイルシートでは、アイコンやフォントへの相対パスを使用しています。正しく表示されているように見えても、開閉パネルの記号や書体が読み込まれないことがあります。
head内でuswds-init.min.jsを読み込み、その次にスタイルシートを読み込みます。uswds.min.jsは、bodyのマークアップの後に読み込んでください。バンドルされたライブラリがアコーディオンを拡張します。下にある検索入力欄とトピックフィルターは、アプリケーション独自のロジックです。リモート検索サービスには接続しません。
ネイティブのlabel、input、select、buttonのスタイルで各コントロールを表示し、アプリケーション側で検索語と選択されたトピックを3件の架空のレコードと照合します。結果件数は、丁寧な通知を行うライブリージョンです。一致する結果がない場合は、入力された検索語を維持したまま、説明とリセット操作を表示します。
このデモでは、機会を探すことと申請することを意図的に区別しています。準備用コンテンツを開いても、下書きが作成されたり、要件が完了扱いになったりすることはありません。実際の助成金申請には、プログラム独自の方針、認証、永続的な取引状態が必要です。
ボタンとパネルの関連付けを明示した、ネイティブの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>CSSがフォントやアイコンを解決できるよう、distディレクトリの構造を維持してください。これはコンパイル済み配布物を使う方法です。テーマをカスタマイズするには、Sassでのビルドが必要です。「ソース」にある完全な動作例のZIPには、プレビューに必要な正確な依存関係とドキュメント一式も含まれています。展開後、そのディレクトリでpython3 -m http.server 8080を実行し、http://localhost:8080/uswds.htmlを開いてください。モジュールを使用する例をfile://経由で開かないでください。
npm install @uswds/[email protected] 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 3.14.0の独立したコンポーネント検証です。機会のレコードは架空のものであり、連邦政府の公式な身元を示すものでも、申請エンドポイントを備えるものでもありません。Helvetica/ArialとGeorgiaはローカルで代用したフォントで、USWDSのデフォルトのフォントアセットではありません。
