@shadcn/lint: エージェントが書く UI を
デザインシステムに合わせるリンター

どんなツールか

@shadcn/lint は、Tailwind v4 のデザインシステム向けのリンターです。ESLint と Oxlint のプラグインとして動きます。名前に shadcn とありますが、shadcn/ui を使っていないプロジェクトでも使えます。

README では「agent-first」、つまり UI を書くコーディングエージェントのために作ったと説明されています。

実際のエラーは次のような文面です(README の画像より)。何がだめかに加えて、代わりに何を使えばよいか、どのファイルを見ればよいかまで書かれています。

型ではなくリンターで決める理由

「Button の margin と width は外から変えてよいが、padding は Button が決める」という決まりを考えます。TypeScript でも、style の型を Pick<CSSProperties, "margin" | "width"> に絞れば守らせることはできます。

もう1つの理由は、リンターの設定はコンポーネントのコードを変えずに書けることです。複雑な型を作る必要もありません。

リンターが読んでいるもの

リンターはアプリを動かさず、ソースコードだけを読みます。そのとき、次の4つを材料にしてエラーと提案を作ります。

クラスは className だけでなく、cn・clsx・cva などの呼び出し、同じファイル内の変数(1段まで)、className を受け渡すラッパーコンポーネントもたどって調べます。

6つのルール

本番のデザインシステムを調べ、コーディングエージェントで試しながら作られたルールです。それぞれ warn か error で有効にします。

何を許すかと、エラーの文面を決める

no-restyle は、クラスを色・文字・余白などのカテゴリに分けて判定します。基本の設定 allow: ["layout"] では、配置(margin や width)だけを外から変えてよいことになります。

コンポーネントごとに別の決まりを持たせたいときは contracts を使います。次の図は、カードのタイトルには文字の調整を、カードの中身には余白の調整を許した例です。

contract は書いたキーだけを置き換え、残りは上の設定を引き継ぎます。allow を書くときは、配置を残したければ layout も並べる必要があります。

エラーの文面も差し替えられます。{{sizes}} や {{variants}}、{{file}} などのプレースホルダーには、実際のコンポーネントの値が入ります。

エージェントで試した結果

作者たちは 150 回を超えるタスク実行で試しています。README の表は、モデルごとに1回分の実行で、lint のフィードバックを受ける前と後のエラー数を比べたものです。

ルールの説明文だけを渡して自分で見直させる場合と、lint のエラーを渡す場合も比べています。Claude の3モデルでは、エラーを渡したほうが修正のコストが 10〜48% 低く、全タスクが1回の修正で通りました。

差が大きいのは小さいモデルです。Haiku はルール文だけだと、間違ったトークン名を3回見直しても見つけられませんでしたが、そのクラスを名指しするエラーを渡すと1回で直しました。

別のモデル(judge)で修正前後の見た目を比べると、ほぼすべての組が 10 点満点中 9〜10 点でした。見た目を捨ててエラーを消したわけではない、という確認です。

見えないものと限界

lint が通っても、すべてのスタイルの経路を調べたことにはなりません。ドキュメントには、見えないものが具体的に挙げられています。

わざとすり抜けを試す7つの実験では、5つを検出し、2つがすり抜けました。

導入の手順

必要なもの: Node.js 20.19 以上、Tailwind v4、ESLint 9.30 以上または Oxlint 1.80 以上(Oxlint の JS プラグイン API はまだ alpha)。npm の @shadcn/lint は 2026-09-15 時点で 0.1.0、ライセンスは MIT です。

まとめ