fandhe-frontend-pre-styled-ui API

1. 目的とトレーサビリティ

本ドキュメントは fandhe-frontend-pre-styled-ui（chakra-ui 参考の pre-styled UI コンポーネント層）の公開 API 表面をまとめる。 fandhe-frontend-headless-ui（ark-ui 相当の下層、 docs/api/headless-ui-api.md）の上に、テーマ トークン・variant API・静的 CSS 生成を重ね、styled 部品を実装する 2 層 構造の上層を担う。

2. モジュール一覧（repo main 時点。crates.io 公開状況は §2a 参照）

本クレートは 106 の公開モジュール + charts サブモジュール群を持つ （charts::bar_chart/charts::bar_list/charts::bar_segment/ charts::scatter_chart/charts::radar_chart/charts::axis/charts::grid/ charts::legend/charts::tooltip/charts::pie/charts::data/ charts::scale/charts::svg は既存の pub mod charts; 配下のサブ モジュールであり、grep -E '^pub mod ' によるトップレベル公開モジュール 集計には計上されない）。106 は grep -c '^pub mod ' crates/pre-styled-ui/src/lib.rs の実測値である。モジュール一覧・本数の正は下表と上記実測値・各モジュール 冒頭 rustdoc とする。部品ごとの詳細（anatomy・Demo・Examples・キーボード 操作）は本表に複製せず、各部品ページ（/themes/<kebab>/）へ委譲する。

2a. crates.io 公開状況とドキュメント対象バージョン（イシュー #1118）

本ドキュメントは repo main（開発中の最新コード）を対象として記述して います。crates.io への公開はリリース運用（.github/workflows/release.yml の workflow_dispatch による手動実行、mode: publish の明示選択）を 経るため、repo main の到達点から遅延することがあります。利用者が Cargo.toml に指定した実際のバージョンに何のモジュールが含まれるかは、 本ドキュメントではなく https://docs.rs/fandhe-frontend-pre-styled-ui/<version> （例: https://docs.rs/fandhe-frontend-pre-styled-ui/0.5.0）で確認してくだ さい。

本節は執筆時点（イシュー #1118 対応時）のスナップショットとして、乖離の 実例を記録します。crates.io 最新公開バージョンは fandhe-frontend-pre-styled-ui 0.5.0（依存する fandhe-frontend-headless-ui は 0.4.0）であり、本節冒頭の 「106 モジュール」（repo main、v0.37.0 時点）に対し、0.5.0 時点では typography・navigation 系モジュール（heading / text / link / breadcrumb / nav_list / separator / list 等）を含む多くのモジュール が未収録です（約 15 モジュール、イシューフィードバックの実測）。この 遅延を解消する crates.io への追加公開は、本イシューのコード変更とは別の 運用アクションとして実施します（承認境界は .claude/rules/ci.md の release ワークフロー節を参照。本ドキュメントの自動更新は行わないため、 公開が進み次第この節を追随更新してください）。

各 headless ラッパーモジュールは対応する fandhe_frontend_headless_ui モジュールの anatomy パーツ・状態機械を薄く再エクスポートし、 stylesheet()（モジュールにより css()）で既定 CSS を追加提供する共通 設計方針を採る。詳細・スコープ外事項は各モジュール冒頭の rustdoc または 対応する部品ページを参照（例: switch は src/switch.rs、avatar/ radio_group は §4b/§4c、checkbox は §4e、input/textarea/ native_select は §4f）。switch/radio_group/checkbox の size/ color-palette variant 拡張の詳細は §4c・§4d・§4e を参照。

クレートルート再エクスポート（fandhe_frontend_headless_ui / fandhe_frontend_core / OpenState / Orientation ほか）は §3a を参照。

examples/headless-pre-styled-ui は本クレート v0.4.0（ fandhe-frontend-pre-styled-ui = "0.4.0"、crates.io バージョン依存）へ 統合済みである。旧来 headless-ui の data-scope/data-part/data-state セレクタへ手書きで当てていたコンポーネント CSS は撤去され、src/main.rs の build_stylesheet() が Theme/SlotRecipe から生成した CSS を stylesheet::StyleSheet で集約し dist/assets/ui.css へ書き出す方式へ 切り替え済み。static/ui.css はショーケースページ固有の骨格レイアウトのみ を保持する形で残存する。

3. 不変条件（実装済み・骨格に記載済み、src/lib.rs 参照）

1. コンポーネントは fandhe_frontend_headless_ui 経由で fandhe_frontend_core::Node を返す通常の Rust 関数として実装する （REQ-5、マクロ DSL は採用しない）。
2. 出力は fandhe_frontend_core::render の既定エスケープを必ず経由する。 raw_html() の使用は stylesheet::StyleSheet::style_element 内の レビュー済み 1 箇所（#[expect(clippy::disallowed_methods, ...)] 付き） に限定する（§4a 参照）。新たなエスケープ迂回経路を作らない。
3. #![forbid(unsafe_code)]（REQ-2）によりクレート全体で unsafe を機械的 に禁止する。
4. 外部依存は fandhe-frontend-headless-ui（path）のみ。 fandhe-frontend-core への直接依存は宣言しない（headless-ui 経由で 間接的に利用する。fandhe-frontend-core はスモークテスト用の dev-dependency としてのみ許容する）。

これらの不変条件は実装済み各モジュール（§2 参照）でも維持されている （.claude/rules/coding-rust.md・docs/api/headless-ui-api.md §6 と同一の 制約を上層でも維持する）。

3a. headless 型の再エクスポート契約

fandhe-frontend-headless-ui の 7 モジュール（tabs/accordion/dialog/ menu/select/popover/tooltip）を薄くラップする各 pre-styled-ui モジュールは、pre-styled-ui のみへの依存でラッパーを呼び出せることを 保証する契約として、以下を明示 pub use で再エクスポートする（棚卸し表、 crates/pre-styled-ui/src/{tabs,accordion,dialog,menu,select,popover,tooltip}.rs の各ファイル冒頭の pub use 直後のコメント参照）。tabs/accordion/ dialog/menu/select の 5 モジュールは size variant クラス付与のため styled root（tabs のみ tabs）を各モジュールで新設しており、headless 自由関数 root（tabs は tabs/tabs_with_root_attrs）との名前衝突を 避けるため選択的 re-export とする（§4d 参照）。popover/tooltip を含め、 styled パーツ関数を再定義しないモジュール 13 件は glob 再エクスポートを 維持する（現況は popover/tooltip の 2 件に留まらない。一覧・維持条件は §3c 参照）。

ActivationMode/TabItem/TabsProps（tabs）・DialogRole/ContentIds （dialog）・SelectAction（select）は各 headless モジュール内定義のため 既存の glob 再エクスポートで到達可能であり、追加の再エクスポートは不要 （モジュール自身の impl Component の Action として使う場合を含む）。

加えて、クレートルート（crates/pre-styled-ui/src/lib.rs）から次を 再エクスポートする。

• pub use fandhe_frontend_headless_ui;: headless 層クレートそのもの。 headless-ui が core に対して行う再エクスポートと同型のエスケープハッチ であり、各ラッパーモジュールの glob では届かない headless API 全域 （positioning/aria 等）への到達路を確保する。
• pub use fandhe_frontend_headless_ui::fandhe_frontend_core;: Node を 組み立てる core API（el/text/render 等）への推移的再エクスポート。 fandhe_frontend_pre_styled_ui::fandhe_frontend_core::{el, text, render, Node} という単独依存パスを完結させる（Cargo.toml へ fandhe-frontend-core への直接依存を追加しない、不変条件 4 を維持）。
• pub use fandhe_frontend_headless_ui::{OpenState, Orientation};: ラッパー呼び出しに頻出する状態値。pre-styled-ui 単独依存での import を 可能にする。

セキュリティ上の注意（REQ-1、.claude/rules/security.md A03）: fandhe_frontend_pre_styled_ui::fandhe_frontend_core 経由で raw_html() へ 到達できる経路が増えるが、raw_html() 自体は既存の明示的オプトイン API であり、本契約は新たな迂回経路を作らない（headless-ui が確立した既存 パターンの推移）。pre-styled-ui 内部の不変条件（raw_html() の使用は [stylesheet::StyleSheet::style_element] 内の 1 箇所限定）は「使用」に関する 規約であり、pub use によるクレート到達性の追加はこれに抵触しない。

固定テストは crates/pre-styled-ui/tests/headless_reexports.rs （import を fandhe_frontend_pre_styled_ui:: パスのみに限定し、コンパイル と実行時アサーションの両方で契約を固定する）。

3b. interactive 層の再エクスポート契約

fandhe-frontend-headless-ui は pub use fandhe_frontend_interactive; （クレート再エクスポート）を持ち、fandhe-frontend-pre-styled-ui はそれを 推移的に pub use fandhe_frontend_headless_ui::fandhe_frontend_interactive; で再エクスポートする。ルートへの個別型再エクスポート（Component 等を ルート直下へ置く構成）は行わない。

棚卸し表（クレート再エクスポートにより全到達可能）

同型で fandhe_frontend_headless_ui::fandhe_frontend_interactive::{...} （headless-ui 単独依存経由）でも到達可能。

固定テスト

• crates/headless-ui/tests/interactive_reexport.rs: headless-ui の クレート再エクスポート到達性を、styled Dialog 相当（headless の Dialog） の SSR → dispatch 往復と、改ざん属性による HydrateError 到達（panic しない）で固定する。
• crates/pre-styled-ui/tests/interactive_reexports.rs: pre-styled-ui の 推移的再エクスポート到達性を、styled Dialog/Accordion/Switch の SSR/hydration/dispatch 往復と HydrateError 到達で固定する。import は fandhe_frontend_pre_styled_ui:: パスのみに限定する。
• crates/pre-styled-ui/tests/headless_reexports.rs は import を fandhe_frontend_pre_styled_ui::fandhe_frontend_interactive::{...} （再エクスポート経由）に限定し、契約テストとしての純度を保つ。

セキュリティ上の注意（REQ-1）

fandhe_frontend_interactive は raw_html() を公開せず、 Component::view/render_for_hydration の戻り値は Node のみで既定 エスケープを必ず経由する（interactive の不変条件 1）。本再エクスポートは 新たな出力経路・エスケープ迂回を一切作らない。Hydrate::from_hydration_attrs は DOM 属性を改ざんされうる入力として扱い panic せず HydrateError を返す 契約（interactive 不変条件 3）も、再エクスポートで弱まらないことを固定 テストで検証している。

3c. 再エクスポートの形式規約（glob / 選択的 / shadowing、イシュー #1062）

各 styled モジュールが headless の対応モジュールを再エクスポートする 形式（glob 併用か選択的個別かの選択、および暗黙 shadowing の禁止）の 規約は crates/pre-styled-ui/src/lib.rs「headless 再エクスポートの形式 規約（イシュー #1062）」節を正とし、本書では二重管理しない。要約:

• 既定は選択的個別再エクスポート（規約 A）。styled パーツ関数を再定義する モジュールは、headless の同名自由関数・未スタイル inherent メソッドを 持つ状態機械型を再エクスポートしない（fail-closed。avatar/breadcrumb 等の既存モジュールがこの運用実体）。
• glob 再エクスポート（規約 B）は「トップレベル pub 項目が stylesheet()/css() のみ・variant 軸を提供しない・CSS 到達が [data-scope]/[data-part] 属性セレクタのみ」の 4 条件（マーカー コメント REEXPORT-GLOB-REVIEWED: を含む）を満たす場合のみ許可する。 イシュー #1062 のレビューにより、現時点で action_bar / popover / hover_card / tooltip / toolbar / tree_view / scroll_area / toggle_tip / menubar / json_tree_view / floating_panel / timer / navigation_menu の 13 モジュールが条件を満たすと判定済み（レビュー来歴は docs/internal/pre-styled-ui-implementation-notes.md §3c 参照）。
• glob 由来の名前をローカル定義・明示 pub use で上書きする暗黙 shadowing は禁止する（規約 C）。同名を styled 側で提供したい場合は 規約 A（選択的）へ移行する。

機械検知は crates/pre-styled-ui/tests/reexport_policy.rs （glob 一覧の双方向一致・マーカーコメント有無・許可 pub 項目・root 再定義 との併存禁止の 4 検査、いずれも fail-closed）が担う。

4. 設計方針

• テーマトークン: 色・スペーシング等のデザイントークンとダークモード 切り替えの基盤。chakra-ui の system/recipe 相当の設計を参考にしつつ、 静的 SSR 出力（ビルド時に確定する CSS）を前提とする。詳細は theme モジュール rustdoc を参照。トークン API・既定値上書き（upsert_*）の 詳細は §4l 参照。
• variant API・静的 CSS 生成: chakra-ui の slot recipe 相当。 コンポーネントの見た目バリエーション（size/variant/colorPalette 等）を 型安全に選択し、対応する静的 CSS を生成する。詳細は pre-styled-recipe-api.md を参照。
• styled 部品: 単純な部品（Button 等）に加え、headless-ui の Accordion/Dialog/Popover/Tooltip/Switch/RadioGroup/Avatar 等をラップした styled 版を提供する（一覧は §2 の表を参照）。

4a. stylesheet::StyleSheet（recipe / theme CSS の書き出し・埋め込みヘルパ）

SlotRecipe::css()・Theme::to_css()・各 styled 部品の css()/stylesheet() は決定的な CSS 文字列を返すのみで、その先の配布は呼び出し側任せだった （examples/headless-pre-styled-ui の手書き static/ui.css コピーが実例）。 stylesheet::StyleSheet はこれを集約し、2 つの配布経路を提供する。

• StyleSheet::new() / push_css(&mut self, css: &str) -> Result<(), StylesheetError>: 唯一の fallible な取り込み口。< を含む、または改行・タブ・復帰以外の 制御文字を含む入力は Err(StylesheetError::CssRejected { .. }) になる （fail-closed）。
• push_recipe(&mut self, recipe: &SlotRecipe) / push_theme(&mut self, theme: &Theme): 生成側 allowlist 検証（< を構成不能にする）に依拠した infallible な 薄いラッパ。
• as_css(&self) -> &str: 取り込んだ CSS 全量。
• write_css_file(&self, path: &Path) -> std::io::Result<()>: 静的 .css ファイルへの書き出し（SSG・ビルドスクリプト向け。親ディレクトリを自動作成）。
• style_element(&self) -> Node: SSR 用 <style> 要素ノード。本クレートで raw_html() を使用する唯一の箇所（§3 の不変条件 2 の例外）であり、 呼び出し文に #[expect(clippy::disallowed_methods, reason = "ESCAPE-REVIEWED: ...")] を付与済み。StyleSheet は private フィールドのみで構成され、検証済み CSS 以外から構築する経路を公開しないため、呼び出し側へエスケープ迂回 経路を公開しない。

use fandhe_frontend_pre_styled_ui::stylesheet::StyleSheet;
use fandhe_frontend_pre_styled_ui::theme::Theme;

let mut sheet = StyleSheet::new();
sheet.push_theme(&Theme::default());
sheet.push_css(&fandhe_frontend_pre_styled_ui::button::css()).unwrap();

// SSG: 静的ファイルとして配信する
sheet.write_css_file(std::path::Path::new("static/ui.css")).unwrap();

// SSR: <style> 要素として埋め込む（render() が既定エスケープを適用する
// 他のノードと同様に合成できる）
let _style_node = sheet.style_element();

4b. avatar（Avatar の styled ラッパー）

fandhe_frontend_headless_ui::avatar（Root/Image/Fallback の 3 anatomy パーツと Avatar 状態機械）を薄く再利用し、stylesheet() で既定 CSS を 追加提供する（設計方針は crate::dialog/crate::tooltip と同じ、 src/avatar.rs 冒頭の rustdoc 参照）。

• 選択的 re-export（Avatar 型は再エクスポートしない）: fallback/ image/AvatarAction/ImageStatus を headless 層からそのまま再 エクスポートする。styled root は本モジュールで variant クラス付与の ために再定義するため、pub use ...::* ではなく選択的 re-export とする （headless の自由関数 root との名前衝突を避けるため）。状態機械 Avatar はあえて再エクスポートしない: Avatar::root() は headless 自由関数 root へそのまま委譲するのみで size/shape variant クラス を一切付与しないため、再エクスポートすると呼び出し側が styled 層の つもりで Avatar::root() を呼びレイアウトが静かに崩れる事故を誘発する。 Avatar による状態管理・hydration が必要な呼び出し側は fandhe_frontend_headless_ui::avatar::Avatar を直接 import すること。
• root(size, shape, attrs, children) -> Node: styled root パーツ。 size（Size::Sm/Md/Lg、既定 Md）・shape（AvatarShape::Circle/ Rounded/Square、既定 Circle）の 2 軸 variant に応じたクラス （fd-avatar--size-<value> / fd-avatar--shape-<value>）を付与する。 呼び出し側 attrs の class は除去してから合成するため class 属性は 常に単一。実体は fandhe_frontend_headless_ui::avatar::root へ委譲する （呼び出し側 data-scope/data-part 偽装は headless 側で除去される）。
• AvatarShape: recipe::VariantValue 実装 enum（Size と並ぶ本 クレート 2 例目の variant 軸）。
• stylesheet() -> String: この styled Avatar の静的 CSS 全量を返す （決定的）。image/fallback の base 規則は display を宣言せず、 headless 層が付与する hidden 存在属性（UA 既定 [hidden] { display: none }）による JS なし SSR の表示制御を壊さない。data-state="hidden" 一致時の display: none は SlotRecipe::state 経由で多層防御として 追加登録する（src/avatar.rs 冒頭の rustdoc 参照）。

4c. styled RadioGroup ラッパー

radio_group モジュールは fandhe_frontend_headless_ui::radio_group の Label/Item/ItemControl/ItemText/ItemHiddenInput 5 anatomy パーツと RadioGroup 状態機械を選択的に再エクスポートし、stylesheet() で既定 CSS を追加提供する（設計方針は他 headless ラッパーと同じ、 src/radio_group.rs 冒頭の rustdoc 参照）。

• item-hidden-input の視覚的非表示化: headless 層はネイティブ <input type="radio"> に aria/data-* のみを設定し視覚的な非表示化を 行わない契約のため、styled 層が visually-hidden パターン（position: absolute + 1px クリップ、select モジュールの hidden-select 規則と 同一の 9 宣言）で覆い隠し、item-control をカスタムラジオ円として描画 する。フォーム送信・キーボード操作・グループ内排他選択はネイティブ semantics のまま維持される。
• StateCondition::FocusWithin の追加: item-hidden-input を視覚的に 隠すと、ネイティブのフォーカスリングも見えなくなる。実フォーカスは 隠された <input> にあり、item（<label>、input の祖先）へ :focus-within を当てるのが CSS 的に成立する唯一の経路のため、 recipe::StateCondition へ FocusWithin（:focus-within 擬似クラス）を 追加した（既存の Attr/AttrEq/FocusVisible に次ぐ 4 つ目の状態条件）。
• root(size, palette, disabled, orientation, labelled_by, attrs, children) -> Node: styled root パーツ。size（Size::Sm/Md/Lg、 既定 Md）・palette（ColorPalette 5 値、既定 Accent）の 2 軸 variant クラス（fd-radio-group--size-<value> / fd-radio-group--color-palette-<value>）を付与する。headless 自由関数 root との名前衝突を避けるため本モジュールで再定義し、pub use ...::* ではなく選択的 re-export とする。RadioGroup 状態機械は inherent root() を持たないため（item 系メソッドのみ）、avatar の Avatar と異なりそのまま再エクスポートを維持する。

4d. 複合部品の variant 統一方針・variant 表

単純部品（button/badge/spinner）・avatar に続き、headless 状態機械を持つ 複合部品ラッパーへ size/color-palette variant を拡張する際の統一方針は crates/pre-styled-ui/src/lib.rs 冒頭の rustdoc「複合部品の variant 統一 方針」節が正本。要旨:

1. クラスは root slot のみに付与し、子孫パーツへの伝搬は root が登録する CSS custom property の通常の継承で行う（SlotRecipe へ子孫セレクタ 機構は追加しない）。
2. var() には Md/Accent 相当のフォールバック値を書き、headless 直接利用 でも現行外観を維持する。
3. size はフォーム操作部品・トリガー系へ、color-palette は選択・ チェック状態を示す部品へ提供する。popover/tooltip は配置・寸法が positioning 起因のため提供しない。

tabs/accordion/dialog/menu/select の実装詳細:

• クラスは root slot のみに付与する。
• root スコープの CSS custom property: tabs --fandhe-tabs-trigger-padding/-content-padding、accordion --fandhe-accordion-trigger-padding/-content-padding、dialog --fandhe-dialog-content-padding/-content-max-width/-title-font-size、 menu --fandhe-menu-trigger-padding/-item-padding/-content-padding、 select --fandhe-select-trigger-padding/-item-padding/-content-padding。 menu/select の --fandhe-reference-width/--fandhe-arrow-*/--fandhe-x/ --fandhe-y（wasm positioning 契約）には手を触れない。
• tabs の color-palette は選択中 trigger の強調色 （border-bottom-color: var(--fandhe-palette, var(--fandhe-color-accent))） にのみ反映する。
• Dialog/Menu/Select（inherent root() を持つ状態機械型）は 未スタイル root の静かな適用漏れ防止のため選択的 re-export へ切り替え ている。Accordion/MultiAccordion（inherent root なし）は再 エクスポート維持。

4d. data-focus-visible によるキーボード専用フォーカスリング

hidden-input パターン（実フォーカスが visually-hidden なネイティブ <input> にあり、リングを見せたい視覚パーツと分離している構成）は、 擬似クラス（:focus-visible/:focus-within）だけでは表現しきれない。 switch（root > control の兄弟配置。:focus-within すら不成立）と radio_group（item の :focus-within は成立するが、マウス操作でも 発火する包括的なフォールバックでしかない）の 2 モジュールがこの補完を 導入した。

• fandhe-frontend-headless-ui の data_attrs::data_focus_visible が data-focus-visible 存在属性の SSR 静的表現（常に属性なし）を契約する （data_highlighted と同型、crates/headless-ui/src/switch.rs/ radio_group.rs/checkbox.rs のフォーカスリング契約 doc 参照）。
• fandhe-frontend-wasm-full の focus 配線（focus_visible モジュール、 keynav/events と同じ 2 層構成）が hidden-input の focusin/focusout と :focus-visible 判定に基づき、境界パーツ（switch: root、 radio_group: item）とその配下で同一 data-scope を共有するパーツ （switch: control、radio_group: item-control）の双方へ付け外しする。
• fandhe-frontend-pre-styled-ui は control/item-control slot へ StateCondition::Attr("data-focus-visible") の状態規則を登録し、 select の trigger（StateCondition::FocusVisible）と同じ視覚言語 （outline: 2px solid var(--fandhe-color-accent)）でリングを表現する。 RadioGroup の item :focus-within は wasm なしでも成立する no-JS フォールバックとして維持し、data-focus-visible はその補完（wasm 配線時のキーボード専用リング）として独立に共存する。
• checkbox も switch の control と同型の StateCondition::Attr("data-focus-visible") 規則を実装済み（詳細は §4e）。

4e. styled Checkbox ラッパー

checkbox モジュールは fandhe_frontend_headless_ui::checkbox の root/control/indicator/label/hidden-input 5 anatomy パーツを選択的に 再エクスポートし、stylesheet() で既定 CSS を追加提供する（設計方針は §4c/§4d と同型、src/checkbox.rs 冒頭の rustdoc 参照）。

• root(size, palette, props, attrs, children) -> Node: styled root パーツ。size（Size::Sm/Md/Lg、既定 Md）・palette （ColorPalette 5 値、既定 Accent）の 2 軸 variant クラス （fd-checkbox--size-<value> / fd-checkbox--color-palette-<value>）を 付与する。headless 自由関数 root はチェック状態を含む CheckboxProps を受け取るため（switch/radio_group の bool 個別引数と 異なる形）、styled root も &CheckboxProps を第 3 引数に取る。headless Checkbox 状態機械（inherent root() を持つ）は switch::Switch と同じ 理由（未スタイル root の静かな適用漏れ防止）で再エクスポートしない。
• indicator の hidden 属性意味論の維持: headless indicator は unchecked 時に hidden 存在属性で非表示化する契約を持つ。styled recipe の indicator base 規則に display 宣言を一切含めないことで、UA stylesheet の [hidden] { display: none } を上書きしない（テスト indicator_base_has_no_display_declaration で固定）。checked/ indeterminate 時の見た目切り替えは border/transform/width/height の組み合わせで表現し、display を使わない。
• data-focus-visible フォーカスリング: control slot へ switch の control と同一の宣言（outline: 2px solid var(--fandhe-color-accent); outline-offset: 2px;）を登録する。属性の付け外しは headless/wasm 層の 責務（fandhe-frontend-wasm-full の focus 配線に ("checkbox", "hidden-input") => Some("root") のマッピングが登録済み）であり、本 モジュールでの wasm 層変更は不要だった。

4f. 静的フォーム部品 input/textarea/native_select

input/textarea/native_select の 3 モジュールは状態機械を持たない （ブラウザネイティブ挙動をそのまま尊重する）。fandhe_frontend_headless_ui::field の input/textarea/select の 3 パーツへ variant/size variant クラスと既定 CSS を重ねる薄い委譲層で、アクセシビリティ配線（id・ ネイティブ disabled/required/readonly・aria-invalid・ aria-describedby・data-*）は headless field::* へ全面委譲する （詳細は src/input.rs 冒頭の rustdoc 参照）。

• field scope を共有する recipe 設計: SlotRecipe が生成する CSS セレクタは [data-scope="<scope>"][data-part="<slot>"] 固定であり、 headless field::* が実際にレンダリングする data-scope="field" と 一致させる必要がある。そのため 3 モジュールは独自の scope を新設せず "field" を共有し、slot を "input"/"textarea"/"select" のみ 個別に宣言する（slot が相互排他のためセレクタ・宣言は衝突しない）。
• 各モジュールの API 形: input(&InputProps, &FieldProps<'_>, extra_attrs) のように、見た目 variant（InputProps）とアクセシビリティ props （headless から再エクスポートした FieldProps/FieldIds）を別引数として 受け取る（ark-ui/chakra-ui が見た目 props とフォーム状態 props を分離 する構成に合わせる）。
• variant 軸: Outline（既定）/Subtle/Flushed の 3 値 （native_select のみ Flushed の代わりに枠なしの Plain）。
• color-palette 軸を提供しない: §4d「複合部品の variant 統一方針」 の基準 3（color-palette は選択・チェック状態を示す部品へ提供する）に 従い、フォーム入力は該当しないため提供しない。フォーカスリングの アクセントは var(--fandhe-color-accent) の直接参照のみで表現する。
• textarea の autoresize フックへの応答: headless field::textarea の autoresize: bool は SSR 時点で data-autoresize="" 存在属性のみを 出力する宣言的フック（実際の高さ調整は CSR/wasm 層またはスタイルの 責務）。textarea モジュールは [data-autoresize] 状態規則として field-sizing: content + resize: none を登録し、この宣言的フックへ styled 層として応答する。
• native_select はネイティブ矢印を維持する: chakra-ui の NativeSelect はカスタム矢印アイコンを重ねるため appearance: none を 使う構成が一般的だが、本モジュールは「ブラウザネイティブ挙動を尊重する」 という設計原則に従い appearance 宣言を持たず、ネイティブの矢印・開閉 挙動をそのまま残す最小サブセットとする。<select readonly> が HTML 仕様上無効なためネイティブ readonly を出力しない判断は headless 層に 委譲済みで、本モジュールは再実装しない。

4g. checkbox_card/radio_card（カード型選択 UI）

chakra-ui の forms/checkbox-card.md/forms/radio-card.md 相当。ark-ui には 対応する headless anatomy が存在しない（chakra-ui 独自の slot recipe）ため、 fandhe-frontend-headless-ui には手を入れず、pre-styled-ui 層のみで 新規 anatomy data-scope="checkbox-card"/"radio-card" を定義する （crate::card が pre-styled 層で独自 anatomy data-scope="card" を持つ 先例と同型の構成、詳細は各モジュール冒頭の rustdoc 参照）。

• 状態機械の再利用（新規状態機械は作らない）: checkbox_card は fandhe_frontend_headless_ui::checkbox::{Checkbox, CheckboxProps, CheckedState} を、radio_card は fandhe_frontend_headless_ui::radio_group::RadioGroup をそのまま利用する。 Checkbox/RadioGroup 自体は再エクスポートしない（checkbox/radio_group モジュールと同じ「未スタイル root の静かな適用漏れ防止」判断。呼び出し側は headless モジュールを直接 import する）。
• anatomy パーツ構成: checkbox_card は root（<label>）/control/ content/label/description/addon/indicator（チェックボックス外枠）/ indicator-check（チェックマーク本体、checkbox::indicator 相当）/ hidden-input の 9 パーツ。radio_card は root（role="radiogroup"）/ label/item（<label>）/item-control/item-content/item-text/ item-description/item-addon/item-indicator（ラジオ円、 radio_group::item_control 相当）/item-hidden-input の 10 パーツ。 chakra-ui の単一 Indicator を「外枠 + マーク」の 2 要素に分けるのは、 SlotRecipe が疑似要素を持たず既存 checkbox/radio-group の実証済み border/transform/box-shadow 描画をそのまま再利用するため。
• hidden-input/item-hidden-input の属性契約: 対応する headless モジュール（crates/headless-ui/src/checkbox.rs/radio_group.rs）の hidden_input/item_hidden_input と同一ロジックで出力する（両ファイルを 合わせて確認する契約）。
• size/color-palette 軸: §4d の統一方針に従い root へのみクラスを 付与し、--fandhe-checkbox-card-*/--fandhe-radio-card-* の root スコープ custom property 経由で子孫パーツへ伝搬する。
• フォーカスリング: 実フォーカスは hidden-input が受けるため、 radio_group の item と同型の StateCondition::FocusWithin（no-JS フォールバック）のみを root（checkbox_card）/item（radio_card）へ 登録する。data-focus-visible（wasm 配線によるキーボード操作専用リング） は crates/wasm-full/src/focus_visible.rs の (scope, part) マッピングに "checkbox-card"/"radio-card" が未登録のため現状スコープ外。

4h. 静的部品 status/empty_state

chakra-ui の feedback/status.md/feedback/empty-state.md 相当。状態機械を 要しない静的マークアップ部品であり、fandhe-frontend-headless-ui には 手を入れない（headless anatomy 自体が存在しないため checkbox_card/ radio_card と同型に pre-styled 層のみで新規 anatomy を定義する）。

• status（scope "status"、root/indicator の 2 パーツ）: size（ドット径・フォントサイズ）/color-palette（Alert/Badge/Spinner と 同じ --fandhe-palette-* セマンティック色）の 2 軸 variant を root へ 付与する。indicator の直径は root の variant が設定する --fandhe-status-dot-size custom property を継承経由で参照する （§4d の「root variant が子孫スコープの custom property を設定する」 統一方針と同型）。role/aria-live は付与しない: ラベルテキスト 自体が状態を伝える静的表示であり、[spinner::spinner] のような非同期 読み込み中の live region 告知とは用途が異なる（呼び出し側が動的な状態 変化を告知したい場合は attrs へ明示的に role/aria-live を足す設計）。
• empty_state（scope "empty-state"、root/content/indicator/ title/description/actions の 6 パーツ）: crate::card と同型の 中立レイアウトコンテナであり color-palette 軸は提供しない。size （root の padding）のみを持つ。title/description は <div>（見出し 要素 <h1>〜<h6> にしない）とし、埋め込み位置に応じて見出しレベルが 変わり得る呼び出し文脈で固定レベルを強制しない（crate::alert::title と 同型の判断）。indicator はアイコン等を children として受け取り、外部 リソース・アイコンフォントを本クレートが直接参照することはない。

4i. タイポグラフィ静的部品（Heading / Text / Em / Mark / Blockquote / List）

chakra-ui typography/heading.md / text.md / em.md / mark.md / blockquote.md / list.md 相当の 6 静的部品。headless 状態機械を要しない 「単一 recipe / slot recipe 静的部品」（badge/skeleton と同型）で、 h1-h6/p/em/mark/blockquote/ul・ol・li の素の HTML 意味論をそのまま styled 化する。

variant 表

heading/list の「タグ選択」は variant クラスではなく、レンダリングする HTML タグそのものを選ぶ引数である点に注意（recipe::VariantValue を実装 しない）。

4j. charts 軸・グリッド・凡例・ツールチップ

chakra-ui charts/axes.md / cartesian-grid.md / legend.md / tooltip.md 相当。charts 基盤（crates/pre-styled-ui/src/charts/{data,scale,svg}.rs）の 最初の消費者であり、pre_styled_ui::charts::{axis, grid, legend, tooltip} の 4 サブモジュールとして実装する（新規トップレベルモジュールは追加しない。 詳細な設計判断は docs/design/charts-foundation-design.md 参照）。

API 一覧

各モジュールは css() を公開し、stylesheet.rs の一元化リスト （all_styled_component_css）へ "charts/axis" 等のキーで登録済み。

anatomy / recipe

• axis/grid/tooltip は scope "chart" を共有する（slot 名が互いに 素なため CSS セレクタは衝突しない、SlotRecipe は scope の一意性を 要求しない）。slot: x-axis/y-axis/axis-line/tick-line/ tick-label（axis）・grid/grid-line（grid）・datum（tooltip）。
• legend は独立 scope "chart-legend" を持つ（SVG 外の通常 HTML <ul>/<li>/<span> のため）。slot: root/title/item/marker/ label。
• grid の線種は GridLines（Solid(既定)/Dashed）の 1 軸 variant。
• tooltip の hover 強調は crate::recipe::StateCondition::Hover （:hover 擬似クラス）を使う唯一の消費者。

SSR ツールチップ方式（JS 不使用）

マウス追従型のリッチツールチップ（recharts <Tooltip> の cursor 追従）は JS ランタイムが必須のためスコープ外。代わりに tooltip::datum がデータ点 （<circle>）へ子 <title> 要素（ブラウザネイティブな hover 表示）と aria-label 属性（同一文字列）を埋め込み、StateCondition::Hover による CSS のみの視覚強調と組み合わせて「ホバーで詳細が分かる」体験を実現する。

4k. LineChart / AreaChart / Sparkline（charts 基盤の消費者）

docs/design/charts-foundation-design.md が提供する charts::data::ChartData （カテゴリ + 系列の値モデル）・charts::scale::LinearScale（線形座標写像）・ charts::svg（SVG ノード木ヘルパー、fmt_coord/ViewBox/svg_root/ PathBuilder）を消費し、「プロット領域（折れ線・面・スパーク）のみを描く 自己完結 SVG」として実装する。軸・グリッド・凡例・ツールチップ （chakra の CartesianGrid/XAxis/YAxis/ChartLegend/ChartTooltip 相当）は §4j のスコープであり本 3 部品には含まれない。

API 概要

いずれも *Props::new(data_or_values, aria_label) が既定寸法・ Size::Md で組み立てる便利コンストラクタを提供する。

variant 表

color-palette 軸は非提供。系列色は charts::series_color_var(index) （var(--fandhe-color-chart-1..6) を系列数に応じて循環）を stroke/fill 属性へ直接付与する（CSS variant ではなく描画時の固定色指定、複数系列を 同時に描く都合上 SlotRecipe の軸機構に載せない判断）。

座標写像・エッジケース

• x 軸: カテゴリ index を等間隔配置（単一カテゴリは中央 1 点）。
• y 軸: ChartData::domain()（フラットデータの非退化パディング込み）を LinearScale::new(domain, (height, 0.0)) で写像（nice() は適用しない）。
• 単一カテゴリ（n == 1）: 折れ線・面のいずれも生成せず、中央に半径固定の circle マーカーのみを描く。
• 負値・フラットデータ: charts 基盤の domain()/fmt_coord の契約に従い 決定的に描画する（golden テスト crates/pre-styled-ui/tests/charts_line_area_sparkline.rs 参照）。

4l. theme モジュール: Theme トークン API と upsert_*（イシュー #547/#606/#1138）

API 一覧

impl Theme {
    pub fn empty() -> Self;
    pub fn default() -> Self; // 標準トレイト実装

    // 追加専用（既存名は ThemeError::DuplicateTokenName で拒否）
    pub fn push_color(&mut self, name: &str, light: &str, dark: &str) -> Result<(), ThemeError>;
    pub fn push_space(&mut self, name: &str, value: &str) -> Result<(), ThemeError>;
    pub fn push_typography(&mut self, name: &str, value: &str) -> Result<(), ThemeError>;
    pub fn push_radius(&mut self, name: &str, value: &str) -> Result<(), ThemeError>;
    pub fn push_shadow(&mut self, name: &str, light: &str, dark: &str) -> Result<(), ThemeError>;

    // 追加または上書き（イシュー #1138。DuplicateTokenName を返さない）
    pub fn upsert_color(&mut self, name: &str, light: &str, dark: &str) -> Result<(), ThemeError>;
    pub fn upsert_space(&mut self, name: &str, value: &str) -> Result<(), ThemeError>;
    pub fn upsert_typography(&mut self, name: &str, value: &str) -> Result<(), ThemeError>;
    pub fn upsert_radius(&mut self, name: &str, value: &str) -> Result<(), ThemeError>;
    pub fn upsert_shadow(&mut self, name: &str, light: &str, dark: &str) -> Result<(), ThemeError>;

    pub fn to_css(&self) -> String;
}

色（colors）・影（shadows）はライト/ダーク 2 値、余白（spaces）・ タイポグラフィ（typography）・角丸（radii）はモード非依存の 1 値を取る。

push_* と upsert_* の意味論対比

Theme::default() の既定値を差し替える正規経路

push_* は同名トークンを常に DuplicateTokenName で拒否するため、 Theme::default() が持つ既定パレット（bg/fg/accent/font-body 等） を差し替える正規経路が存在しなかった（イシュー #1118 で判明した欠落）。 upsert_*（イシュー #1138）がこの欠落を解消する正規経路であり、 push_* では代替できない。

Theme::to_css 出力への反映

upsert_* で置換・追加した値は、Theme::to_css の既存の出力構造 （:root の light 値ブロック・@media (prefers-color-scheme: dark) の dark 値ブロック・:root[data-theme="..."] による明示上書きブロック）へ そのまま反映される。内部表現は Vec による挿入順保持のため、出力は 呼び出し順序にのみ依存する決定的な文字列になる。

使用例（イシュー #1118 の実シナリオ）

use fandhe_frontend_pre_styled_ui::theme::Theme;

let mut theme = Theme::default();
// 既定の font-body を日本語フォントスタックへ差し替える（正規経路）
theme.upsert_typography("font-body", "Noto Sans JP, system-ui, sans-serif")?;
// アクセント色の上書き（light / dark 2 値）
theme.upsert_color("accent", "#0f766e", "#2dd4bf")?;
let css = theme.to_css();

値はいずれも [CssValue::new] の allowlist（ASCII 英数字・空白・ # % . , ( ) - _ のみ許可）を通過する文字列に限る。 引用符（" '）は allowlist で拒否されるため、フォント名は引用符なしで 書く。

セキュリティ上の不変条件（REQ-1 相当、CSS 文脈）

upsert_* も push_* と同一の allowlist 検証（TokenName::new / CssValue::new）を唯一の入口とし、迂回経路を持たない。: ; { } を拒否するため宣言追加・セレクタ脱出・url(javascript:...) は構成不可能 であり、< > / " ' を拒否するため </style> 脱出も構成不可能で ある。検証は全引数に対して完了してから書き込むため、検証失敗時は Theme を一切変更しない（部分書き込みなし）。固定テストは crates/pre-styled-ui/src/theme.rs 内ユニットテスト・ crates/pre-styled-ui/tests/theme_css.rs・ crates/pre-styled-ui/tests/theme_injection.rs。

upsert_* は「重複拒否の無効化」ではなく、既存トークンを明示的に 上書きするための独立したオプトイン API である（push_* の fail-closed 挙動自体は変更しない）。

upsert API は fandhe-frontend-pre-styled-ui v0.38.0 以降に収録される （§2a の crates.io 公開状況・バージョン確認方針を参照）。

5. 関連ドキュメント

• docs/api/headless-ui-api.md: 本クレートの下層。 Format 系 / Locale（§4e）は本クレートに対応モジュールを持たないため、 掲載は同ドキュメントを正とする（本クレートからの到達経路は §2 表 「headless 由来ユーティリティ」行・§3a 参照）
• docs/api/component-api.md: Node/el/text/ raw_html/render の凍結 API 表面
• docs/api/pre-styled-recipe-api.md: variant API・静的 CSS 生成の詳細
• examples/headless-pre-styled-ui/README.md: 本クレート v0.4.0 へ統合済みのショーケースサンプル（§2 参照）
• .claude/skills/chakra-ui/: 設計時の参考にした chakra-ui リファレンス スキル
• docs/internal/pre-styled-ui-implementation-notes.md: 実装経緯・ ロードマップ・トレーサビリティの記録（docs サイト非掲載のためリンク化 しない）