loamui

LoamUI の使用方法

エージェントと協働する開発者のためのモダンな UI プリミティブです。領域がその意味を宣言し、内部のコンポーネントがそれに適応します。プロパティを設定するのではなく、パーツを組み合わせます。結果は要件に適合し、対象にふさわしいデザインでなければなりません。

正式な情報の参照先

• ドキュメントから生成されたオフラインのリファレンスは references/ にあります。インデックスから始めてください。オンライン版は、https://loamui.com の任意のページの末尾に .md を追加すると表示できます。インデックスは https://loamui.com/llms.txt にあります。
• コンポーネントを使う前に、そのリファレンスを読んでください。パーツ、プロパティ、カスタムプロパティ、使用する場面、アクセシビリティの仕様が記載されています。
• references/recipes/ にあるレシピは、デザイン上の判断を含む、移植可能な React と CSS です。目的に合うものを選んでから応用してください。方法についてはレシピガイドを参照してください。
• リファレンスは、ライブラリと同じコミットの内容に一致します。動作が異なる場合は、node_modules/@loamui/core/package.json にあるインストール済みのバージョンを確認してください。

1. プロジェクトを確認する

npx loamui@latest doctor を実行してください。不足が報告された場合、npx loamui@latest init で既存のものを維持しながら不足分を補えます。競合するツールやスタイルを置き換える必要がある場合は、事前に確認してください。セットアップはツールの役割です。ツールでできることを、スタイルシートの接続、Lint、チェックなどを手作業で行わないでください。AGENTS.md の ## LoamUI セクションには、セットアップ内容と check コマンドが記録されています。現在のエージェントから、4 つのスキル loamui、frontend-design、modern-css、modern-web-guidance を参照できることを確認してください。セットアップがブロックされた場合や断られた場合は、縮小した成果物について合意し、報告でその旨を伝えてください。リポジトリがない場合は、まず環境で何ができるかを確認してください。@loamui/core のエクスポートを偽造したり、通常の要素に loam-* クラスを借用したり、近似したものを LoamUI と呼んだりしてはいけません。

2. コードを書く前にデザインする

frontend-design スキルに従ってください。対象とユーザーを踏まえ、短いデザイン計画（カラーパレット、書体、レイアウトのコンセプト、原則、記憶に残る要素を 1 つ）を作成し、ありきたりでないか見直してから、実装します。スキル間で意見が分かれる場合の役割分担は決まっています。**何を作るかはユーザーの依頼、方向性は frontend-design、表現方法は LoamUI が決めます。**計画で決めた色は oklch() の light-dark() ペアとしてトークンの入力値にし、書体は --loam-font と --loam-font-display に設定します。間隔はスペーススケールから選び、ルールはレイヤーとスコープに配置します。下位にリセットを置いてはいけません。デザインでは、対応関係、テーマ用スタイルシート、ページ単位の指針を説明しています。デフォルトのパレットと system-ui は出発点であり、デザインそのものではありません。実際のプロダクトには、独自のテーマを用意してください。

3 つのプリミティブ

1. トークン（--loam-*）：少数のセマンティックな入力値から、それ以外のすべてを導きます。テーマの設定は入力値を上書きして行います。
2. 要素のスタイル：ネイティブ HTML にあらかじめ適用される、ページ全体にわたるスタイルです。レスポンシブに対応し、ライト／ダークモードも考慮されています。
3. コンポーネント：上記 2 つを組み合わせた、厳選されたセットです。ネイティブ要素に必要な構造がない場合に限り追加します。たとえば、ラベルとエラーを関連付けるフィールド、フォーカスをトラップするダイアログ、フォーカス移動を管理するメニューなどです。それ以外は、スコープ付きルールを適用したセマンティックな要素がコンポーネントになります。

ルール

• ネイティブプラットフォーム。 セマンティクスには実際の要素を、スタイリングには静的 CSS を使います。 操作にはボタン、遷移先にはリンクを使います。<dialog> と showModal()、 <details>、ラベルとキーボード操作に対応したネイティブコントロールを使います。
• モダン CSS。 レシピのルールは @scope (.recipe) to ([class*="loam-"]) 内の @layer loamui.components に記述します。ネスト、論理プロパティ、コンテナークエリ、 固有サイズのグリッドとフレックス、重なりのないクエリ範囲を加算的に使います。 スコープ内ではマークアップが API です。要素の種類（h2、figure、nav、h1 + p）で参照します。 クラスは同じ種類の兄弟要素間に実際の違いがある場合にのみ使い、スタイリング用のフックにはしません。 クラスを付けるためだけのラッパー要素は作りません。!important、BEM、リセット、 ピクセル指定のサイズ、サイズにビューポート単位は使いません。 @layer loamui.tokens, loamui.elements, loamui.components; の順序は、 どのレシピがレイヤーを登録するよりも先に確立しておく必要があります。 Baseline Widely と Newly Available の機能はネイティブに使います。それを超える機能は プログレッシブエンハンスメントとし、プロジェクトのブラウザーポリシーを無断で変更しません。
• コンポジション。 シンプルな用途には呼び出し可能なコンポーネントを、コンポジションには名前付きパーツを、 サポートされている要素の差し替えには render を使います。アイコンとローダーは子要素にします。 Field.Root 内のコントロールにはラベル、説明、エラーの関連付けが設定されます。 Field.Item はグループ化されたオプションのスコープを設定します。
• コンテキスト重視。 意味を担う領域で --loam-context を宣言すると、その内側すべてに適応します。 サイズは利用可能なスペースに従います。size、variant、color、fullWidth プロパティはありません。 例外は固有の表示サイズ（Badge、Loader、Progress、Meter）と、プラットフォーム固有の数値です。 アイデンティティに頼るのは最後の手段です。ブランドカラーのラッパーは適切ですが、 要素ごとに色を指定するのは適切ではありません。
• アクセシブル。 セマンティック HTML、名前付きコントロール、キーボード操作とフォーカス、ユーザー設定に対応します。 フォーカスリングを削除したり、状態を色だけで伝えたりしてはいけません。 必須が明示されていない場合は必須とし、任意の場合は言葉で示します。 エラーには何が起きたかと修正方法を、質問で使われた言葉で伝えます。 新しいエラーは送信後に表示し、ネイティブの制約エラーは、修正が有効になったら解消します。

コンポーネント

カテゴリー	コンポーネント
入力	Field, Fieldset, ErrorSummary, Button, Input, Textarea, Select, DateInput, Checkbox, Radio, Switch, Range, Search, QuantityInput, Rating, FileInput, CopyButton, Combobox, PasswordInput, SegmentedControl
データ表示	Badge, Price, Time, Card, Avatar, Table, Separator, Carousel, Stepper
フィードバック	Alert, Progress, Meter, Skeleton, Loader, Toast
開示	Details, Tooltip, Modal, Drawer, Popover, Menu
ナビゲーション	Tabs, SignpostLink, SkipLink, Breadcrumbs, Pagination, Nav
ユーティリティ	VisuallyHidden

レイアウトコンポーネント（スペーストークンを使ったネイティブのグリッド、フレックス、フロー）はありません。Heading や Text（セマンティック要素とスコープを限定したルールで代用します）、Accordion（Details で代用します）、Slider（Range で代用します）もありません。

3. 構成

1. 必要なプラットフォームパターンごとに modern-web-guidance を検索し、該当する modern-css のルールを確認します。レシピガイドと最も近いレシピ、使用する各パーツの契約も確認します。
2. 設計計画に基づいてテーマのスタイルシートを作成し、core の後に読み込みます。
3. レシピから意図的な順序でページを組み立て、スペーススケールでセクションにリズムをつけ、文章の幅を var(--loam-measure) 以下に抑えます。
4. ネイティブ CSS でレイアウトします。:root またはスコープでトークンを使ってテーマを設定し、コンポーネントの内部やプライベートな --_* プロパティには決して触れません。
5. 納品物の移植性を保ちます。React と CSS、アプリケーションに必要な統合、明確な境界の内側にある実際のアクションを用い、ドキュメント専用の仕組みは含めません。

レシピがない場合

レシピは、手を動かして参照できる例であり、カタログではありません。フッター、統計情報の帯、推薦文、ロゴの列、価格表など、実際のサイトの大半にはレシピがありません。それらを適切に構築することはスキルの役割であり、レシピがないことは不足ではありません。次の順に検討し、要件を満たす最初の段階で止めてください。

1. 要素のスタイルがすでに装飾しているネイティブ要素：<footer>、<table>、<blockquote>などです。多くの場合、それ以上は必要ありません。
2. スコープを限定したルールを適用するセマンティック要素：@scope (blockquote.testimonial)などです。デザインシステムの別名ではなく、製品における実際の役割に合わせて名前を付けてください。
3. 既存のコンポーネントと要素の組み合わせ：Cardのグリッド、Nav、Fieldフォームなどです。
4. それでも必要な場合に限り、新しいコンポーネントを作成します。ただし、ネイティブ要素にない動作を実現する場合だけです。

どの段階であっても、各レシピと同じ形式にしてください。スタイルシートを隣に置いた専用のコンポーネントファイルを作り、ページにインラインJSXを書かないこと、ルートクラスは1つにすること、ルールは@scope (.root) to ([class*="loam-"])の中の@layer loamui.componentsに記述すること、色、間隔、文字スタイルにはトークンを使うこと、制御対象のレイアウトの外側に計測用コンテナーを置くこと、セクションごとに役割を1つにすること、適切な見出しレベルを使うこと、実際のコンテンツを使うことです。ページはセクションを組み立てるものであり、セクション自体を含めるものではありません。最も近いレシピを構造の手本にしつつ、そのコンテンツを無理に合わせないでください。loam-*クラス名を借用したり、独自のパーツを作ったり、別のライブラリで代用したりしないでください。ステップ4のレビューは、レシピを応用した場合と同じように適用されます。

よくある間違い

• size、variant、colorのプロパティを独自に作る。 色は領域で決まり、サイズはコンテナーで決まり、幅は親のレイアウトで決まります。ModalとDrawerの幅には--loam-modal-sizeと--loam-drawer-sizeを使います。
• デフォルトのままにする。 コードを書く前に「デザイン」を確認してください。
• カウントにtype="number"を使う。 1つずつ増減するカウントにはQuantityInputを使います。それ以外の数値入力には、inputModeを指定したInputを使います。
• 生の要素にloam-*クラスを借用する。 クラス名はAPIではありません。コンポーネントには、そのクラスにはない配線とテストが備わっています。
• リンクをボタンのように装飾する。 目立たせるナビゲーションにはSignpostLink、通常のナビゲーションには<a>を使います。Buttonはアクション用です。
• Fieldの配線を重複させる。 Field.Rootに任せ、実際の関連付けに必要な場合だけ明示的なIDを追加してください。繰り返し使うレシピにはuseIdを使います。
• 必須を示すアスタリスクや「この項目は必須です」という文言を使う。 ルールを確認してください。
• リセットしてから再スタイルする。 要素のスタイルがベースラインです。それを基に構築してください。
• Inputのラッパー。 className、style、refはネイティブの入力要素を対象とし、wrapperPropsはそのボックスを対象とします。InputにはstartSectionとendSectionがあります。
• 削除された間隔の名前を使う。 --loam-space-sm/md/lgは存在しません。スケールは4xsから4xlまでで、固定のジオメトリには--loam-space-fixed-*を使います。

4. レビューしてから報告する

独立したレビュー工程を行い、そこで得られた所見を以下の順序で書き留めるまでは、何も報告しません。

1. ゲート。 プロジェクトの check スクリプト（CSS lint、JS lint、composition、format）、型チェッカー、テストを実行します。報告された問題を修正し、チェックに合格するために無効化してはいけません。これらで確認できることを手作業でレビューする必要はありません。
2. 設計方針。 上記のルールに照らして composition を読み直します。プリミティブが適切な順序になっているか、コンポーネントの前にネイティブ要素があるか、props ではなく context を使っているか、設定ではなくパーツを使っているか、Field の接続、スコープのドーナツ、リセットがないこと、正当な場合に限って identity を使っていること、各セクションがそれぞれ独立したコンポーネントファイルになっていることを確認します。
3. モダン CSS。 作成した CSS を、どの lint でも強制されない modern-css のルールに照らして読み直します。oklch() のみを使っているか、rem 項を含む流動的な clamp()、フロー相対プロパティ、state クラスではなく :has()、固定間隔ではなくコンテナ単位、範囲が重複していないこと、モーションがオプトインであること、スコープ内の各クラスについて型セレクターで代用できなかったかを確認します。
4. モダン Web ガイダンス。 ステップ 3 で調べた各パターンについて、ガイドの方針に従っていることを確認するか、従わなかった理由を述べます。
5. レンダリング結果。 狭い幅と広い幅で、両方のカラースキームを確認します。長いコピー、キーボード操作とフォーカス、モーション低減、強制カラーも確認し、テーマを変更したすべてのコントラストの組み合わせを測定します。次にデザイン計画を確認します。記憶に残る要素が 1 つあり、ほかはすべて控えめで、削除した要素が 1 つあることを確認します。

各所見には、file:line、違反しているルール、修正内容を記載します。修正したら、影響するゲートを再実行します。実行した内容、発見して修正した内容、確認した項目、未検証の項目を報告します。チェックに合格したことは、そのチェックが確認する範囲の証拠であり、適合性を包括的に保証するものではありません。

参考資料

• デザイン、テーマ、ページのリズム：references/guides/design.md。
• トークンとダークモード：references/guides/tokens.md。レイアウト： references/guides/layout.md。タイポグラフィ：references/guides/typography.md。
• 領域とアイデンティティ：references/guides/contextualism.md。
• init がセットアップした内容と、エージェントの契約全文： references/guides/agent-workflow.md。
• composition されたフォーム：references/recipes/forms/sign-in-with-errors.md。ページの導入部： references/recipes/heroes/hero-with-image.md。
• 各コンポーネント：references/components/<slug>.md。