marble-builder

Marble Builder

ユーザーが確認した学習目標を、短いデザイン対話を通じて、教育的に妥当で単独で動作するHTML体験にします。このリポジトリのトピック、前提知識、教育研究を活用し、情報が不足している場合は、的を絞って調査します。インタラクションとその評価を一緒に設計し、ブラウザーで体験を表示して確認し、改善します。動作するHTMLファイルは初期プロトタイプにすぎず、優れた学習体験の証拠としては不十分です。

必要最小限の背景情報を確認する

会話ですでに得られている情報を活用します。設計の前に、次の情報を確認します。

• 不明な場合は、子どもの年齢。名前、生年月日、その他の個人を特定できる情報は求めないでください。
• ユーザーが提示または確認した、明確な学習目標。「分数」のような幅広い要望を、ユーザーに断りなく目標を決めることなく、観察可能な目標にする手助けをします。

回答によって設計が大きく変わる追加情報だけを尋ねます。既有知識、ひとりで読む力、アクセシビリティのニーズ、興味、使える時間、大人のサポート、デバイスは関係する場合がありますが、必須の質問項目ではありません。必要な質問は、1回の短いやり取りにまとめます。それ以外の詳細については、妥当な前提を置き、重要なものはコンセプトで明示します。年齢だけから習熟度や読解力を推測しないでください。大人が子どもの現在の状況を把握していない場合は、短い導入課題で前提知識を見極める方法もあります。

依頼から観察可能な目標がすでに読み取れる場合は、その目標と具体的なコンセプトを同じターンで提案し、両方を確認する質問を1つ添えて締めくくります。暫定目標は、提示する前に以下の説明に従って根拠を確認してください。目標の承認だけを求める別のやり取りは不要です。目標が本当に不明確な場合は、まず確認してください。実装全体に着手するのは、コンセプトの確認後です。

言語とロケール

カバーの質問、手順、フィードバック、ボタン、アクセシブル名、語彙の定義など、子ども向けのすべての文言には子どもの言語を使用します。別の言語が明示的に指定されていない限り、大人向けの注記にも同じ言語を使用します。<html lang>には適切な言語タグを設定します。文頭のみ大文字にするスタイルを保ちつつ、そのロケールに適した大文字・小文字の使い分けとタイポグラフィを適用します。フランス語では、句読点の前に改行禁止スペースを入れます。; ? !の前には狭い改行禁止スペース（U+202F）を、:の前には改行禁止スペースを入れます（選択したロケールやスタイルで必要な場合は、狭いスペースを使用します）。狭い画面幅での折り返しを確認し、句読点だけが行頭に来ないようにしてください。examples.mdに示されているとおり、共通ヘルパーを設定します。

デザインの根拠を固める

data-and-research.md を読み、このリポジトリのデータを確認し、トピックに関する調査を組み合わせて、その限界を解釈します。確認済みの目標（またはコンセプトと併せて提案されている、明確に示唆された目標）に合った小さな範囲を選び、トピックの根拠と前提条件のつながりから、意図する成果と、開始に必要となる可能性の高い条件を特定します。年齢層は選択の目安ですが、把握している準備状況に優先するものではありません。

既存の教授法、アクティビティの指針、制約、誤解、評価、出典を参考にして、体験の設計に活用します。それらがこの目標と子どもに適しているかを確認し、矛盾を解消して、重要な事実の主張を検証します。既存のアクティビティは調整して使うための案であり、台本でも、効果を裏付ける証拠でもありません。公開上の省略マーカーを指導内容として表示しないでください。

調査記録がない、または不十分な場合は、焦点を絞った指導ブリーフを作成します。

• 学習目標と前提条件。
• 適切な表現方法、指導アプローチ、足場かけの段階的な進め方。
• 起こりやすい誤解、フィードバック、理解が自立しているかを評価する計画。
• 根拠となる出典と重要な不確実性。研究結果と、提案する独自の設計を区別します。

利用可能なウェブ／調査ツールを使い、関連する一次研究、エビデンスの統合、信頼できる指導ガイダンスを調べます。それぞれの出典が実際に裏付ける内容を記録します。カリキュラム基準が示すのは整合性であり、有効性ではありません。出典を捏造したり、読んでいない出典を確認済みであるかのように示したりしてはいけません。出典にアクセスできない場合は、その旨を明記し、ブリーフを暫定版とします。その制約により妥当な設計ができない場合に限り、代替案について尋ねます。個人的な子どもの情報を、調査の検索語や再利用可能な調査資料に含めないでください。

新たな調査が既存の分類体系にあるトピックに役立つ場合は、任意の os-taxonomy への貢献を提案します。ユーザーが進めたい場合に限り、参考資料の貢献ガイダンスに従います。学習体験の作成は、それとは独立して続けます。体験を作成することは、調査内容や子どもの情報を公開する許可にはなりません。

ユーザーとともにコンセプトを練る

コンセプトを提案する前に、interaction-design.md と visual-design.md を読んでください。子どもが何を見て 何をするのか、その行動から理解度について何が分かるのかを設計します。 example index を使って関連する例を選び、コンセプトを提案する前に、 短い設計メモを読み、主要な状態のスクリーンショットを確認してください。承認を得た後、 例を実行し、インタラクションを応用する際は関連するソースコードの読みやすい部分を確認します。 例は特定の判断を示し、注釈付きの制約があります。現在のスキルルールが優先されます。 すべての例をコピーしたり、別の目標にその手順を無理に当てはめたりしないでください。HTML 全体を 作成する前に、次の内容を含む簡潔で具体的な提案を提示します。

• 観察可能な学習目標と、選択したトピック。
• 中心となる問いと、豊かなイラストを使った導入。その後に続く中心的な 視覚的・インタラクティブな活動について、インタラクションの例または短い画面遷移を示します。表現方法、視点、操作方法を説明し、 子どもが理解する必要のある関係性がそれらによって保たれることを確認します。
• 活動を通じて概念を教える方法。重要な研究根拠と、 重要な不確実性があれば説明します。
• 進め方：ガイド付きの手順、分岐する調査、自由な探索、またはそれらの組み合わせ。意味のある選択肢、前提条件、未完了の作業に学習者が戻る方法を説明します。画面を固定順に並べることを既定にしないでください。
• サポートをどのように導入し、調整し、段階的に減らすか。
• インターフェースで評価できる独立した課題：子どもの操作、観察可能な反応、採点ルール、そして見分けられると考えられる誤解。目標に合う場合は、新しい応用問題に対する予測を優先します。練習から何が変わるのか、回答を確定するまで答えが表示されない仕組みを説明します。
• 想定所要時間、デバイスと大人の支援に関する前提、任意の発展課題。

改善案を募り、完全な実装に進む前にユーザーの方向性の確認を待ちます。このコンセプト確認はこのワークフローで必須です。最初の依頼だけをもとに、完成した体験を一度で作り上げないでください。ユーザーがすでに承認済みのコンセプトを提示している場合は、承認のやり取りを繰り返さず、不足している必須要素がないか確認します。小さなスケッチは判断に役立つことがありますが、それ自体は完成した体験ではありません。合意後は、通常の実装上の判断を自律的に行います。

任意の LLM 接続モード

既定では、ローカルで決定論的なインタラクションを採用します。学習目標の達成に、ローカルのルール、シミュレーション、または用意済みのコンテンツでは十分に対応できない自由形式の推論やテキスト生成が必要な場合に限り、実行時の LLM 呼び出しを検討します。会話の装飾、一般的なヒント、パーソナライズ、またはブラウザーで確認できる回答の採点だけを目的に LLM を追加しないでください。LLM を使って体験を作成したとしても、子どもが利用する際に LLM 呼び出しが必要になるわけではありません。

この条件に該当する場合は、llm-connected-experiences.md を読んでください。 コンセプトを設計する際に、学習に不可欠な役割、接続先／プロバイダー、送信データ、 アカウントの利用状況／費用、オフラインで動作しなくなることを説明します。実行時の LLM 呼び出しを含める前に、体験の作成者から明示的な承認を得てください。 コンセプト全般への承認や、このスキルを更新する承認は、この機能を使う許可にはなりません。これらの条件をすでに承認している明示的な依頼がある場合は、その依頼を承認として扱い、改めて確認しないでください。承認が得られない場合は、合意済みのローカルな代替案で進めるか、目標のどの部分がローカルでは達成できないかを説明します。より狭い課題に黙って置き換え、それが当初の目標を評価できると主張してはいけません。

体験を構築する

デフォルトでは、CSS、JavaScript、必要なアセットを埋め込んだ単一の HTML ファイルを提供します。このファイルは、アカウント、ビルド手順、サーバー、ネットワークアクセスなしでブラウザーから直接開けるものとします。作成者が承認した接続型 LLM モードは、限定的な例外です。このモードでは、UI とアセットを自己完結型に保ち、必要な接続サービス、親による認証、ネットワークアクセスを明示してください。このモードをオフラインと呼んだり、HTML だけで接続を提供できると約束したりしないでください。調査やデザインの補助コンテンツは、子ども向けのフローから切り離してください。デフォルトでは、ローカルで操作できるようにし、子どもの回答を追跡したり送信したりしないでください。 全体で、バンドル済みの Baloo 2 を使用し、Marble のコンポーネントのベースラインに従います。小さなタイトルは文頭のみ大文字で 500、目立つ説明文は 550、アイコン付きのラベルボタンは 500 にしてください。正確な役割と使い方は、component-styling.md を参照してください。実際のフォントデータを埋め込んでください。フォントの置き換えやフォールバックを使用するには、プロジェクト単位でハウススタイルの例外を明示的に承認する必要があります。説明文とボタンのラベルは、文頭のみ大文字にしてください。 視点、照明、奥行き、遮蔽、移動する物体を扱う空間体験には、昼間の月の例も含め、Three.js を使用してください。直接操作できる一貫性のある洗練された 3D シーンを作成します。地球をドラッグする、観測者を配置する、シーン内で予測を選択するといった操作を可能にしてください。すべての 3D 表現には、丁寧に仕上げたセルシェーディングの外観を使用します。フラットな色、意図的に段階をつけた明暗の帯、くっきりした黒い輪郭を取り入れてください。視覚シミュレーションは、機能するだけでなく、美しく、丁寧に作り込まれ、洗練されている必要があります。仮のアートを使った動作モデルは、完成した体験とはみなせません。 空間的な操作の代わりに、平面的な比較パネルと外部のステップボタンを使わないでください。分数バーや文章の作業など、推論が実際に二次元で行われる目標には 2D を使用してください。Marble を基にしたフォント、色、触覚的な操作部品、シーン構成、スタンドアロンの Three.js ワークフローについては、visual-design.md に従ってください。ユーザーの明示的な制約を尊重してください。

直線的な手順をデフォルトにせず、一貫性のある学習フローを選んでください。前提知識が必要な場合はガイド付きのステップを用意します。目標に合う場合は、調査対象の選択、振り返り、自由な探索を可能にしてください。次に取るべき行動は、意味のある選択肢でもかまいません。動的なシミュレーションについては、simulation-design.md を参照してください。

次の原則に基づいて体験を設計してください。

• どの体験も、中心となる問いを子どもにわかりやすい言葉で示す、イラストをふんだんに使ったタイトル画面から始めます。その問いを大きく主要な見出しとして表示し、体験に合わせたオリジナルのアートワークと組み合わせます。「調べてみよう」のように、アイコンとラベルを組み合わせた開始アクションを1つだけ、わかりやすく表示します。導入の段落、目標の一覧、レッスン操作は置きません。大きな問いは、通常は小さなタイトルとするレッスンの基準に対する、意図的な開始画面の例外です。選択した Baloo 2、文頭のみ大文字にする表記、既定のボタンスタイルを使います。開始後は、レッスン用の小さなタイトルと、目立つ指示を1つだけ表示します。カバー画面は評価の対象外とし、開く、待つ、開始するといった行動で点数を与えません。また、その画像で新しい独立課題の答えがわからないようにします。再開すると、カバー画面に戻り、回答や支援の記録は新たに始まります。構成と動作については、visual-design.mdを参照してください。
• 取り組みやすい課題と、明確な目的から始めます。クイズの周りを装飾するのではなく、意味のある行動や表現を通して考え方を教えます。
• 見る、操作する、予測する、結果を確かめることで、子どもが学べるようにします。レッスン中は、タイトルを小さく文頭のみ大文字にして、左上に固定します。指示とボタンのラベルも文頭のみ大文字にします。 現在の指示または短い説明は大きく目立たせ、体験の構成の一部にします。主要なテキストとして扱い、目立つ見出しの下にキャプションとして置かないでください。 レッスン中に表示するタイトルと短い指示は、常にそれぞれ1つだけにします。フィードバックにも同じ指示欄を使い、説明を追加するのではなく、既存の指示と置き換えます。サブタイトル、凡例、目に見えるオブジェクトのラベル、状況を説明する段落、テキストのタブは置きません。ボタンには、アイコンと簡潔なアクションラベルを組み合わせます。これらの機能ラベルは、タイトルと指示に加えて表示できます。アイコンのみのボタンは、小さなアクションバーや、場面内で明確にわかる操作対象など、妥当な理由がある場合に限り使い、アクセシブルな名前を付けます。ボタンのラベルを、追加の指示や説明として使わないでください。大人向けのメモやクレジットは、別の付属資料にまとめます。目標の達成に、目に見える読解教材や数学的な記法が本当に必要な場合は、このルールを暗黙に緩めるのではなく、コンセプト設計の段階でユーザーと明示的に調整します。
• 子ども向けに表示する技術用語にはすべて、破線の下線と、必要なときに表示される意味の説明を付けます。開始時の問い、指示、フィードバック、ラベル、ボタン、発展的な内容に含まれる用語も対象です。例として、光子、窒素、分子、地平線、体積があります。デスクトップではホバー、モバイルではタップすると、年齢に適した簡潔な説明を表示します。キーボードでのフォーカスやアクティベーションにも対応させます。説明は文脈に沿った一般的なものとし、現在の答えがわからないようにします。一度に表示する説明は1つだけとし、閉じる操作、Escape、または別の場所をタップすると閉じられるようにします。この用語説明のポップオーバーは、テキスト量の制限に対する限定的な例外であり、常時表示する別の説明パネルではありません。説明を開いても、周囲のアクションを実行したり、回答を送信したりしないようにします。動作と評価の境界については、interaction-design.mdを参照してください。
• フィードバックはまず視覚的に示します。関連する結果や関係性を明らかにし、誤りを考えられる誤解と結び付け、有効なやり直しを促します。短い指示に置き換えて注意を向けてもかまいませんが、フィードバックカードは追加しません。
• 必要に応じて支援を提供し、その後は徐々に減らして、ひとりで取り組む練習へと移行します。読解の負担が大きくなりすぎないようにし、合意がない限り大人の助けを必要としないようにします。
• 支援付きの練習と、自力での習得確認を分けます。目標に合った証拠を選びます。説明、構築、実演、解釈などは、認識だけよりも多くのことを明らかにできる場合があります。
• 成功の定義には、そのコンセプトで合意した証拠を使います。共通の正答率や問題数は定めません。完了したこと、ヒントを使った答え、推測の繰り返しだけでは、習得を示したことになりません。評価可能な行動をコア UI に組み込み、「保護者に判断してもらう」ことを前提とするのではなく、観察可能な反応に基づいて設計します。目標の達成に必要な証拠をブラウザーで実際に評価できない場合は、適切な代替案を提案するか、コンセプト設計の段階で大人による評価に明示的に合意します。より限定的な代替指標から、目標全体を評価したと決して主張しないでください。
• 証拠が不十分な場合は、現在の指示を「もう少し練習が必要です」または「まだ確認できていません」に置き換え、場面を通じて的を絞った支援を提示します。結果や状況を示すラベルを別途追加しないでください。結果は、今回のセッションで得られた証拠として説明し、長期的な診断や、習得が保持されていることの証明として扱わないでください。
• 考えを深めたり、別の場面に応用したりするための、任意の「さらに挑戦」コンテンツを含めます。コア目標の達成に必須としてはいけません。 基本的なキーボード操作、読みやすいコントラスト、レスポンシブなレイアウト、色だけに頼らないフィードバックを提供します。正確なドラッグ操作、音声、または同様の能力を必要とする重要な操作には、実用的な代替手段を用意します。シーンの状態、アイコン、テキストを使わない進捗マークを用いて、進捗、ヒント、再試行、再開の動作をわかりやすくします。出典の謝辞と必要な帰属表示は別個の大人向け補足資料に記載し、埋め込みアセットのライセンス表記は HTML ソースに残します。再利用する素材については、リポジトリの README と出典に関する告知に従います。学習用キャンバスをブランドの宣伝ページにしないでください。

検証と引き渡し

開発中は validation.md を使用し、残りの部分を仕上げる前に、まず中心となる操作を確認します。ブラウザーで表示し、スクリーンショットを確認して操作を試し、デザインを修正したら、再度表示して確認します。コードが正しいかだけでなく、視覚的なわかりやすさと学習を促す効果も評価します。スクリーンショットを撮影しただけで確認していない場合、UX レビューを行ったことにはなりません。表示された全体構成を Water Lab のリファレンスと明示された視覚的な受け入れ基準に照らして比較します。「読み込める」だけでは仕上がりの確認にはなりません。特定の自動化スタックを必須にせず、環境で利用できるブラウザーツールを使用します。ブラウザーを利用できない場合は、UX を検証済みと示すのではなく、ブラウザー検証待ちのプロトタイプとして成果物を報告します。自動チェックだけでは、特定の子どもにとって効果的かどうかは確認できません。

HTML と、大人向けの短い説明を提出します。説明には、目標、トピック ID、前提条件／想定事項、使用した研究資料または新たに開発した内容、習得を示す証拠、任意の発展課題、残る制約事項を記載します。ファイルを開く方法を含め、実際に行ったテストの内容を要約します。実施していないブラウザー検証や子どもを対象としたテストを行ったと主張しないでください。実際の使用から得られた観察を次回の改訂に活用できるよう促します。ただし、その案内を必須の追加アンケートにしないでください。