specsfy-specialist-design-system

Specsfy スペシャリストデザインシステム

使用するタイミング

このスキルは、利用側プロジェクトの DESIGNSYSTEM.MD ドキュメントを管理します。ビジュアル言語、シェル、サーフェスの構成、状態、インターフェースに反映されるビジネスルールを定義します。このドキュメントは、UX、UI、インターフェース体験、React コンポーネントの指針となります。

画面、CRUD フロー、ナビゲーション、フォーム、グローバルコンポーネントを作成またはレビューする前に使用してください。また、ドキュメントが存在しない場合、古くなっている場合、またはすでに設計された画面と競合している場合にも使用してください。

コンポーネント、props、ローカルファイルのカタログ化には、このスキルを使用しないでください。それらの記録は INTERFACE.md の役割です。INTERFACE.md では、マクロレベルの選択事項を複製せずに参照してください。

必須の情報源

次の順に読みます。

1. 利用側プロジェクトのルートにある DESIGNSYSTEM.MD（存在する場合）。
2. 不足している情報源を作成するための .specsfy/templates/DESIGNSYSTEM.MD。
3. すでに記録されているコンポーネントと画面を確認するための INTERFACE.md。
4. .specsfy/STACK.md、マニフェスト、ルート、画面、権限、および成果物に関連するドメインルール。

情報源が存在しない場合は、管理対象のテンプレートを DESIGNSYSTEM.MD にコピーし、確認済みのコンテキストのみを記入してください。汎用的なテキストで不足部分を隠さないでください。

フロー

1. 対象となるプロダクト、モジュール、サーフェス、フローを特定します。
2. 依頼内容を DESIGNSYSTEM.MD と照合し、すでに適用されているルールを維持します。
3. 依頼者がビジュアルの方向性を指定していない場合は、ドキュメントのデフォルトを適用し、成果物の標準的な方向性として記録します。
4. 依頼者が異なる方向性を示した場合は、例外、その適用範囲、置き換えるルールを記録します。画面単位の例外によって、プロダクト全体のルールが変わることはありません。
5. ルールがマクロレベルの適用範囲を持つ場合に限り、ドキュメントを更新します。特定のコンポーネントや画面は INTERFACE.md に記録します。
6. UX、UI、または実装にガイダンスを引き渡す前に、サーフェスの標準シナリオを整理します。
7. 読み込んだファイル、適用したルール、記録した例外、対象としたシナリオを報告します。

ビジュアルを伴うすべての成果物では、依頼者から求められていなくても、開発中にレビューを行ってください。関連するビューポートと状態で、システムの境界線、間隔、マージン、パディング、タイポグラフィを確認します。方法、結果、調整内容をタスクの VISUAL 項目に記録してください。

標準

SaaSで必須のデフォルト

視覚的な指示がない場合は、次の構成を適用します。

• CRUD一覧：PageHeader + 役立つサマリー + DataGrid。データ量やドメインに応じて、検索、フィルター、並べ替え、ページネーション、選択、行ごとのアクションを使用します。
• 詳細：PageHeader + DetailLists。ドメインに役立つ場合は、ステータス、次のアクション、関連情報またはアクティビティを含めます。
• 作成・編集：コンテキスト列とフィールドパネルを備えた、レスポンシブな2列構成のフォームセクションをPageHeaderに続けます。
• フォーム：フィールドの上に常に表示されるラベル、コンテキストに応じたヘルプ、値の保持、送信状態を備えます。
• フィールドエラー：赤色の意味的なボーダー、背景、またはアイコンを使用し、フィールドの下にメッセージを表示します。意味的に関連付け、最初のエラーにフォーカスします。
• 複数のエラー：影響を受けるフィールドへのリンクを含むサマリーを先頭に表示します。
• 画面：フローで該当する場合は、loading、空、エラー、成功、権限なし、コンテンツの一部表示、未保存の各状態に対応します。
• Breadcrumb：アプリケーションのすべての画面で必須です。アクティブなチーム名を、モジュールと現在のタイトルより前に表示します。Laravelでは、レイアウト内に既存のBreadcrumbまたはBreadcrumbsと、そのルート型があれば再利用します。
• DataGrid：行全体をクリックして詳細を開けるようにし、キーボード操作に相当する機能も用意します。内部の操作コントロールは、TableRowActionまたは同等の仕組みで保護します。
• CRUD：すべての画面で同じコンポーネント化されたPageHeaderを再利用します。一覧では全幅のDataGridを使用し、ID列を表示して、行に編集ボタンと削除ボタンを用意します。行のリンクから詳細を開き、ボタンの操作を妨げないようにします。
• 繰り返し使うヘッダー、テーブル、行、アクション、フォーム、状態、フィードバックのコンポーネントはINTERFACE.mdに記録し、新たに実装する前に再利用します。

これらのデフォルトは、ありきたりな見た目を意味するものではありません。個性は、データの階層、ドメインに即した表現、タイポグラフィ、トークン、リズム、状態、コントラスト、シェルの使い方から生まれます。構成によって、タスクの内容を伝え、ユーザーを導く必要があります。

ダッシュボードと共通ブロック

納品物にダッシュボードが含まれる場合は、PageHeader、期間または範囲、フィルター、値、単位、期間、比較、情報源を含むKPIの短いストリップに続けて、主要な傾向または分布、調査用の詳細リストまたはDataGridを配置します。各指標とビジュアライゼーションには、ローディング、空、エラー、更新の各状態に加え、グラフの代替となるテキストまたはテーブルを用意します。

基本的なコントロールにはshadcn/uiのプリミティブを使用します。タスクに適している場合は、CRUDやダッシュボードの構成にReUIの無料ブロックを使用します。プロダクトに合わせて、トークン、データ、権限、アクセシビリティ、表現を調整します。情報源、状態、利用者をINTERFACE.mdに記録します。

作成・編集フォーム

作成と編集は、独立したセクションに整理します。各セクションでは、左側にコンテキスト、右側にフィールドパネルを配置します。パネル内では、関連するフィールドを広いブレークポイントで2列、モバイルで1列にします。長いフィールド、アップロード、エラーは全幅にできます。フッターでは、キャンセルと保存をアクションの結果に近い位置に保ちます。

Breadcrumbとシェル

すべての画面で、グローバルシェルにBreadcrumbを表示します。パンくずリストには、アクティブなチーム、モジュール、現在の画面を表示し、前の項目には実際のラベルと有効なリンクを使用します。Laravelアプリケーションでは、レイアウトにすでに存在するBreadcrumbまたはBreadcrumbsコンポーネントと項目の型を特定して再利用し、プリミティブを重複させずにチームを挿入するために必要な構成だけを調整します。モバイルでも、チームと現在の画面が見えるようにします。

すべての納品物でカバーするシナリオ

テンプレートの Cenários canônicos セクションを参照し、該当する範囲を DESIGNSYSTEM.MD または納品物の spec に記録してください：

• レコードがある一覧；
• 空の一覧；
• ステータスとアクションを含む詳細；
• 有効な作成；
• 有効な編集；
• フィールドエラーがある作成または編集；
• 権限がない場合；
• 読み込みの失敗；
• 編集がある場合、未保存の変更；
• 削除またはキャンセルがある場合、破壊的なアクションの結果。

各シナリオについて、事前条件、アクション、応答、視覚的な状態、フォーカス、 メッセージ、次のステップを記載してください。

制限とハンドオフ

• UX は、この情報源に基づいてタスクのフロー、情報アーキテクチャ、言葉遣いを定義します。
• UI は、この情報源に基づいてトークン、階層、視覚的な構成、状態を定義します。
• React コンポーネントは、この情報源と INTERFACE.md を読んだ後、互換性のあるプリミティブと構成を選択します。
• インターフェイス体験のスキルは納品を調整します。DESIGNSYSTEM.MD を読み込まずに画面の作成を開始してはいけません。

アンチパターン

• レコードを比較する必要があるのに、カードを大量に並べること。
• ドメインに異なる情報グループがあるのに、セクションのないフォームにすること。
• モバイルで2列にすること、またはフィールド、ヘルプ、エラーが分断されるグリッドにすること。
• プレースホルダーを唯一のラベルとして使うこと。
• エラーをアイコン、色、またはフィールドから離れたトーストだけで示すこと。
• PageHeader がない、空の状態がない、または復旧手段がない画面。
• 質問、期間、単位、次のアクションを示さずに数値を表示するダッシュボード。
• 階層や詳細を調べる手段のないカードの大量表示を使うダッシュボード。
• 製品のデータ、状態、権限、トークンに合わせて調整せずに使用する ReUI ブロックまたは shadcn/ui プリミティブ。
• ドキュメントと INTERFACE.md を確認せずに作成する新しいトークンまたはコンポーネント。
• 明確な適用範囲を示さず、局所的な視覚上の例外を全体ルールとして記録すること。
• ヘッダーの重複、幅の狭い DataGrid、非表示の ID、または行に編集・削除アクションがない CRUD。

検証

ハンドオフの前に、次の項目を確認してください：

• 利用側プロジェクトのルートに DESIGNSYSTEM.MD があり、分類、ポリシー、デフォルト、状態、シナリオ、履歴が記載されている。
• 一覧で DataGrid と PageHeader を使用している。
• すべての画面に、アクティブなチーム名、モジュール、現在の画面を示す Breadcrumb がある。
• Laravel では、レイアウトにすでにある Breadcrumb または Breadcrumbs を再利用している。
• 詳細画面で DetailLists と PageHeader を使用している。
• 作成画面と編集画面ではセクションとコンテキスト列を使用し、幅の広いブレークポイントではフィールドパネルを2列、モバイルでは1列にしている。
• フィールドエラーがフィールドの下に赤色で表示され、意味的に関連付けられている。
• 標準の方向性または例外が適用範囲とともに記録されている。
• INTERFACE.md に納品物のローカルな記録のみが含まれている。
• spec とタスクで、状態、権限、フォーカス、メッセージ、戻り方を扱っている。
• ダッシュボードがある場合、フィルター、指標のコンテキスト、視覚化のアクセシブルな代替手段、詳細な調査手段がある。
• shadcn/ui プリミティブと ReUI ブロックについて、出所、状態、利用者が INTERFACE.md に記録されている。
• 各タスクでは EVIDENCE の前に VISUAL 項目が完了しており、境界線、間隔、マージン、パディング、タイポグラフィを確認している。または、インターフェイスがない具体的な理由を示している。

実装がある場合は、スタックのテストとバリデーターを実行してください。Specsfy のスキルでは、quick_validate.py とモノレポのテストスイートを実行してください。

関連スキル

• references/standards.md
• skills/templates/DESIGNSYSTEM.MD
• skills/templates/Interface.md
• specsfy-specialist-interface-experience
• specsfy-specialist-ux-design
• specsfy-specialist-ui-design
• specsfy-specialist-react-ui-components