lucide-icons

Rails での Lucide アイコン

lucide-rails gem を使って、Lucide アイコンをインライン SVG としてレンダリングします。アイコンは currentColor を使うため、自動的にテキストの色を継承します。

このスキルを使う場面

• Rails のビューにアイコンを追加するとき（ボタン、ナビゲーション、バッジ、空状態）
• UI 要素に適した Lucide アイコン名を選ぶとき
• アイコンをアクセシブルにするとき（装飾用か、操作用か）
• SVG アイコンのスタイルやサイズを CSS で調整するとき

基本方針

1. アイコンは、そうでなくなるまでは装飾です — 装飾用アイコンにラベルは不要です。操作用アイコン（ボタン、リンク）には、アクセシブルなテキストが必須です。
2. 意図的にサイズを指定する — 必ず size: を指定してください。デフォルトの 24px は、インラインで使う場合のほとんどの場面で大きすぎます。
3. 色は CSS に任せる — アイコンは currentColor を継承します。SVG ではなく親要素にスタイルを指定してください。
4. ヘルパーを使い、生の SVG は使わない — lucide_icon を使うと、アイコンの一貫性を保ち、キャッシュや更新が容易になります。
5. 名前は kebab-case のみ — "chevron-right" を使い、"chevronRight" や "ChevronRight" は使いません。

インストール

# Gemfile
gem "lucide-rails"

bundle install

JavaScript も、import maps も、アセットパイプラインの設定も必要ありません。この gem は、インライン SVG をレンダリングする Ruby ヘルパーを提供します。

基本的な使い方

<%= lucide_icon "home", size: 18 %>

レンダリング結果：

<svg width="18" height="18" viewBox="0 0 24 24" fill="none"
     stroke="currentColor" stroke-width="2"
     stroke-linecap="round" stroke-linejoin="round">
  <path d="..."></path>
</svg>

ヘルパーのパラメーター

パラメーター	デフォルト	説明
size	24	ピクセル単位の幅と高さ
class	nil	CSS クラス
stroke_width	2	線の幅（一般的な範囲は 1～3）

<%= lucide_icon "home", size: 16, class: "text-muted" %>
<%= lucide_icon "home", size: 24, stroke_width: 1.5 %>

追加の HTML 属性はすべて、<svg> 要素に渡されます。

<%= lucide_icon "copy", size: 14, data: { action: "click->clipboard#copy" } %>
<%= lucide_icon "x", size: 18, aria: { label: "Close" } %>

サイズのガイドライン

用途に応じてサイズを選びます。用途ごとに一貫したサイズにしてください。

用途	サイズ	場面
バッジ、インラインラベル	12px	狭いスペース、小さなテキスト
閉じる操作、インライン操作	14px	本文テキストに添える場合
テキスト付きボタン	16px	操作で最も一般的
ナビゲーションサイドバー	18px	ナビゲーションリンク、メニュー項目
カード／リスト項目のアイコン	20px	コンテンツの種類を示す場合
空状態、ヒーロー	32～48px	大きな装飾アイコン

CSS によるスタイル設定

色の継承

アイコンの線には currentColor が使われるため、親要素の color を継承します。

.nav-link { color: var(--color-muted); }
.nav-link:hover { color: var(--color-default); }
/* Icon color changes automatically on hover */

アイコンへの直接的なスタイル設定

アイコン固有の色が必要な場合は、親要素またはアイコンのラッパーにユーティリティクラスを指定します。

.text-success { color: var(--color-positive); }
.text-danger  { color: var(--color-negative); }
.text-warning { color: var(--color-warning); }
.text-muted   { color: var(--color-muted); }

<span class="text-success"><%= lucide_icon "check", size: 14 %></span>
<span class="text-danger"><%= lucide_icon "alert-circle", size: 14 %></span>

線の幅

大きなサイズでは、線を細くすると洗練された印象になります。小さなサイズでは、線を太くすると見やすくなります。

<%= lucide_icon "settings", size: 48, stroke_width: 1.5 %>  <%# Large, elegant %>
<%= lucide_icon "check", size: 12, stroke_width: 2.5 %>     <%# Small, readable %>

ダークモード

アイコンは currentColor を使うため、テキストの色がダークモードに対応すると、アイコンもそれに合わせて変わります。色のシステムで CSS カスタムプロパティを使っていれば、追加の作業は不要です。

よく使うパターン

アイコン付きテキストボタン

<button class="btn btn-primary">
  <%= lucide_icon "plus", size: 16 %>
  Create Project
</button>

.btn {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
}

アイコンのみのボタン

<button class="btn-icon" aria-label="Close">
  <%= lucide_icon "x", size: 18 %>
</button>

.btn-icon {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: 0.5rem;
}

アイコンのみのボタンには aria-label が必須です。

ナビゲーションリンク

<%= link_to dashboard_path, class: "nav-link" do %>
  <%= lucide_icon "layout-dashboard", size: 18 %>
  Dashboard
<% end %>

アイコン付きバッジ

<span class="badge">
  <%= lucide_icon "lock", size: 12 %>
  Restricted
</span>

.badge {
  display: inline-flex;
  align-items: center;
  gap: 0.25rem;
}

空状態

<div class="empty-state">
  <%= lucide_icon "folder-plus", size: 48, stroke_width: 1.5 %>
  <h3>No projects yet</h3>
  <p>Create your first project to get started.</p>
</div>

.empty-state {
  text-align: center;
  padding: 3rem 1rem;
}
.empty-state svg {
  color: var(--color-muted);
  margin-bottom: 1rem;
}

リンク内のアイコン（Turbo）

<%= link_to edit_post_path(@post), class: "action-link", data: { turbo_frame: "post_form" } do %>
  <%= lucide_icon "edit", size: 14 %>
  Edit
<% end %>

Stimulus との連携

<button data-controller="clipboard" data-action="click->clipboard#copy"
        data-clipboard-text-value="<%= @invite_url %>">
  <%= lucide_icon "copy", size: 14 %>
  Copy Link
</button>

アクセシビリティ

ルール：装飾用か、意味を持つものか

装飾用 — アイコンに表示テキストが添えられています。追加のマークアップは不要です。

<button>
  <%= lucide_icon "plus", size: 16 %> Add Item
</button>

意味を持つもの — アイコンが唯一のコンテンツです。アクセシブルなテキストを追加する必要があります。

<%# Option 1: aria-label on the interactive element %>
<button aria-label="Close" class="btn-icon">
  <%= lucide_icon "x", size: 18 %>
</button>

<%# Option 2: sr-only span %>
<button class="btn-icon">
  <%= lucide_icon "x", size: 18 %>
  <span class="sr-only">Close</span>
</button>

スクリーンリーダー専用クラス

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

SVG はデフォルトで aria-hidden

lucide_icon ヘルパーがレンダリングする SVG は、スクリーンリーダーによって読み飛ばされます。これは適切な動作です。アクセシブルな名前はアイコンではなく、操作可能な親要素に指定します。

用途別のよく使うアイコン

ナビゲーション

アイコン名	用途
home	ホーム／ダッシュボード
layout-dashboard	ダッシュボード／概要
settings	設定
users	チーム／メンバー
file-text	ドキュメント／ページ
log-out	サインアウト
log-in	サインイン
menu	ハンバーガーメニュー
search	検索

操作

アイコン名	用途
plus	作成／追加
edit	編集／変更
trash	削除
copy	クリップボードにコピー
x	閉じる／解除
check	確定／保存
eye	表示／プレビュー
eye-off	非表示
download	ダウンロード
upload	アップロード
external-link	新しいタブで開く

矢印とシェブロン

アイコン名	用途
arrow-left	戻る
arrow-right	進む
chevron-down	展開／ドロップダウン
chevron-right	次へ／詳細を表示
chevron-up	折りたたむ
arrow-up-right	外部／外部への移動

ステータスとフィードバック

アイコン名	用途
check-circle	成功
alert-circle	エラー
alert-triangle	警告
info	情報
help-circle	ヘルプ
loader	読み込み中（CSSでアニメーションを適用）
lock	制限あり／非公開
unlock	公開／オープン

コミュニケーション

アイコン名	用途
mail	メール
bell	通知
message-circle	チャット／コメント
megaphone	お知らせ
send	メッセージを送信

ファイルとコンテンツ

アイコン名	用途
file	一般的なファイル
file-text	ドキュメント
folder	フォルダー／カテゴリ
folder-plus	新しいフォルダー
image	画像／写真
video	動画
link	リンク／URL

ソーシャルとその他

アイコン名	用途
github	GitHub
twitter	Twitter/X
globe	ウェブサイト／世界
calendar	日付／スケジュール
clock	時刻／履歴
star	お気に入り
heart	いいね
filter	フィルター
sort-asc	昇順で並べ替え
sort-desc	降順で並べ替え

アンチパターン

1. アイコン名の大文字・小文字が間違っている — "chevronRight" ではなく、"chevron-right" を使用します（常にケバブケースを使用）
2. サイズの指定がない — デフォルトの24pxに頼らず、size: 16 のように明示します
3. 生の <svg> または <img> タグを使う — 常に lucide_icon ヘルパーを使用します
4. SVGを直接スタイル設定する — SVGの stroke ではなく、親要素の color をスタイル設定します
5. aria-label のないアイコンのみのボタン — スクリーンリーダーで内容を説明できません
6. サイズに一貫性がない — コンテキストごとにサイズを決め、統一します
7. 異なるアイコンを使いすぎる — アプリ全体で、同じ概念には同じアイコンを再利用します
8. 意味が曖昧なのに、表示テキストなしでアイコンを使う — 鉛筆アイコンは「編集」や「書く」を意味する場合があります。テキストまたはツールチップを追加します。

アイコンを探す

完全なライブラリは lucide.dev/icons でご覧ください。

検索のヒント：

• 概念で検索します：「arrow」、「file」、「user」、「check」
• アイコン名は内容がわかるように付けられています：checkmark-in-circle ではなく circle-check
• 関連するアイコンには共通の接頭辞が付いています：file、file-text、file-plus、file-x
• アイコンが lucide-rails に存在しない場合、ヘルパーはレンダリング時にエラーを発生させます

リファレンス

詳しいパターン、例外的なケース、高度な使い方については、reference.md をご覧ください。