visant-refine

Visant Refine

仕上げ。このスキルでは、要素を含める判断はすでに行われ、別の場所でその根拠も示されているものとし、描画方法だけを扱います。

階層は交渉の余地がありません

スキル	判断する内容
visant-frontend	要素が存在するべきかどうか、および要素が動かすビジネス変数。カットテストはここで行います。
dataviz	チャートが正しいかどうか：形式、機能に応じた色分け、パレットの検証、アンチパターン。
visant-motion	イージングと継続時間のSSoTに加え、React、Tailwind、Radix 固有の注意点。
revenue-centric-design	これをアニメーション化し、あれはしない理由（注意をどこに向けるか）。
このスキル	要素の描画方法と、隣接する要素と同じ系統に見えるようにする方法。

Refine は要素の正当性を主張しません。「この要素はどの変数を動かすのか」という問いへの答えが無言なら、修正すべきなのは磨き上げることではなく、削除することです。誰にも使われないデータの美しいチャートは、見栄えがよくなっただけの粗悪なものにすぎず、醜いバージョンより多くの注意を奪います。

作業は必ず次の順序で進めます。

1. visant-frontend のカットテストに合格します。要素ごとに変数を明記します。
2. すでに存在するものを洗い出します。以下の「描画の前に」を参照してください。
3. 形式を選びます。チャートコードの最初の行を書く前に dataviz を読み込みます。
4. 共通の構造（下表）に沿って描画します。
5. その後で初めて、references/smart-motion.md を参考にアニメーションを決めます。
6. visant-frontend の指示に従って検証します（実データを使った 390px、バックエンド停止時、キーボード）。さらに、次の両方のゲートを実行します。

node ~/.claude/skills/visant-refine/scripts/refine-scan.mjs <target>   # finishing layer
node ~/.claude/skills/visant-killer/scripts/killer-scan.mjs --report AUDIT.md <target>

--report は必須です。killer-scan は、サーフェステーブルと ## Screen seen セクション（## Tela vista でも可）がなければ GATE OPEN を出力しません（--init-report AUDIT.md でひな形を生成できます）。また、refine-scan 単独でゼロになっても、完全な合格ではありません。検出器がクリーンだと、終了コードが出るため仕上げまで終わったように感じられます。そしてまさにそのために、visant-frontend が完全に省略されてしまいます。

refine-scan には、コンパイルと lint を通過しても問題を引き起こす、次の 6 つのルールがあります。チャートのプロパティにおける生の色（recharts をインポートしているファイルのみ）、状態ラッパーのないチャート、スコープ指定のない defs の id、SSoT の範囲外のイージングまたは継続時間、UI での transition-all と ease-in、幅または高さのアニメーションです。ファイル内で ChartState、isEmpty、noData、semDado、vazio のいずれかに言及していれば、状態ラッパーとして認識されるため、どのリポジトリでも機能します。components/ui の指摘は抑制されます（上流のプリミティブ）が、最後に必ず集計され、隠されることはありません。ゼロを信用する前に、--self-test で 6 つのルールが両方向に検証されることを確認してください。

描画の前に：リポジトリにすでにあるものを見つける

まず検索せずに新しいプリミティブを作ってはいけません。ほとんどの refine の依頼は新規作成ではなく組み合わせですが、それを知るには確認が必要です。対象リポジトリのルートで、次の順に実行します。

# 1. installed chart lib (recharts, visx, nivo, chart.js, echarts, d3)
grep -E '"(recharts|@visx/[a-z-]+|@nivo/[a-z-]+|chart\.js|react-chartjs-2|echarts|d3)"' package.json
# 2. existing chart state wrapper and tooltip
grep -rlE 'ChartState|ChartContainer|ChartTooltip|isEmpty' --include=*.tsx --exclude-dir=node_modules .
# 3. slider, ratio bar and skeleton primitives
find . -path ./node_modules -prune -o -type f \( -iname 'slider.tsx' -o -iname 'progress.tsx' -o -iname 'skeleton.tsx' \) -print
# 4. motion tokens (easing and duration SSoT)
grep -rnE -- '--(ease|dur|duration)-[a-z0-9-]+:' --include=*.css --exclude-dir=node_modules . | head
find . -path ./node_modules -prune -o -type f -iname 'motion.ts*' -print
# 5. color token format (bare HSL channels or full color)
grep -nE -- '--(primary|muted-foreground|destructive):' $(find . -path ./node_modules -prune -o -name 'globals.css' -print)

最初のコード行を書く前に、見つかったものを「必要なもの | 存在する場所」の表に書き出します。不足しているものについては、次の順で検索します。

1. リポジトリ自体（上記のコマンド）。
2. Visant ライブラリ：ui.visantlabs.com にある、あらゆるプロジェクトですでに仕上げられたパーツ：gauge、sim-slider、measure-bar、activity-heatmap、streamgraph、count-up、elastic-slider、skeleton-rail。components.json に "@visant": "https://ui.visantlabs.com/r/{name}.json" を設定し、npx shadcn@latest add @visant/<name> でインストールします。各パーツの仕様書は /r/<name>.md にあります。
3. 公式 shadcn プリミティブ（npx shadcn@latest add slider progress skeleton）。

明示的な許可なしに、デザインシステムのコンポーネントを作成または編集してはいけません。インストールする前に警告してください。プリミティブのデフォルト設定の上書きは、利用側に記述します。

共通の構成

画面がデザインされているように見えるのは、各要素がそれぞれ美しいからではなく、すべての要素が同じ順序で同じことを伝えているからです。仕上げの要素はすべて、常に同じ視覚的な順序で次の4つの役割を担います。

役割	内容	表示方法
ラベル	測定対象の名前	text-xs uppercase tracking-wider text-muted-foreground
値	判断の基準となる数値	ブロック内で最も太いウェイト、tabular-nums、ニュートラルカラー
補足情報	値に意味を与える物差し（上限、目標、期間、基準値）	text-xs text-muted-foreground、値の横
根拠	物差しに対する値を示す形状	バー、ゲージ、スパークライン、帯

すべての要素で、次の4つのルールを適用します。

• 色は例外です。 ニュートラルカラーを1つ使い、実際に例外がある場合に限り色を使います。テキストにはテキストトークンを使い、系列色は使いません。色はエンティティに基づき、順位に基づくものではありません。
• 物差しのない数値は使いません。 補足情報のない値は単なる雑学です。「R$ 25.201,42」では何もわかりませんが、「売上総額の11,3%」ならわかります。
• 分母がなければ比率もありません。 分母がゼロの場合はnullとし、その行は表示しません。「0,0%」は事実に反します。
• 形状が有効なのは、その適用範囲内だけです。 比率バーは、値が上限内に収まる間は尺度を示します。上限を超えるとバーは飽和し、誤解を招きます。その場合は、どれだけ超えたかを示す数値でバーを置き換えます。これは細かな点ではなく、最もよく現れるルールです。
• 空、エラー、読み込みはそれぞれ異なる状態であり、どれもデザインされている必要があります。
• 両端で同じ種類を使います。 同じ種類の2つ目の要素を追加するときは、1つ目を抽出します。同じものに2つのバリエーションができたら、3つ目が生まれる始まりです。

各要素の構成、プロパティ、よくある間違いについては、要素カタログを参照してください。 references/elements.md。

チャート

datavizを読み込み、その手順に従います。ここで変わる点、そこにはない点は次のとおりです。

• 系列色はトークンから取得し、最初の線を描く前にトークン形式を確認します（上記のコマンド5）。CSSに素のHSLチャンネル（--primary: 0 0% 9%、古いshadcnのデフォルト値）が格納されている場合、プロパティにはラッパーが必要です。stroke="hsl(var(--primary))"のように指定します。素のvar(--primary)は文字列0 0% 9%になるため、色として認識されず、tsc、lint、検出器のいずれでもエラーが出ないまま線が表示されなくなります。JSXでTailwindのパレットを直接使うことや、16進カラーを使うことも避けてください。text-purple-400のようなクラスは汎用検出器をすり抜けます。
• すべてのチャートを状態ラッパーで囲みます（リポジトリのChartState、またはコマンド2で見つかった同等のもの）。軸だけが空の状態は、datavizにおける「0 items」です。
• clipPathとdefsのIDは名前が重複すると衝突します。 同じページに同じidのチャートが2つあると、互いに上書きされます。インスタンスごとにスコープを設定してください。
• 上限と目標は、ラベル付きのReferenceLineで示し、背景色では表しません。 線は事実を示しますが、色は意見を示すものです。
• descriptionと大きなペイロードはチャートデータに含めません。

すぐに使えるrechartsのレシピ（上限を示すReferenceLine、帯を横切る累積値、軸なしのスパークライン、比率ゲージ）と、機能別トークン対応表については、次を参照してください。 references/charts.md。

スライダーシミュレーション

シナリオを投影するスライダーは、設計で投影と事実を分けていなければ、誤解を招く装置です。最低限、次の仕様を満たす必要があります。

1. 実際の値は常に画面に表示します。トラック上に示し、どちらの値かラベルで明記します。同じ単位で種類の異なる2つの数値を、ラベルなしで表示すると、読み取りを誤らせます。
2. 重要な上限値で止まります。スライダーは、判断を変える数値（制度上限や税率区分など）で止まり、切りのよい倍数では止まりません。
3. 帯はトラック上に描画します。ユーザーはドラッグする前に、制度が切り替わる位置を確認できます。
4. 実際の値に戻す操作はワンクリックで、シミュレーション中のみ表示します。
5. 何も永続化しません。シミュレーション結果はデータベースに書き込まず、共有が要件に含まれる場合のみ、URLに状態を含めます。
6. キーボードで操作できます。aria-valuetext で書式設定済みの値を読み上げます。

状態パターンとよくある間違いを含む仕様全文： references/simulators.md。

スマートアニメーション

スマートとは、機会があるときではなく、変数に応じて選ばれるということです。ほかのルールの基準となるルールは、判断を左右するものを、判断が変わるタイミングでアニメーションさせることです。

• ユーザーが手動で操作している値（スライダーのドラッグ）は、アニメーションさせません。指の動きに追従させます。ここでのアニメーションは、見栄えのよい遅延にすぎません。
• 結果として変化する値（スライダーの再計算後の合計値）は、新しい数値まで短く一度だけカウントアップさせてもかまいません。
• 上限を超えることはイベントです。イベントには重みを持たせるべきです。アニメーションさせるのは帯の状態変化であり、カードの発光ではありません。
• ユーザーが直前の画面遷移ですでに数値を読んでいる場合、マウント時には何もアニメーションさせません。
• 1日に100回表示されるものはアニメーションさせません。

各ケースの判断表とSSoTの値： references/smart-motion.md。

実例：税金パネル

税金シミュレーションパネルは、3つのトピックすべてを組み合わせた典型例です。何を取り入れ、何をなぜ却下したかを、手順を追って references/tax-panel-case.md に記載しています。数値パネルを調整する前に読んでください。よくある間違いは同じです。上限に張り付くバー、予測と事実の混同、誤ったデータのアニメーションです。