Retrixは、マスタ管理・顧客管理・案件管理・設定のような業務の画面を組み立てるためのデザインシステムです。手本は2012年前後の37signalsの画面（Basecamp 2・Highrise）です。クリーム色の机の上に白いシートを置き、そこに表や一覧や文章を並べる見た目で、情報を多く並べても読み順が崩れないようにします。
- 表を中心にしたマスタ画面が得意：並べ替え・列の幅の変更・行の選択と一括操作を持つ
Tableを中心に、一覧・詳細・編集の画面を組めます。文書・予定・連絡・ボードの画面も同じ作法で組めます。 - 中央に揃えた画面構成：
AppShellは、ヘッダー（アプリの名前・主な移動先・検索）と白いシートを画面の中央に揃えます。上の階層はシートの背後に重ねたシートで、分類ごとの移動先はシートの外の先頭側の列で示します。画面の端に固定するサイドバーは持ちません。 - 平らな塗りと罫線と枠：シートとカードは枠を持たず、四方へのぼかしの影で机から浮かせた白い面です。一覧と表の行は罫線で区切り、欄とボタンは1pxの枠を持ちます。控えめなボタンは高さ22px・角丸5pxの平らな白、主操作は平らな緑です。グラデーションとアニメーションは使いません。リンクは青緑の文字に下線を引き、今日・選んだ行・更新した行は黄色のハイライトで示します。
- フレームワークに依存しない基盤：CSSとセマンティックHTMLが基盤です。同じHTMLを出力するHono JSXのSSRコンポーネントと、必要な動作を担うStimulus controllerも提供します。
ButtonやInputなどの基本コンポーネントに加え、Table・Board・Calendar・DangerZoneなど、特定の用途で情報と操作をまとめるコンポーネントを含めて約90種類を提供します。業務データ・権限・通信・永続化は利用するアプリが持ち、Retrixは情報の読み順・配置・操作を共通化します。
| 画面の要素 | 使うコンポーネント |
|---|---|
| アプリの画面構成 | AppShell（ヘッダー・シート・trail・aside）。AppShellを使わない時はSurface |
| 名前で探す移動と操作 | CommandMenu（AppShellのcommandsに置く検索） |
| 同じ列で項目を見比べる一覧 | Table。セルを矢印キーで移動するならGrid、親子の階層があるならTreegrid |
| 題名と補足で読ませる一覧 | DataList。一つの対象の属性はValueList |
| ページの見出しと操作 | PageHeader、まとまりの見出しはSection |
| 入力のフォーム | Field・FieldGroup・Inputなど。修正先の一覧はErrorSummary |
| 対象に対する操作 | Button・ButtonGroup・SplitButton・DropdownMenu |
| 判断が必要な処理と近くの補足 | Dialog、Popover |
| 案内・結果・空の状態 | Notice、Toast、EmptyState |
| 作業面に付属する開閉式のパネル | Wing（AppShellのwings） |
全てのコンポーネントの使いどころはコンポーネントのリファレンスにあります。
pnpm add @tknf/retrix
hono・@hotwired/stimulus・@tknf/stimulus-uiはpeer dependencyです。Hono JSXのコンポーネントを使う場合はhono、controllerを使う場合は@hotwired/stimulusと@tknf/stimulus-uiを追加します。CSSだけで使う場合は追加しません。ESMのみを提供しています。詳しくは導入を参照してください。
import { Button, Field, Input } from "@tknf/retrix/hono";
const EditForm = () => (
<form method="post" action="/items">
<Field id="title" label="名前" help="一覧に表示する名前です。">
{(attributes) => <Input {...attributes} name="title" required />}
</Field>
<Button type="submit" variant="primary">
保存する
</Button>
</form>
);
CSSだけでも同じHTMLで使えます。
<button class="rx-button" type="submit" data-variant="primary">保存する</button>
開閉・選択・キーボード操作が必要なコンポーネントは、@tknf/retrix/controllersのcontrollerを決められた登録名で登録します。controllerは自動では登録しません。次はTableの並べ替え・行の選択・列の幅の変更を使う場合です。
import { Application } from "@hotwired/stimulus";
import {
TableController,
TableResizeController,
TableSelectController,
TableSortController,
} from "@tknf/retrix/controllers";
const application = Application.start(); // 既存のApplicationがあればそれを使う
application.register("table", TableController);
application.register("table-sort", TableSortController);
application.register("table-select", TableSelectController);
application.register("table-resize", TableResizeController);
登録名の一覧はcontrollerの登録名にあります。
見本と利用例は公開カタログで確認できます。 ローカルでカタログを起動する場合は、リポジトリで次のコマンドを実行します。
vp install
vp run dev
http://127.0.0.1:5173にカタログを表示します。DB・認証・外部サービスは不要です。
/：全コンポーネントを分類ごとに並べます。ヘッダーの末尾側の検索（CommandMenu）から名前で探せます。/components/<名前>：見本、使い方、同じ見本のHTMLとHonoのコード。/apps/customersなど：コンポーネントだけで組んだ利用例のアプリ「つむぐ」（取引先のマスタ・プロジェクト・受信トレイ・予定・文書・資料・売上・検索・メンバー・設定）。
| エントリーポイント | 内容 |
|---|---|
@tknf/retrix/css/* |
フレームワークに依存しないCSS |
@tknf/retrix/hono |
HonoのSSRコンポーネントと型 |
@tknf/retrix/controllers |
Stimulus controller（自動では登録しない） |
@tknf/retrix/icons.svg |
アイコンのSVGスプライト |
テーマはライトテーマだけを提供しています。
-
導入：CSSだけで使う、Honoで使う、controllerを登録する
-
デザインの原則：画面構成・色・形・文字・状態・余白の決まり
-
トークン：
--rx-*の種類と使い方 -
CSSの構造：読み込み順、レイヤー、クラス名の決まり
-
コンポーネント：全コンポーネントのリファレンス。使いどころ、使い方、キーボード、props、controller、読み込むCSS、コード
-
controller：登録の決まりとイベントの規約
-
アイコン：大きさ、配置、ライセンス
Retrixを使って画面を組むためのAgent Skillをskills/retrixに同梱しています。コンポーネントの選び方、CSSの読み込み、controllerの登録、文字位置などの注意点をまとめています。
Codexでは、組み込みのskill installerでこのリポジトリから入れます。
$skill-installer Install the retrix skill from https://github.com/tknf/retrix/tree/main/skills/retrix
Claude Codeでは、skills/retrixディレクトリを利用するプロジェクトの.claude/skills/retrix/に置きます。Codexでプロジェクトだけに置く場合は.agents/skills/retrix/に置きます。
Retrixの開発に参加する場合は開発ガイドを参照してください。脆弱性は公開のissueではなく、セキュリティポリシーの手順で報告してください。
RetrixはMITライセンスで公開しています。
アイコンにはPhosphor Icons（MIT）を使っています。著作権・許諾文はスプライトとdist/PHOSPHOR-LICENSEに同梱しています。