01 Semi Design デザインシステムのインターフェースプレビュー 名前を検証し、ダイジェストの設定を選択して、前のステップに戻り、最終的なローカル設定を確認できます。
Semi のテーマスケールと Steps/Input/Switch の動作をオフラインで HTML 解釈したものです。ネイティブな React の例は別途掲載しています。 ·
実装リファレンス 02
Semi Design デザインシステムのデザインリファレンス Semi の公式ドキュメントとデフォルトテーマの SCSS スナップショット。$ で始まる名前はコンパイル時の Sass 定数、--semi-* で始まる名前は実行時の CSS 変数です。アプリケーションのワークフローデータは独自のものです。
名前 / ルール 値 / 設定 用途 $height-control-small / default / large24 / 32 / 40px公開されているコントロールの高さ。 $spacing-super-tight2px最も狭い間隔。 $spacing-extra-tight4pxかなり狭い間隔。 $spacing-tight8px狭い間隔。 $spacing-base-tight12pxコンパクトなグループ間隔。 $spacing-base16px標準の間隔。 $spacing-base-loose20pxゆとりのあるグループ間隔。 $spacing-loose24pxセクション間隔。 $spacing-extra-loose32px広い間隔。 $spacing-super-loose40pxこのセットで最大の名前付き間隔。
名前 / ルール 値 / 設定 用途 font-size-small mixin12 / 16pxサイズは variables.scss、行の高さは mixin に基づきます。 font-size-regular mixin14 / 20px本文テキスト。 font-size-header-6 mixin16 / 22px小見出し。 font-size-header-4 mixin20 / 28pxセクション見出し。 font-size-header-3 mixin24 / 32pxページ見出しの選択肢。 font-size-header-1 mixin32 / 44px名前付き見出しの最大サイズ。
名前 / ルール 値 / 設定 用途 --semi-color-primaryrgba(var(--semi-blue-5),1)ライトパレットは rgb(0,100,250) に解決されます。 --semi-color-primary-hoverrgba(var(--semi-blue-6),1)ライトパレットは rgb(0,98,214) に解決されます。 --semi-color-text-0rgba(var(--semi-grey-9),1)ライトテーマのプライマリテキストは rgb(28,31,35) に解決されます。 --semi-color-text-2Grey 9 at .62 opacity in light modeセカンダリテキスト。ダークテーマでは不透明度が異なります。 --semi-color-fill-0Grey 8 at .05 opacity in light mode控えめな塗りつぶし色は、背景レイヤーに応じて変わります。 --semi-border-radius-small3px一般的なコントロール。 --semi-border-radius-medium6pxメニューなどの背景レイヤー。 --semi-border-radius-large12px大きなコンテナ向けのロール。 --semi-border-radius-full9999pxピル型のスタイル。
名前 / ルール 値 / 設定 用途 type="basic"Recommended simple step bar以前のデフォルトスタイルは、ドキュメントで非推奨とされています。 currentZero-based number0 から始まります。 statuswait / process / finish / error / warning現在のステップの状態。 type="nav"Non-interactive navigation appearanceクリック可能なウィザードの代わりにはなりません。 onChange(index)Index includes initial offsetナビゲーションを許可するかどうかは、アプリケーション側で決定します。
名前 / ルール 値 / 設定 用途 Input onChange(value,event)第 1 引数は新しい値です。 Input validateStatusdefault / error / warning見た目のスタイル設定のみで、業務データの検証は行いません。 Input compositionBoolean, false by default有効にすると、IME の確定まで onChange の呼び出しを遅らせます。 Input aria-describedbyDescription IDヘルプテキストとエラーテキストを関連付けます。
名前 / ルール 値 / 設定 用途 Switch checkedControlled Boolean設定値は親の state で管理します。 Switch onChange(checked,event)Boolean 値をそのまま使用します。 Switch aria-labelMeaningful state label見た目の切り替えではなく、設定内容を説明します。 Switch size="small"No checkedText / uncheckedText treatment長いラベルはスイッチの外側に配置します。
03 Semi Design デザインシステム完全ガイド 実際のインターフェースで、このデザインシステムを選び、適用し、レビューするための実践ガイドです。
DESIGN-semi-design.md 詳しいガイダンス、実装の出発点、ソースへのリンクをまとめています。
ガイドをダウンロード Semi Design デザインシステム：実際の React メジャーバージョンに対応するパッケージを選択 サフィックスによって連携方法が変わります Semi の最新の Quick Start では、React 19 用のパッケージと、それ以前の React バージョンで使用するパッケージが分けられています。この例では、React 18 と @douyinfe/semi-ui を明示的に選択しています。React 19 に切り替える場合は、ドキュメントに記載された @douyinfe/semi-ui-19 の import と依存パッケージの選択が必要です。
対応するバンドラーでは、関連する CSS をコンポーネント JavaScript から読み込みます。カスタムプレフィックス、テーマのコンパイル、CSS レイヤーなど、コンパイル時の変更には別途ツール上の考慮事項があります。基本的な import の例を、あらゆるテーマのカスタマイズが設定なしで機能するという主張にすり替えないでください。
関連する仕様を確認する
Semi Design デザインシステム：名前付き Sass スケールで密度を具体化 公開されている 24、32、40px のコントロールの高さを使用する Semi のコントロールの高さを表す定数は、24、32、40px の3つです。間隔の名前付きスケールは2〜40pxをカバーし、値は一定の間隔では増加しません。ウィザード内の標準フィールドには、ヘルプテキストとの間隔に12px、次のセクションとの間隔に24pxを使用でき、新たな間隔の体系を導入する必要はありません。
これらの値は Sass 定数であり、自動的に実行時変数になるわけではありません。サンプルでは、独自のページ CSS 内で解決後の寸法を使用しています。実行時にレイアウトのテーマを変更する場合と、スタイルシートを再ビルドする場合とでは、この違いが重要です。
関連する仕様を確認する
Semi Design デザインシステム：実際のサイズと行の高さの組み合わせを使用する 本文と見出しでは、行のリズムが異なります regular mixin は14pxのテキストと行の高さ20pxを、small mixin は12pxと16pxを組み合わせます。Header 3 は24/32、Header 1 は32/44です。短いウィザードのタイトルには前者を使い、後者はより強いページ階層を示す見出しに取っておけます。
標準のフォントファミリーは Inter から始まり、プラットフォーム用フォント、CJK フォールバックの順に続きます。オフラインプレビューでは利用可能なシステムフォントを使用しており、特定のフォントをダウンロードしたとは謳っていません。狭いビューポートでステップバーが折り返されても意味が伝わるよう、ステップ名は簡潔にしてください。
関連する仕様を確認する
Semi Design デザインシステム：テーマロールとパレットのチャンネルは別のもの アプリケーションの CSS では、解決後のロールを使用する プライマリロールは、パレットチャンネルの変数を rgba で包んでいます。一般的な色指定には --semi-color-primary を使用できますが、--semi-blue-5 のようなチャンネルリストだけでは、有効な CSS カラーになりません。ライトテーマとダークテーマでは、これらのチャンネル値が変わります。
テキストロールにも不透明度が使われます。セカンダリテキストは、任意の薄い16進カラーで代用できるものではありません。また、重要なヘルプテキストに無効状態のテキスト色を使わないでください。設定の準備だけでは実際のアカウントは作成されないため、ウィザードでは完了メッセージに中立的な表現を使っています。
関連する仕様を確認する
Semi Design デザインシステム：Basic Steps は進捗を伝えるものであり、検証を省略する許可ではありません 遷移のルールはアプリケーション側で管理します シンプルなステップバーには type="basic" を使うことを Semi は推奨しています。current は0から始まり、現在のステップには process、error、またはその他の対応するステータスを設定できます。以前のデフォルトの外観は、ドキュメントで非推奨とされています。
このサンプルでは、［続ける］と［戻る］の操作で意図的に手順を進めます。すべてのステップのクリックを setCurrent に結び付けてはいません。そうすると、ユーザーが名前を空欄のまま［確認］に進めてしまうためです。別途説明されているナビゲーションの見た目は操作できず、ウィザードのルーティングと混同しないでください。
最初のステップを離れる前に名前を検証します。 前のステップに戻っても、選択した週次ダイジェストの Boolean 値を保持します。 ［確認］に設定内容をすべて表示します。 アカウントやサブスクリプションが作成されたと誤解させることなく、ローカルの設定を準備します。 関連する仕様を確認する
Semi Design デザインシステムのスイッチと並べても設定内容が分かるようにする 状態は親コンポーネントで保持する Switch は checked と、最初の引数に Boolean 値を取る onChange コールバックを使います。ラベルには「週次ダイジェスト」のように設定項目を示し、周囲のテキストでその設定の意味を説明します。checked と unchecked の長い文言は小さなコントロールの外側に配置してください。小型スイッチでは、内側にテキストを表示する形式はサポートされていません。
設定項目が分かる、明確なアクセシブルネームを設定します。 ウィザードのステップを移動しても設定値を保持します。 確認ページでは最終値を通常のテキストで表示します。 関連する仕様を確認する
Semi Design デザインシステムでは Button の type と theme は異なる役割を担います セマンティックな役割と視覚的なスタイル Semi Button の type は primary や danger などの役割を選びます。theme は light、solid、borderless、outline などの視覚的なスタイルを選びます。このサンプルでは、solid の primary アクションを［続ける］に、控えめなスタイルを［戻る］に使っています。ボタンを目立たせるために danger を誤用することはありません。
オフラインのサンプルでは、ステップが変わると新しいセクションの見出しにフォーカスを移し、検証に失敗すると無効なフィールドにフォーカスを戻します。モバイルレイアウトとキーボード操作の順序は、ソースを確認済みのネイティブな React の例とは別にテストされています。
関連する仕様を確認する
Semi Design デザインシステムのコンポーネント例 完全なスタンドアロンのインタラクティブ見本 ドキュメント全体を index.html として保存し、ブラウザーで開いてください。Semi の theme のスケールと Steps/Input/Switch の動作をオフラインで HTML として解釈した例です。ネイティブな React の例は別途用意されています。
html コードをコピー
<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Semi workspace setup interpretation</title><style>
*{box-sizing:border-box}body{margin:0;background:#f5f6f8;color:#1c1f23;font:14px/20px Inter,system-ui,sans-serif}button,input{font:inherit}button{cursor:pointer;min-height:32px;border:0;border-radius:3px;padding:6px 16px;background:rgba(46,50,56,.05);color:inherit}button.primary{background:#0064fa;color:white}button.primary:hover{background:#0062d6}button:focus-visible,input:focus-visible{outline:2px solid #0064fa;outline-offset:3px}header{padding:20px 32px;border-bottom:1px solid rgba(28,31,35,.08);background:white;display:flex;justify-content:space-between;gap:16px}header strong{font-size:16px}header span,.muted{color:#63656a}main{max-width:950px;margin:32px auto;padding:0 24px}h1{font-size:24px;line-height:32px;font-weight:600;margin:0 0 8px}h2{font-size:20px;line-height:28px;font-weight:600;margin:0 0 12px}p{margin:0 0 16px}.card{background:white;border:1px solid rgba(28,31,35,.08);border-radius:12px;overflow:hidden;margin-top:24px}.steps{padding:24px;display:flex;list-style:none;margin:0;border-bottom:1px solid rgba(28,31,35,.08);gap:12px}.steps li{flex:1;display:flex;align-items:center;gap:8px;color:#63656a;font-size:12px}.steps b{height:24px;width:24px;border-radius:50%;display:grid;place-items:center;background:#eee;flex-shrink:0}.steps [aria-current]{color:#0064fa}.steps [aria-current] b{background:#0064fa;color:white}.steps .done b{background:#eaf5ff;color:#0064fa}.workspace{display:grid;grid-template-columns:1fr 240px;min-height:300px}.panel{padding:32px}.illustration{background:#eaf5ff;display:flex;flex-direction:column;justify-content:center;padding:24px;gap:12px}.mini{background:white;box-shadow:0 6px 20px #0064fa12;border-radius:6px;padding:16px;transform:rotate(-3deg)}.mini i{display:block;height:8px;background:#eaf5ff;width:80%;margin:8px 0;border-radius:3px}.mini i:first-child{background:#0064fa;width:36%}.mini i:nth-child(3){width:55%}.mini:last-child{transform:rotate(4deg);margin-left:20px}.mini span{font-size:12px;color:#63656a}.form-label{display:block;font-weight:600;margin:20px 0 8px}input[type=text]{height:32px;background:rgba(46,50,56,.05);border:1px solid transparent;border-radius:3px;padding:5px 12px;width:100%}input[aria-invalid=true]{border-color:#d52515}.error{color:#b21b13;min-height:20px;font-size:12px;margin:8px 0}.preference{border:1px solid #eee;border-radius:6px;padding:16px;display:flex;align-items:center;justify-content:space-between;gap:20px}.preference p{margin:4px 0 0;font-size:12px}.toggle{appearance:none;width:40px;height:24px;border-radius:999px;background:#bbb;position:relative;cursor:pointer;flex-shrink:0}.toggle:checked{background:#0064fa}.toggle:before{content:'';position:absolute;left:3px;top:3px;background:white;border-radius:50%;width:18px;height:18px}.toggle:checked:before{left:19px}footer{display:flex;justify-content:space-between;padding:20px 32px;border-top:1px solid rgba(28,31,35,.08)}dl{margin:20px 0}dt{color:#63656a;font-size:12px}dd{margin:4px 0 20px;font-size:16px;font-weight:600;overflow-wrap:anywhere}#result{margin-top:16px;border-radius:6px;background:#eaf5ff;padding:16px}#result:empty{display:none}.boundary{font-size:12px;margin-top:20px;color:#63656a}h2:focus{outline:none}@media(max-width:600px){header{padding:16px}header span{display:none}main{margin:24px auto;padding:0 16px}.workspace{grid-template-columns:1fr}.illustration{display:none}.steps{padding:16px;gap:8px}.steps li{flex-direction:column;align-items:flex-start;gap:4px}.panel{padding:24px 20px}footer{padding:16px 20px;gap:12px}footer button{padding:6px 12px}}
</style><header><strong>◒ Workspace</strong><span>Configuration studio</span></header><main><h1>Make room for your team</h1><p class="muted">Three steps to prepare a workspace configuration.</p><div class="card"><ol class="steps" aria-label="Setup progress"><li><b>1</b>Name workspace</li><li><b>2</b>Choose updates</li><li><b>3</b>Review settings</li></ol><div class="workspace"><section class="panel" id="panel"></section><aside class="illustration" aria-hidden="true"><div class="mini"><i></i><i></i><i></i><span>A place for shared ideas</span></div><div class="mini"><i></i><i></i><i></i><span>Updates on your terms</span></div></aside></div><footer><button id="previous">Previous</button><button class="primary" id="next">Continue</button></footer></div><div id="result" role="status"></div><p class="boundary">Independent HTML interpretation of Semi’s theme and components. This example stores a draft only in memory; it does not create an account.</p></main><script>
let step=0,name='',digest=true;const panel=document.querySelector('#panel'),next=document.querySelector('#next'),previous=document.querySelector('#previous'),result=document.querySelector('#result');function render(focus=false){document.querySelectorAll('.steps li').forEach((el,i)=>{el.className=i<step?'done':'';el.removeAttribute('aria-current');if(i===step)el.setAttribute('aria-current','step')});previous.style.visibility=step?'visible':'hidden';next.textContent=step===2?'Prepare configuration':'Continue';if(step===0){panel.innerHTML='<h2 tabindex="-1">Name your workspace</h2><p class="muted">Choose a name your team will recognize.</p><label class="form-label" for="name">Workspace name</label><input id="name" type="text" placeholder="e.g. Studio North" autocomplete="organization" aria-describedby="help error"><p id="error" class="error" role="alert"></p><p id="help" class="muted">You can revisit this step before preparing the configuration.</p>';let input=document.querySelector('#name');input.value=name;input.oninput=()=>{name=input.value;input.removeAttribute('aria-invalid');document.querySelector('#error').textContent='';result.textContent=''};input.onkeydown=e=>{if(e.key==='Enter')next.click()}}else if(step===1){panel.innerHTML='<h2 tabindex="-1">Choose your updates</h2><p class="muted">Keep the weekly digest in your configuration, or switch it off.</p><label class="preference"><span><strong>Weekly digest</strong><p class="muted">A weekly summary of workspace activity.</p></span><input class="toggle" type="checkbox" role="switch" aria-label="Weekly digest" id="digest"></label>';let input=document.querySelector('#digest');input.checked=digest;input.onchange=()=>{digest=input.checked;result.textContent=''}}else{panel.innerHTML='<h2 tabindex="-1">Review settings</h2><p class="muted">Check the draft before preparing it.</p><dl><dt>Workspace name</dt><dd id="review-name"></dd><dt>Weekly digest</dt><dd id="review-digest"></dd></dl>';document.querySelector('#review-name').textContent=name.trim();document.querySelector('#review-digest').textContent=digest?'Enabled':'Disabled'}if(focus)panel.querySelector('h2').focus()}
next.onclick=()=>{if(step===0&&!name.trim()){document.querySelector('#error').textContent='Enter a workspace name.';let input=document.querySelector('#name');input.setAttribute('aria-invalid','true');input.focus();return}if(step<2){step++;render(true)}else result.textContent='Configuration prepared locally: '+name.trim()+' · Weekly digest '+(digest?'enabled':'disabled')+'. No account created.'};previous.onclick=()=>{step=Math.max(0,step-1);result.textContent='';render(true)};render();
</script></html>
コードリファレンス
［続ける］を押すと、次に進む前にワークスペース名を検証します。このドキュメントでは steps を解釈しています。React 18 と 19 のパッケージ境界については、別の React の項目で説明しています。 検証機能付きの3ステップ設定ウィザード Basic Steps で現在の進行状況を管理し、Input と Switch でページ間の設定値を保持します。［続ける］を押すと名前を検証し、最後の操作ではローカル設定のみを準備します。
jsx コードをコピー
// React 18 example. React 19 uses @douyinfe/semi-ui-19 instead.
// npm install react@18 react-dom@18 @douyinfe/semi-ui
import React,{useState} from 'react';
import {createRoot} from 'react-dom/client';
import {Steps,Input,Switch,Button} from '@douyinfe/semi-ui';
function WorkspaceSetup(){
const [current,setCurrent]=useState(0),[name,setName]=useState('');
const [digest,setDigest]=useState(true),[error,setError]=useState('');
const [prepared,setPrepared]=useState(false);
function next(){
if(current===0&&!name.trim()){setError('Enter a workspace name.');return;}
setError('');setCurrent(n=>Math.min(2,n+1));
}
return <main style={{maxWidth:760,margin:'auto',padding:24,color:'var(--semi-color-text-0)'}}>
<h1>Workspace setup</h1>
<Steps type="basic" current={current} status={error?'error':'process'}>
<Steps.Step title="Name workspace"/>
<Steps.Step title="Choose updates"/>
<Steps.Step title="Review settings"/>
</Steps>
<section style={{padding:'24px 0'}}>
{current===0&&<><label htmlFor="workspace-name">Workspace name</label>
<Input id="workspace-name" value={name} onChange={setName}
validateStatus={error?'error':'default'} aria-invalid={!!error} aria-describedby="error" />
<p id="error" role="alert">{error}</p></>}
{current===1&&<><h2>Weekly digest</h2><p>Include a weekly activity summary in the local configuration.</p>
<Switch checked={digest} onChange={setDigest} aria-label="Weekly digest"/></>}
{current===2&&<><h2>Review your draft</h2><dl><dt>Workspace</dt><dd>{name}</dd>
<dt>Weekly digest</dt><dd>{digest?'Enabled':'Disabled'}</dd></dl>
<p>No workspace or notification subscription is created.</p></>}
</section>
{current>0&&<Button onClick={()=>{setCurrent(n=>n-1);setPrepared(false);}}>Previous</Button>}
{current<2 ? <Button theme="solid" type="primary" onClick={next}>Continue</Button> :
<Button theme="solid" type="primary" onClick={()=>setPrepared(true)}>Prepare configuration</Button>}
<p role="status">{prepared?'Configuration prepared locally. No account created.':''}</p>
</main>;
}
createRoot(document.getElementById('root')).render(<WorkspaceSetup />); コードリファレンス
React 18 の例では @douyinfe/semi-ui を意図的にインストールします。React 19 では、Quick Start に記載されている -19 パッケージが必要です。 サポート対象のバンドラーでは、Semi のコンポーネント JavaScript が関連する CSS をインポートします。標準のセットアップで、根拠のないグローバルスタイルシートの読み込み手順は必要ありません。 埋め込みの HTML サンプルでは、フォーカス移動を明示的に指定しています。製品でネイティブコンポーネントを使う場合も、この動作を再現してください。 04
Semi Design デザインシステムのエージェント設定 実装の出発点 依存関係の分岐から1つ選んでください。この例では React 18 を使います。現在の Quick Start では、Vite/Webpack/Rspack でコンポーネント JavaScript が関連する CSS をインポートすると説明されています。テーマのコンパイルには、追加のツール要件があります。
bash サンプルをコピー
npm install react@18 react-dom@18 @douyinfe/semi-ui
# For a React 19 application instead:
# npm install react@19 react-dom@19 @douyinfe/semi-ui-19 あなたのプロジェクト向けプロンプト AI エージェント用プロンプト プロンプトをコピー
Semi の Basic Steps と、制御された Input および Switch を使います。インストールした React のメジャーバージョンに合った React パッケージを選んでください。次に進む前に検証し、［戻る］を押してもデータを保持します。架空のアカウント作成完了を示すことなく、最後にローカル設定を提示します。 05
Semi Design デザインシステムの参照元と対象範囲 独立した OpenDesign の参照例。元のワークスペースサンプルであり、アカウントや通知サブスクリプションは作成されません。
