Bone Flow #018 Icon ガイド

このガイドについて

DOC ID: DOC-0018
UI ID: UI-018
Component: #018 Icon
Runtime Version: 1.0.18
DOC Version: 1.0.0

このDOCは、#018 Iconを初めて使う人が「何を設定すると、実際に何が変わるのか」まで確認できる操作ガイド兼正式仕様です。画面Help、HTML Functional Classガイド、印刷説明書、PDF、Help検索から同じ DOC-0018 を再利用します。

各Propertyは 説明 → 正式仕様 → 全許容値 → 使用サンプル → 使用結果 の順で説明します。コードブロックには「コピー」ボタンが表示され、そのまま利用できます。

実行時初期値（Runtime Default）と、#018テスト画面の設定欄（Property Editor）の初期値は同じとは限りません。異なる場合は両方を明記します。

このガイドで使う用語

Runtime（実行本体）: ブラウザ上でIconを生成・更新する BoneIcon 本体。
Runtime Default（実行時初期値）: 何も指定しなかったときにRuntimeが使用する値。
Property（設定項目）: Iconの表示、状態、OUT、表示領域を変更する設定。
Property Editor（画面の設定欄）: bone-icon.html の「プロパティ設定」で変更できる設定欄。
Public API（JavaScript高度操作）: HTMLだけでは表現できない設定をJavaScriptから操作する正式機能。
HTML Functional Class: class="bf-icon" を付けてHTMLからIconを使い始める入口。
OUT: Jointなど次の処理へ渡すIconの出力値。
表示領域: Icon本体、Name、Unicodeを格納する bone-icon-view の領域。

英語のProperty名やError Codeは正式仕様名なので残しますが、必ず日本語で「何が変わるのか」を併記します。

最初に

#018 Iconの最小利用は、bf-icon とFont AwesomeのアイコンClassを同じ要素へ付けます。アイコン名を要素内の文字列で指定しません。

<span class="bf-icon fa-solid fa-star" aria-label="お気に入り"></span>

使用結果: Font Awesome Solidの star を#018 RuntimeでIconとして生成します。aria-label は読み上げ用の名前として使用されます。

別のIconへ変える場合は fa-star を変更します。

<span class="bf-icon fa-solid fa-play" aria-label="再生"></span>

使用結果: play アイコンを表示します。#018は fontawesome-icons.json の正式1,944件から fa-play を解決し、name=play、unicode=f04b、className="fa-solid fa-play" をRuntimeへ渡します。

Iconとは

#018 IconはFont Awesome Free SolidのIconを表示し、Icon本体・アイコン名・Unicode・表示領域設定を管理するPrimitive UIです。

主な責務:

Font Awesome Solid 1,944件の検索・選択・表示
Iconのサイズ、色、回転、反転
10種類のAnimation
通常背景 / Active背景
Icon / Name / Unicodeの表示ON/OFF
Icon / Name / UnicodeのOUT ON/OFF
Name / Unicodeの文字サイズ、色、Font、位置、Iconとの間隔
表示領域の幅、高さ、最小/最大、Padding、Border、形状、配置、Overflow、Opacity、Shadow
Active / Disabled表示
#040 ColorPickerから返されたSolid / Transparent / Gradient値の反映
#002 Bone Jointの接続イメージ
Smoke Test / Validation / Completion
Public APIによる高度操作

HTML Functional Class

正式Class

一般利用向けHTML Functional Classは bf-icon 1件だけです。Public API 13件をHTML Classへ1対1変換しません。

<span class="bf-icon fa-solid fa-star"></span>

対応HTML要素

span
i

それ以外の要素へ bf-icon を付けた場合は BONE_ICON_HTML_CLASS_ELEMENT_UNSUPPORTED です。

Iconの指定方法

bf-icon と一緒に fa-<name> Classを付けます。

<i class="bf-icon fa-solid fa-bell" aria-label="通知"></i>

fa-bell はFont Awesomeカタログから検索され、Unicodeと正式Classを自動解決します。要素内TextはIcon名として使用しません。

HTMLから直接指定できるもの

HTML Functional Classは、既存HTML/CSSの意味が明確な指定だけをRuntimeへ渡します。独自の汎用イベント引数方式は使用しません。

fa-<name> Class → name / unicode / className を1,944件カタログから解決
aria-label → title の優先値
title → title
aria-disabled="true" → disabled=true
style="font-size:32px" → size=32
style="color:#RRGGBB" → color
style="background-color:#RRGGBB" → backgroundColor
width / height / min-width / max-width / min-height / max-height のpx値 → containerStyle
padding-top / right / bottom / left のpx値 → containerStyle
対応する border-width / border-style / border-color → Border設定
px指定の border-radius → shape=custom / borderRadius
justify-content:start|center|end → containerStyle.justify
align-content:start|center|end → containerStyle.align
overflow:visible|hidden|auto → containerStyle.overflow
opacity → 0〜1へ補正して containerStyle.opacity

HTMLから直接指定しないもの: rotate、flip、animation、active、表示/OUT選択、Name/Unicode書式、Gradient、Shadow詳細、Active Style詳細、Disabled Style詳細、Completion。これらはPublic APIを使用します。

HTML使用サンプル: サイズと色

<span class="bf-icon fa-solid fa-heart"
      aria-label="お気に入り"
      style="font-size:40px; color:#FF5A7A;"></span>

使用結果: heart を40px、#FF5A7Aで表示します。

HTML使用サンプル: 背景・枠・表示領域

<span class="bf-icon fa-solid fa-check"
      aria-label="完了"
      style="font-size:28px;
             color:#FFFFFF;
             background-color:#1F7A4D;
             width:72px;
             height:72px;
             padding:10px;
             border:2px solid #55E6A5;
             border-radius:12px;
             overflow:hidden;"></span>

使用結果: 72×72pxの表示領域にPadding、Border、背景を設定した check Iconになります。

使用サンプル

ここは値一覧ではなく、実際に使う場面をそのままコピーするためのサンプルです。

1. 通知Icon

<span class="bf-icon fa-solid fa-bell" aria-label="通知"></span>

使用結果: 通知を表すBell IconをRuntime Defaultで表示します。

2. 大きい警告Icon

<span class="bf-icon fa-solid fa-triangle-exclamation"
      aria-label="警告"
      style="font-size:64px; color:#FFB454;"></span>

使用結果: 64pxの警告Iconになります。

3. 無効状態をHTMLから表示

<span class="bf-icon fa-solid fa-lock"
      aria-label="利用不可"
      aria-disabled="true"></span>

使用結果: disabled=true として生成され、Runtime DefaultのDisabled opacity 0.45 が適用されます。

4. 90度回転 + spin Animation

HTML Functional Classは高度設定を無理に独自属性へ割り当てません。Public APIで指定します。

<div id="icon-host"></div>
<script>
BoneIcon.render(document.getElementById("icon-host"), {
  name: "spinner",
  unicode: "f110",
  className: "fa-solid fa-spinner",
  size: 40,
  color: "#55E6A5",
  rotate: 90,
  animation: "spin"
});
</script>

使用結果: Spinnerを90度回転した状態で連続回転Animation表示します。

5. Icon名とUnicodeも同時表示

<div id="icon-detail"></div>
<script>
BoneIcon.render(document.getElementById("icon-detail"), {
  name: "star",
  unicode: "f005",
  className: "fa-solid fa-star",
  visible: { icon: true, name: true, unicode: true },
  nameStyle: { position: "bottom", fontSize: 16, gap: 8 },
  unicodeStyle: { position: "right", fontSize: 14, gap: 8 }
});
</script>

使用結果: Iconの下に star、右側に f005 を表示します。

6. 表示とOUTを分離

<div id="icon-output"></div>
<script>
const icon = BoneIcon.render(document.getElementById("icon-output"), {
  name: "play",
  unicode: "f04b",
  className: "fa-solid fa-play",
  visible: { icon: true, name: false, unicode: false },
  output: { icon: true, name: true, unicode: true }
});
console.log(BoneIcon.getOutput(icon));
</script>

使用結果: 画面にはIconだけを表示し、OUTにはIcon Class・Icon名・Unicodeをすべて保持します。

7. 円形Container

<div id="status-icon"></div>
<script>
BoneIcon.render(document.getElementById("status-icon"), {
  name: "check",
  unicode: "f00c",
  className: "fa-solid fa-check",
  color: "#FFFFFF",
  backgroundColor: "#1F7A4D",
  containerStyle: {
    width: 72,
    height: 72,
    shape: "circle",
    paddingTop: 10,
    paddingRight: 10,
    paddingBottom: 10,
    paddingLeft: 10
  }
});
</script>

使用結果: 72×72pxの円形背景内へCheck Iconを表示します。

8. Gradient Icon

<div id="gradient-icon"></div>
<script>
BoneIcon.render(document.getElementById("gradient-icon"), {
  name: "star",
  unicode: "f005",
  className: "fa-solid fa-star",
  size: 56,
  color: {
    kind: "gradient",
    type: "linear",
    angle: 90,
    stops: [
      { position: 0, color: "#55E6A5" },
      { position: 100, color: "#5BA6FF" }
    ]
  }
});
</script>

使用結果: Icon文字へ90°の2-stop Linear Gradientを適用します。

Runtime Default / Property Editor

Runtime Default 全件

BoneIcon.normalize() が何も指定されなかったPropertyへ適用する正式Defaultです。

Property	Runtime Default	型 / Runtime許容
`name`	`star`	空でないstring
`unicode`	`f005`	3〜6桁hex
`className`	`fa-solid fa-star`	string
`size`	`56`	number、1以上
`color`	`#55E6A5`	Color Value
`rotate`	`0`	Number化した値。Runtimeに角度範囲検査なし
`flip`	`none`	4値
`title`	空文字	string
`animation`	`none`	10値
`backgroundColor`	`null`	Color Value / null
`activeBackgroundColor`	`null`	Color Value / null
`active`	`false`	Boolean化
`disabled`	`false`	Boolean化
`visible.icon`	`true`	truthy/falsy
`visible.name`	`false`	truthy/falsy
`visible.unicode`	`false`	truthy/falsy
`output.icon`	`true`	truthy/falsy
`output.name`	`true`	truthy/falsy
`output.unicode`	`true`	truthy/falsy
`nameStyle.fontSize`	`16`	number、1以上
`nameStyle.color`	`#DCE8F8`	Color Value
`nameStyle.fontFamily`	`inherit`	string
`nameStyle.position`	`bottom`	top/bottom/left/right
`nameStyle.gap`	`8`	number、0以上
`unicodeStyle.fontSize`	`14`	number、1以上
`unicodeStyle.color`	`#9FC5F8`	Color Value
`unicodeStyle.fontFamily`	`monospace`	string
`unicodeStyle.position`	`right`	top/bottom/left/right
`unicodeStyle.gap`	`8`	number、0以上
`containerStyle.width`	`null`	null / auto / number 0以上
`containerStyle.height`	`null`	null / auto / number 0以上
`containerStyle.minWidth`	`null`	null / auto / number 0以上
`containerStyle.maxWidth`	`null`	null / auto / number 0以上
`containerStyle.minHeight`	`null`	null / auto / number 0以上
`containerStyle.maxHeight`	`null`	null / auto / number 0以上
`containerStyle.paddingTop`	`10`	number、0以上
`containerStyle.paddingRight`	`10`	number、0以上
`containerStyle.paddingBottom`	`10`	number、0以上
`containerStyle.paddingLeft`	`10`	number、0以上
`containerStyle.borderEnabled`	`false`	Boolean化
`containerStyle.borderColor`	`#425A78`	Color Value
`containerStyle.borderWidth`	`1`	number、0以上
`containerStyle.borderStyle`	`solid`	4値
`containerStyle.shape`	`rounded`	6値
`containerStyle.borderRadius`	`8`	number、0以上
`containerStyle.justify`	`center`	Runtimeはstringを列挙検査しない
`containerStyle.align`	`center`	Runtimeはstringを列挙検査しない
`containerStyle.overflow`	`visible`	3値
`containerStyle.opacity`	`1`	数値化後0〜1へclamp。不正数値は1
`containerStyle.shadowEnabled`	`false`	Boolean化
`containerStyle.shadowInset`	`false`	Boolean化
`containerStyle.shadowX`	`0`	number、-999以上
`containerStyle.shadowY`	`4`	number、-999以上
`containerStyle.shadowBlur`	`12`	number、0以上
`containerStyle.shadowSpread`	`0`	number、-999以上
`containerStyle.shadowColor`	`#00000066`	#RRGGBB / #RRGGBBAA / transparent、Gradient不可
`containerStyle.output`	`true`	Boolean化
`activeStyle.borderColor`	`null`	Color Value / null
`activeStyle.borderWidth`	`null`	Runtime normalizeで範囲検査なし
`activeStyle.shadowColor`	`null`	現行Runtimeでは描画へ未使用
`disabledStyle.opacity`	`0.45`	現行Runtimeでは範囲正規化なし
`disabledStyle.backgroundColor`	`null`	Color Value / null
`disabledStyle.borderColor`	`null`	Color Value / null

Property Editor 初期値

現在の bone-icon.html 画面設定欄は、Runtime Defaultと異なる実表示用初期値を含みます。

Icon: star / f005 / fa-solid fa-star
Size: 56、Editor範囲 8〜256
Icon Color: #55E6A5
Rotate: 0、Editor範囲 0〜359
Flip: none
Animation: none
Background: OFF。色保持値 #172943
Active Background: OFF。色保持値 #245A91
Preview Active: 通常（false）
Container Width / Height: 220 / 150。Runtime Defaultはauto/null
Min Width / Min Height: 0 / 0。Runtime Defaultはnull
Max Width / Max Height: 空欄（制限なし）
Border: OFF / solid / 1px / #425A78
Shape: rounded / Radius 8
Padding: 上右下左すべて 10
justify / align: center / center
overflow: visible
opacity: 1
Shadow: OFF、Inset OFF、X 0、Y 4、Blur 12、Spread 0、Color UI保持 #000000。Runtimeへはalpha 66を付けて渡す
Active Border: #5BA6FF / 2px
Disabled Preview: OFF、Opacity 0.45、Background #222B38、Border #687386
Container Style OUT: ON
Display Mode: icon-only
Preview visible: Icon ON / Name OFF / Unicode OFF
OUT: Icon ON / Name ON / Unicode ON
Name Style: 16px / #DCE8F8 / inherit / bottom / gap 8
Unicode Style: 14px / #9FC5F8 / monospace / right / gap 8

Icon識別 Property

name

Iconの論理名です。Runtime Defaultは star。空文字は BONE_ICON_NAME_REQUIRED。

HTML Functional Classでは fa-star の star 部分を正式カタログから解決します。

unicode

Font Awesome GlyphのUnicode hexです。3〜6桁の16進文字列。Runtime Default f005。不正値は BONE_ICON_UNICODE_INVALID。

className

Font Awesomeの描画Class文字列です。Runtime Default fa-solid fa-star。Runtime自体は文字列の内容検証をしていませんが、name / unicode / className は同じIconを表す組合せで使用します。

size / rotate

size

Icon GlyphのFont Sizeをpxで設定します。

Runtime Default: 56
Runtime: 1以上
Property Editor: 8〜256、初期56
HTML Functional Class: inline font-size:...px を読取可能
Invalid: BONE_ICON_SIZE_INVALID

rotate

Icon GlyphへCSS rotate(<value>deg) を適用します。

Runtime Default: 0
Property Editor: 0〜359
Runtime: Number(value) || 0。Editorと異なり0〜359へ制限していない
HTML Functional Class: 直接指定不可。Public API使用

flip 全4値

flip はIcon Glyphを上下・左右に反転します。Runtime Default none。

none: 反転なし
horizontal: 左右反転。scaleX(-1)
vertical: 上下反転。scaleY(-1)
both: 左右と上下の両方を反転

不正値は BONE_ICON_FLIP_INVALID。

使用サンプル:

<div id="flip-icon"></div>
<script>
BoneIcon.render(document.getElementById("flip-icon"), {
  name: "arrow-right",
  unicode: "f061",
  className: "fa-solid fa-arrow-right",
  flip: "horizontal"
});
</script>

使用結果: 右矢印Glyphを左右反転して見た目は左方向になります。

animation 全10値

animation はIcon Glyphの時間変化を設定します。Runtime Default none。

none: Animationなし
beat: 拡大・縮小を繰り返す
beat-fade: 拡大・縮小とOpacity変化を組み合わせる
bounce: 上下に跳ねる動き
fade: Opacityを周期的に変化
flip: 3D方向へ反転する動き
shake: 左右へ小刻みに振動
spin: 一定速度で連続回転
spin-pulse: 段階的な回転
spin-reverse: 逆方向へ連続回転

不正値は BONE_ICON_ANIMATION_INVALID。

Animationは#018 Runtime/CSSの責務です。#118 Transitionの状態遷移補間とは別の設定です。

color / Background / #040 ColorPicker

Color Value正式仕様

#018の色Propertyは文字列または2-stop Linear Gradientを使用します。

Solid

#RRGGBB

Transparent

transparent

Gradient V1

{
  kind: "gradient",
  type: "linear",
  angle: 90,
  stops: [
    { position: 0, color: "#55E6A5" },
    { position: 100, color: "#5BA6FF" }
  ]
}

Gradientの正式条件:

kind: gradient
type: linear
angle: 0以上360未満
stops: 正確に2件
各position: 0〜100
1件目のposition < 2件目のposition
各color: #RRGGBB

不正Colorは BONE_ICON_COLOR_INVALID、不正Gradient構造は BONE_ICON_GRADIENT_INVALID。

#040 ColorPicker連携

#018テスト画面では #040 ColorPicker v1.0.15 の attachCaller() を使用します。#018側はColorPicker内部DOM/CSSを複製しません。

ColorPicker対象10色:

Icon Color
Background Color
Active Background Color
Container Border Color
Container Shadow Color
Active Border Color
Disabled Background Color
Disabled Border Color
Name Color
Unicode Color

Shadow Colorだけは既存 shadowColor + alpha 契約を維持するため、Solid / TransparentのみでGradient不可です。

Background / Active / Disabled

backgroundColor

通常状態の表示領域背景。Default null（無色）。Solid / Transparent / Gradient。

activeBackgroundColor

active=true のとき使用する背景。Default null。値がnullなら通常 backgroundColor を使用します。

active

Default false。trueで is-active Classが付き、Active背景・Active Borderを適用します。

disabled

Default false。trueで is-disabled Classが付き、Disabled Styleを優先して適用します。

disabledStyle

opacity: Default 0.45
backgroundColor: Default null
borderColor: Default null

disabledStyle.backgroundColor / borderColor が指定されている場合にDisabled時へ反映します。

表示（visible）/ OUT（output）

表示とOUTは独立です。「画面に表示しないがOUTへ渡す」が可能です。

visible

visible.icon: Default true
visible.name: Default false
visible.unicode: Default false

output

output.icon: Default true → OUT key icon
output.name: Default true → OUT key iconName
output.unicode: Default true → OUT key unicode

containerStyle.output=true の場合は containerStyle もOUTへ追加します。

Property EditorのDisplay Mode 全5値

これはRuntime Propertyではなく、画面上で3つのvisible checkboxをまとめて操作する補助UIです。

icon-only: Iconだけ表示
icon-name: Icon + Name
icon-unicode: Icon + Unicode
icon-name-unicode: Icon + Name + Unicode
custom: checkboxの組合せが上記4件に一致しない状態

Name / Unicode表示位置全4値

nameStyle.position と unicodeStyle.position は同じ4値です。

top: Iconの上側slotへ表示。gapはLabelの下Margin
bottom: Iconの下側slotへ表示。gapはLabelの上Margin
left: Iconの左側slotへ表示。gapはLabelの右Margin
right: Iconの右側slotへ表示。gapはLabelの左Margin

不正値は BONE_ICON_POSITION_INVALID。

Name Style

nameStyle.fontSize

Default 16。Runtime 1以上。Editor 8〜128。

nameStyle.color

Default #DCE8F8。Solid / Transparent / Gradient。

nameStyle.fontFamily

Runtime Default inherit。Runtimeは任意string。Property Editor選択肢は全6件:

inherit: 親Fontを継承
Meiryo, sans-serif: Meiryo優先
'Yu Gothic', sans-serif: 游ゴシック優先
sans-serif: Sans Serif系
serif: Serif系
monospace: 等幅Font

nameStyle.position

Default bottom。4値は「Name / Unicode表示位置全4値」を参照。

nameStyle.gap

Default 8 px。Runtime 0以上。Editor 0〜100。

Unicode Style

unicodeStyle.fontSize

Default 14。Runtime 1以上。Editor 8〜128。

unicodeStyle.color

Default #9FC5F8。Solid / Transparent / Gradient。

unicodeStyle.fontFamily

Runtime Default monospace。Property Editor選択肢はNameと同じ6件。

unicodeStyle.position

Default right。4値。

unicodeStyle.gap

Default 8 px。Runtime 0以上。Editor 0〜100。

Container Size

width / height / minWidth / maxWidth / minHeight / maxHeight は表示領域サイズです。

null / 空文字 / auto: CSSサイズ指定を外す
数値: pxとして使用
Runtime数値範囲: 0以上
Invalid: BONE_ICON_CONTAINER_SIZE_INVALID

Runtime Defaultは6項目すべて null。Property Editorはwidth 220、height 150、minWidth 0、minHeight 0、maxWidth/maxHeight空欄です。

Padding

4方向を個別にpx指定します。

paddingTop: Default 10
paddingRight: Default 10
paddingBottom: Default 10
paddingLeft: Default 10

Runtimeは0以上。不正値は BONE_ICON_PADDING_INVALID コードではなく、現行実装では共通 BONE_ICON_PADDING_INVALID をnumber()へ渡しています。

Border Style 全4値

solid: 実線
dotted: 点線
dashed: 破線
double: 二重線

Runtime Default solid。不正値 BONE_ICON_BORDER_STYLE_INVALID。

Shape 全6値

shape は表示領域の角丸計算を決めます。

square: Radius 0。四角
rounded: borderRadius をpxで使用。Default
circle: Radius 50%
ellipse: Radius 50%。width/heightが異なる場合は楕円
capsule: Radius 9999px。長方形をカプセル状にする
custom: borderRadius をpxで使用

不正値 BONE_ICON_SHAPE_INVALID。

borderRadius Runtime Default 8、0以上。Editor 0〜999。

justify 全3値 / align 全3値

Property Editorの正式選択肢

justify（横配置）:

start: 左
center: 中央
end: 右

align（縦配置）:

start: 上
center: 中央
end: 下

両方のEditor Defaultは center。

Runtimeとの差

現行v1.0.18 Runtimeは justify / align を列挙値として検証せず、その文字列をCSS justifyContent / alignContent へ設定します。したがって正式画面では上記3値を使用し、Public APIから任意文字列を渡した場合はブラウザCSS側の解釈結果になります。RuntimeがEditor 3値と同じValidationを行うとは扱いません。

overflow 全3値

visible: はみ出した内容を表示。Default
hidden: 表示領域外を切る
auto: 必要に応じてスクロール領域化

不正値 BONE_ICON_OVERFLOW_INVALID。

opacity

containerStyle.opacity は表示領域全体のOpacityです。

Default: 1
Runtime: Number化し0〜1へclamp
数値化できない場合: 1
Property Editor: 0〜1、step 0.05

Disabled時は disabledStyle.opacity が上書きします。

Shadow

shadowEnabled

Default false。falseならShadow関連値が存在しても box-shadow:none。

shadowInset

Default false。trueなら inset Shadow。

shadowX / shadowY / shadowBlur / shadowSpread

X Default 0、Runtime -999以上
Y Default 4、Runtime -999以上
Blur Default 12、Runtime 0以上
Spread Default 0、Runtime -999以上

shadowColor

Default #00000066。許容は #RRGGBB、#RRGGBBAA、transparent。Gradient不可。

#018 Property Editorは#040から受けたSolid色 #RRGGBB に既存alpha 66 を加えてRuntimeへ渡します。

Active Style

activeStyle.borderColor

Default null。ActiveかつBorder Enabledのとき、通常Border Colorを上書きします。Solid / Transparent / Gradient / null。

activeStyle.borderWidth

Default null。ActiveかつBorder Enabled時にBorder Widthを上書き。Property Editor初期値2、min 0。現行Runtime normalizeはこのPropertyの数値範囲を検証していません。

activeStyle.shadowColor

Default null。Objectには存在しますが、現行v1.0.18の applyContainer() はこの値をShadow描画へ使用していません。画面設定欄にも入力欄はありません。存在するPropertyを「Active Shadowが描画される」と誤説明しません。

Container OUT

containerStyle.output Default true。

trueの場合、BoneIcon.getOutput() は containerStyle を返します。返却値には通常Container設定に加え、背景、Active背景、Active/Disabled Styleも含まれます。

falseの場合、Container設定は画面へ反映されてもOUTの containerStyle keyは生成されません。

操作方法 / Keyboard

Property Editor

Icon一覧または検索からIconを選択。
基本設定、表示領域、表示/OUT、Name/Unicode設定を変更。
右側「合算プレビュー」で全設定を確認。
色は各Color Triggerから#040 ColorPickerを開く。
Smoke Test / Validationを実行。
両方ALL PASSの場合のみCompletion操作が有効になります。

Keyboard

通常の Tab / Shift+Tab: 入力、select、Color Trigger、Icon Card、テストボタンへ移動
Enter / Space: Button・Icon Card・Color Triggerの実行
ColorPickerのKeyboard操作は#040責務
DOC Guide: Escapeで閉じる

#018 RuntimeのIcon表示自体はButtonではありません。クリック動作を必要とする場合は親Buttonなど適切な操作Componentを使用します。

Joint / 接続イメージ

Jointは#002 Bone Joint責務です。#018は見た目だけの独自線を作りません。

接続イメージでは:

IN 接続線: 青
OUT 接続線: 緑
型不一致: オレンジ
接続エラー / Target不存在: 赤

IconのOUT候補:

icon: Font Awesome Class
iconName: Icon名
unicode: Unicode hex
containerStyle: output=trueの場合

実際のEndpoint互換性、Target不存在、型不一致は#002の評価結果に従います。

Smoke / Validation

#018テスト画面には正式Smoke TestとValidationがあります。

SmokeではRuntime、ColorPicker Caller、Font Awesome全1,944件、表示/OUT、Container、Jointなどの正常系を確認します。

Validationでは少なくとも次のErrorを実動作で検査します。

空Icon名
不正Unicode
不正Size
不正Flip
不正Animation
不正Gradient
Shadow Gradient拒否
不正Border Style
不正Shape
不正Overflow
不正Position
Instance以外へのAPI操作

テスト期待値を書き換えてPASSにしません。

Completion

CompletionはSmoke TestとValidationの双方ALL PASSが前提です。

BoneIcon.complete(validation) は、次がすべてtrueでなければ BONE_ICON_COMPLETION_VALIDATION_REQUIRED です。

allPass
smokePassed
validationPassed

Completion後:

completionFlag=true
status=Release Ready
validationStatus=ALL PASS
completedAt 記録

BoneIcon.reopen() でDevelopmentへ戻します。

ユーザーlocalhost確認前にDOC統合作業をCompleted / Specification Frozenと断定しません。

JavaScript高度操作（Public API）

HTML Functional Class bf-icon とPublic APIは別です。Public APIは13件です。

normalize(options)

設定Objectを正式な#018契約へ正規化します。DOMは生成しません。

create(options)

新しい bone-icon-view Elementを生成します。Documentがない場合 BONE_ICON_DOCUMENT_UNAVAILABLE。

getCompletionState()

localStorageのCompletion状態を取得します。

complete(validation)

Smoke/Validation結果を確認してCompletionを確定します。

reopen()

Completionを解除します。

render(target, options)

target Elementへ新しいIconをappendします。Elementでない場合 BONE_ICON_TARGET_INVALID。

update(el, options)

既存#018 Instanceの設定を合成し、新しいElementで置換します。戻り値は置換後の新Instanceです。

getOptions(el)

現在の正規化済み設定をCloneして返します。

getOutput(el)

現在の output と containerStyle.output に従ったOUT Objectを返します。

setActive(el, active)

active をBoolean化してupdateします。updateによりElementが置換されるため、戻り値の新Instanceを保持してください。

<div id="active-host"></div>
<script>
let icon = BoneIcon.render(document.getElementById("active-host"), {
  name: "star",
  unicode: "f005",
  className: "fa-solid fa-star"
});
icon = BoneIcon.setActive(icon, true);
</script>

setDisabled(el, disabled)

Disabled状態を更新し、新Instanceを返します。

isInstance(el)

Elementが現在のBoneIcon InstanceかBooleanで返します。

destroy(el)

Instanceを管理対象から外してDOMから削除します。Instance以外は BONE_ICON_INSTANCE_INVALID。

発生イベント（HTML Functional Class）

bone-icon-html-class-mounted

bf-icon が正式#018 Runtime Instanceへ変換された後に生成Elementから発火します。detailにcomponentId、className、iconName、elementを含みます。

bone-icon-html-class-error

HTML Functional Classの解決・変換に失敗した場合に元要素から発火します。detailにcode/messageを含みます。

Error / Troubleshooting

Runtime Error Code

BONE_ICON_NAME_REQUIRED: nameが空
BONE_ICON_UNICODE_INVALID: Unicodeが3〜6桁hexではない
BONE_ICON_SIZE_INVALID: sizeが1未満または数値でない
BONE_ICON_FLIP_INVALID: flipが4値外
BONE_ICON_ANIMATION_INVALID: animationが10値外
BONE_ICON_COLOR_INVALID: Color Value不正
BONE_ICON_GRADIENT_INVALID: Gradient構造不正
BONE_ICON_CONTAINER_SIZE_INVALID: Container Size不正
BONE_ICON_FONT_SIZE_INVALID: Name/Unicode Font Size不正
BONE_ICON_GAP_INVALID: Name/Unicode Gap不正
BONE_ICON_PADDING_INVALID: Padding不正
BONE_ICON_BORDER_WIDTH_INVALID: Border Width不正
BONE_ICON_BORDER_STYLE_INVALID: Border Style不正
BONE_ICON_SHAPE_INVALID: Shape不正
BONE_ICON_RADIUS_INVALID: Border Radius不正
BONE_ICON_OVERFLOW_INVALID: Overflow不正
BONE_ICON_SHADOW_INVALID: Shadow X/Y/Blur/Spread不正
BONE_ICON_POSITION_INVALID: Name/Unicode Position不正
BONE_ICON_DOCUMENT_UNAVAILABLE: create時Documentなし
BONE_ICON_TARGET_INVALID: renderのtarget不正
BONE_ICON_INSTANCE_INVALID: Instance必須APIへ別Elementを渡した
BONE_ICON_COMPLETION_VALIDATION_REQUIRED: ALL PASS情報なしでCompletionしようとした

HTML Functional Class Error Code

BONE_ICON_HTML_CLASS_RUNTIME_UNAVAILABLE: BoneIcon が未読込
BONE_ICON_HTML_CLASS_ELEMENT_UNSUPPORTED: span/i以外
BONE_ICON_HTML_CLASS_NAME_REQUIRED: fa-<name> Classなし
BONE_ICON_HTML_CLASS_ICON_NOT_FOUND: 1,944件に存在しないIcon Class
BONE_ICON_HTML_CLASS_FETCH_UNAVAILABLE: Catalog読込に必要なfetchなし
BONE_ICON_HTML_CLASS_CATALOG_LOAD_FAILED: fontawesome-icons.json 読込失敗
BONE_ICON_HTML_CLASS_CATALOG_EMPTY: Catalogが空

Iconが出ない

bone-icon.js と bone-icon-html-class.js が読み込まれているか。
bone-icon.css とFont Awesome webfontが読み込まれているか。
bf-icon と fa-solid と fa-<name> が同じspan/iにあるか。
fa-<name> が#018正式1,944件に存在するか。
DevTools ConsoleのHTML Class Error Codeを確認。

色が反映されない

Runtimeへ渡した色が #RRGGBB / transparent / 正式Gradient か確認します。ShadowはGradient不可です。

Active Borderが見えない

containerStyle.borderEnabled=true が必要です。Active Borderだけ設定して通常BorderをOFFにしている場合、現行RuntimeはBorderを描画しません。

maxWidth等が効かない

min/maxとwidth/heightを同時指定している場合はCSS sizing規則も関係します。Runtimeは数値をpxへ変換してstyleへ設定します。

Dependencies / DOC再利用

現在の#018画面が検証する依存:

#001 Bone Core v1.0.0
#002 Bone Joint v1.1.36
#020 Bone Label v1.0.50（#040経由）
#022 Hover Border Effect v1.0.5（#040経由）
#040 ColorPicker v1.0.15

#017 Textは画面構成・接続イメージの参照実装で、#018 Runtime依存ではありません。

DOC経路:

UI-018 → DOC-0018 → doc-registry.json → content/DOC-0018/ja.md|en.md → BoneDocLoader → BoneDocGuide

同じDOC資産をUI Help、HTML Functional Class Guide、印刷説明書、PDF、Help検索から再利用します。

#018 Icon

bf-icon

正式ガイド DOC-0018