Tavero

Tavero

エージェントが作成するUIの一貫性を保ちます。
taveroui.com · ドキュメント · デモ

Taveroは実行中のReactアプリをスキャンし、ボタン、カード、色、間隔の不整合を見つけ、修正に必要なファイル、行、使用すべきトークンをコーディングエージェントに提示します。マシン上でCLIとして、Claude Code、Cursor、Codexなどのエージェント向けMCPサーバーとして、また意図したデザインを判断できるローカルパネルとして動作します。

_{このリポジトリのAcmeデモ（demo/acme）で実際に検出した結果です。3つの幅で6ページをスキャンしています。}

仕組み

1. スキャン。 Taveroは開発サーバーをChromiumで開き、アプリでログインが必要な場合はログインした状態で、モバイル、タブレット、デスクトップの各幅でスキャンします。
2. 特定。 React独自の開発モードデータを使い、表示されるすべての要素を、その要素を描画したReactコンポーネントとソース行に対応付けます。プロジェクトには何も追加しません。
3. 検出。 4つのルールで、描画結果をトークンおよび描画結果自体と比較します。対象はボタン、カード、色、スケールです。
4. 修正。 各検出結果はタスクです。対象、場所（file:line）、現在の値、期待されるトークンまたはコンポーネントが示されます。エージェントが修正した後、数秒で1つのルートを再スキャンし、問題が解消されたことを確認します。

クイックスタート

Node 20以降、ViteまたはNextを使ったReact 19アプリが開発モードで動作している必要があります。

npm i -D tavero
npx playwright install chromium                      # once per machine
npx tavero login --url http://localhost:5173/login   # once, if the app has a login
npx tavero scan --url http://localhost:5173
npx tavero findings

id            sev     rule     decision  title                                                         evidence
f_c75ac3d6a2  high    buttons            7 text button styles                                          7
f_36cb934b5e  high    scales             13 distinct padding values, 1 declared                        12
f_94269275c1  medium  buttons            Two text button styles differ only in radius, paddingY, pa…   2
f_057122e1f9  medium  buttons            4 place(s) write <button> directly in page or section mark…   4
… 30 more, use --page 2

npx tavero finding f_ff30adc07c   # evidence: file:line, current value, expected token, crops
npx tavero context                # a ~1,500-token brief of the design system for an agent
npx tavero report                 # a self-contained HTML report

Taveroが書き込むのは<project>/.tavero/だけです。すべての読み取りコマンドで--jsonを指定でき、テキスト出力はエージェントのコンテキストに収まるよう20行までに制限されています。

エージェントから使う

tavero mcpは、9つのツールを備えたstdio上のMCPサーバーです。クライアント用の設定を表示し、指定された場所に貼り付けます。

npx tavero mcp --print-config claude       # Claude Code: .mcp.json
npx tavero mcp --print-config cursor       # .cursor/mcp.json
npx tavero mcp --print-config codex        # .codex/config.toml
npx tavero mcp --print-config gemini       # .gemini/settings.json
npx tavero mcp --print-config antigravity  # .agents/mcp_config.json
npx tavero mcp --print-config vscode       # .vscode/mcp.json (GitHub Copilot)
npx tavero mcp --print-config windsurf     # ~/.codeium/windsurf/mcp_config.json

続いて、docs/AGENTS.snippet.mdをAGENTS.md、CLAUDE.md、またはGEMINI.mdに貼り付けます。これにより、エージェントはUIを作成する前にデザインのコンテキストを読み取ります。SKILL.mdは、ワークフロー全体を記載したAgent Skillです。

シェルを使わずにClaude CodeでAcmeデモを実行した記録です。所要時間は29秒です。

› tavero_context
  Action button is Button from src/components/Button.tsx (props: variant)
› tavero_findings rule=colors
  f_ff30adc07c  Color #4263eb is not a project token
› tavero_finding f_ff30adc07c
  src/app.css:33  literal #4263eb in source
  expected  --acme-primary #3b5bdb (ΔE 3.5)
  edit src/app.css:33  background: #4263eb → var(--acme-primary)
› tavero_scan routes=/billing rules=colors
› tavero_diff
  resolved  f_ff30adc07c  Color #4263eb is not a project token
  resolved  f_18862a0332  Hardcoded color #4263eb in 1 place(s)
  new  0

ツール	用途
tavero_context	デザインシステムの概要。UI作成前に呼び出します
tavero_findings、tavero_finding	重大度の高い順に問題を表示します。1つの問題について、根拠、期待値、正確な再スキャン呼び出しを表示します
tavero_scan	アプリをスキャンします。修正後は、変更したroutesとrulesだけを指定します。進捗をストリーミングし、キャンセルできます
tavero_diff	前回のスキャンから解消、新規、未変更の検出結果を表示します
tavero_components、tavero_component、tavero_show、tavero_tokens	コンポーネント一覧、切り抜きのパス、トークン

ルール

ルール	報告内容
buttons	テキストボタンとアイコンボタンのスタイルの種類と、それらを描画するコンポーネント、よく似たペア、ボタンコンポーネントの外に書かれた<button>
cards (予備段階)	カードスタイルの種類、よく似たペア、インラインで構築されたカード風コンテナー
colors	トークンに含まれない色と最も近いトークンおよびΔE、独自パレットのあるプロジェクトで使われているTailwindのデフォルトカラー、よく似たペア、ファイル名と行番号付きのハードコードされたリテラル
scales	トークンで宣言されたスケールから外れた、角丸、パディング、間隔、フォントサイズ、太さ、シャドウの値

意図を判断する

npx tavero ui --open   # http://127.0.0.1:4747

エージェントを使う人のためのローカルパネルです。キーボードで検出結果を確認し、判断します。再スキャンしなくても、次回の呼び出し時にエージェントが各判断を確認できます。

判断	エージェントに表示される内容
修正	検出結果が最初に表示され、作業対象として確認済みと示されます
意図的	検出結果が新しい場所で見つかるまで非表示になります
正規	ボタンとカードのバリエーションでは、基準となるバリエーションと許可されるバリエーションを指定します。必要に応じて「primary」や「ghost」などの名前を付けられます。それ以外はexpectedとして扱われます
メモ	検出結果とともに表示されるメッセージです

判断は、安定した検出結果IDをキーとして.tavero/decisions.jsonに保存されます。チームやエージェントと共有するには、これをコミットしてください。npx tavero ui --export ./panelを実行すると、静的な読み取り専用パネルが書き出されます。

要件と制限

• ViteまたはNext（App Router、Turbopack）上の開発モードで、React 19が必要です。React 18ではデバッグデータの形式が異なるため、現時点ではサポートされていません。
• トークンはCSSカスタムプロパティとTailwind 3または4のテーマから読み取られます。
• カードの検出はヒューリスティックなため、cardsルールは予備段階としてマークされています。
• Taveroはローカルで実行され、外部にデータを送信しません。アカウントもテレメトリーもありません。

開発

npm ci
npx playwright install chromium
npm test             # unit and Playwright runtime tests; starts the test apps itself
npm run typecheck
npm run build

ウェブサイトはsite/（Next.jsの静的エクスポート）にあります。npm run site:install && npm run site:devで起動し、npm run site:auditでゲートを実行します。ゲートでは、サイト自体に対するTaveroの実行（重大および中程度の検出結果が0件であること）、Lighthouse、axe、3種類の幅を確認します。

src/
  core/      scan orchestration, aggregates, query API, decisions, diff, stable ids
  project/   framework detection
  static/    tokens, Tailwind theme and palette, hardcoded colors, component index
  runtime/   dev server, session, crawl, in-page collector, attribution, crops
  rules/     signatures and the four rules
  context/   the agent-facing brief
  report/    HTML report
  mcp/       MCP server, tools, client configs
  ui/        local panel and static export
  cli/       the command line
demo/acme/   a small dashboard with deliberate drift, used by tests and the website
test/        unit and runtime tests with mini Vite and Next apps
design/      design tokens shared by the panel and the website
site/        the website

プルリクエストを作成する前に、CONTRIBUTING.mdを確認してください。

ライセンス

MIT