rico-design-md

Get Design MD

任意のウェブサイトをデザインシステムのドキュメントに変換したり、形式を相互変換したりできます。

すべきこと

• まず参照例を読みます。 形式を生成する前に、references/themes-github/ 内の対応するファイルを読み、構成を正確に合わせます。これにより、形式のずれを防げます。
• 意味に基づくトークン名を使います。 トークン名は、見た目（vapor-white、charcoal-canvas）ではなく役割（ink、surface-1、accent-blue）に基づいて付けます。ただし、説明的な名前がブランド独自のものである場合を除きます。
• シャドウの CSS 構文をすべて記録します。 「控えめなシャドウ」ではなく、rgba(255,255,255,0.1) 0 0.5px 0 0.5px のように記述します。後続の利用者が解析できる値を必要とします。
• 確認できたコンポーネントの状態をすべて記録します。 ホバー、フォーカス、アクティブ、選択済みなど、各状態で CSS プロパティが変わります。状態が欠けていると、実装が不完全になります。
• スクリーンショットと照合して色の値を確認します。 CSS の調査では、オーバーレイ効果、グラデーションの混色、ブラウザー固有のレンダリングを見落とすことがあります。視覚的な証拠と照合してください。
• オープンソースのフォント代替を提示します。 プロプライエタリフォント（GT Walsheim、Söhne）には、誰でもデザインを実装できるよう代替フォント（Mona Sans、Inter、DM Sans）が必要です。
• tokens.json に $description を含めます。 各トークンには、用途を説明する人が読める説明が必要です。これは DTCG 標準であり、誤用を防ぎます。
• ブランドボイスをデザイン批評として記述します。 概要の段落は、機能の一覧ではなく、デザイナーがブランドの視覚的な個性を説明するような内容にします。

してはいけないこと

• 仮の値を作らないでください。 ソースにないトークンカテゴリ（例：シャドウが確認できない場合）は省略し、欠落していることを記載します。捏造した値は信頼を損ないます。
• 複数のテーマのトークンを混ぜないでください。 サイトにライトモードとダークモードがある場合、どちらを記録するかユーザーに確認します。ダークモードが視覚的に異なる場合（例：Linear、Supabase）は、独自の4ファイルを含む別の dark/ サブディレクトリを生成することを提案します。両方のテーマのトークンを1つのドキュメントに混在させないでください。
• DESIGN.md に汎用的な「すべきこと／してはいけないこと」を記載しないでください。 各ルールは、具体的なトークンまたはプロパティを参照する必要があります。「十分なコントラストを使う」では役に立ちませんが、「ハイパーリンクとフォーカスリングにのみ accent-blue を使う」なら実行可能です。
• letter-spacing と line-height を省略しないでください。 これらがないタイポグラフィトークンは不完全です。トラッキングと行送りは、font-size と同じくらいブランドボイスを形作ります。
• 複雑なシャドウを単一の値にまとめないでください。 レイヤー化されたシャドウ（光の縁＋ドロップ）は簡略化して単一の box-shadow にせず、そのまま保持します。
• ブランドボイスの段落を省略しないでください。 これは今後の判断を導くデザインの根拠です。これがなければ、ドキュメントはトークンの羅列にすぎません。

トリガー時の動作

コマンド	出力
rico DESIGN.md [url]	DESIGN.md + preview.html（デフォルト）
rico preview [url]	preview.html のみ
rico tokens [url]	tokens.json のみ
rico variables [url]	variables.css のみ
rico theme.css [url]	theme.css のみ
rico 全部输出 [brand]	5ファイルすべて（DESIGN.md + preview.html + tokens + variables + theme）
rico 把 DESIGN.md 转为 tokens	形式変換

自然言語での指示にも対応します：「linear.app の DESIGN.md を作成して」「stripe.com からデザイントークンを抽出して」「[url] のプレビューを生成して」。

出力構成

themes/{brand-slug}/
├── DESIGN.md         # Full style reference (default)
├── preview.html      # Visual design system preview (default)
├── tokens.json       # DTCG format tokens
├── variables.css     # CSS custom properties
└── theme.css         # Tailwind v4 @theme

デフォルト出力： rico DESIGN.md [url] は DESIGN.md と preview.html の両方を生成します。

preview.html は、自己完結型の単一ファイルのデザインシステム参照ページです。

• Linear の上から下へのレイアウト（bento grid なし）。コンテンツに合わせて調整され、どのブランドにも対応します
• セクション：ヒーロー → 色（スウォッチ付き）→ グラデーション → タイポグラフィ（文字サイズのスケール＋フォント）→ 余白と形状 → シャドウ → 奥行きとサーフェス → コンポーネント（ライブプレビュー付き）→ すべきこと／してはいけないこと
• すべての仕様ファイル（DESIGN.md、tokens.json、variables.css、theme.css）のダウンロードリンク
• セクションアンカー付きの固定ナビゲーション
• スクロールをトリガーとする表示アニメーション
• レスポンシブ（モバイルファースト）
• references/themes-github/github-preview.html の GitHub プレビューテンプレートに基づいています

参考例

references/ ディレクトリには、テンプレートと例のファイルが含まれています。 生成前に該当するファイルを読み、構成を一致させてください。

• DESIGN.md テンプレート → references/DESIGN-TEMPLATE.md — 新しいサイトでは、このテンプレートを埋めてください
• DESIGN.md の例 → references/themes-github/DESIGN.md — GitHub の完成版
• preview.html の例 → references/themes-github/github-preview.html — GitHub のビジュアルプレビュー
• tokens.json → references/themes-github/tokens.json — DTCG 形式の参考資料
• variables.css → references/themes-github/variables.css — CSS カスタムプロパティの参考資料
• theme.css → references/themes-github/theme.css — Tailwind v4 @theme の参考資料

ワークフロー

ステップ 1 — ビジュアルデータの収集

ヒーロー、ナビゲーション、CTA、カード、タイポグラフィのセクション、フッターのスクリーンショットを撮影します。DevTools で CSS 変数、@font-face、計算済みスタイル、box-shadow、border-radius、間隔を確認します。

理由： スクリーンショットでは、CSS の調査だけでは見落とす装飾要素（グラデーション、グロー、イラスト）を捉えられます。

ステップ 2 — トークンの抽出

色 — 確認した値をセマンティックトークンに対応付けます。

確認した値	トークン	種類
ページ背景	canvas	color
カード背景	surface-1	color
浮き上がった背景	surface-2	color
メインテキスト	ink	color
セカンダリテキスト	ink-muted	color
リンク／アクセント	accent-blue	color
成功	semantic-success	color
エラー	semantic-error	color
境界線	hairline	color
グラデーション	gradient-{name}	gradient

タイポグラフィ — 各フォントについて、fontFamily、fontSize、fontWeight、lineHeight、letterSpacing を記録します。サイズをトークンに対応付けます：110px→display-xxl、85px→display-xl、62px→display-lg、 32px→display-md、22px→headline、15px→body、14px→body-sm、13px→caption、12px→micro。

OpenType の font-feature-settings を確認します：cv01-99（字形バリエーション）、ss01-20 （スタイルセット）、tnum（等幅数字）、dlig（任意の合字）。

フォントの代替候補：GT Walsheim → Mona Sans／Geist／Inter 600-700。Söhne → Inter／DM Sans。

間隔 — 基準単位を特定します：4 の倍数 → base=4px。5／10／15／20 の倍数 → base=5px。

角丸 — xs(4px)·sm(6px)·md(10px)·lg(15px)·xl(20px)·xxl(30px)·pill(100px)·full(9999px)

シャドウ — CSS の完全な構文のみを使用します。

ステップ 3 — コンポーネントのドキュメント化

各コンポーネントについて、状態を含むすべての CSS プロパティを記録します。

### Primary Button
**Role:** Main CTA
- background: `{colors.ink}` (#ffffff)
- color: `{colors.canvas}` (#0a0a0a)
- border-radius: `{rounded.pill}` (100px)
- padding: 10px 15px
- font: 14px/500/1.0/-0.14px
- hover: opacity 0.85
- active: transform scale(0.97)

コンポーネント：ナビゲーション、ボタン（プライマリ／セカンダリ／半透明／アイコン）、料金プランのタブ、入力欄（デフォルト／フォーカス時）、カード（標準／注目／スポットライト）、比較行、フッター。

ステップ 4 — ブランドボイスの記述

デザイン批評として 5～8 文で記述します：主要な表面 → 書体の個性 → アクセントカラーの使い方 → 奥行きの表現方法 → 特徴的なリズムの変化 → コンポーネントの表現。

ステップ 5 — Do's / Don'ts の記述

それぞれ 7～8 項目を記述します。すべてのルールで、具体的なトークンを理由とともに示します。

ステップ 6 — 出力の生成

参考例を読み、指定されたファイルを生成します。

デフォルト： DESIGN.md と preview.html を生成します。

preview.html の生成：

1. references/themes-github/github-preview.html のテンプレートを読みます
2. すべての CSS カスタムプロパティ（:root 変数）をブランドのトークンに置き換えます
3. 色見本、文字サイズのサンプル、間隔バー、角丸のボックス、シャドウのデモ、奥行きレベル、表面カード、コンポーネントのプレビューを、ブランドの実際の値に置き換えます
4. ヒーローのテキスト、タグ、ダウンロードリンクを、ブランド固有の内容に置き換えます
5. ナビゲーションの GitHub アイコンリンクを、該当する場合はブランドのリポジトリ URL に置き換えます
6. 全体の構成とセクションの順序は維持し、内容とトークンのみを変更します
7. 文字サンプルには、ブランドの実際のフォントファミリーを使用します（フォールバックは Inter）
8. コンポーネントカードを、ブランドの実際のコンポーネント（ボタン、入力欄、カード、ナビゲーション）に合わせて調整します

単一ファイルの原則： preview.html は、完全に自己完結している必要があります（インライン CSS を使用し、外部依存関係は Google Fonts のみ）。file:// プロトコル経由で直接開いた場合も動作する必要があります。

フォーマット変換

DESIGN.md → tokens.json / variables.css / theme.css

Markdown テーブルを解析し、出力先の形式にマッピングします。Role 列から $description を含めます。 variables.css は次の項目ごとにグループ化します：Colors、Font Families、Type Scale、Weights、Spacing、Layout、 Border Radius、Shadows、Surfaces。

tokens.json → DESIGN.md

DTCG グループを解析し、Markdown テーブルを生成して、トークンの関係からコンポーネントを推定します。

variables.css → DESIGN.md

:root {} を解析し、プレフィックス（--color-、--font-、--text-、--spacing-、--radius-）ごとにグループ化します。 → テーブルを生成します。

tokens.json ↔ variables.css ↔ theme.css

直接マッピングします：$value → --{name}: {value} → @theme { --{name}: {value} }

エッジケース

• SPA／クライアントレンダリング： CSS ファイルには「ページのソースを表示」とネットワークタブを使用します
• 圧縮された CSS： DevTools の計算済みスタイルパネルを使用します
• マルチテーマ： 文書化するテーマをユーザーに確認します。ダークモードが見た目に明確に異なる場合は、別の themes/{brand}-dark/ サブディレクトリを提案します。両方のテーマのトークンを混在させないでください
• 認証が必要なページ： 公開されているマーケティングページに焦点を当てます
• トークンがない場合： 値を捏造せず、該当セクションを省略します