ui-craft は何をしますか?
どのプラットフォームでも、プレミアムで使いやすいインターフェースを構築する方法。 数値はCSSのpxで表記します。ネイティブアプリの場合は、pxをpt(iOS、macOS)、dp(Android)、またはepx(Windows)として読み替えてください。
プレミアムとは4つのことを意味します。 適切:対象ユーザー、その心理状態、プラットフォームに合っていること。決定:小さなシステム(少数のサイズ、1つの角丸ファミリー、1つのアクセントカラー)が全体に適用されていること。精巧:細部まで仕上げられていること。誠実:信頼を得て、決してユーザーを騙さないこと。正しいだけの画面は凡庸に見え、装飾だけの画面は安っぽく見えます。
1. ワークフロー(毎回これを行う)
- 構築する前に見る。 既存のデザインシステム(トークン、テーマファイル、Tailwind設定、コンポーネントライブラリ、ブランドカラー、フォント、またはui-craft Studioからエクスポートされた
DESIGN.mdの概要とtheme.css)を確認します。存在する場合はそれを使用し、新たに作成しないでください。 不足部分のみを補います。 - ユーザーを理解する。 誰が、どのような心理状態(忙しい、不安、懐疑的、フロー状態のエキスパート)でこれを使用し、どう感じるべきかを一文で記述します。
references/psychology-emotion.mdを参照。 - 方向性を選択する。 アイデンティティが決まっていない場合は、
references/directions.mdから対象ユーザーに合った1つのビジュアルディレクションを選び(新奇性のためではなく)、assets/directions/内の該当ファイルのヘッダーを読み、そのシグネチャを把握します。ブランドカラーが決まっている場合は、方向性を維持しつつ色を再構築します:node <skill-dir>/scripts/palette.mjs --accent "#HEX"。自分の目で選びたい人は、ui-craft Studio (https://najeebafridi.github.io/ui-craft/) を使用できます:方向性を選び、実際の画面で調整し、theme.cssとDESIGN.mdの概要をエクスポートして、それに従います。 - コードの前にデザインブリーフを書く(返信またはコメント内で):
プロダクト:中小企業向け給与管理(ウェブアプリ、デスクトップ優先) ユーザーと感情:夜間に給与管理を行う経営者、ミスを不安に思っている -> 安全、ガイドされる、正確 方向性:信頼される台帳;アクセントはダークティール(ブランドカラー)、クールなニュートラル、ライトテーマ タイポグラフィ:IBM Plex Sans + Mono、14px本文、テーブルナンバー 形状と奥行き:6px角丸、ソフトシャドウ 密度とアニメーション:コンパクト、くっきり(120-200ms) プラットフォーム:レスポンシブウェブ シグネチャ:台帳のように数字を揃える;確認画面では正確な金額と時刻を表示 この画面の主要タスク:今月の処理を確認し承認する - 最初に構造を構築し、次にスタイルを適用する。 実際のコンテンツでレイアウトと階層を決め、次にシステム(トークン)、そして詳細へと進みます。Lorem ipsumは使用せず、現実的な名前、数値、コピーを書いてください。シグネチャは早い段階で構築し、それ以外の要素はすべてそれよりも控えめにします。 動作している状態を見せる。 最初のビューは使用中の画面とします:実際のデータ、適切なデフォルトが既に選択され、主要なインタラクションが見えている状態。すべてが空の状態やロックされた状態、"$0"の合計、主要なステップが前のステップを完了するまで隠れている状態で開かないでください。
- すべての状態をデザインする: ローディング、空、エラー、成功、長いテキスト、多数のアイテム、1つのアイテム、権限なし(
references/feedback-states.md)。 - 仕上げとチェック。
references/premium-craft.mdで仕上げのパスを行います。次に結果を確認します: Node.jsとChromeが利用可能な場合、node <skill-dir>/scripts/ui-audit.mjs page.htmlを実行します。これは、コントラスト、サイズ、タップターゲット、1440pxと390pxでのオーバーフローをスコアリングし、クラフト上の問題を指摘し、スクリーンショットを保存します。両方のスクリーンショットを開き、スマートフォンのものをデスクトップと同様に厳しく評価します: クリップ、隠れ、圧迫がないこと、キーコンテンツが最初の画面に収まっていること。画面が一つのストーリーを語っていることを確認します:サマリーが選択と一致し、合計が足し算と合い、カウントがリストと一致し、日付が合っていること。問題を修正し、主要タスクに役立たないものは削除します。チェックリスト:references/review-checklist.md。
クライアント向けの簡単なモックアップ:references/mockups.md。既存プロダクトのレビューまたはスコアリング:references/review-mode.md。
同じテーマの上のレイヤー。 3Dシーン、シェーダー、スクロールストーリーテリング、シネマティックモーションについては、immersive-webスキル(同じプラグイン)を使用します:これらは同じトークンを読み取り、テーマの--immersiveレベル(0:静止から3:ストーリー)が適用範囲を示します。他のジャンルやメディア(ゲーム、SF、映画)の外観を借用するには、references/mixing.mdを参照してください。
2. プロダクトタイプ別の密度
| プロダクト | 本文テキスト | 密度 | ナビゲーション |
|---|---|---|---|
| データツール、管理画面、開発ツール、金融 | 14px | コンパクト:行36px、コントロール32-36px | 左サイドバー220-280px |
| SaaSウェブアプリ | 14-16px | 標準:コントロール36-40px | サイドバーまたはトップバー |
| ダッシュボード、分析ツール | 14px | コンパクト | サイドバー + フィルターバー |
| マーケティング、ランディングページ | 16-18px | ゆったり:セクション間隔64-96px | トップバー、リンク4-6 + アクション1 |
| モバイルアプリ | 16-17px | タッチ:ターゲット44px以上 | ボトムタブバー、項目3-5 |
| デスクトップアプリ | 13-14px(プラットフォームデフォルト) | コンパクト | サイドバー + ツールバー;OSに従う |
| 消費者向け、遊び心 | 16px | 標準 | プラットフォームによる |
本文テキストのデフォルトは16px。14pxは高密度デスクトップツールのみ。12px未満は禁止。コンパクト密度はマウスとキーボードのみ: タッチスクリーンではすべてのコントロールが44pxに拡大されます(§13)。
3. 階層構造(最大の効果)
- 画面ごとに1つのヒーローと1つのプライマリアクション。 プライマリアクションだけが塗りつぶしのアクセントボタン。それ以外はアウトラインボタン、控えめボタン、テキストボタン。
- サイズ、ウェイト、色を組み合わせて階層を構築します。タイトルを目立たせるには、タイトルを大きくする代わりにラベルやメタテキストを控えめにします。
- ラベルは値よりも控えめに。「売上 $48,210」の場合、ラベルは12-14pxの控えめな色、値は24pxのセミボールド。
- グループ化は最初にスペーシング、次に背景色、次に線、最後にシャドウ。グループ間の間隔は、グループ内の間隔の少なくとも2倍。ボックスや線が少ないほど高級に見えます。
- 読み順は重要度と一致:主要タスクは左上(左から右の言語の場合)または中央に配置します。
4. レイアウトとスペーシング
- スペーシングスケール(4pxベース):4, 8, 12, 16, 24, 32, 48, 64, 96。 これのみを使用。
- コンポーネント内部:4-12;コンポーネント間:16-24;セクション間:32-48(アプリ)、64-96(マーケティング)。
- ページサイドパディング:モバイル16px、タブレット24px、デスクトップ32px以上。コンテンツ最大幅1200-1440px(アプリ)、1120-1280px(マーケティング);読み物テキストは65-75文字。
- グリッドまたはフレックスボックスと
gapでレイアウト。両軸で揃える:隣接要素は左端とベースラインを共有。わずかなズレは素人っぽく見えます。 - 外側のパディングは少なくとも内側のギャップ以上。迷ったら、余白を増やして境界線を削除します。
- デッドスペースをなくす。 カードを隣の高いカードに合わせて伸ばさない(
align-items: start)。パネルがほとんど空のままにならないようにする:実際のコンテンツを入れるか、縮小するか、削除します。 - 密度は決定事項:ゆったりかコンパクトか、常に正確に。ブレークポイントは640、1024、1440。最低でも375と1440で確認します。
詳細:references/layout-spacing.md。
5. タイポグラフィ
- タイプスケール:12, 14, 16, 18, 20, 24, 30, 36, 48, 60(より大きいものはディスプレイ用のみ)。アプリ画面では4-6サイズ、マーケティングページでは最大7サイズ。
- フォントは方向性またはブランドから:アプリでは1ファミリー、最大2つ(見出し用のディスプレイフェイス + ニュートラルなテキストフェイス)。デフォルトだからという理由でフォントを使用しないこと。推奨フォントはすべて無料(SIL OFL)。
- タイプをサイズに合わせて調整。 行間:本文1.5、見出し1.2-1.3、ディスプレイ1.05-1.15。文字間隔:14-16pxで0、20-24pxで約-0.015em、30-36pxで-0.025em、48px以上で-0.03から-0.04em;小さいオールキャップスのラベルで+0.06em。
- ウェイト:本文400、ラベルとボタン500、見出し600;700以上は大きなディスプレイのみ。画面あたり最大3つ。ホバー時にウェイトを変えないこと。
- 見出しには
text-wrap: balance、段落にはpretty。変更または整列するすべての数値にfont-variant-numeric: tabular-nums;表内の数値は右揃え。 - 見出し、ボタン、ラベルは文頭大文字。本物の引用符、ダッシュ、省略記号を使用。
詳細:references/typography.md。
6. 色彩
- 最初に感情を選ぶ。 明度と彩度は色相よりも画面の印象を変えます:明るいほど快適、彩度が高いほど刺激的、低彩度で強いコントラストは落ち着いて真剣。次に、意味、カテゴリへの適合、競合との差別化のために色相を選びます。
references/color-theory.md。 - パレットは着色されたニュートラル + 1つのアクセント + ステータスカラー(成功、警告、危険、情報)。ニュートラルには微量の色味(暖色、寒色、ブランド色)が含まれ、無彩色のグレーは避ける。大きな領域に純粋な黒や白は使用しない。
- ほとんどがニュートラル。 アクセントは全体の約5-10%:プライマリボタン、リンク、選択状態、フォーカス、主要データ。高彩度は小さく価値のある箇所のみに。
scripts/palette.mjs(OKLCH、ライト + ダーク、すべてのテキストと境界線の色がコントラストを満たすように解決済み)で構築するか、方向性から取得します。目分量でHEX値を発明しないこと。- コンポーネントではセマンティックトークンのみ使用:
--bg、--surface、--surface-2、--border、--border-strong、--text、--text-muted、--text-subtle、--accent、--accent-fg、--accent-soft、--accent-text、--focus、--danger… 各サーフェスにはフォアグラウンドのパートナーがあります。 - コントラストの最低基準(WCAG 2.2 AA):テキストは4.5:1、大きなテキスト(24px以上、または18.66px以上のボールド)とUI部品(入力欄の境界線、アイコン、フォーカスリング、チャートのマーク)は3:1。 区切り線は薄くても可。入力欄の境界線には
--border-strongを使用。 - 意味を伝えるのに色だけに頼らない: アイコン、テキスト、または形状を追加します。ステータスカラーはブランドカラーとは別に保つ。赤いブランドカラーがエラーカラーを兼ねることは避ける。
- ダークモードは独自のパレット: ほぼ黒に色味を加えたサーフェス、浮き上がったサーフェスは明るく、オフホワイトのテキスト、落ち着いたアクセント。両方のテーマを提供し、OSに従います。
詳細:references/color-theory.md、references/color-dark-mode.md。トークン:assets/tokens.css、assets/directions/。
7. ライト、奥行き、形状
- 1つの光源を上方から、全体に。3レベルだけ: フラット、浮き上がり(
--shadow-raised)、オーバーレイ(--shadow-overlay)。 - シャドウはレイヤー状で色味がある: 複数の薄いレイヤーで、1つのグレーのぼかしではない。高いほど大きく、柔らかく、薄くなります。
- カードとメニューは、境界線の代わりにシャドウ内に1pxのリングを使用。塗りつぶしボタンは、かすかな内側のトップハイライト(
--shadow-button)を持ちます。 - 1つの角丸ファミリー。 角丸のサイズは浮き上がりに応じて大きくなります(コントロール、次にカード、次にシート)。入れ子になった角は同心円状:内側の角丸 = 外側の角丸 - 間のパディング。
- ダークテーマでは、奥行きは明るいサーフェスとリングから生まれ、シャドウからは生まれません。
- プロダクトごとに1つの奥行き技法(ヘアライン、ソフト、クリスプ、ディフューズ、フラットまたはリップ。方向性で設定)。グロー効果は使わない、すべてのカードにシャドウをつけない。
- ぼかしと半透明はクローム部分(スティッキーヘッダー、シート、システムマテリアル)のみに使用し、コンテンツカードには使用しません。
詳細:references/premium-craft.md。
8. コンポーネント
- すべてのインタラクティブ要素に状態がある: デフォルト、ホバー、フォーカス可視、押下、無効;ボタンにはローディング;行とトグルには選択。ホバーだけが唯一の手がかりであってはなりません。
- ボタンと入力欄:デフォルト40px、コンパクト32-36px、タッチ44-48px。水平パディングは垂直の約2倍。ラベル = 動詞 + 目的語("請求書を作成")。アイコンのみのボタンには
aria-labelとツールチップが必要。 - フォーカスリングはキーボードユーザーに常に可視: 2pxの
--focus、2pxのオフセット。代替なしにoutline: noneを使用しない。 - 入力欄:上部に表示ラベル(プレースホルダーはラベルではない)、
--border-strongのエッジ、下部にヘルパーテキスト、エラー時は下部にアイコンと文言。長いフォームの場合は上部にエラーサマリーを追加。 - フォームのメインアクション(保存、続行)は最初から表示されていること。何かが変更されるまで控えめに見えてもよいが、編集後に初めて表示されることは避ける。
- トグルスイッチは即座に効果を適用。チェックボックスは保存時に適用。
- カードは、別々で比較可能なものにのみ使用。すべてのセクションの周りに配置しない。カードの中にカードを入れない。
- アイコン:1つのセット、1つのストローク幅、隣接するテキストに合わせたサイズ。絵文字をアイコンとして使用しない。
- 画像:実際のコンテンツ、固定の
aspect-ratio、意味のあるalt、1pxの内側アウトライン。プレースホルダーサービスは使用しない。実際の写真がない場合は、最終的なクロップ領域に控えめなトーンブロックと小さなキャプション("写真:ガーデンルーム")を配置。被写体の粗い描画は避け、周囲すべてを安っぽく見せる。 - モーダルは短く集中したタスクのみ。インライン編集やサイドパネルを優先。
- 破壊的アクション:危険色、名前を明記("プロジェクトを削除")、確認または元に戻し可能。頻繁なアクションでは、確認よりも元に戻すが勝る。
references/forms.md、references/tables-lists.md、references/navigation.md、references/dashboards-charts.md。
9. フィードバック状態
- 100ms以内にすべての押下を認識。スピナーまたはスケルトンは約300ms後に表示し、その後約500ms維持。
- スケルトンは既知のレイアウトを持つページまたはセクションの読み込みに使用。スピナーはボタン内部と小さなウィジェットに。プログレスバー(%付き)は約10秒以上経過後に表示。
- 空の状態 = これが何か + なぜ空か + 1つのアクション。エラー = 何が起こったか + 修正方法を、平易な言葉で、発生した場所に表示。ユーザーの入力を決して消去しない。
- 成功 は控えめで具体的に("請求書1042をアンナに送信しました、14:02")。トーストは4-6秒。重要な情報の唯一のコピーにしない。
- 安全な場合は楽観的に更新し、失敗時は元に戻せるようにする。速度は品質として認識されます。
詳細:references/feedback-states.md。
10. 感情と信頼
- 人は画面の見た目を約50msで判断し、その見た目が信頼性の最初のテストになります。シンプルで、構造に親しみがあり、詳細に独自性があるものが勝ちます。
- ユーザーの状態にデザインを合わせる:不安(次に何が起こるかを伝える、コミット前にサマリーを表示、簡単に戻る方法を用意)、忙しい(最小ステップ、事前入力、ショートカット)、懐疑的(主張の横に証拠を表示、早い段階で全額表示)、エキスパート(高密度、ショートカット、確認より元に戻す)、恥ずかしい、悲しんでいる(中立なトーン、お祝いしない)。
- 強く終える:最後のステップと確認は、人々が覚えているもの。
- 喜びはリスクの低い瞬間(初回起動、空の状態、成功)に提供し、エラー時やセンシティブなタスク中には決して提供しない。頻繁に発生するものほど、シンプルに。
- ダークパターンを拒否する: 偽の緊急性や希少性、偽のレビュー、事前チェックされたオプション、隠れたコスト、解約困難、確認の恥辱化、大きな「同意」と隠れた「拒否」。代わりに誠実なバージョンを提供します。
詳細:references/emotion-trust.md。
11. アクセシビリティ
- すべてのインタラクティブ要素はキーボードで操作可能かつフォーカス可能。フォーカス順序は視覚的な順序と一致。
- すべての画像に意味のある
altテキスト。装飾画像にはalt=""。 - ボタンとリンクは役割が異なる:ボタンはアクション(送信、保存)、リンクは移動(詳細を見る、設定)。
- 色覚多様性:伝達に色のみを使用しない。チャートにはパターンやラベルを追加。
- 十分なターゲットサイズ:タッチターゲットは最低44×44 CSS px。
- 動きを減らす設定を尊重:
prefers-reduced-motion。アニメーションは不要な場合に削除。 - テキストの拡大:200%まで機能することを確認。コンテナがオーバーフローしたりクリップしたりしないこと。
- 意味のあるマークアップ:見出しのための見出し、リストのためのリスト、テーブルのためのテーブル。
roleは最後の手段。
詳細:references/accessibility.md。
12. パフォーマンスとプログレッシブエンハンスメント
- フォントはパフォーマンスに影響する最初のもの:
font-display: swapを常に使用。必要なウェイトのみを読み込む。可変フォントが望ましい。 - 画像を最適化する:WebP、適切なサイズ、遅延読み込み。装飾画像には
loading="lazy"。 - CSSアニメーションは
transformとopacityのみ。レイアウトやペイントをトリガーしない。 - いくつかのスタイルが適用されていない場合でもコンテンツは読めること。
- タッチの遅延をなくすために
touch-action: manipulationを使用。
13. プラットフォーム固有のガイド
- ウェブ: メディアクエリとコンテナクエリを使用。モバイルファーストが基本。IE11はサポートしない。
- macOS/iOS(Cocoa/SwiftUI): システムフォント(San Francisco)を使用。ネイティブのコントロールとレイアウトガイドに従う。マテリアル(
NSVisualEffectView)は適切に使用。 - Windows(WinUI/UWP): システムフォント(Segoe UI Variable)を使用。アクセントカラーはシステム設定に従う。Fluent Designの原則(アクリル、リビール)に従う。
- Android(Jetpack Compose): Material Design 3ベース。システムフォント(Roboto)を使用。動的カラーをサポート。
- Flutter: MaterialまたはCupertinoをプラットフォームに合わせて使用。
ThemeDataを使ってテーマ設定。 - React Native: プラットフォーム固有のファイル(
.ios.js、.android.js)を使用。Platform.selectでスタイル調整。 - Electron: メニューバーはOS標準に従う。キーボードショートカットはプラットフォームの慣例に従う(Cmd/Ctrl)。
詳細:references/platform-conventions.md。
14. プレミアムクラフトの詳細
「仕上げ」とは、これらすべてが一貫していることです:
- 端: 正確に位置合わせされ、ぼやけやゴーストピクセルがない。
- テキスト: ゴミ(orphans、widows)なし。見出しはバランスが取れている。
- 色: 彩度の高い色は小さなアクセント領域のみ。コントラストはすべての状態でパス。
- スペーシング: すべての要素はグリッドに乗っている。
- 動き: すべてのアニメーションは目的があり、滑らか。
- 状態: すべてのインタラクティブ要素にすべての状態がある。
- コンテンツ: リアルで具体的。Lorem ipsumはない。
- 心理: ユーザーの状態にデザインが合っている。
チェックリストと詳細:references/premium-craft.md。
15. 付録:スクリプトとアセット
scripts/palette.mjs:アクセントカラーから完全なOKLCHパレットを生成。scripts/ui-audit.mjs:UIをスコアリングし、スクリーンショットをキャプチャ。scripts/theme.mjs:テーマファイルを生成。assets/tokens.css:セマンティックCSSカスタムプロパティ。assets/directions/:各ビジュアルディレクションのCSS変数。references/:詳細なガイドとチェックリスト。- ui-craft Studio:インタラクティブな方向性選択とテーマ生成のためのウェブツール。