fluid-functionalism

流れる機能主義

shadcn/ui のコンポーネントレジストリです。あらゆるトランジションで状態の変化をわかりやすく示します。期間ではなくスプリングを使い、リストごとにホバー時のハイライトを1つだけ表示してカーソルに最も近い項目へ滑らかに移動させ、ラベルは隣の要素を動かさずに太くします。プリミティブを使うコンポーネントは、Radix と Base UI の2種類を同じ API で提供します。

ドキュメントとライブデモはこちらです：https://www.fluidfunctionalism.com — 各コンポーネントのページにはプレイグラウンドと プロンプトをコピー ボタンがあり、そのテキストには自己完結した概要（インストールコマンド、使用例、props、ドキュメント URL）が記載されています。

このスキルで対応する4つの作業：

1. プロジェクトを把握する — 実行のたびに最初にスタックを読み取ります（次のセクションを参照）。読み取りは高速かつ正確なので、何もキャッシュされず、古くなることもありません。
2. コンポーネントをインストールして組み合わせる — 適切なレジストリアイテムと種類を選び、組み込み、既に構築されているものを中心に組み合わせます。カタログはreferences/components.md、各ドキュメントページとトップレベルブロックに組み込まれた正確な動作、値、理由といった作り込みの内容はreferences/craft.mdを参照してください。カタログでは、個別にインストールできるパーツと、それらを管理する親セクションを対応付けています。組み合わせる前にそのセクションを読むことで、このライブラリを使いこなすことと、単にインストールすることの違いが生まれます。
3. 隣に並べても調和するカスタム UI を作る — ライブラリにないものを構築するときは、アプリのほかの部分と同じ動きになるよう、モーションシステムに従ってください。アニメーション、ホバー、状態変化のスタイルを手作業で書く前に、references/custom-motion.mdを読んでください。
4. 最新の状態を保つ — ローカルの作業を失わずに、インストール済みアイテムを最新リリースに更新します：更新を依頼された場合。

実行のたびにスタックを読み取る

インストール、組み合わせ、アドバイスを行う前に、アプリのディレクトリ（package.json と components.json がある場所）を指定してスタックスクリプトを実行します。ほとんどのプロジェクトではこれが現在のディレクトリです。モノレポでは、ディレクトリを渡してください：

node <skill>/scripts/stack.mjs [apps/web]

必要なのは Node だけで、1秒もかからずに完了し、何も書き込みません。FF に必要な依存関係（React 19、Tailwind v4、motion、shadcn の配線）を読み取り、使用する種類を判定し、品質を損なう2つの見落としやすい要因（アプリを囲む MotionConfig reducedMotion="user"、opsz 軸を含まない Inter）を確認し、インストール済みの FF コンポーネントと、同名のファイルが標準のものかローカルのものかを一覧表示します。各行には、情報の出所である file:line が記載されています。Node がない場合は、同じファイルを手作業で確認してください：確認項目。

事実は記憶せず、読み取ります。 スタックに関する事実は、キャッシュしたコピーを検証するよりも、毎回読み直す方が速く、コードと食い違うキャッシュ済みの判定は、その後のすべてのセッションに誤解を招きます。使用する種類の判定が記録なしでも安定するのは、毎回同じ方法で導き出されるからです。まずインストール済みの FF コンポーネントを確認し、次に package.json を確認します。監査結果をプロジェクトに書き込まず、返信に記載してください。

決定事項は例外です。 ユーザーが決めたことはコードからはわかりません。たとえば、滑らかなホバーを採用しないこと、静止状態を選ぶこと、トークンにない期間を意図的に維持することなどです。スクリプトの DECISIONS 行には、アプリのディレクトリからリポジトリのルートまで、以前の決定事項が記録されている場所が示されています。それらを読み、尊重し、決着済みの内容を再び提起しないでください。新しい決定事項を記録するかどうかは任意です。プロジェクトが既に意図を記録している場所に記録してください。詳しくは決定事項を参照してください。このスキルの以前のバージョンによるレガシー監査ファイルがスクリプトで報告された場合は、その決定事項を尊重し、事実は無視してください（以前の監査ファイル）。

インストールのたびに、対象の現在のファイルを確認し、同名のファイルがあれば差分を確認してください。確認の結果、対象がまだ標準のものだとわかった場合に限り、--overwrite を渡してください。

監査やアドバイスを求められた場合

references/stack-audit.md に沿って完全な監査を実施します。 スタックの読み取りに加えて、最も効果が期待できる UI の改善点を 2～5 件選びます。まずシステム（モーションのトークン、滑らかなホバー、サーフェス、サイズ）を確認し、次にコンポーネントを確認します。それぞれに効果と工数を評価し、効果対工数の比率で順位を付けます。対象は UI とデザインシステムのみです。インフラに関する指摘は事実として述べ、推奨事項として提示しません。アドバイスとリンターレポートを分けるのは、次の 3 つのルールです。

• 原因となるコードではなく、インターフェースを起点にそれぞれの指摘を書きます。製品を使う人が現在どの画面で何を目にし、それをどのくらい頻繁に見て、どのような品質を取り戻せるのかを記述します。ファイル名と修正規模は補足情報であり、見出しにすべきではありません。
• アプリにこれまでなかった動作は、指摘事項ではなく質問です。 製品がすでに備えている機能の動作が悪い場合、それを修正するようアドバイスします。一方、新しい特徴的なモーション、特に滑らかなホバーを導入すると、全体の使い心地が変わるため、提案に含める前に確認します。動きのなさが意図的な場合も少なくありません。
• インストールがブロックされても、改善の妨げにはなりません。 古い Tailwind や React がブロックするのは CLI であり、製品の改善ではありません。すべての項目は手作業で対応できます。ユーザーが依頼していない移行を最初に持ち出してはいけません。

測定してから、アドバイスします。 アプリが動作する場合は、何かを推奨する前に、最もよく使われるルートを scripts/audit.mjs に渡します。実際にポインターを動かし、各リストのホバーが滑らかに切り替わるか、行の間で一瞬消えるか、タブの選択で隣のタブが押しのけられるか、実際に適用されているトランジションの継続時間とコントロールの高さ、読み込まれたフォントがウェイトの変更を描画できるかを報告します。その後、すべてのアドバイスと候補リストの項目をエビデンスゲートに通します。引用した測定結果または file:line、実際に使われている画面、正確に 1 つの FF 修正、そして根拠が成り立たない項目を削除する反証チェックが必要です。「変更の推奨事項はありません」も妥当な結論です。必ず何かを見つける監査では、いずれ誰も耳を貸さなくなります。

候補リストは返信に含めます。各項目には根拠が示されているため、次回の監査では、その時点のコードに基づいて候補リストを作り直せます。修正済みの項目は自動的に除外され、見送られた項目だけ、対応を保留するかどうかの判断が必要になります。

更新を求められた場合

ユーザーから Fluid Functionalism の更新やアップグレード、またはインストール後に何が変わったかを尋ねられた場合：

1. スタックを確認します（上記）。更新によってファイルが別のフレーバーに移ることはありません。各ファイルは、インポート内容が示すプリミティブのままです。

2. 更新内容を確認します：

   node <skill>/scripts/upgrade.mjs [apps/web]
   

   インストール済みのすべての FF ファイルを、各ファイル自身のインポート内容が示すフレーバーで、レジストリが現在提供している項目と比較します。インストール時に書き換えられる内容（インポートエイリアス、改行コード、"use client" 行）は無視します。CURRENT のファイルは対応不要です。DIFFERS には残りのファイルと行数が表示されます。--diff <name>（またはパス）を指定すると、ローカルを - 側、レジストリを + 側として差分を表示します。REWRITES 行は、CLI がそれ以上の内容（JavaScript の出力、Tailwind のプレフィックス）を書き換えることを示します。これらは手動で比較してください。ファイルへの書き込みは行われず、fluidfunctionalism.com へのネットワークアクセスが必要です。

3. 変更履歴を確認します： https://www.fluidfunctionalism.com/changelog.md。新しい月から順に記載されています。各エントリーにはインストール URL があり、すべての Breaking エントリーには移行手順と変更前後の差分が含まれています。

4. 各差分を分類します。 変更履歴に記載された変更は、レジストリ側の更新です。レポートにある該当行を使って、その項目を再インストールします。変更履歴に記載されていない変更はローカル編集です。内容を提示し、上書きする前に確認してください。同じファイルに両方ある場合は、再インストールしてから編集を再適用します。あるいは、次回の更新でも保持されるように、ラッパーに移してください（「注意点」を参照）。--overwrite は項目の依存関係も書き換えます。依存関係はレポートの該当行に記載されているため、実行前にローカル編集がないか確認してください。

5. 該当する呼び出し箇所を移行します。 プロジェクトで使用している項目に関わる Breaking エントリーごとに、アプリ全体から差分の - 行を探し、+ 行の内容に書き換えます。名前の変更は型チェッカーでエラーになるため、検出を任せてください。

6. 検証します： 型チェッカーとビルドを実行し、upgrade.mjs をもう一度実行します（すべてのファイルが CURRENT と表示されるか、ユーザーが保持したローカル編集であることを確認します）。そのうえで、変更した項目と変更しなかった項目をそれぞれ報告します。

すべてを確認せずに再インストールして更新してはいけません。--overwrite はローカルの作業を消去します。また、リリースによって、インストールでは変更されない呼び出し箇所が壊れることがあります。

プロジェクトの初回セットアップ

スタックの確認で、すでに完了している作業がわかります。完了済みのものはスキップしてください。

1. レジストリを追加します（または、次のセクションの URL ごとのインストールを使用します）。

   npx shadcn@latest registry add @fluid
   

2. プロジェクトごとにフレーバーを一度だけ選びます。 名前だけを指定すると Radix フレーバーがインストールされます。Base UI を使う場合は base/ をプレフィックスとして付けます。スタックスクリプトは、プロジェクトですでに使われているものから判定します。インストール済みの FF コンポーネントを最初に確認し、次に package.json の @base-ui/react を確認します。該当する場合は、すべての名前に base/ を付けます。@radix-ui/react-* がある場合（またはまだ何もない場合）は、プレフィックスなしの名前を使います。input-group、color-picker、ask-user-questions はどちらのフレーバーでも Base UI をインポートするため、判定材料にはなりません。1 つのプロジェクト内でフレーバーを混在させないでください。依存関係は選んだフレーバーに応じるため、Base UI のダイアログをインストールすると Base UI のボタンも追加されます。

3. ルートでモーションの軽減を有効にします。 ThemeProvider などを使い、アプリのレイアウトに 1 行追加します。

   import { MotionConfig } from "motion/react";
   
   <MotionConfig reducedMotion="user">{/* providers + app */}</MotionConfig>
   

   これにより、すべての Motion コンポーネントが OS の prefers-reduced-motion 設定に従います。変形とレイアウトアニメーションは無効になり、不透明度と色のフェードは維持されます（理解の助けになるためです）。

4. プロジェクトで Inter を使っていて、ウェイトのアニメーション中も幅を維持したい場合は、光学サイズ軸を指定して Inter を読み込みます。 next/font/google の場合：Inter({ subsets: ["latin"], axes: ["opsz"] })。セルフホストする場合：font-weight: 100 900 を指定し、InterVariable.ttf を参照する @font-face を使います。opsz 軸がなくても動作しますが、ウェイトが太くなるとラベルの幅がわずかに広がります。

コンポーネントのインストール

npx shadcn@latest add @fluid/button            # Radix flavor
npx shadcn@latest add @fluid/base/button       # Base UI flavor
# URL form (no registry entry needed) - the flavor lives in the path, so a
# base project needs the /base/ segment here too:
npx shadcn@latest add https://www.fluidfunctionalism.com/r/button.json       # Radix
npx shadcn@latest add https://www.fluidfunctionalism.com/r/base/button.json  # Base UI

依存関係、共有ライブラリ（springs、font-weight、コンテキスト）、フックは自動的に解決されます。必要なコンポーネントだけをインストールすればよく、その依存部分を個別にインストールする必要はありません。

プロジェクトの shadcn ファイルが標準のままの場合は、--overwrite を渡してください。このライブラリは同じ名前（button.tsx、dialog.tsx、…）でインストールされるため、このフラグがないと CLI はファイルごとに確認を求めます。非対話型シェル（あなた）では、最初の質問で処理が終了します。ただし、それらのファイルにローカルのカスタマイズや同じ場所にあるストーリー／テストが含まれている場合（各対象を diff して確認してください）、--overwrite を使うとその作業が失われます。安易に実行せず、内容を確認するか diff を取ってください。

npx shadcn@latest add @fluid/dialog --overwrite

要件に合うものがあれば、ブロックを優先してください。sidebar-app（完全なアプリシェル）、dialog-sidebar（設定ダイアログ）、queued-stack（キューに入ったコンポーザーメッセージ）は、それぞれ使用するすべてのコンポーネントと組み合わせ済みの状態で、1 つの項目としてインストールできます。

すべてのコンポーネント、システム、ブロックと、レジストリ名、バリエーション、各項目の機能を網羅したカタログは、references/components.md にあります。インストールするものを選ぶときに参照してください。名前を推測すると、インストールをやり直すことになります。

プリセット： Sidebar、Card、InputMessage、AskUserQuestions、Dropdown、Combobox、CommandMenu のプレイグラウンドでは、設定が短いコードに変換されます。ユーザーからプリセットコード、または ?preset= を含むドキュメント URL が提示された場合は、組み合わせ済みのブロックとして直接インストールしてください。 npx shadcn@latest add https://www.fluidfunctionalism.com/r/preset/<code>.json。

システムを使った構成

インストール済みのコンポーネントは、すでにすべてのルールに従っています。これらのルールが重要になるのは、独自のリスト、特注のカードグリッド、独自にアニメーションさせるアイコンなど、コンポーネントの周囲に UI を作成するときです。レシピとコードスニペットは references/custom-motion.md にあります。システムの要点は次のとおりです。

• トークン化された3段階のスプリング速度。 @/lib/springs の spring.fast（0.08s）／spring.moderate （0.16s）／spring.slow（0.24s）を使います。動くものが大きいほど、スプリングは遅くします。duration を手書きしてはいけません。トークンをインポートし、閉じるときは対応する .exit トゥイーンを使います。終了アニメーションを入口の逆再生にするのではなく、きびきびした印象にできます。
• ページのリビールは1つのクラスで。 @fluid/reveal をインストールし、ページのコンテナーにクラスを1つ設定します。一度だけ見るページには reveal-landing、アプリには reveal-product、控えめにするには -subtle を使います。アプリでデータの表示が遅い場合は、shadcn の Skeleton を reveal-swap 内に表示すると、実際のブロックへクロスフェードします。両方に reveal-items を設定すると、行が1つずつ表示されます。すべての要素に whileInView のフェードを独自実装してはいけません。また、ヒーロー画像と見出しはリビールの対象から外してください。ルールとレシピ： references/custom-motion.md。
• リストごとにホバーハイライトは1つ。 ホバー機能を備えた独自のリスト、メニュー、ストリップ、グリッドには、useFluidHover と <FluidHoverHighlight /> を使います（@fluid/use-fluid-hover をインストールしてください）。ハイライトが滑らかに移動するコンポーネントの横で、行ごとに :hover の背景を設定してはいけません。
• 再レイアウトなしでウェイトを変える。 選択中／アクティブ／開いた状態などでテキストを太くする場合は、fontWeights トークンを使ったゴーストスパンパターンを使用し、レイアウトがずれないようにします。
• 文字スタイルは6つのロールから選ぶ。 @/lib/size-context の typeClass(role, variant) または useSize().type.<role> を使ってテキストのサイズを指定します（display、title、subtitle、body、caption、micro。それぞれサイズと行の高さを持ちます）。サーバーコンポーネントでは、@/lib/type-scale から typeClass をインポートします。テキストには3種類のウェイトを使います。テキストには fontWeights.normal、見出しと選択項目には fontWeights.semibold、display スタイルにのみ fontWeights.bold を使います。Tailwind の font-* は使ってはいけません。テキストカラーは foreground と muted の2種類のみとし、不透明度を変えてはいけません。大文字表記、文字間隔、眉見出しは使いません。text-[13px] のような値を直接指定してはいけません。また、cn() 内で text-caption を単独で使ってはいけません。標準の tailwind-merge はこれを色として解釈し、削除します。テキストフィールドには useSize().field を使います。これによりタッチスクリーンでは16pxが追加され、iOS Safari がフォーカス時にページをズームしないようにします。レンダリングされた Markdown は手作業でスタイルを設定した要素ではなく、.typeset に入れます（@fluid/typography をインストールしてください）。
• アイコンの切り替えは1つのセル内でクロスフェード。 2つのグリフを同じグリッドセルにマウントし、少しのぼかしと拡大縮小を加えてフェードさせます。スロットのサイズは変わりません。
• 入れ子の角は同心円状に。 角丸のサーフェスを別の角丸サーフェスの内側近くに配置するときは、inner radius = max(0, outer radius - inset - border) から導きます。inset は内側の余白（通常は親のパディング）、border は親の境界線の幅です。提供されている形状の組み合わせ（container 12/24px → bg 8/20px）は、合計4pxの inset を前提とした固定値です。それ以外の inset には、この組み合わせを使い回さず、@/lib/shape-context の nestedRadius() を使います。24pxを超える場合、間隔が非対称の場合、または内側のサーフェスが角まで届かない場合は、各レイヤーを個別に扱い、目視で調整してください。
• 移動には transform／opacity を使い、top／left／width／height は使いません。 これにより、モーションはコンポジター上で処理され、MotionConfig による軽減も追加作業なしで適用されます。
• テーマ設定は標準の shadcn に従います。 プロジェクトに既存のテーマトークン（色、角丸、フォント）があれば、そのまま適用します。別のトークンを独自に作ってはいけません。デフォルトではアイコンに Lucide を使います。ライブラリをアプリ全体で切り替える場合は、インストール済みコンポーネントを編集せず、@/lib/icon-context の IconProvider を使います。

最後の1％：細部にこそ、深いこだわりが宿ります

リファレンスではシステムについて説明しています。各コンポーネントの細部―― 正確な振る舞い、エッジケースでの動作、その理由――も記されています。影響範囲の大きい順に並べると、次のとおりです。

• references/craft.md — ドキュメント化された各システムとコンポーネント、および各トップレベルブロックの設計上のこだわりをまとめています。組み込みの動作、正確な値、その理由を記載しています。カタログでは、個別にインストールできるパーツを、それらを統括する親セクションへ案内しています。コンポーネントを組み合わせたり、ラップしたり、拡張したり、模倣したりする前に、該当するセクションをお読みください。既存の動作を知らずにコードを組み合わせて衝突させるのを防げます（ボタンはすでに独自の押下判定領域を処理し、セレクトは選択を300msにわたって受け付けたことを示し、パネルは折りたたまれる子要素の下にすでにスナップします）。
• インストール済みのソースが最終的な基準です。 これらのコンポーネントには、コメントで設計の理由が記されています。変更する前に、インストール済みのファイル（components/ui/*、hooks/*、lib/*）をお読みください。標準のshadcn版の動作を記憶に頼って、スタイルやタイミングを変更してはいけません。
• 設計上のこだわりはreferences/craft.mdに記載されています。 コピー用プロンプトの概要には、インストール方法、使用方法、propsのみが記載されています。コンポーネントを組み合わせる前に、該当する設計セクションを読み、箇条書きを提案ではなく制約として扱ってください。

注意点

• タイミングやホバーの動作を変更するために、インストール済みのコンポーネントを編集しないでください。代わりにラップするか、組み合わせてください。編集内容は次回の--overwriteインストールで失われ、アプリがシステムから逸脱します。
• フレーバー付きコンポーネントを基にしたコンポーネント（AskUserQuestions、ColorPicker、CommandMenu、InputCopy、InputMessage、各ブロック）も、base/プレフィックスを取ります。単一ソースの項目（badge、card、table、input-group、chat-message、thinking-indicator、各ライブラリとフック）は、どちらの種類のプロジェクトでも名前は共通です。
• レジストリはTailwind CSS v4、React 19、motion（motion/reactとしてインポート）を前提としています。古いスタックの場合は、ツリーの一部だけをインストールする前に、不一致があることをユーザーに伝えてください。
• 名前を指定したインストールに失敗した場合は、references/components.mdのカタログを確認してください。レジストリ名はコンポーネントの表示名と異なることがあります（例：TabsSubtle → tabs-subtle、Fluid Hover → use-fluid-hover、Motion → springs）。
• baseフレーバーはbase/<name>というパスにあります。@fluid/base/select、URL /r/base/select.jsonを使用してください。<name>-baseのような名前は内部ビルド名です。/r/<name>-base.jsonは意図的に404になります（ビルド時にこれらのファイルはbase/に移動されます）。そこでの404は、レジストリにbaseフレーバーがない証拠ではありません。結論を出す前に、ドキュメントに記載されたbase/<name>形式を試してください。また、推測したURLから「レジストリはRadixのみ」と記録してはいけません。