01 Web Awesome デザインシステムのインターフェースプレビュー 角丸と間隔のスケールを変更し、サンプルの外観を切り替え、地域を選択して、ローカルのワークスペース名を検証します。
ネイティブのWeb Awesome 3.14.0カスタム要素とデフォルトテーマをローカルにバンドル。·
実装リファレンス 02
Web Awesome デザインシステムのデザインリファレンス インストール済みパッケージを確認したWeb Awesome 3.14.0のデフォルトテーマCSS。以下の色項目はセマンティックエイリアスです。推測した16進数値に置き換えず、参照先のパレットを保持しています。スケールから算出したピクセル値の例は、ルートサイズ16px、scale=1を前提としています。
名前 / ルール 値 / 設定 用途 --wa-color-surface-defaultwhiteメインのサンプル表面。 --wa-color-surface-raisedwhite浮き上がったレイヤー。 --wa-color-surface-loweredvar(--wa-color-neutral-95)コード表示用の表面。 --wa-color-surface-bordervar(--wa-color-neutral-90)コンテナの境界線。 --wa-color-text-normalvar(--wa-color-neutral-10)標準テキスト。 --wa-color-text-quietvar(--wa-color-neutral-40)セカンダリテキスト。 --wa-color-text-linkvar(--wa-color-brand-40)リンクの役割。 --wa-color-brand-fill-loudvar(--wa-color-brand-50)強いブランドカラーの背景。 --wa-color-brand-on-loudwhite強いブランドカラーの背景上のテキスト。 --wa-color-brand-fill-quietvar(--wa-color-brand-95)控えめなバッジの背景。 --wa-color-brand-on-quietvar(--wa-color-brand-40)控えめなブランドカラーの背景上のテキスト。
名前 / ルール 値 / 設定 用途 --wa-space-scale1間隔トークンに使用する倍率。 --wa-space-xscalc(var(--wa-space-scale) * 0.5rem)既定のスケールでは8px。 --wa-space-scalc(var(--wa-space-scale) * 0.75rem)既定のスケールでは12px。 --wa-space-mcalc(var(--wa-space-scale) * 1rem)既定のスケールでは16px。 --wa-space-lcalc(var(--wa-space-scale) * 1.5rem)既定のスケールでは24px。 --wa-space-xlcalc(var(--wa-space-scale) * 2rem)既定のスケールでは32px。 --wa-space-2xlcalc(var(--wa-space-scale) * 2.5rem)既定のスケールでは40px。 --wa-border-radius-scale1スケーラブルな角丸に使用する倍率。 --wa-border-radius-scalc(var(--wa-border-radius-scale) * 0.1875rem)既定のスケールでは3px。 --wa-border-radius-mcalc(var(--wa-border-radius-scale) * 0.375rem)既定のスケールでは6px。 --wa-border-radius-lcalc(var(--wa-border-radius-scale) * 0.75rem)既定のスケールでは12px。
名前 / ルール 値 / 設定 用途 --wa-font-family-bodyui-sans-serif, system-ui, sans-serif本文用のシステムサンセリフフォント。 --wa-font-family-headingvar(--wa-font-family-body)見出し用フォントファミリーのエイリアス。 --wa-font-family-codeui-monospace, monospace等幅の表示テキスト。 --wa-font-size-scale1文字サイズスケールの倍率。 --wa-font-size-mcalc(1rem * var(--wa-font-size-scale))ルートサイズとスケールが既定値の場合は16px。 --wa-font-size-lround(calc(var(--wa-font-size-m) * 1.125 * 1.125), 1px)ルートサイズとスケールが既定値の場合は20px。 --wa-font-size-xlround(calc(var(--wa-font-size-l) * 1.125 * 1.125), 1px)ルートサイズとスケールが既定値の場合は25px。 --wa-font-size-2xlround(calc(var(--wa-font-size-xl) * 1.125 * 1.125), 1px)ルートサイズとスケールが既定値の場合は32px。 --wa-line-height-condensed1.2幅を詰めたタイトル/ラベル。 --wa-line-height-normal1.6通常の本文用行高。
名前 / ルール 値 / 設定 用途 --wa-form-control-background-colorvar(--wa-color-surface-default)入力欄の表面のエイリアス。 --wa-form-control-border-colorvar(--wa-color-neutral-border-loud)入力欄の境界線の役割。 --wa-form-control-border-radiusvar(--wa-border-radius-m)フィールドの角丸エイリアス。 --wa-form-control-label-colorvar(--wa-color-text-normal)アクセシブルなラベルの色。 --wa-form-control-hint-colorvar(--wa-color-text-quiet)ヒントの色のエイリアス。
03 Web Awesome デザインシステム完全ガイド 実際のインターフェースで、このデザインシステムを選び、適用し、レビューするための実践ガイドです。
DESIGN-web-awesome.md 詳しいガイダンス、実装の出発点、ソースへのリンクをまとめています。
ガイドをダウンロード Web Awesome デザインシステム:独自のコンポーネント境界を持つカスタム要素 独自のコンポーネント境界を持つカスタム要素 Web Awesomeは、Reactアプリケーションを必要とせずに利用できる、登録済みのHTMLカスタム要素を提供します。wa-inputまたはwa-selectをインポートすれば、通常のHTMLに配置し、ドキュメント化されたプロパティやイベントを通じて制御できます。このワークベンチはバージョン3.14.0をバンドルし、公開パッケージで利用できるコンポーネントのみを使用しています。
表示されているコントロールは、シャドウルートの実装も含め、実際のカスタム要素です。周囲のヘッダー、セクション、表示領域は、独自に作成したHTMLです。これにより、継承されるカスタムプロパティを介してコンポーネント境界を越えるスタイル設定と、ページ構成に属する設定の違いを確認できます。
関連する仕様を確認する
Web Awesome デザインシステム:セマンティックカラーエイリアスを維持する セマンティックカラーエイリアスを維持する デフォルトのテーマでは、隆起・標準・低層の各背景面、通常テキストと控えめなテキスト、複数のブランド塗りつぶし色とオンカラーの組み合わせを使い分けています。トークンの表示には低層の背景面、メインのサンプルには標準の背景面を使用し、小さなバッジでは brand-fill-quiet と brand-on-quiet を組み合わせています。表示方法が変わっても、これらの役割は明確です。
参照例では、すべての役割を想定上の16進値に置き換えず、var(--wa-color-neutral-10) のようなエイリアスをそのまま使用しています。パレットを変更しても、セマンティックな割り当ては有効なままです。強調度の高いブランドアクションをカスタマイズする場合は、塗りつぶし色とそのオンカラーの両方を検討してください。片方だけを変更すると、ボタンのテキストが読みにくくなることがあります。
関連する仕様を確認する
Web Awesome デザインシステム コンポーネントを書き換えずにスケールを変更する コンポーネントを書き換えずにスケールを変更する 角丸のセレクターは、サンプル上の --wa-border-radius-scale のみを変更します。スケールが1の場合、ルートサイズが16ピクセルであれば、デフォルトの小・中・大の角丸はそれぞれ3、6、12ピクセルになります。スケールを0にすると、スケールに応じて変化する角が四角になり、2にすると2倍になります。ピル型と円形のトークンは別の概念であり、この倍率に従うとは限りません。
間隔のセレクターは --wa-space-scale を変更します。サンプルのパディング、間隔、表示欄のスペースには公式のスペーストークンが使われているため、それらの関係もまとめて変化します。ただし、すべてのコンポーネントのあらゆる寸法がスケールするわけではありません。コンポーネントのコントロールサイズには、独自のトークン関係があります。編集パネルは対象外なので、サンプルを変更しても比較条件は一定です。
Square を選択して、入力欄、コンテナー、表示欄の角を確認します。 Relaxed spacing を選択し、サンプルの間隔を、変更されない編集パネルと比べます。 Restore defaults を選択すると、両方の倍率と表示設定がまとめて初期状態に戻ります。 関連する仕様を確認する
Web Awesome デザインシステム タイポグラフィトークンと独自の見出し設定 タイポグラフィトークンと独自の見出しの選択 デフォルトの本文フォントファミリーは ui-sans-serif, system-ui, sans-serif です。見出しのフォントファミリーには本文のフォントファミリーのエイリアスが使われ、コードには ui-monospace が使われます。通常の行の高さのトークンは1.6、詰めた行の高さは1.2です。中サイズの文字トークンは、font-size-scale を乗じた1remで、大きなサイズは丸めた計算値を使います。表では依存関係を隠さず、これらの式を示しています。
このワークベンチでは、見出しに34px、セクション見出しに23pxを独自に設定しており、ローカルのブレークポイント700pxでページ見出しを小さくしています。これらは明示的に、このページ独自のルールです。ネイティブの入力欄にはライブラリ標準のラベルとヒントのスタイルを適用し、ページ独自の階層構造とデフォルトのコンポーネントタイポグラフィを比較できるようにしています。
関連する仕様を確認する
Web Awesome デザインシステム 初期値、プロパティ、変更イベント 初期値、プロパティ、変更イベント 各セレクトには、値が安定している wa-option の子要素が含まれています。初期選択には selected を指定し、現在のコンポーネントガイダンスに沿った設定にしています。実行時の変更では、セレクトの value プロパティを読み取ります。テーマコントロールは change イベントを監視し、CSS のカスタムプロパティを更新します。レンダリング後の option ラベルからテキストを解析することはありません。
リージョン選択は通常のサンプル入力欄であり、外部ストレージサービスを制御するものではありません。選択した値は、ローカルのアクションメッセージに表示されます。ヨーロッパを選ぶとストレージが割り当てられるかのような誤解を招かない設計です。実際の製品で使われるような用語を用いたコンポーネントのデモでは、この区別が重要です。
関連する仕様を確認する
Web Awesome デザインシステム トークンとドキュメントに記載されたパーツでスタイルを設定する トークンとドキュメント化されたパーツでスタイルを設定する 通常の子孫セレクターでは、コンポーネントのシャドウツリー内部に自由にアクセスできません。この例では、継承されるテーマ変数を使い、フィールドの背景、テキスト、角丸を周囲の HTML と連動させています。これはサポートされているスタイル設定用の仕組みであり、生成された内部マークアップを直接狙う方法ではありません。
コンポーネント固有の変更については、そのコンポーネントのドキュメントに記載された CSS のカスタムプロパティと CSS のパーツを確認してください。グローバルな input セレクターで wa-input 内部の input まで変更できるとは限りません。一方、共通の祖先にテーマクラスや変数を設定すれば、多数の子孫カスタム要素に意図的に影響を与えられます。そのため、適用範囲は慎重に選ぶ必要があります。
関連する仕様を確認する
Web Awesome デザインシステム アップグレード、検証、ローカルでの結果 アップグレード、検証、ローカルでの結果 ページから見ると、コンポーネントの登録は非同期で行われます。この例では、使用するAPIについて customElements.whenDefined を待ち、その後セレクトの更新を待ってから初期値を読み取ります。これにより、未知の HTML タグがコンポーネントクラスにアップグレードされる前に、デフォルト値を適用してしまうのを防げます。
ワークスペースのアクションでは、wa-input の setCustomValidity と reportValidity を使用します。前後の空白を取り除いた名前が2文字未満の場合は無効になり、input イベントが発生するとカスタムエラーを解除して、修正後に再試行できるようにします。「Invite later」ボタンは、ネイティブコンポーネントの無効状態です。ステータステキストに表示されるのはローカルで適用された名前だけで、コード全体にもワークスペースの作成や割り当てをリクエストする処理はありません。
label 属性でアクセシブルなラベルを指定します。 エラーが発生する前に、ヒントで名前の制約を説明します。 無効状態のアクションは目的を示したまま、操作できない状態を保ちます。 関連する仕様を確認する
Web Awesome デザインシステム テーマと使用するコンポーネントをインポートする テーマと使用するコンポーネントをインポートする Vite の vanilla アプリケーションに @awesome.me/[email protected] をインストールし、用意されている main.js をエントリーポイントとして使用します。デフォルトのテーマスタイルシートは必須です。この例では、ページレイアウトを明示的に定義している CSS ため、より広範なネイティブリセットやユーティリティバンドルは読み込みません。インポートによって、マークアップで使用する5種類のコンポーネントを登録します。
npm の dist モジュールはバンドラーでの使用を想定しています。ブラウザーで直接モジュールを読み込む場合は、依存関係のバンドル方法が異なる dist-cdn を使用してください。dist のインポートを通常の script タグにコピーして、bare dependency も解決されると想定しないでください。外部アセットが必要なコンポーネントには、ドキュメントに記載されたベースパスの設定が必要です。このサンプルでは、ユーザー提供のアイコンアセットを使わず、オフラインで動作するようにバンドルしています。
関連する仕様を確認する
Web Awesome デザインシステム 公開コンポーネントとテーマの適用範囲 公開コンポーネントとテーマの適用範囲を明確にする このワークベンチでは、デフォルトテーマと公開コンポーネントを紹介します。一部のWeb Awesomeコンポーネント、パターン、デザインリソースはPro向けのため、公開パッケージをインストールすればカタログ内のすべてを利用できると誤解させない構成になっています。共有デザインシステムで必須の依存関係にする前に、コンポーネントが利用可能か確認してください。
再利用可能なプロダクトテーマでは、変更する変数、その適用範囲、両方の表示モードでの確認方法を明記する必要があります。ライブワークベンチは、そのプロセスを小規模に示す例です。切り離されたパレット画像に頼るのではなく、変更した変数を正確に確認し、その結果をネイティブコンポーネントと比較できます。
関連する仕様を確認する
Web Awesomeデザインシステムのコンポーネント例 カスタム要素のワークベンチ用マークアップ wa-select、wa-option、wa-input、wa-switch、wa-buttonを、通常のセマンティックなHTMLと組み合わせます。
html コードをコピー
<main class="token-workbench"><header><p class="eyebrow">WEB AWESOME / TOKEN WORKBENCH</p><h1>See the theme cross the component boundary.</h1><p>Change a scoped token and inspect native custom elements alongside ordinary HTML.</p></header><div class="workbench-grid"><section class="controls"><h2>Theme controls</h2><wa-select id="radius" label="Corner scale"><wa-option value="0">Square / 0</wa-option><wa-option value="1" selected>Default / 1</wa-option><wa-option value="2">Rounder / 2</wa-option></wa-select><wa-select id="spacing" label="Spacing scale"><wa-option value="0.8">Compact / 0.8</wa-option><wa-option value="1" selected>Default / 1</wa-option><wa-option value="1.25">Relaxed / 1.25</wa-option></wa-select><wa-switch id="dark">Dark appearance</wa-switch><wa-button id="reset" appearance="outlined">Restore defaults</wa-button><p class="hint">These controls change only the specimen. The editing controls keep their original dimensions.</p></section><section id="specimen" class="specimen" aria-label="Theme specimen"><div class="sample-head"><span class="badge">COMPONENT PREVIEW</span><span class="hint">Free components</span></div><h2>Your next workspace</h2><p class="hint">Form labels, field borders and actions inherit semantic tokens through the shadow boundary.</p><wa-input id="workspace" label="Workspace name" hint="Use at least two characters." value="Field notes"></wa-input><wa-select id="region" label="Storage region"><wa-option value="europe" selected>Europe</wa-option><wa-option value="america">North America</wa-option><wa-option value="asia">Asia Pacific</wa-option></wa-select><div class="sample-actions"><wa-button id="create" variant="brand">Apply name locally</wa-button><wa-button disabled>Invite later</wa-button></div><p id="result" role="status">No workspace is created by this specimen.</p><div class="token-readout"><code id="values">--wa-border-radius-scale: 1;<br>--wa-space-scale: 1;</code></div></section></div><footer>Native Web Awesome 3.14.0. The surrounding workbench is original HTML/CSS.</footer></main>
コードリファレンス
初期選択にはwa-optionのselectedを使用します。 無料のコンポーネントのみを使用しています。 完全なインポートとトークンのコントロール コンポーネントを登録し、アップグレードを待ってから、スコープ付きカスタムプロパティを変更し、ローカルの入力検証を適用します。
JavaScript コードをコピー
import '@awesome.me/webawesome/dist/styles/themes/default.css';
import '@awesome.me/webawesome/dist/components/button/button.js';
import '@awesome.me/webawesome/dist/components/input/input.js';
import '@awesome.me/webawesome/dist/components/select/select.js';
import '@awesome.me/webawesome/dist/components/option/option.js';
import '@awesome.me/webawesome/dist/components/switch/switch.js';
import './style.css';
const $=id=>document.getElementById(id);function update(){const s=$('specimen');s.style.setProperty('--wa-border-radius-scale',$('radius').value);s.style.setProperty('--wa-space-scale',$('spacing').value);s.classList.toggle('wa-dark',$('dark').checked);s.classList.toggle('wa-light',!$('dark').checked);$('values').textContent=`--wa-border-radius-scale: ${$('radius').value};\n--wa-space-scale: ${$('spacing').value};`;}
Promise.all(['wa-select','wa-switch','wa-input','wa-button'].map(x=>customElements.whenDefined(x))).then(async()=>{await Promise.all([...document.querySelectorAll('wa-select')].map(e=>e.updateComplete));for(const id of ['radius','spacing','dark'])$(id).addEventListener('change',update);$('reset').addEventListener('click',()=>{$('radius').value='1';$('spacing').value='1';$('dark').checked=false;update()});$('create').addEventListener('click',()=>{const field=$('workspace');field.setCustomValidity(field.value.trim().length<2?'Use at least two non-space characters.':'');if(!field.reportValidity())return;$('result').textContent=`Applied “${field.value.trim()}” in the ${$('region').value} specimen. No workspace or storage allocation was created.`});$('workspace').addEventListener('input',()=>$('workspace').setCustomValidity(''));update()});
コードリファレンス
whenDefinedを使うと、アップグレード前のカスタム要素から値を読み取るのを防げます API。 コードでは、使用するコンポーネントのみをインポートします。 スコープ付きのサンプルCSS 通常のHTMLも、ネイティブカスタム要素と同じテーマ変数を継承して使用します。
CSS コードをコピー
*{box-sizing:border-box}body{margin:0;font-family:var(--wa-font-family-body);font-size:16px;line-height:var(--wa-line-height-normal);color:var(--wa-color-text-normal);background:#f5f6f8}.token-workbench{max-width:1100px;margin:auto;padding:32px}header{max-width:740px;margin-bottom:28px}h1{font-size:34px;line-height:1.15;letter-spacing:-.03em}h2{font-size:23px;line-height:1.25}.eyebrow{font-size:11px;letter-spacing:.12em;font-weight:700}.workbench-grid{display:grid;grid-template-columns:300px minmax(0,1fr);gap:24px}.controls{display:flex;flex-direction:column;gap:20px;padding:24px;background:white;border:1px solid #d9dde3;border-radius:12px}.controls h2{margin:0}.hint,footer{color:var(--wa-color-text-quiet);font-size:14px}.specimen{background:var(--wa-color-surface-default);color:var(--wa-color-text-normal);border:1px solid var(--wa-color-surface-border);border-radius:var(--wa-border-radius-l);padding:var(--wa-space-xl);display:flex;flex-direction:column;gap:var(--wa-space-l)}.specimen h2,.specimen p{margin:0}.sample-head,.sample-actions{display:flex;align-items:center;flex-wrap:wrap;gap:var(--wa-space-s)}.sample-head{justify-content:space-between}.badge{font-size:10px;letter-spacing:.09em;font-weight:700;background:var(--wa-color-brand-fill-quiet);color:var(--wa-color-brand-on-quiet);padding:4px 8px;border-radius:var(--wa-border-radius-s)}.token-readout{background:var(--wa-color-surface-lowered);padding:var(--wa-space-m);border-radius:var(--wa-border-radius-m);font:13px/1.7 var(--wa-font-family-code);white-space:pre-wrap;overflow-wrap:anywhere}#result{font-size:13px}footer{margin-top:20px}@media(max-width:700px){.token-workbench{padding:20px 16px}.workbench-grid{grid-template-columns:1fr}.controls{padding:20px}h1{font-size:28px}.specimen{padding:var(--wa-space-l)}}
コードリファレンス
ワークベンチの見出しとレイアウトのブレークポイントは、独自に設定したものです。 index.htmlの全体 付属のmain.jsとスタイルシートを使用するViteのルートドキュメントです。
html コードをコピー
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Web Awesome token workbench</title></head><body><main class="token-workbench"><header><p class="eyebrow">WEB AWESOME / TOKEN WORKBENCH</p><h1>See the theme cross the component boundary.</h1><p>Change a scoped token and inspect native custom elements alongside ordinary HTML.</p></header><div class="workbench-grid"><section class="controls"><h2>Theme controls</h2><wa-select id="radius" label="Corner scale"><wa-option value="0">Square / 0</wa-option><wa-option value="1" selected>Default / 1</wa-option><wa-option value="2">Rounder / 2</wa-option></wa-select><wa-select id="spacing" label="Spacing scale"><wa-option value="0.8">Compact / 0.8</wa-option><wa-option value="1" selected>Default / 1</wa-option><wa-option value="1.25">Relaxed / 1.25</wa-option></wa-select><wa-switch id="dark">Dark appearance</wa-switch><wa-button id="reset" appearance="outlined">Restore defaults</wa-button><p class="hint">These controls change only the specimen. The editing controls keep their original dimensions.</p></section><section id="specimen" class="specimen" aria-label="Theme specimen"><div class="sample-head"><span class="badge">COMPONENT PREVIEW</span><span class="hint">Free components</span></div><h2>Your next workspace</h2><p class="hint">Form labels, field borders and actions inherit semantic tokens through the shadow boundary.</p><wa-input id="workspace" label="Workspace name" hint="Use at least two characters." value="Field notes"></wa-input><wa-select id="region" label="Storage region"><wa-option value="europe" selected>Europe</wa-option><wa-option value="america">North America</wa-option><wa-option value="asia">Asia Pacific</wa-option></wa-select><div class="sample-actions"><wa-button id="create" variant="brand">Apply name locally</wa-button><wa-button disabled>Invite later</wa-button></div><p id="result" role="status">No workspace is created by this specimen.</p><div class="token-readout"><code id="values">--wa-border-radius-scale: 1;<br>--wa-space-scale: 1;</code></div></section></div><footer>Native Web Awesome 3.14.0. The surrounding workbench is original HTML/CSS.</footer></main>
<script type="module" src="/main.js"></script></body></html> コードリファレンス
Viteのvanillaプロジェクトを作成し、上記の完全なmain.jsとstyle.cssを使用してください。 04
Web AwesomeデザインシステムのAIエージェント設定 実装の出発点 完全なmain.js、CSS、bodyの例を使用すると、バンドラーでワークベンチを再現できます。オフラインデモは、テーマをCSSにインライン化したesbuildのバンドルです。Reactプロバイダーは必要ありません。
JavaScript サンプルをコピー
// Create a Vite vanilla project, then install:
// npm install @awesome.me/[email protected]
// index.html: paste the complete workbench markup in body,
// then add <script type="module" src="/main.js"></script>.
// main.js: use the complete imports and token-controls example above.
// style.css: use the complete scoped specimen CSS above.
// Minimum registration pattern used by this example:
import '@awesome.me/webawesome/dist/styles/themes/default.css';
import '@awesome.me/webawesome/dist/components/button/button.js';
import '@awesome.me/webawesome/dist/components/input/input.js';
import '@awesome.me/webawesome/dist/components/select/select.js';
import '@awesome.me/webawesome/dist/components/option/option.js';
import '@awesome.me/webawesome/dist/components/switch/switch.js';
// Do not duplicate these imports if using the complete main.js above. あなたのプロジェクト向けプロンプト AI エージェント用プロンプト プロンプトをコピー
Web Awesome 3.14.0のスコープ付きトークンワークベンチを使用し、付属のwa-select、wa-option、wa-input、wa-button、wa-switch要素を登録してください。初期選択値を読み取る前に、コンポーネントの定義とupdateCompleteを待ちます。--wa-border-radius-scaleと--wa-space-scaleはサンプル領域にのみ適用し、無関係なページコンテンツを変更せずに、領域のwa-light/wa-darkクラスを切り替えてください。表示されるトークン値はネイティブコントロールと同期し、ラベルを維持してください。このワークベンチは確認用のツールであり、デバイス管理インターフェースではありません。 05
Web Awesomeデザインシステムのソースと適用範囲 Web Awesome 3.14.0の公開コンポーネントとデフォルトテーマです。レイアウトは独自に設定しています。ローカルでの名前の入力によって、ワークスペースやストレージが作成されることはありません。