rtl-design

RTL デザイン

正確な RTL インターフェース（方向、双方向テキスト、数字、カレンダー、Unicode）と、美しいインターフェース（ペルシャ語に合わせたタイポグラフィとフォントの組み合わせレシピ）を作りましょう。LTR デザインを単に反転させた後付けにはしません。ペルシャ語が中核のモジュールですが、方向のレイヤーはアラビア語とヘブライ語にも適用されます。

防ぐべき失敗は 2 つあります。LTR の習慣が入り込むこと（物理方向を前提とした CSS、反転されないアイコン、ラテン文字のメトリクス）と、「技術的には RTL」でも雑な仕上がりになること（方向は正しくてもラテン文字の行高が窮屈、どこでも同じデフォルトフォントを使う）です。

基本ルール — 常に適用する

方向とレイアウト

1. ルートで一度だけ方向を設定します（<html dir="rtl" lang="fa"> / Flutter のロケール fa）。text-align／float／行の反転で RTL を偽装してはいけません。
2. 物理方向ではなく論理方向で記述します。margin-left ではなく margin-inline-start、EdgeInsets.only(left:) ではなく EdgeInsetsDirectional、left／right ではなく start／end を使います。物理方向の値は、動画コントロール、地図、コードエディターなど、物理的な位置に固定されるものに限ります。
3. 方向性のあるアイコンを反転します。シェブロン、矢印、戻る／次へ、元に戻す／やり直し、返信、送信、ページネーションです。反転してはいけないもの： 再生／一時停止、メディアのシーク／巻き戻し、音量、電話、時計、ロゴ、チェックマーク、検索、更新です。複製したアセットではなく、transform: scaleX(-1)／matchTextDirection で反転します。

テキストとデータ 4. ペルシャ語では ی（U+06CC）と ک（U+06A9）を使います。ペルシャ語のテキストでアラビア語の ي／ك を使うのはバグです。入力境界で正規化してください。 5. 数字：UI テキストにはペルシャ数字 ۰–۹ を使います。電話番号、OTP／コード、カード番号、技術 ID にはラテン数字を使います（LTR の独立したテキスト領域として扱います）。アラビア・インド数字 ٠–٩ はペルシャ語では使いません。 6. ペルシャ語ユーザー向けの日付には、ジャラリ暦、ペルシャ語の月名、ペルシャ数字を使います — «۵ مرداد ۱۴۰۵»。ISO／グレゴリオ暦形式で保存し、表示時に変換してください。 7. メールアドレス、URL、電話番号、コード、ラテン文字の名前など、LTR の独立したテキスト領域は dir="auto"／<bdi>／unicode-bidi: isolate で分離します。句読点が崩れて表示される場合は、分離が欠けています。 8. ZWNJ（半角スペースなしの区切り）を正しく扱います。می‌شود が正しく、「می شود」／「میشود」は誤りです。保存、検索、切り詰めの処理を通じて U+200C を保持してください。

タイポグラフィ（最低限 — 詳細な調整については references/typography.md を参照） 9. ペルシャ語本文の行高は 1.8–2.0 にします（ラテン文字の 1.5 では窮屈です）。見出しは 1.4 にします。 10. ペルシャ語に letter-spacing を設定してはいけません — 文字の連結が崩れ、PDF のテキストレイヤーも壊れます。デザインシステムのデフォルト値（Material 3 にもあります）はゼロにしてください。 11. フォントを使う前に、実際にペルシャ語を表示できることを確認してください。よく使われる「アラビア語」フォントの中には、پ چ ژ گ がまったくないものもあります（typography.md §3）。フォントスタックの末尾には、確実に使えるフォールバックを指定し、フォントが見つからないときに文字化けではなく代替フォントで表示されるようにしてください。 12. 制約のある表示領域すべてで、「تست」ではなく、実際の長いペルシャ語文字列（«استانداردسازی زیرساخت‌های بین‌المللی»）を使ってテストしてください。

ルーティング — 必要に応じて参照

状況	参照先
Web UI（CSS、React/Next、Tailwind、アイコン、双方向テキスト、フォーム、モーション）の構築／レビュー	references/web.md
Flutter プロジェクト（Directional ウィジェット、アイコン、ジャラリ暦パッケージ、TextField、テスト）	references/flutter.md
フォント（安全性、ライセンス、組み合わせ）、フォントメトリクス、数字／ZWNJ の詳細、見本ページ	references/typography.md

監査モード — ゼロトークン検出器

既存のコードでは、まず決定論的検出器を実行します（LLM 不使用、依存関係なし）。

python3 scripts/detect.py <path>

標準出力の JSON：ルール ID、重大度、ファイル:行、該当箇所、提案を含む指摘事項。 終了コード 0 = 問題なし、1 = 指摘事項あり、2 = 使用方法の誤り。人が読む場合は --format text を指定してください。出力には上限があります（デフォルトは指摘事項 300 件。counts には常に全件数が格納され、上限に達した場合は truncated がその旨を示します）。違反件数が非常に多い場合は、--rules でルールまたはディレクトリごとに修正してください。

機械的に検出できる違反（アラビア語の ي/ك、数字の誤り、ペルシャ語の数字間の ASCII 区切り文字、CSS/Flutter の物理プロパティ、ペルシャ語に対する letter-spacing、本文のラテン文字向け行間、dir の欠落／ハードコード、dir="ltr" のないラテン文字データ入力、می の後の ZWNJ 欠落）を検出します。すべての error を修正し、各 warning は文脈に応じて確認してください（正当な例外があるものもあり、その場合は指摘に記載されています）。設計上正当な行（数字／イェーの正規化マップなど）には、行内に rtl-ignore コメントを付けるか、直前の行に rtl-ignore-next を付けてください。検出器は最低限の確認にすぎず、正規表現では検出できない点も必ず確認してください。ジェスチャー／ドラッグの計算とネストされた方向性の島（flutter.md §10、web.md §6）、視覚的な階層、アイコンの方向の意味、オーバーフロー時の挙動、レシピの品質などです。

完了前に — 自分の出力を検証する

これらのルールの対象となる UI ファイルを作成または編集した場合は、作業完了を報告する前に、作成したファイルに対して検出器を実行し、すべての指摘事項を修正してください。

python3 scripts/detect.py <the files you touched> --format text

これは任意の仕上げ作業ではありません。ルールを書き留めるだけでも大部分はカバーできますが、チェックを実行して初めて抜け漏れが解消されます。残る不具合は、スクリーンショットでは正しく見えるものだからです。入力中に表示が崩れる電話番号フィールド、ペルシャ語の数字間に入った ASCII カンマ、ペルシャ語の本文に使われたラテン文字向けの行間などです。結果が空でない場合は、助言ではなく未完了の作業として扱ってください。

Claude Code のユーザーは、これを覚えておく代わりに自動化できます。references/hooks.md を参照してください。

他のデザインスキルとの併用

このスキルは一般的なデザインスキル（センス、構造、色、動きはそれらに任せます）と組み合わせて使えます。競合する場合は、RTL／ペルシャ文字の要件を優先してください。一般的なスキルはラテン文字を前提としているため、見出しへの letter-spacing、ラテン文字向けの行間（1.4–1.5）、ペルシャ語テキストへのラテン文字向けフォント（Inter など）の提案は採用せず、代わりにこのスキルの指標、フォントレシピ、アイコンの反転ルールを適用してください。一般的なデザインスキルの品質チェックはラテン文字向けに調整されているため、一般的なデザインリンターを問題なしで通過しても、ペルシャ語として正しいとは限りません。scripts/detect.py も実行してください。

ワークフロー

• 新規 UI： 対象プラットフォームと言語を確認 → 最初のコード行からコアのルールを適用（RTL の後付けには 10 倍のコストがかかります）→ 既定の選択に頼らず、雰囲気に合ったタイポグラフィレシピを選択 → 詳細についてはプラットフォームのリファレンスを読み込む → 長い文字列や双方向テキストが混在する内容でストレステストを実施。
• LTR から RTL へのローカライズ： 機械的な項目について検出器を実行 → アイコンを反転対象／反転しない対象の一覧と照合 → 物理プロパティを論理プロパティに置き換える → その後、タイポグラフィを再設計（フォントだけでなく指標も）。ペルシャ語のタイポグラフィ指標なしに翻訳することが、「技術的には RTL」な粗雑さの原因です。
• 「どのフォントがいい？」： フォントを 1 つだけ答えることは避けてください。typography.md の選択段階とレシピを使い、ライセンスを尊重してください（まずは無料のものを検討し、有料フォントは正式なリンク付きで名称を挙げる場合に限り、商用フォントのファイルは絶対に同梱しない）。選択肢を見たいという要望があれば、サンプルページ（typography.md §10）を提案してください。